docs(atoms): JARL407 — per-atom documentation, split primitives, and two demos - #114
Draft
randomdevpete wants to merge 10 commits into
Draft
docs(atoms): JARL407 — per-atom documentation, split primitives, and two demos#114randomdevpete wants to merge 10 commits into
randomdevpete wants to merge 10 commits into
Conversation
Splits the routeAtom.ts grab-bag into locationAtom.ts, routeAtom.ts, rootAtom.ts, staticRouteAtom.ts, paramRouteAtom.ts and transformRouteAtom.ts, with shared types moved to types.ts. Public API from the package root is unchanged. Also untracks src/notAtom.d.ts, a stale generated declaration file checked in before packages/*/src/**/*.d.ts was added to .gitignore; its presence broke the dts build once RouteAtom moved out of routeAtom.ts.
The original routeAtom.ts exported Path; it should be re-exported from routeAtom.ts after splitting to maintain the public API unchanged. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Binds a segment to a number instead of a string, with min/max options that reject out-of-range values (no match). Composed from paramRouteAtom + transformRouteAtom, the existing idiom for constrained segments, rather than a new base primitive.
A classic /blog/:year/:month/:day/:slug tree over a seeded set of faker-generated mock posts, hand-composed from numericRouteAtom chained as parent/child rather than a dedicated date primitive. Each level validates its own range, plus (once matched) that the date is real and posts exist there, falling back to a not-found view - and to the Switch's own fallback when no level's URL shape matches at all.
Remove structural details visible in code; highlight the non-obvious two-layer 404 pattern (URL-shape via Switch, content-level via validation). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A route whose existence only a database can answer: the lookup runs against the parent route's matched values, `undefined` back means no match (so a Switch fallback or notAtom renders the not-found case), and a hit matches with the loaded object typed onto the route's own values - one call answering both "does this exist" and "what is it". Matching stays synchronous, so the lookup settles into the store first: preloadRoutes awaits it (the step a server render needs before it can produce HTML and a status code) and returns snapshots, hydrateAsyncRoutes seeds those into a client store without repeating the lookup, and followAsyncRoutes keeps them settled across client navigation. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A demo at /demos/async-lookup backed by a fake Promise-based database: a known slug renders the article the route match already loaded, an unknown one renders the demo's not-found view. The server render now awaits preloadRoutes before rendering and reports a status alongside the HTML, from a notFoundAtom listing every route the site has content for. The prerender and dev servers pass that status through, and the build fails if a path in staticPaths renders a 404 (or if 404.html doesn't). Preloaded data is embedded for the client entry to hydrate from, so a page load looks nothing up twice. DemoBox/SourceDisclosure, duplicated in both existing demo pages, move into lib/DemoPage. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The synchronous-matching rationale already lives in asyncRouteAtom's own docblock; the file-level preamble restated it as a whole-file essay.
…review isRedirect had no doc comment, RouteProps/SwitchProps lacked top-level descriptions, and several exports (staticRouteAtom, useNavigate, createRootAtom, transformRouteAtom, followResolvedRedirects, UseLinkOptions, LinkChildrenRenderProps, ExtractRouteParams, RouteOptions, RootOptions, Store) had prose too thin to be useful on the generated API reference page. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…indings Adds four guide pages distinct from the mechanical API reference: Custom Route Atoms (routeAtom, transformRouteAtom, numericRouteAtom), Switch & Not Found (Switch's first-match/fallback, notAtom's use as a status-code source), Location & Base Paths (locationAtom, createRootAtom scoping, the href utilities), and Hooks & Links (useRoute/useNavigate/ useIsActive/useHref/useLink, Link's render-prop form). Registered in docPages, grouped into Atoms/Components sections on the docs index alongside the existing Guides section. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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
1 participant
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.
Per-atom documentation pages for each route atom primitive, plus the demos and
API-comment work that came with them.
Implementation:
routeAtom.tsis split into one file per primitive;numericRouteAtomand
asyncRouteAtomare added; thin doc comments flagged by the API reference review areexpanded; a blog routing demo and an async-lookup demo land alongside, the latter
returning a real 404 status from SSR.
masterandneeds a rebase before it is reviewable. Raising it now so the work is visible rather
than sitting on an unlisted branch.