Skip to content

Load documentation by page and examples near the viewport - #59

Open
Floating-Y wants to merge 2 commits into
deeplethe:devfrom
Floating-Y:fix/route-loading-boundaries
Open

Floating-Y wants to merge 2 commits into
deeplethe:devfrom
Floating-Y:fix/route-loading-boundaries

Conversation

@Floating-Y

@Floating-Y Floating-Y commented Oct 18, 2026 •

Copy link
Copy Markdown
Contributor

Why

The shared entry loaded home-page charts and every document body on unrelated routes. Standalone Block previews also imported the listing's Code panel and highlighter. Within a document, every ComponentPreview still mounted its example and requested its raw source immediately, including previews far below the viewport and unused source for hideCode previews.

What changes

  • Lazy-load Home and the document renderer; separate the metadata-only catalog, layout and component directory from document bodies.
  • Generate one JSON body per section/slug, load only the selected body with import.meta.glob, clean deleted pages, and assert catalog/body consistency. Preserve loading layout, errors, fast-navigation isolation, anchors and history.
  • Move BlockView into its own entry while preserving theme, image fallback and Toaster behavior.
  • Normalize Windows document input and invoke the installed registry CLI through Node. Registry contents and dependencies remain unchanged.
  • Activate document previews once they enter a 300px viewport margin, reusing React.lazy, import.meta.glob and the existing cache. Keep activated examples mounted so inputs, selections and expanded code survive scrolling.
  • Load ordinary preview source on activation and never request raw source for hideCode previews. Preserve three-line summaries, View Code, full code, copying and installation ComponentSource loading.
  • Reserve loading space while retaining custom/responsive heights. Clean up observers under StrictMode, load immediately without IntersectionObserver, and surface failures through the existing document error boundary. Guard the table-of-contents observer for the same fallback.
  • Add a dependency-free browser behavior check. Keep /dev/examples on its independent full-mount path.

How it was checked

Based on dev b328113; retains upstream fragment-link and malformed-escape fixes.

Current preview implementation:

  • npm run docs, npm run typecheck, npm run build and git diff --check passed. The generated registry has no committed changes.
  • node --test scripts/block-metadata.test.mjs: 8 passed.
  • /scripts/check-component-preview.html, served by npm run dev: 11 behavior assertions passed, covering first activation, non-intersecting callbacks, retained input/DOM/code state, hideCode source suppression, StrictMode cleanup and fallback without IntersectionObserver.
  • /dev/examples: 389/389 mounted, 0 failed.
  • Button, Input, Chart and Calendar checked in light/dark themes, desktop and 390px layouts: expanded code, copying, scroll-away/return, directory links, direct hash URLs and browser back/forward. Input values, Chart selection and Calendar selection remained after scrolling. Custom heights, including Input's 32rem and Calendar's 560px preview, were retained.
  • Installation Manual source loading checked. Both example and raw-source requests were deliberately made to return 500: the document showed a visible error instead of loading indefinitely. Disabling IntersectionObserver still loaded the Button document immediately.
  • Actual development request records: Button's first view requested only button-demo JS and raw source among its 14 previews. button-size made no own JS/raw requests at approximately 350px below the viewport; both appeared at approximately 250px. Chart's chart-demo and chart-tooltip requested JS and no raw source. Direct hash navigation loaded previews near the target. Shared dependencies may already be requested by other visible examples.

Earlier route-split validation, recorded for a264b58:

  • npm ci; 76-document catalog/body consistency, repeated generation and add/delete checks.
  • /dev/examples: 389/389 mounted, 0 failed in both themes.
  • Headless Chrome at 1440x1000, dark/light, with both / and /solid-glass/: search, navigation, invalid URLs, delayed loading, rapid navigation, failed-body recovery, preview and image fallback.
  • Production responses mapped to Vite chunk.modules: Home loaded no document bodies/Markdown; installation loaded only its body and no Recharts; the component directory loaded no bodies; login-03 loaded no bodies, Markdown, Recharts, Code panel or highlighter. Development-only example data was absent from production. The prior response-byte measurements were not repeated after the preview change.

Other browsers and physical devices were not tested. Auto-height placeholders remain estimates (Chart measured 404px before loading and about 431px afterward at a 506px viewport). Existing nativeButton and value/defaultValue development warnings remain outside this change. No speedup percentage is claimed.

Before review

  • Every commit is signed off (DCO)
  • npm run typecheck and npm run build pass
  • /dev/examples reports 0 failed
  • Affected pages checked in both themes, including open code
  • No material, registry, dependency or URL changes

@Floating-Y Floating-Y changed the title Load documentation and previews only on their own routes Load documentation by page and examples near the viewport Oct 18, 2026

This branch has not been deployed

No deployments
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.

1 participant