Skip to content

docs(examples): replace static snippets with live previews - #733

Merged
IzumiSy merged 15 commits into
mainfrom
docs/migrate-static-examples
Nov 18, 2026
Merged

IzumiSy merged 15 commits into
mainfrom
docs/migrate-static-examples

Conversation

@IzumiSy

@IzumiSy IzumiSy commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Motivation

This PR addresses three documentation problems:

  • Examples are difficult to evaluate. Many pages render only their basic example and leave variants or compositions as static snippets. Readers must assemble those fragments themselves, and the snippets are outside the examples' TypeScript check. Useful demonstrations should show real interactions without production credentials or backend services.
  • Navigation is unnecessarily noisy. Readers need to browse different documentation categories without losing the open page or resetting its previews. Collapsible category groups and breadcrumbs add friction to an otherwise shallow document hierarchy.
  • Preview structure is hard to distinguish. The browser needs a neutral canvas for comparing components, while dense examples such as Timeline need their own visible boundaries, guides, and row hierarchy—not just colored content.

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.tsx files, 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:

  • Inputs and Tree: simulate loading, retry, and delayed results with cancellable fixtures and lifecycle cleanup. Tree's asynchronous catalogue loads the complete hierarchy, not individual branches.
  • AIChat: exercise the real useAIChat() hook with a stable in-memory AIGatewayClient that streams predefined chunks and honors cancellation. Previews do not call a production Gateway or execute tools; a separate static integration example connects the hook's toolCalls to the conversation.
  • Attachment: keep selected files in browser memory and demonstrate buffered operations through callbacks. Save and Download do not upload, persist, or download files, and picker hints are not file validation.
  • Host state: guard previews use local permissions rather than changing authentication or context data; static context-based guards demonstrate route/UI reuse. The URL-binding example uses local URLSearchParams, not the browser's URL. FilterRail layout preferences use their own namespaced storage key.

Navigation: change sidebar selection, not document routing

Use GlobalHeaderLayout to exercise the existing layout API. Its header selects one of three sidebar views: Guide and Concepts, Components and APIs, or Patterns 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.

スクリーンショット 2026-11-17 22 25 17

As an example that inspired this PR, mantine-ui also has high-level category switcher in the tab.

スクリーンショット 2026-11-18 11 07 55

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

  • Authored documentation (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.
  • Generated documentation (docs/ and docs-manifest.json): regenerate rendered examples, references, and hashes through docs:sync, which also refreshes the packaged consumer documentation.
  • Documentation browser (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.
  • Release metadata (.changeset/): provide one patch changeset for the documentation improvements. Package runtime APIs and dependencies remain unchanged.

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Code Metrics Report

main (c90cdf6) #733 (7f92d05) +/-
Coverage 62.9% 62.9% 0.0%
Test Execution Time 3m33s 3m11s -22s
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%)

Files Coverage +/- Patch Coverage Status
docs-browser/package.json 100.0% 0.0% 100.0% modified

Reported by octocov

@IzumiSy
IzumiSy force-pushed the docs/migrate-static-examples branch from b4be46a to e0f5d55 Compare November 17, 2026 13:03

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 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

@IzumiSy
IzumiSy marked this pull request as ready for review November 18, 2026 02:02
@IzumiSy
IzumiSy requested a review from a team as a code owner November 18, 2026 02:02

@interacsean interacsean left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

  1. 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.tsx files. Now they render only the function body, with no import { Text } and no export 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.
  2. 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 Text to the Import line. That contradicts the page's own statement that the module has no React dependency.
    • Fix: restore the annotated static snippets.
  3. 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().toolCalls with AIChat.ToolCall inside AIChat.Conversation. The example renders a hard-coded array inside a bare AIChat.Message, with no hook and no Conversation.
    • Nothing on the page now connects toolCalls to useAIChat.
    • Fix: render the fixture inside AIChat > AIChat.Conversation, and add a short static const { toolCalls } = useAIChat(...) snippet.
  4. 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, became parseDate("2025-12-01"). The Import block still lists today, but no example uses it.
    • This is borderline. Fix: go back to today(getLocalTimeZone()).
  5. 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.featureFlags and context.currentUser.subscription guards. 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 Guard type.
    • 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.

@IzumiSy

IzumiSy commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

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:

  1. Quickstart / file-based routing: restored all three static, complete page.tsx snippets, including the required imports and default exports. Removed their redundant preview modules.
  2. Aggregations: restored static calls with expected-result comments and removed the React/Text preview wrapper.
  3. AIChat: placed the fixture inside AIChat > AIChat.Conversation and added a typed application example that reads toolCalls from useAIChat() and renders them after the message history. The runnable fixture still executes no tools.
  4. WithGuard: added context-based guards beside Feature Flags and Subscription Tiers, so those guards can be reused for both routes and UI.

Major 4 is handled separately in #739, targeting main. The final approach corrects the documentation to use the existing useTimeZone() API and minValue={timeZone.today()}, so the constraint follows AppShell's configured timezone rather than the browser's timezone. It also aligns the migration/current-date guidance and uses a browser-timezone-independent weekend predicate. No standalone today export, runtime implementation change, or new dependency is added.

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.

@IzumiSy
IzumiSy requested a review from interacsean November 18, 2026 04:46
@IzumiSy

IzumiSy commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

@copilot resolve the merge conflicts in this pull request

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Copilot AI commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

@copilot resolve the merge conflicts in this pull request

Resolved the conflicts with main, regenerated the documentation and manifest, and published merge commit 5a701f9e.

@IzumiSy
IzumiSy merged commit 923933d into main Nov 18, 2026
6 checks passed
@IzumiSy
IzumiSy deleted the docs/migrate-static-examples branch November 18, 2026 06:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants