shelving 1.320.0 → 1.322.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (171) hide show
  1. package/docs/guides/building-with-shelving.md +230 -1
  2. package/docs/llms-full.txt +1395 -351
  3. package/docs/ui/App.md +105 -7
  4. package/docs/ui/AppLayout.md +85 -0
  5. package/docs/ui/AppLayoutProps.md +21 -0
  6. package/docs/ui/BackButton.md +75 -0
  7. package/docs/ui/BackButtonProps.md +21 -0
  8. package/docs/ui/Catcher.md +1 -1
  9. package/docs/ui/ClickableProps.md +0 -2
  10. package/docs/ui/ErrorPage.md +2 -1
  11. package/docs/ui/FixedLayout.md +91 -0
  12. package/docs/ui/FixedLayoutProps.md +13 -0
  13. package/docs/ui/GapVariants.md +2 -2
  14. package/docs/ui/Head.md +2 -2
  15. package/docs/ui/HeightVariant.md +30 -0
  16. package/docs/ui/HeightVariants.md +26 -0
  17. package/docs/ui/HorizontalTransition.md +1 -1
  18. package/docs/ui/LinkClickable.md +0 -1
  19. package/docs/ui/Meta.md +3 -1
  20. package/docs/ui/Navigation.md +102 -37
  21. package/docs/ui/NavigationEntryState.md +22 -0
  22. package/docs/ui/NavigationPosition.md +24 -0
  23. package/docs/ui/NavigationPositionContext.md +8 -0
  24. package/docs/ui/NavigationProps.md +12 -2
  25. package/docs/ui/NavigationStore/back.md +6 -4
  26. package/docs/ui/NavigationStore/forward.md +6 -2
  27. package/docs/ui/NavigationStore/history.md +15 -0
  28. package/docs/ui/NavigationStore/listen.md +14 -0
  29. package/docs/ui/NavigationStore/replace.md +15 -0
  30. package/docs/ui/NavigationStore.md +100 -19
  31. package/docs/ui/PaddingVariants.md +2 -2
  32. package/docs/ui/Page.md +12 -8
  33. package/docs/ui/PageLoader.md +2 -1
  34. package/docs/ui/RouteCache.md +77 -36
  35. package/docs/ui/RouteCacheProps.md +3 -3
  36. package/docs/ui/Router.md +12 -6
  37. package/docs/ui/Scroll.md +60 -6
  38. package/docs/ui/ScrollVariants.md +5 -1
  39. package/docs/ui/SidebarLayout.md +17 -8
  40. package/docs/ui/SpaceValue.md +1 -0
  41. package/docs/ui/StackButton.md +64 -0
  42. package/docs/ui/StackButtonProps.md +21 -0
  43. package/docs/ui/TreeApp.md +1 -1
  44. package/docs/ui/VerticalTransition.md +1 -1
  45. package/docs/ui/getBlockClass.md +1 -1
  46. package/docs/ui/getGapClass.md +1 -1
  47. package/docs/ui/getHeightClass.md +64 -0
  48. package/docs/ui/getPaddingClass.md +1 -1
  49. package/docs/ui/getScrollClass.md +4 -2
  50. package/docs/ui/getSpaceClass.md +2 -0
  51. package/docs/ui/mergeMeta.md +2 -1
  52. package/docs/ui.md +25 -17
  53. package/package.json +1 -1
  54. package/ui/README.md +1 -1
  55. package/ui/app/App.md +105 -7
  56. package/ui/button/Clickable.d.ts +1 -3
  57. package/ui/button/Clickable.js +2 -2
  58. package/ui/button/Clickable.tsx +0 -4
  59. package/ui/docs/DocumentationApp.js +4 -1
  60. package/ui/docs/DocumentationApp.tsx +10 -1
  61. package/ui/layout/AppLayout.d.ts +21 -0
  62. package/ui/layout/AppLayout.js +18 -0
  63. package/ui/layout/AppLayout.md +57 -0
  64. package/ui/layout/AppLayout.module.css +106 -0
  65. package/ui/layout/AppLayout.tsx +36 -0
  66. package/ui/layout/FixedLayout.d.ts +18 -0
  67. package/ui/layout/FixedLayout.js +15 -0
  68. package/ui/layout/FixedLayout.md +65 -0
  69. package/ui/layout/FixedLayout.module.css +55 -0
  70. package/ui/layout/FixedLayout.tsx +25 -0
  71. package/ui/layout/SidebarLayout.d.ts +2 -2
  72. package/ui/layout/SidebarLayout.js +3 -4
  73. package/ui/layout/SidebarLayout.md +15 -6
  74. package/ui/layout/SidebarLayout.module.css +11 -16
  75. package/ui/layout/SidebarLayout.tsx +10 -13
  76. package/ui/layout/index.d.ts +2 -1
  77. package/ui/layout/index.js +2 -1
  78. package/ui/layout/index.tsx +2 -1
  79. package/ui/misc/Catcher.d.ts +2 -1
  80. package/ui/misc/Catcher.js +4 -3
  81. package/ui/misc/Catcher.md +1 -1
  82. package/ui/misc/Catcher.tsx +5 -4
  83. package/ui/misc/Loader.d.ts +1 -0
  84. package/ui/misc/Loader.js +6 -2
  85. package/ui/misc/Loader.tsx +11 -2
  86. package/ui/page/Head.d.ts +2 -2
  87. package/ui/page/Head.js +9 -8
  88. package/ui/page/Head.tsx +8 -6
  89. package/ui/page/Page.md +12 -8
  90. package/ui/router/BackButton.d.ts +22 -0
  91. package/ui/router/BackButton.js +19 -0
  92. package/ui/router/BackButton.md +47 -0
  93. package/ui/router/BackButton.tsx +34 -0
  94. package/ui/router/Navigation.d.ts +22 -12
  95. package/ui/router/Navigation.js +67 -51
  96. package/ui/router/Navigation.md +93 -27
  97. package/ui/router/Navigation.test.tsx +27 -7
  98. package/ui/router/Navigation.tsx +90 -53
  99. package/ui/router/NavigationContext.d.ts +9 -1
  100. package/ui/router/NavigationContext.js +9 -0
  101. package/ui/router/NavigationContext.tsx +11 -1
  102. package/ui/router/NavigationStore.d.ts +126 -19
  103. package/ui/router/NavigationStore.js +301 -30
  104. package/ui/router/NavigationStore.md +82 -9
  105. package/ui/router/NavigationStore.test.ts +384 -0
  106. package/ui/router/NavigationStore.tsx +347 -30
  107. package/ui/router/RouteCache.d.ts +16 -22
  108. package/ui/router/RouteCache.js +37 -47
  109. package/ui/router/RouteCache.md +63 -16
  110. package/ui/router/RouteCache.tsx +56 -62
  111. package/ui/router/Router.d.ts +2 -1
  112. package/ui/router/Router.js +9 -14
  113. package/ui/router/Router.md +10 -5
  114. package/ui/router/Router.tsx +9 -20
  115. package/ui/router/StackButton.d.ts +24 -0
  116. package/ui/router/StackButton.js +35 -0
  117. package/ui/router/StackButton.md +34 -0
  118. package/ui/router/StackButton.tsx +44 -0
  119. package/ui/router/index.d.ts +2 -2
  120. package/ui/router/index.js +2 -2
  121. package/ui/router/index.ts +2 -2
  122. package/ui/style/Block.d.ts +3 -2
  123. package/ui/style/Block.js +3 -2
  124. package/ui/style/Block.tsx +4 -2
  125. package/ui/style/Gap.d.ts +1 -1
  126. package/ui/style/Gap.tsx +1 -1
  127. package/ui/style/Height.d.ts +32 -0
  128. package/ui/style/Height.js +13 -0
  129. package/ui/style/Height.module.css +88 -0
  130. package/ui/style/Height.tsx +61 -0
  131. package/ui/style/Padding.d.ts +1 -1
  132. package/ui/style/Padding.tsx +1 -1
  133. package/ui/style/Scroll.d.ts +9 -5
  134. package/ui/style/Scroll.js +6 -4
  135. package/ui/style/Scroll.md +59 -0
  136. package/ui/style/Scroll.module.css +13 -1
  137. package/ui/style/Scroll.tsx +13 -5
  138. package/ui/style/Space.d.ts +1 -1
  139. package/ui/style/Space.module.css +12 -0
  140. package/ui/style/Space.tsx +1 -0
  141. package/ui/style/getHeightClass.md +30 -0
  142. package/ui/style/getSpaceClass.md +2 -0
  143. package/ui/style/index.d.ts +1 -0
  144. package/ui/style/index.js +1 -0
  145. package/ui/style/index.ts +1 -0
  146. package/ui/transition/HorizontalTransition.md +1 -1
  147. package/ui/transition/VerticalTransition.md +1 -1
  148. package/ui/tree/TreeApp.d.ts +1 -1
  149. package/ui/tree/TreeApp.js +5 -2
  150. package/ui/tree/TreeApp.tsx +11 -2
  151. package/ui/util/meta.d.ts +4 -1
  152. package/ui/util/meta.ts +4 -1
  153. package/docs/ui/CenteredLayout.md +0 -66
  154. package/docs/ui/CenteredLayoutProps.md +0 -14
  155. package/docs/ui/NavigationStore/redirect.md +0 -12
  156. package/docs/ui/RouteConfig.md +0 -75
  157. package/docs/ui/RouteConfigProps.md +0 -24
  158. package/docs/ui/RouteContext.md +0 -6
  159. package/docs/ui/RouteState.md +0 -30
  160. package/ui/layout/CenteredLayout.d.ts +0 -21
  161. package/ui/layout/CenteredLayout.js +0 -28
  162. package/ui/layout/CenteredLayout.md +0 -41
  163. package/ui/layout/CenteredLayout.module.css +0 -72
  164. package/ui/layout/CenteredLayout.tsx +0 -56
  165. package/ui/router/RouteConfig.d.ts +0 -28
  166. package/ui/router/RouteConfig.js +0 -30
  167. package/ui/router/RouteConfig.md +0 -42
  168. package/ui/router/RouteConfig.tsx +0 -44
  169. package/ui/router/RouteContext.d.ts +0 -22
  170. package/ui/router/RouteContext.js +0 -8
  171. package/ui/router/RouteContext.tsx +0 -26
@@ -320,7 +320,7 @@ Mirrors `shared/config/` folder-for-folder. Where `shared/config/<area>/` define
320
320
  - **`app/index.html`** — production HTML shell. References `./style.css` and `./index.tsx`; the bundler resolves and bundles from here.
321
321
  - **`app/start.html`** — identical shell for local dev, minus any third-party scripts you don't want running locally.
322
322
  - **`app/index.tsx`** — mounts `<App />` into `#root`. Nothing else.
323
- - **`app/App.tsx`** — the composition root of the client: the `ROUTES` table, the app-level context value, and the provider tree (Shelving's `App`, `Navigation`, `PageCatcher`, `Router`, `Dialogs`, `Notices`). Every page component is registered here.
323
+ - **`app/App.tsx`** — the composition root of the client: the `ROUTES` table, the app-level context value, and the provider tree (Shelving's `App`, `Navigation`, `Dialogs`, `Notices`), and the app shell (layout picker, layout, cache and router — see [The app shell](#the-app-shell)). Every page component is registered here.
324
324
  - **`app/start.ts`** — local dev server: `Bun.serve` on the port derived from `APP_URL`, serving the HTML shell for all SPA routes and static files (e.g. `/img/*` mapped to `shared/img/`).
325
325
 
326
326
  ### Routing
@@ -387,6 +387,197 @@ The client has one local database (`DB`, a plain `MemoryDBProvider`). API result
387
387
  - **No inline `style` props, ever.** All styling lives in `.module.css` files named after their component (`OrderPage.module.css` for `OrderPage.tsx`).
388
388
  - Reusable components expose styling options as **variants**: boolean props mapped to class names in the CSS module. Pages compose existing `shelving/ui` primitives (`Button`, `Notice`, `Page`, `Row`, layouts, transitions) rather than styling raw elements.
389
389
 
390
+ ### The app shell
391
+
392
+ The app shell is everything around the pages: the layout, the scroll box, the page cache, the page transition and the tab stacks. **Every part is opt-in.** Start with the smallest shell that works, and add a part only when the app needs it. Each recipe below says what to add and where.
393
+
394
+ The full nesting, from the outside in, is: contexts, then the app-level catcher, then your layout picker, then the layout, then the transition, then `<RouteCache>`, then `<Scroll vertical cover>`, then `<PageLoader>`, then `<Router>`, then the page. Leave out the parts you do not need, but keep the order. "Composing an app" on `<App>` has the full rules and a complete `App.tsx`.
395
+
396
+ #### A simple site: no layout
397
+
398
+ With no layout, the document body scrolls. This is fine for a site or a small app.
399
+
400
+ ```tsx
401
+ <App app="My site" root="https://example.com/">
402
+ <Navigation>
403
+ <PageLoader>
404
+ <Router routes={ROUTES} />
405
+ </PageLoader>
406
+ </Navigation>
407
+ </App>
408
+ ```
409
+
410
+ #### A full-screen app with its own scroll box
411
+
412
+ Use `<FixedLayout>`. It locks the body and gives one full-screen content slot inside the safe areas. It does not scroll, so put a `<Scroll vertical cover>` in it. `cover` makes the scroll box fill the slot.
413
+
414
+ ```tsx
415
+ <FixedLayout>
416
+ <Scroll vertical cover>
417
+ <PageLoader>
418
+ <Router routes={ROUTES} />
419
+ </PageLoader>
420
+ </Scroll>
421
+ </FixedLayout>
422
+ ```
423
+
424
+ #### Content in the middle of the screen
425
+
426
+ A layout never centres. The page centres its own content with `<Block height="full" middle>`. The block is at least as tall as the scroll box, so short content sits in the middle, and tall content starts at the top and scrolls. Use `top` or `bottom` to put it at an edge. This is how to make a log-in page or an error page.
427
+
428
+ ```tsx
429
+ <Page title="Log in">
430
+ <Block height="full" middle width="narrow" padding="xxlarge" indent="normal">
431
+ <LoginForm />
432
+ </Block>
433
+ </Page>
434
+ ```
435
+
436
+ #### A sidebar
437
+
438
+ Use `<SidebarLayout sidebar>`. On a narrow screen the sidebar becomes a drawer with a menu button. Fill its content slot the same way as any other layout.
439
+
440
+ ```tsx
441
+ <SidebarLayout sidebar={<Menu />}>
442
+ <Scroll vertical cover>
443
+ <Router routes={ROUTES} />
444
+ </Scroll>
445
+ </SidebarLayout>
446
+ ```
447
+
448
+ #### A tab bar
449
+
450
+ Use `<AppLayout nav>`. It puts the content slot above a bar, at every screen size. The bar has its own view-transition group, so it stays still while pages slide. Set `nav={false}` to hide the bar.
451
+
452
+ ```tsx
453
+ <AppLayout nav={<StackBar />}>
454
+ <Scroll vertical cover>
455
+ <Router routes={ROUTES} />
456
+ </Scroll>
457
+ </AppLayout>
458
+ ```
459
+
460
+ #### A custom layout with a custom scroll area
461
+
462
+ Make your own frame when no layout fits, for example a header that stays on screen above the content. A frame does three things:
463
+
464
+ 1. It locks the document, so only its own boxes scroll.
465
+ 2. It fills the screen with `position: absolute; inset: 0`, so it works inside a mount element such as `<div id="root">`.
466
+ 3. It gives a content slot with `position: relative`, which a `<Scroll vertical cover>` fills.
467
+
468
+ A frame does not scroll, centre, cache or transition. The app puts those in the slot.
469
+
470
+ ```tsx
471
+ export function TopBarLayout({ bar, children }: TopBarLayoutProps): ReactElement {
472
+ return (
473
+ <div className={LAYOUT_CLASS}>
474
+ <header className={BAR_CLASS}>{bar}</header>
475
+ <main className={CONTENT_CLASS}>{children}</main>
476
+ </div>
477
+ );
478
+ }
479
+ ```
480
+
481
+ ```css
482
+ @layer components {
483
+ html:has(.layout) { height: 100dvh; overflow: hidden; }
484
+ body:has(.layout) { position: fixed; inset: 0; margin: 0; }
485
+ .layout { position: absolute; inset: 0; display: flex; flex-direction: column; }
486
+ .content { position: relative; flex: 1; min-height: 0; overflow: hidden; }
487
+ }
488
+ ```
489
+
490
+ `modules/ui/layout/AppLayout.module.css` in Shelving is a full example, with the safe areas.
491
+
492
+ #### Other scroll boxes
493
+
494
+ `<Scroll>` is not only for pages. Use `<Scroll horizontal>` for a wide table, or `<Scroll vertical cover reverse>` for a chat that starts at the end and stays there as messages arrive. See `<Scroll>`.
495
+
496
+ #### Keep page state when you go back
497
+
498
+ By default a page unmounts when you leave it, so its scroll position, toggles and form input are lost. Add `<RouteCache>` to keep recent pages mounted but hidden. Put the scroll box **inside** the cache, so each page keeps its own scroll position.
499
+
500
+ ```tsx
501
+ <RouteCache>
502
+ <Scroll vertical cover>
503
+ <PageLoader>
504
+ <Router routes={ROUTES} />
505
+ </PageLoader>
506
+ </Scroll>
507
+ </RouteCache>
508
+ ```
509
+
510
+ Keep the layout **outside** the cache, so the chrome has one copy and keeps its own state. Clear a create form after it saves, because the cache keeps its input. See `<RouteCache>`.
511
+
512
+ #### Page transitions
513
+
514
+ Put a page transition, for example `<HorizontalTransition>`, **around** `<RouteCache>` and inside the layout. The pages slide and the chrome stays still. Do not put a transition inside the cache around each page: Safari loses the exit animation.
515
+
516
+ ```tsx
517
+ <AppLayout nav={<StackBar />}>
518
+ <HorizontalTransition>
519
+ <RouteCache>
520
+ <Scroll vertical cover>…</Scroll>
521
+ </RouteCache>
522
+ </HorizontalTransition>
523
+ </AppLayout>
524
+ ```
525
+
526
+ #### Tab stacks, like a phone app
527
+
528
+ Each tab keeps its own stack of pages, and its back button goes back within that tab. You need four parts:
529
+
530
+ 1. Set `stacks` on `<Navigation>` to the root path of each tab, in tab order, and `stack` to the tab the app opens in: `<Navigation stacks={["/home", "/discover", "/profile"]} stack="/home">`.
531
+ 2. Make a tab bar of `<StackButton stack="/home">` buttons, and put it in `<AppLayout nav>`.
532
+ 3. Put `<BackButton href="/home" />` in each page header. It goes back in the current tab, or to `href` when there is no page before.
533
+ 4. Use `<RouteCache>`, so each tab shows the page you left it on.
534
+
535
+ Use `className="replace"` on in-page tab links (for example `/dave/posts` and `/dave/likes`), so they change the URL without a new page. See `<Navigation>`, `NavigationStore`, `<StackButton>` and `<BackButton>`.
536
+
537
+ #### Hide the tab bar on some pages
538
+
539
+ All pages in one stack share one layout, because they share one cache. So a page cannot change the layout itself. Pick the layout props from the URL in your layout picker, above the router:
540
+
541
+ ```tsx
542
+ function Shell() {
543
+ const { path } = requireMetaURL();
544
+ return (
545
+ <AppLayout nav={path.startsWith("/squad/") ? false : <StackBar />}>
546
+ <Content />
547
+ </AppLayout>
548
+ );
549
+ }
550
+ ```
551
+
552
+ #### Pick a layout by state or path
553
+
554
+ The layout picker is plain React, so any rule works: the session, the path, or both. Swap to another layout only between sections the user does not move back and forth in, such as log-in and the main app, because a new layout mounts a new cache.
555
+
556
+ ```tsx
557
+ function Shell({ signedIn }: { signedIn: boolean }) {
558
+ if (!signedIn) return <FixedLayout><Content routes={LOGIN_ROUTES} /></FixedLayout>;
559
+ return <AppLayout nav={<StackBar />}><Content routes={ROUTES} /></AppLayout>;
560
+ }
561
+ ```
562
+
563
+ Put the slot content (transition, cache, scroll box, loader and router) in one small `Content` component, and reuse it in each layout.
564
+
565
+ #### Errors and loading
566
+
567
+ A page, an error page or a loading state never renders a layout. `<PageLoader>` catches errors and shows a loading state inside the scroll box, in the layout the user already sees. An app-level `<Catcher>` sits outside every layout, so it picks one itself:
568
+
569
+ ```tsx
570
+ function AppError({ reason }: ErrorProps) {
571
+ return (
572
+ <FixedLayout>
573
+ <Scroll vertical cover>
574
+ <ErrorPage reason={reason} />
575
+ </Scroll>
576
+ </FixedLayout>
577
+ );
578
+ }
579
+ ```
580
+
390
581
  ## Boundaries
391
582
 
392
583
  Three mechanisms keep the packages honest:
@@ -693,6 +884,44 @@ If every file in that list is in the right place, the client and server share on
693
884
 
694
885
  ## Upgrade notes
695
886
 
887
+ ### Tab stacks in `<Navigation>`
888
+
889
+ `<Navigation>` now keeps one stack of pages for each tab, like a phone app. It uses the browser [Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API). Some names and props changed. To upgrade an app:
890
+
891
+ 1. **Rename `redirect()` to `replace()`.** Change each `nav.redirect(url)` to `nav.replace(url)`. It does the same thing: it changes the URL of the current page with no new history entry and no slide.
892
+ 2. **Change the `back` prop to a class.** The `back` prop on `<Button>` and `<Link>` is removed, and so is the `data-back` attribute. Change `<Button href="/profile" back>` to `<Button href="/profile" className="back">`. For a page-header back button, use `<BackButton href="/profile"/>` (see step 6).
893
+ 3. **Remove `<RouteConfig>`.** `<RouteConfig>` and `RouteContext` are removed.
894
+ - `<RouteConfig path>` kept a page mounted for its tabs (for example `/dave/{tab}`). Instead, add `className="replace"` to each in-page tab link: `<Button href="/dave/posts" className="replace">Posts</Button>`. A replace keeps the same page mounted, with no slide and no new history entry.
895
+ - `<RouteConfig cache={false}>` unmounted a create form when you left it. Instead, clear the form after a successful submit: change the `key` of the `<Form>`, or call `form.reset()` on a plain HTML form. See `<RouteCache>` for an example.
896
+ 4. **Canonical URLs.** `<Head>` no longer writes browser history itself. When a page renders a `<Head>` with a `url` that is not the current URL, `<Head>` calls `NavigationStore.replace()`. You do not need to change anything, but do not also call `window.history.replaceState()` for it.
897
+ 5. **Add stacks (optional).** For an app with a tab bar, set `stacks` on `<Navigation>` to the root path of each tab, in tab order: `<Navigation stacks={["/home", "/discover", "/profile"]}>`. Each link then opens a new page in the current tab, wherever it points. Set `stack` on `<Navigation>` to the stack the app opens in. With no `stack`, the app opens in the `/` stack, which is unstacked: no tab is selected until the user taps a tab, or the app names a stack. Deep links and login pages are unstacked. A login page calls `nav.replace("/home", "/home")` to send the user into the Home tab.
898
+ 6. **Use the new buttons (optional).**
899
+ - `<StackButton stack="/home">` is a tab bar button. It goes to the page you left in that tab, goes back to the tab's root when you are already in it, and scrolls to the top at the root.
900
+ - `<BackButton href="/home"/>` goes back to the page before this one in the current tab, or to `href` when there is none.
901
+ 7. **Move the page transition outside `<RouteCache>`.** Put `<HorizontalTransition>` (or any page `<Transition>`) around the `<RouteCache>`, not inside it around each page. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
902
+ 8. **Check pages that change URL for the same component.** `<RouteCache>` now keys each page by its stack and depth, not by its path. A replace from `/post/1` to `/post/2` keeps the same component mounted with its state. If the page must reset, wrap its content in an element with `key={id}`.
903
+ 9. **Know the fallback.** Without the Navigation API (older browsers), links still work with no page reload, but there are no stacks, no slides and no page cache. `<StackButton>` and `<BackButton>` become plain links.
904
+
905
+ What changes for users:
906
+
907
+ - Each tab remembers the page you left it on, and its back button goes back within that tab.
908
+ - The browser back button walks the history as before, across tabs. The page slides the right way.
909
+ - When you go back from a page, it leaves the cache. So the browser forward button then shows that page fresh, from the top.
910
+
911
+ See `<Navigation>`, `NavigationStore`, `<RouteCache>`, `<StackButton>` and `<BackButton>` for the full details.
912
+
913
+ ### Layouts are frames
914
+
915
+ Layouts no longer include a `<RouteCache>` or a scroll box. Each layout is a frame with a content slot, so the app chooses the scroll box, the transition and the cache. `<CenteredLayout>` is now `<FixedLayout>`, and it no longer centres or scrolls. `<ErrorPage>` and the `<PageLoader>` fallback no longer render a layout. To upgrade an app:
916
+
917
+ 1. **Fill the `<SidebarLayout>` slot.** Put `<RouteCache>`, then `<Scroll vertical cover>`, then `<PageLoader>`, then your `<Router>` in it. Without a scroll box, the content does not scroll. Put a page transition around the `<RouteCache>`, inside the layout, so the sidebar stays still.
918
+ 2. **Change `<CenteredLayout>` to `<FixedLayout>`.** Put a `<Scroll vertical cover>` in it, then your page or `<Router>`. Move the centring into the page: `<Block height="full" middle width="narrow" padding="xxlarge" indent="normal">`. The new `height` and `middle` block variants put the content in the middle of the screen, and it still scrolls when it is taller. The `width`, `padding` and `indent` props and the `--centered-layout-*` hooks are removed; the background and colour hooks are now `--fixed-layout-background` and `--fixed-layout-color`.
919
+ 3. **Do not render a layout in a page.** A page, an error page or a loading state never renders a layout. Pick the layout once, above the router. An app-level catcher sits outside every layout, so give it one: `<Catcher as={AppError}>`, where `AppError` renders `<ErrorPage>` in a `<FixedLayout>` and a `<Scroll vertical cover>`.
920
+ 4. **Use `<AppLayout>` for a tab bar (optional).** `<AppLayout nav={<StackBar />}>` puts a bar of `<StackButton>`s below the content slot. Set `nav={false}` to hide it for some pages.
921
+ 5. **Rename the scroll focus hook.** `--scrollable-focus-border` is now `--scroll-focus-border`.
922
+
923
+ See "Composing an app" on `<App>` for the full nesting rules and an example `App.tsx`, and [The app shell](#the-app-shell) above for each part as a recipe.
924
+
696
925
  ### From `CacheDBProvider` to `HydratingAPIProvider`
697
926
 
698
927
  `CacheDBProvider` and the paging in `QueryStore` are removed. To upgrade an app: