Repository navigation
docs(examples): replace static snippets with live previews - #733
Conversation
Code Metrics Report
Details | | main (c90cdf6) | #733 (7f92d05) | +/- |
|---------------------|----------------|----------------|------|
| Coverage | 62.9% | 62.9% | 0.0% |
| Files | 294 | 294 | 0 |
| Lines | 13483 | 13483 | 0 |
| Covered | 8485 | 8485 | 0 |
+ | Test Execution Time | 3m33s | 3m11s | -22s |Code coverage of files in pull request scope (100.0% → 100.0%, patch 100.0%)
Reported by octocov |
b4be46a to
e0f5d55
Compare
There was a problem hiding this comment.
🟢 Approval recommended
The review reports no active issues with the documentation-preview changes.
No open issues 🎉
What changed in this PR
This PR makes AppShell documentation more practical by replacing static UI snippets with runnable previews through the existing documentation pipeline. It also adds documentation-browser section mapping and a neutral preview theme, without changing package runtime APIs.
Changes:
- Add self-contained React examples with local interactions, validation, loading states, and visible results.
- Connect authored outlines to live previews and update generated documentation while preserving import and routing guidance.
- Add sidebar-section mapping tests, neutral browser styling, and patch changesets.
| File | Description |
|---|---|
docs/quickstart.md |
Generated home and dashboard previews. |
docs/concepts/testing.md |
Generated accessible field example. |
docs/concepts/file-based-routing.md |
Generated minimal page preview. |
docs/concepts/custom-components.md |
Generated step-indicator preview. |
docs/components/toolbar.md |
Generated toolbar composition previews. |
docs/components/textarea.md |
Generated textarea variant previews. |
docs/components/text.md |
Generated typography and labeling previews. |
docs/components/tabs.md |
Generated disabled and icon-tab previews. |
docs/components/spinner.md |
Generated loading indicator previews. |
docs/components/metric-card.md |
Generated trend and icon previews. |
docs/components/input.md |
Generated input variant previews. |
docs/components/dialog.md |
Generated deletion and form workflows. |
docs/components/csv-importer.md |
Generated import-summary preview. |
docs/components/checkbox.md |
Generated controlled and select-all previews. |
docs/components/card.md |
Generated card composition previews. |
docs/components/button.md |
Generated button and link previews. |
docs/components/avatar.md |
Generated avatar size previews. |
docs/components/attachment.md |
Generated browser-memory attachment workflow. |
docs/components/action-panel.md |
Generated loading-action preview. |
docs/api/use-toast.md |
Generated notification previews. |
docs/api/use-time-zone.md |
Generated timezone value previews. |
docs/api/use-theme.md |
Generated theme-aware previews. |
docs/api/use-resolved-locale.md |
Generated locale-formatting previews. |
docs/api/use-app-shell.md |
Generated configured-locale preview. |
docs/api/use-app-shell-config.md |
Generated configuration and module previews. |
docs/api/router/use-location.md |
Generated current-path preview. |
docs-src/hooks/use-toast.docs.outline.md |
Connects toast previews and usage guidance. |
docs-src/hooks/use-toast.docs.examples.tsx |
Adds notification and duration examples. |
docs-src/hooks/use-time-zone.docs.outline.md |
Connects timezone previews. |
docs-src/hooks/use-time-zone.docs.examples.tsx |
Displays date, timestamp, and timezone. |
docs-src/hooks/use-theme.docs.outline.md |
Connects theme previews and import guidance. |
docs-src/hooks/use-theme.docs.examples.tsx |
Displays theme state and themed icons. |
docs-src/hooks/use-resolved-locale.docs.outline.md |
Connects fixed-value formatting previews. |
docs-src/hooks/use-resolved-locale.docs.examples.tsx |
Adds localized date and currency displays. |
docs-src/hooks/use-app-shell.docs.outline.md |
Connects configured-locale preview. |
docs-src/hooks/use-app-shell.docs.examples.tsx |
Displays the host’s configured locale. |
docs-src/hooks/use-app-shell-config.docs.outline.md |
Connects configuration previews. |
docs-src/hooks/use-app-shell-config.docs.examples.tsx |
Displays application configuration and modules. |
docs-src/hooks/router/use-location.docs.outline.md |
Connects non-navigating route preview. |
docs-src/hooks/router/use-location.docs.examples.tsx |
Displays the current pathname. |
docs-src/hooks/aggregations.docs.outline.md |
Connects aggregation result previews. |
docs-src/hooks/aggregations.docs.examples.tsx |
Demonstrates aggregation, transformation, and validation. |
docs-src/guides/quickstart.docs.outline.md |
Connects previews while preserving setup guidance. |
docs-src/guides/quickstart.docs.examples.tsx |
Adds home and dashboard examples. |
docs-src/concepts/testing.docs.outline.md |
Connects accessible field preview. |
docs-src/concepts/testing.docs.examples.tsx |
Adds a labeled email control. |
docs-src/concepts/styling-theming.docs.outline.md |
Connects styling-token previews. |
docs-src/concepts/styling-theming.docs.examples.tsx |
Demonstrates typography, color, motion, and layering. |
docs-src/concepts/file-based-routing.docs.outline.md |
Preserves default-export guidance alongside preview. |
docs-src/concepts/file-based-routing.docs.examples.tsx |
Adds a minimal About page. |
docs-src/concepts/custom-components.docs.outline.md |
Connects custom-component preview. |
docs-src/concepts/custom-components.docs.examples.tsx |
Adds an accessible step indicator. |
docs-src/components/with-guard.docs.examples.tsx |
Adds local role and permission examples. |
docs-src/components/tooltip.docs.outline.md |
Connects previews and corrects timeout documentation. |
docs-src/components/tooltip.docs.examples.tsx |
Adds placement, delay, and controlled examples. |
docs-src/components/toolbar.docs.outline.md |
Connects toolbar composition previews. |
docs-src/components/toolbar.docs.examples.tsx |
Adds grouped and aligned toolbar examples. |
docs-src/components/timeline.docs.outline.md |
Connects scrolling, dependency, and decoration previews. |
docs-src/components/textarea.docs.outline.md |
Connects textarea variant previews. |
docs-src/components/textarea.docs.examples.tsx |
Adds height, disabled, and field examples. |
docs-src/components/text.docs.outline.md |
Connects previews and removes duplicate snippets. |
docs-src/components/text.docs.examples.tsx |
Adds typography, label, and table examples. |
docs-src/components/tabs.docs.outline.md |
Connects disabled and icon-tab previews. |
docs-src/components/tabs.docs.examples.tsx |
Adds disabled and accessible icon tabs. |
docs-src/components/table.docs.outline.md |
Connects table structure and alignment previews. |
docs-src/components/table.docs.examples.tsx |
Adds footer, caption, and alignment examples. |
docs-src/components/spinner.docs.outline.md |
Connects loading indicator previews. |
docs-src/components/spinner.docs.examples.tsx |
Adds accessible, decorative, and sizing examples. |
docs-src/components/sheet.docs.outline.md |
Connects sheet composition previews. |
docs-src/components/sheet.docs.examples.tsx |
Adds sizes, sides, and panel examples. |
docs-src/components/select.docs.outline.md |
Connects previews and explains mock loading. |
docs-src/components/select.docs.examples.tsx |
Adds grouped, multiple, async, and field examples. |
docs-src/components/metric-card.docs.outline.md |
Connects trend and icon previews. |
docs-src/components/metric-card.docs.examples.tsx |
Adds trend directions and icon examples. |
docs-src/components/menu.docs.outline.md |
Connects previews and clarifies row actions. |
docs-src/components/menu.docs.examples.tsx |
Adds stateful formatting and action menus. |
docs-src/components/layout.docs.outline.md |
Connects layout composition previews. |
docs-src/components/layout.docs.examples.tsx |
Adds columns, headers, spacing, and styling. |
docs-src/components/input.docs.outline.md |
Connects input variant previews. |
docs-src/components/input.docs.examples.tsx |
Adds labeled input variants. |
docs-src/components/grid.docs.outline.md |
Connects responsive grid previews. |
docs-src/components/grid.docs.examples.tsx |
Adds sizing, spanning, and alignment examples. |
docs-src/components/document-progress-card.docs.outline.md |
Connects legend and fulfilment previews. |
docs-src/components/document-progress-card.docs.examples.tsx |
Demonstrates legends and return-accounting options. |
docs-src/components/dialog.docs.outline.md |
Documents local deletion and validated editing. |
docs-src/components/dialog.docs.examples.tsx |
Adds repeatable deletion and form workflows. |
docs-src/components/description-card.docs.outline.md |
Connects detailed record previews. |
docs-src/components/description-card.docs.examples.tsx |
Adds badges, nested data, and order details. |
docs-src/components/csv-importer.docs.outline.md |
Connects CSV import preview. |
docs-src/components/csv-importer.docs.examples.tsx |
Displays local CSV import summaries. |
docs-src/components/combobox.docs.outline.md |
Connects previews and explains async fixtures. |
docs-src/components/combobox.docs.examples.tsx |
Adds grouped, creatable, and async examples. |
docs-src/components/checkbox.docs.outline.md |
Documents controlled and select-all interactions. |
docs-src/components/checkbox.docs.examples.tsx |
Adds stateful checkbox and field examples. |
docs-src/components/card.docs.outline.md |
Connects card composition previews. |
docs-src/components/card.docs.examples.tsx |
Adds header, content, and table compositions. |
docs-src/components/button.docs.outline.md |
Connects button variant and composition previews. |
docs-src/components/button.docs.examples.tsx |
Adds links, actions, and labeled icons. |
docs-src/components/badge.docs.outline.md |
Connects badge variant and styling previews. |
docs-src/components/badge.docs.examples.tsx |
Adds status, icon, and dynamic variants. |
docs-src/components/avatar.docs.outline.md |
Connects avatar size preview. |
docs-src/components/avatar.docs.examples.tsx |
Demonstrates all avatar sizes. |
docs-src/components/autocomplete.docs.outline.md |
Connects search, validation, and retry previews. |
docs-src/components/attachment.docs.outline.md |
Explains local operations and validation limits. |
docs-src/components/attachment.docs.examples.tsx |
Adds in-memory attachment operation feedback. |
docs-src/components/alert.docs.outline.md |
Connects previews and removes selected static sections. |
docs-src/components/alert.docs.examples.tsx |
Adds dismissal, replay, and local actions. |
docs-src/components/activity-card.docs.outline.md |
Connects overflow, grouping, and composition previews. |
docs-src/components/activity-card.docs.examples.tsx |
Adds history fixtures and relative-date grouping. |
docs-src/components/action-panel.docs.outline.md |
Documents simulated loading and timer cleanup. |
docs-src/components/action-panel.docs.examples.tsx |
Adds repeatable loading-action feedback. |
docs-browser/tests/sections.test.mjs |
Tests category partitioning and route mapping. |
docs-browser/src/theme.css |
Defines neutral light and dark backgrounds. |
docs-browser/src/sections.ts |
Maps document paths to three sections. |
docs-browser/src/index.css |
Replaces Bloom with the local theme. |
docs-browser/package.json |
Adds the Node test-runner script. |
.changeset/working-component-guides.md |
Records interactive component documentation updates. |
.changeset/tidy-forms-work.md |
Records runnable Form documentation updates. |
.changeset/tidy-examples-preview.md |
Records static-to-live example conversion. |
.changeset/simple-tables-work.md |
Records runnable DataTable documentation updates. |
Review effort: Balanced
There was a problem hiding this comment.
Claude review copy/paste:
Major
All five have the same cause. A static snippet became a runnable example, and the code people and agents copy got worse. The generated markdown ships to consumers in the packaged app-shell-patterns skill, so these reach real apps.
-
The quickstart and file-based routing page blocks no longer work when copied.
- Where: quickstart.docs.outline.md:74, :101, file-based-routing.docs.outline.md:107.
- On main these blocks were full
page.tsxfiles. Now they render only the function body, with noimport { Text }and noexport default. Both survive only as a prose instruction. - Pasted as-is, the page doesn't compile, and the Vite plugin can't find it without a default export. That breaks the PR's promise to keep the default-export convention.
- A preview of one
<h1>adds nothing. Fix: keep these three as static full-file snippets.
-
The aggregations page lost its documented results.
- Where: aggregations.docs.outline.md:14.
- The old snippets annotated each call with its result (
// "3 units",// { total: 3, valid: true },// "Mixed currencies: JPY, USD"). Those results now appear only in the browser preview, not in the generated markdown. - Wrapping the calls in JSX also adds
Textto the Import line. That contradicts the page's own statement that the module has no React dependency. - Fix: restore the annotated static snippets.
-
The AIChat tool-calls example no longer shows how to use the hook.
- Where: ai-chat.docs.examples.tsx:226.
- The prose says to render
useAIChat().toolCallswithAIChat.ToolCallinsideAIChat.Conversation. The example renders a hard-coded array inside a bareAIChat.Message, with no hook and noConversation. - Nothing on the page now connects
toolCallstouseAIChat. - Fix: render the fixture inside
AIChat>AIChat.Conversation, and add a short staticconst { toolCalls } = useAIChat(...)snippet.
-
The DatePicker constraints example now hard-codes a fixed date.
- Where: date-picker.docs.examples.tsx:63.
minValue={today(getLocalTimeZone())}, the "no past dates" pattern, becameparseDate("2025-12-01"). The Import block still liststoday, but no example uses it.- This is borderline. Fix: go back to
today(getLocalTimeZone()).
-
No guard example reads from
{ context }any more. The PR body says this is deliberate, so I'm flagging it once.- Where: with-guard.docs.examples.tsx:14.
- The Feature Flags and Subscription Tiers sections used to show
context.featureFlagsandcontext.currentUser.subscriptionguards. They now point at guards that read React state through a closure. - Those can't be reused as route guards, even though the page stresses that both kinds share the
Guardtype. - Fix: add context-based one-liners next to those two sections.
Below the bar: the Alert page dropped two small examples (a form validation error and a success confirmation). description-card keeps a fixture outside its exported function, which predates this PR. Some examples link to paths that only exist in the docs browser.
|
Thanks for the review. Agreed that making a preview runnable must not make the copied documentation less useful. Addressed Major 1, 2, 3, and 5 in 3538ddde:
Major 4 is handled separately in #739, targeting Regenerated the documentation and consumer-skill references. The copied static examples were type-checked separately, and the aggregation results and context-guard outcomes were checked. Type checking, lint, documentation checks, and the regular test suite pass, including all 3,090 core tests. This follow-up is limited to the Major items; the below-the-bar observations are unchanged. |
|
@copilot resolve the merge conflicts in this pull request |
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Resolved the conflicts with |
Motivation
This PR addresses three documentation problems:
Design Decision
Authoring: keep one typed source of truth
Reuse the existing outline/example pipeline rather than adding a demo framework or dependencies. Keep runnable examples beside their outlines and reference them through the existing example tokens. Fixtures needed by an extracted example stay inside its exported function; duplicate snippets reuse an existing preview where possible.
Keep complete
page.tsxfiles, including imports and default exports, and aggregation calls with expected-result comments as static code so copied examples remain usable without a preview. Keep type definitions, negative examples, and integration configuration static when running them would not help explain their purpose.Execution: separate real local interactions from simulated services
Use public components and hooks with local fixtures and visible outcomes. Forms submit registered values; DataTable examples actually sort, filter, and paginate fixture rows. Query-editor playgrounds are explicitly limited to generating query state. Keep validation, adoption, confirmation, and persistence consumer-owned rather than adding library behavior.
The infrastructure and side-effect boundaries are explicit:
useAIChat()hook with a stable in-memoryAIGatewayClientthat streams predefined chunks and honors cancellation. Previews do not call a production Gateway or execute tools; a separate static integration example connects the hook'stoolCallsto the conversation.URLSearchParams, not the browser's URL. FilterRail layout preferences use their own namespaced storage key.Navigation: change sidebar selection, not document routing
Use
GlobalHeaderLayoutto exercise the existing layout API. Its header selects one of three sidebar views:Guide and Concepts,Components and APIs, orPatterns and Pages. Selecting a view does not navigate away from the open document.Keep all modules registered and document paths unchanged so direct links and global search remain available. Follow document navigation when choosing the active sidebar view without remounting the layout. Use static section headings and separators, move the home link into the responsive header, retain the appearance switcher, and omit breadcrumbs.
As an example that inspired this PR, mantine-ui also has high-level category switcher in the tab.
Presentation: keep theme changes local and preserve visual hierarchy
Replace Bloom with a browser-local theme based on the default palette. Override only the canvas backgrounds: white in light mode and the default background in dark mode.
Style Timeline through its examples rather than changing component defaults. Combine colorful bars with muted axis headers, translucent row striping, visible guides, and frame/row borders. Use theme tokens for structural styling and retain labels so meaning does not depend on color alone.
Summary
docs-src/): update 48 documents—37 component pages, eight API pages, and three concepts—and increase the repository total from 65 to 281 runnable previews. Preserve copyable static examples where execution adds no value.docs/anddocs-manifest.json): regenerate rendered examples, references, and hashes throughdocs:sync, which also refreshes the packaged consumer documentation.docs-browser/): introduce the global header, three sidebar views, static navigation groups, and neutral theme. Add section-mapping tests using Node's built-in runner..changeset/): provide one patch changeset for the documentation improvements. Package runtime APIs and dependencies remain unchanged.