feat(site): generated multipart component api reference (#468)

2026-08-16 02:45:09 +00:00 · 2026-02-09 12:20:45 +11:00
parent 3c4152fb58
commit 4b1e863883
31 changed files with 1413 additions and 327 deletions
@@ -5,13 +5,13 @@ Generates interactive API documentation from TypeScript sources for Video.js 10
 ## Architecture

 ```
-TypeScript Sources (core/html packages)
+TypeScript Sources (core/html/react packages)
         ↓
   api-docs-builder (typescript-api-extractor)
         ↓
   JSON files (site/src/content/generated-api-reference/)
         ↓
-   <ApiRefSection /> Astro component
+   <ApiReference /> Astro component
         ↓
   Interactive tables in MDX pages
 ```
@@ -25,6 +25,7 @@ The builder scans `packages/core/src/core/ui/` for component directories. For ea
 - **Core file**: `play-button-core.ts` → Extracts `PlayButtonProps`, `PlayButtonState`, and `defaultProps`
 - **Data attrs file**: `play-button-data-attrs.ts` → Extracts data attributes with JSDoc descriptions
 - **HTML element file**: `packages/html/src/ui/play-button/play-button-element.ts` → Extracts `tagName`
+- **Parts index**: `packages/react/src/ui/play-button/index.parts.ts` → Detects multi-part components

 ### 2. TypeScript Extraction

@@ -70,34 +71,35 @@ Generates one JSON file per component at `site/src/content/generated-api-referen

 ### 4. Astro Components

-The `<ApiRefSection />` component:
+The `<ApiReference />` component:

 1. Loads the JSON via Astro Content Collections (`getEntry('apiReference', 'play-button')`)
-2. Filters props based on current framework (hides React-only props on HTML pages)
-3. Renders interactive tables with expandable prop details
+2. For single-part components: renders Props, State, and Data Attributes sections with h3 headings
+3. For multi-part components: renders each part with a framework-aware h3 heading, part description, and h4 sub-sections
+4. Renders interactive tables with expandable prop details

 ## Usage

 ### In MDX

+Use the unified `<ApiReference />` component for both single-part and multi-part components:
+
 ```mdx
-import ApiRefSection from '@/components/docs/api-reference/ApiRefSection.astro';
+import ApiReference from "@/components/docs/api-reference/ApiReference.astro";

-## API Reference
-
-### Props
-
-<ApiRefSection component="PlayButton" section="props" />
-
-### State
-
-<ApiRefSection component="PlayButton" section="state" />
-
-### Data Attributes
-
-<ApiRefSection component="PlayButton" section="dataAttributes" />
+<ApiReference component="PlayButton" />
 ```

+For multi-part components, the same pattern applies — the component automatically renders part headings, descriptions, and sub-sections:
+
+```mdx
+import ApiReference from "@/components/docs/api-reference/ApiReference.astro";
+
+<ApiReference component="Time" />
+```
+
+Part descriptions are extracted from JSDoc on the React component exports (e.g., `packages/react/src/ui/time/time-value.tsx`).
+
 ### Building

 The builder runs automatically before dev/build via npm scripts:
@@ -111,6 +113,58 @@ pnpm dev      # via predev hook
 pnpm build    # via prebuild hook
 ```

+## Multi-Part Components
+
+Some components are composed of multiple parts (e.g., Time has Value, Group, Separator). The builder auto-discovers these via convention.
+
+### Detection
+
+**Trigger**: Presence of `packages/react/src/ui/{name}/index.parts.ts`.
+
+Single-part components (PlayButton, MuteButton) don't have this file and are unaffected.
+
+### Discovery Algorithm
+
+1. **Part name discovery**: Named (non-type-only) exports are parsed from `index.parts.ts`. Each value export becomes a part.
+2. **Kebab segment derivation**: Source path `./time-group` → strip `./time-` prefix → `group`.
+3. **HTML element matching**: Each part's kebab segment is used to find `{name}-{kebab}-element.ts` in the HTML directory (e.g., `time-group-element.ts`).
+4. **Primary part identification**: The part with NO `{name}-{part}-element.ts` match, whose element is just `{name}-element.ts`, is the primary part.
+5. **Shared resource attribution**: `{name}-core.ts` and `{name}-data-attrs.ts` are attributed to the primary part only.
+
+### Naming Conventions Required
+
+- Core interfaces must be `{Name}Props` and `{Name}State` (not `{Name}CoreProps` etc.)
+- Part exports in `index.parts.ts` must be value exports (not type-only)
+- HTML element files must follow `{name}-{part}-element.ts` naming
+- Element classes must be `{Name}{Part}Element` (e.g., `TimeGroupElement`)
+
+### JSON Output
+
+Multi-part components have empty top-level `props`/`state`/`dataAttributes`. All data lives in the `parts` record:
+
+```json
+{
+  "name": "Time",
+  "props": {},
+  "state": {},
+  "dataAttributes": {},
+  "platforms": {},
+  "parts": {
+    "value": { "name": "Value", "description": "Displays a formatted time value.", "props": { ... }, ... },
+    "group": { "name": "Group", "description": "Container for composed time displays.", "props": {}, ... },
+    "separator": { "name": "Separator", "description": "Divider between time values.", "props": {}, ... }
+  }
+}
+```
+
+### Troubleshooting
+
+- **Part not appearing in JSON?** Check `index.parts.ts` exports the part as a value export (not type-only).
+- **Props/state empty for primary part?** Verify core interfaces are named `{Name}Props`/`{Name}State`.
+- **HTML tag name missing?** Verify element file follows `{name}-{part}-element.ts` naming and has `static tagName`.
+- **No primary part warning?** Ensure the primary part's element file is just `{name}-element.ts` (not `{name}-{part}-element.ts`).
+- **Part description missing?** Add a JSDoc comment to the React component export (e.g., `/** Displays a formatted time value. */` above `export const Value`).
+
 ## File Structure

 ```
@@ -120,22 +174,27 @@ site/scripts/api-docs-builder/
    ├── index.ts           # Main entry point, orchestrates handlers
    ├── types.ts           # TypeScript interfaces
    ├── formatter.ts       # Type formatting utilities
+    ├── utils.ts           # Utility functions (naming helpers)
    ├── core-handler.ts    # Extracts Props/State from core packages
    ├── data-attrs-handler.ts  # Extracts data attributes
    ├── html-handler.ts    # Extracts Lit element info
+    ├── parts-handler.ts   # Parses index.parts.ts for multi-part components
    └── tests/
        ├── test-utils.ts
        ├── core-handler.test.ts
        ├── data-attrs-handler.test.ts
        ├── formatter.test.ts
-        └── html-handler.test.ts
+        ├── html-handler.test.ts
+        ├── parts-handler.test.ts
+        └── utils.test.ts

 site/src/
 ├── content/generated-api-reference/  # Generated JSON files (gitignored)
 │   ├── play-button.json
-│   └── mute-button.json
+│   ├── mute-button.json
+│   └── time.json
 └── components/docs/api-reference/
-    ├── ApiRefSection.astro    # Main wrapper, loads JSON
+    ├── ApiReference.astro     # Unified component — renders full API reference from JSON
    ├── ApiPropsTable.astro    # Props table
    ├── ApiStateTable.astro    # State interface table
    ├── ApiDataAttrsTable.astro # Data attributes table
@@ -144,16 +203,32 @@ site/src/

 ## Adding a New Component

+### Single-Part Component
+
 1. Create the component in `packages/core/src/core/ui/{name}/`
 2. Export `{Name}Props` interface and `{Name}State` interface
 3. Optionally create `{name}-data-attrs.ts` with data attribute definitions
 4. Create the HTML element in `packages/html/src/ui/{name}/` with `static tagName`
 5. Run `pnpm api-docs` to generate JSON
-6. Use `<ApiRefSection component="{Name}" section="{section}" />` in MDX as described above
+6. Use `<ApiReference component="{Name}" />` in MDX

-## Differences from base-ui
+### Multi-Part Component

-This implementation is adapted from MUI base-ui's api-docs-builder with key differences:
+1. Follow the single-part steps above for the primary part's core/data-attrs/element files
+2. Create `packages/react/src/ui/{name}/index.parts.ts` exporting each part
+3. Add JSDoc descriptions to each React component export for part descriptions
+4. Create HTML element files for each non-primary part at `packages/html/src/ui/{name}/{name}-{part}-element.ts`
+5. Run `pnpm api-docs` to generate JSON
+6. Use `<ApiReference component="{Name}" />` in MDX
+
+## Acknowledgements
+
+This builder's architecture and approach were inspired by [Base UI](https://github.com/mui/base-ui)'s
+`api-docs-builder`, maintained by MUI. Base UI is licensed under the
+[MIT License](https://github.com/mui/base-ui/blob/master/LICENSE) (Copyright 2019 Material-UI SAS).
+Thank you to the MUI team for the excellent reference implementation.
+
+### Key differences from Base UI's builder

 1. **Multi-platform**: One JSON per component containing all platform variants (React/HTML)
 2. **Core-first**: Props come from core package, not platform-specific components