shelving 1.321.0 → 1.322.1

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 (107) hide show
  1. package/docs/guides/building-with-shelving.md +204 -1
  2. package/docs/llms-full.txt +793 -115
  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/Catcher.md +1 -1
  7. package/docs/ui/Dialog.md +3 -1
  8. package/docs/ui/Dialogs.md +4 -0
  9. package/docs/ui/ErrorPage.md +2 -1
  10. package/docs/ui/FixedLayout.md +91 -0
  11. package/docs/ui/FixedLayoutProps.md +13 -0
  12. package/docs/ui/GapVariants.md +2 -2
  13. package/docs/ui/HeightVariant.md +30 -0
  14. package/docs/ui/HeightVariants.md +26 -0
  15. package/docs/ui/Navigation.md +20 -11
  16. package/docs/ui/PaddingVariants.md +2 -2
  17. package/docs/ui/Page.md +12 -8
  18. package/docs/ui/PageLoader.md +2 -1
  19. package/docs/ui/RouteCache.md +22 -17
  20. package/docs/ui/Router.md +9 -5
  21. package/docs/ui/Scroll.md +60 -6
  22. package/docs/ui/ScrollVariants.md +5 -1
  23. package/docs/ui/SidebarLayout.md +17 -8
  24. package/docs/ui/SpaceValue.md +1 -0
  25. package/docs/ui/TreeApp.md +1 -1
  26. package/docs/ui/getBlockClass.md +1 -1
  27. package/docs/ui/getGapClass.md +1 -1
  28. package/docs/ui/getHeightClass.md +64 -0
  29. package/docs/ui/getPaddingClass.md +1 -1
  30. package/docs/ui/getScrollClass.md +4 -2
  31. package/docs/ui/getSpaceClass.md +2 -0
  32. package/docs/ui.md +13 -8
  33. package/package.json +1 -1
  34. package/ui/README.md +1 -1
  35. package/ui/app/App.md +105 -7
  36. package/ui/dialog/Dialog.md +3 -1
  37. package/ui/dialog/Dialogs.d.ts +4 -0
  38. package/ui/dialog/Dialogs.js +4 -0
  39. package/ui/dialog/Dialogs.tsx +4 -0
  40. package/ui/docs/DocumentationApp.js +4 -1
  41. package/ui/docs/DocumentationApp.tsx +10 -1
  42. package/ui/layout/AppLayout.d.ts +21 -0
  43. package/ui/layout/AppLayout.js +18 -0
  44. package/ui/layout/AppLayout.md +57 -0
  45. package/ui/layout/AppLayout.module.css +92 -0
  46. package/ui/layout/AppLayout.tsx +36 -0
  47. package/ui/layout/FixedLayout.d.ts +18 -0
  48. package/ui/layout/FixedLayout.js +15 -0
  49. package/ui/layout/FixedLayout.md +65 -0
  50. package/ui/layout/FixedLayout.module.css +55 -0
  51. package/ui/layout/FixedLayout.tsx +25 -0
  52. package/ui/layout/SidebarLayout.d.ts +2 -2
  53. package/ui/layout/SidebarLayout.js +3 -4
  54. package/ui/layout/SidebarLayout.md +15 -6
  55. package/ui/layout/SidebarLayout.module.css +11 -16
  56. package/ui/layout/SidebarLayout.tsx +10 -13
  57. package/ui/layout/index.d.ts +2 -1
  58. package/ui/layout/index.js +2 -1
  59. package/ui/layout/index.tsx +2 -1
  60. package/ui/misc/Catcher.d.ts +2 -1
  61. package/ui/misc/Catcher.js +4 -3
  62. package/ui/misc/Catcher.md +1 -1
  63. package/ui/misc/Catcher.tsx +5 -4
  64. package/ui/misc/Loader.d.ts +1 -0
  65. package/ui/misc/Loader.js +6 -2
  66. package/ui/misc/Loader.tsx +11 -2
  67. package/ui/page/Page.md +12 -8
  68. package/ui/router/Navigation.md +20 -11
  69. package/ui/router/RouteCache.d.ts +2 -1
  70. package/ui/router/RouteCache.js +2 -1
  71. package/ui/router/RouteCache.md +20 -16
  72. package/ui/router/RouteCache.tsx +2 -1
  73. package/ui/router/Router.md +9 -5
  74. package/ui/style/Block.d.ts +3 -2
  75. package/ui/style/Block.js +3 -2
  76. package/ui/style/Block.tsx +4 -2
  77. package/ui/style/Gap.d.ts +1 -1
  78. package/ui/style/Gap.tsx +1 -1
  79. package/ui/style/Height.d.ts +32 -0
  80. package/ui/style/Height.js +13 -0
  81. package/ui/style/Height.module.css +88 -0
  82. package/ui/style/Height.tsx +61 -0
  83. package/ui/style/Padding.d.ts +1 -1
  84. package/ui/style/Padding.tsx +1 -1
  85. package/ui/style/Scroll.d.ts +9 -5
  86. package/ui/style/Scroll.js +6 -4
  87. package/ui/style/Scroll.md +59 -0
  88. package/ui/style/Scroll.module.css +13 -1
  89. package/ui/style/Scroll.tsx +13 -5
  90. package/ui/style/Space.d.ts +1 -1
  91. package/ui/style/Space.module.css +12 -0
  92. package/ui/style/Space.tsx +1 -0
  93. package/ui/style/getHeightClass.md +30 -0
  94. package/ui/style/getSpaceClass.md +2 -0
  95. package/ui/style/index.d.ts +1 -0
  96. package/ui/style/index.js +1 -0
  97. package/ui/style/index.ts +1 -0
  98. package/ui/tree/TreeApp.d.ts +1 -1
  99. package/ui/tree/TreeApp.js +5 -2
  100. package/ui/tree/TreeApp.tsx +11 -2
  101. package/docs/ui/CenteredLayout.md +0 -66
  102. package/docs/ui/CenteredLayoutProps.md +0 -14
  103. package/ui/layout/CenteredLayout.d.ts +0 -21
  104. package/ui/layout/CenteredLayout.js +0 -28
  105. package/ui/layout/CenteredLayout.md +0 -41
  106. package/ui/layout/CenteredLayout.module.css +0 -72
  107. package/ui/layout/CenteredLayout.tsx +0 -56
@@ -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. Pages slide in the content slot above the bar, so the bar stays still. 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:
@@ -719,6 +910,18 @@ What changes for users:
719
910
 
720
911
  See `<Navigation>`, `NavigationStore`, `<RouteCache>`, `<StackButton>` and `<BackButton>` for the full details.
721
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
+
722
925
  ### From `CacheDBProvider` to `HydratingAPIProvider`
723
926
 
724
927
  `CacheDBProvider` and the paging in `QueryStore` are removed. To upgrade an app: