UI Library docs: page-per-component + source-generated tables (3/3) - #46
Open
librowski wants to merge 16 commits into
Open
UI Library docs: page-per-component + source-generated tables (3/3)#46librowski wants to merge 16 commits into
librowski wants to merge 16 commits into
Conversation
This was referenced Jun 24, 2026
librowski
marked this pull request as ready for review
June 24, 2026 12:31
librowski
requested review from
lukasz-jazwa,
piotrblaszczyk and
szymon-t-sc
as code owners
June 24, 2026 12:31
librowski
force-pushed
the
ui-consumers
branch
2 times, most recently
from
July 31, 2026 08:41
7970aa1 to
6192878
Compare
…tyle props/CSS tables Wrap every UI Library example in a shadow-DOM ComponentPreview so components are styled only by @workflowbuilder/ui (isolated from Starlight CSS), shown in a fixed 2:1 dotted preview box that matches the original Overflow UI docs. Collapse each example island to a single representative instance. Rework the generated Props and CSS-variable references from tables into card lists: props show a 'required' chip (required-first) instead of a line-wrapping '?' marker, with Type/Default/description rows; CSS variables group into Color/Size. Drop the now-unused example-frame styles.
Give the Edge, NodeIcon, NodeDescription and NodePanel pages the same shadow-DOM ComponentPreview the UI components use, rendering each as a standalone example (NodePanel compositions; EdgeLabel variants positioned relatively outside a canvas) for parity with the original Overflow UI docs. NodeAsPortWrapper stays props-only, matching the reference. Adds @phosphor-icons/react to the docs app for the example icons.
Status is an absolutely-positioned corner badge; rendered standalone it had no positioned ancestor and floated to the wrong place. Wrap it in a relative box that stands in for the node/field it marks, so it sits in the top-right corner as intended.
The UI Library overview told consumers to install @base-ui/react alongside the package. It is now a regular dependency that installs automatically; react and react-dom are the only peers.
@workflowbuilder/ui components and generate-ui-api.mjs's TypeDoc pass both need packages/ui/dist to exist; add a Build UI step ahead of Build docs, mirroring the existing Build SDK step.
- Fix the generator's lint errors (renamed vars for clarity, imported node:process, top-level await with process.exitCode instead of process.exit/main().catch, matching tools/preflight.mjs's pattern). - Strip internal engineering notes (matching /missing token/i) out of CSS variable comments instead of rendering them on the public docs pages. - Treat an unresolved props type as fatal (process.exitCode = 1) instead of a warning, so a renamed/typo'd type can't silently ship an empty page. - Add collectVariantProps() to merge Button's discriminated-union variant props (Label/Icon/IconLabel) into one deduped table with per-variant notes, and switch the TypeDoc entry point from index.ts (resolve) to src/components (expand) so those variant-only prop types get full reflections. - Add a check-ui-component-coverage.mjs guard, wired into generate:ui-api, asserting every packages/ui/vite.config.mts componentEntries item has a matching COMPONENTS entry, so a new published component can't ship without a docs page. - Run generate:ui-api before astro check in typecheck, so the coverage guard and generator failures surface there too. The unrelated PropRow/CssVar -> PropertyRow/CssVariable renames in props-table.astro / css-variables-table.astro are a lint-driven cleanup in the same generator/docs-api area.
- Add a Collapsible page: intro, live example, Usage, a hand-authored Parts table for Collapsible.Button/Collapsible.Content (no exported prop type to key a generated table on, same precedent as NodePanel), and generated Props/CSS variables tables. List it in the components index. - Add an Icon switch section to the Switch page documenting IconSwitch (live example, Usage, generated Props/CSS variables tables). - Rewrite the overview's Styles section: importing from the package root auto-injects the layer order/reset/tokens setup, so only tokens.css is needed; the styles.css + tokens.css pair only applies to the per-component subpath-import path. Matches packages/ui/README.md and packages/ui/css-layers.md. Depends on the collapsible/icon-switch COMPONENTS entries and the Button-variant TypeDoc entry point switch landed in the generator commit.
The runtime default (shape = 'default' in the forwardRef destructure) was documented as @default '' in the TSDoc comment, which the UI Library docs render verbatim.
Resolves vite-plugin-dts, vite-plugin-svgr, and i18next/react-i18next to a single typescript@5.9.3 peer resolution instead of a stale mixed 5.6.3/5.9.3 set, matching --frozen-lockfile.
Helper types like WithIcon live in src/shared, outside the components entry tree, so they got no reflection and their members (Accordion's and Modal's icon prop) silently vanished from the generated tables.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part 3 of 3. Stacked on #45 (base branch
librowski/ui-consumers) - review/merge #44 then #45 first. This PR's diff is only the documentation work.Summary
Builds the UI Library documentation in
apps/docs(Starlight): a page-per-component reference (twin to the old Overflow UI docs) with live interactive examples, props and CSS-variable tables generated from source (no hand-maintained tables), and a Design Tokens pipeline page.Changes
Docs site
@astrojs/react);@workflowbuilder/uistyles loaded via StarlightcustomCss(safe - no global reset; tokens follow the Starlight light/dark theme).@workflowbuilder/uion Base UI.Source-generated API tables
apps/docs/scripts/generate-ui-api.mjsruns TypeDoc over the@workflowbuilder/uibarrel to extract per-component props (type / required / default / description), and extracts--ax-public-*CSS variables from the stylesheets, into a git-ignoredui-api.json. Rendered inline viaPropsTable/CssVariablesTableAstro components. Wired into docsdev/build.@workflowbuilder/uibarrel, with@defaultJSDoc tags. This is the onlypackages/uichange in this PR and is additive.Design tokens
tokens.json(Figma) → Style Dictionary →--ax-*CSS pipeline, theming, customization, regeneration, and the known "missing token" gaps.Verification
build:docsgreen (177 pages); docstypecheckhas no errors in the new files (only the 4 pre-existinghead.astro/sidebar.astroerrors).Notes
overflow-card.astro) is intentionally left as-is (advertises the commercial product, not the vendored library).Update (2026-07-31): review fixes + rebase
Rebased onto the fixed #45; review fixes landed on this branch.
deploy-docs.ymlnow builds@workflowbuilder/uibefore the docs build - previously the production docs deploy would fail to resolve thecustomCss/ island imports (packages/ui/distnever existed on the runner).generate-ui-api.mjs): unresolvedpropsTypeis now a fatal error instead of a silent empty table; discriminated-union props are merged (Button'sisLoading/shape/ variantchildrennow appear in the table); internal/* missing token */engineering notes no longer leak into public CSS-variable tables; new coverage guard asserts everycomponentEntriesentry has aCOMPONENTSentry;typecheckruns generation first (fixed the fresh-checkout failure); 33 ESLint errors in the new files fixed.overview.mdxis aligned withpackages/ui/README.md(root barrel import needs onlytokens.css); SegmentPicker's@defaultforshapecorrected to'default'.Known follow-up (out of scope here): the shared
WithIconiconprop still doesn't reach the generated tables of accordion / icon-switch / modal / select / snackbar.Verification (fresh):
build:docsgreen (208 pages), docs lint + typecheck green (known pre-existinghead.astro/sidebar.astroastro-check errors excluded);pnpm install --frozen-lockfileverified on this tip. pr-check runs only for PRs targetingmain, so checks appear once the stack merges bottom-up.