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
@@ -3,12 +3,12 @@
3
3
  - Kind: function
4
4
  - Import: `import { getScrollClass } from "shelving/ui";`
5
5
 
6
- Get the scroll class for a component from its `horizontal` / `vertical` variant props.
6
+ Get the scroll class for a component from its `horizontal`, `vertical`, `cover` and `reverse` variant props.
7
7
 
8
8
  ## Signatures
9
9
 
10
10
  ```ts
11
- getScrollClass({ horizontal, vertical }: ScrollVariants): string
11
+ getScrollClass({ horizontal, vertical, cover, reverse }: ScrollVariants): string
12
12
  ```
13
13
 
14
14
  ## Parameters
@@ -18,6 +18,8 @@ getScrollClass({ horizontal, vertical }: ScrollVariants): string
18
18
  | `options` | `ScrollVariants` | |
19
19
  | `.vertical` | `boolean \| undefined` | Vertical scrolling (defaults to `false`). Optional. |
20
20
  | `.horizontal` | `boolean \| undefined` | Horizontal scrolling (defaults to `false`). Optional. |
21
+ | `.cover` | `boolean \| undefined` | Cover the nearest positioned ancestor (`position: absolute; inset: 0`), for example a layout's content slot (defaults to `false`). Optional. |
22
+ | `.reverse` | `boolean \| undefined` | Start at the end and stay there as the content grows, for example a chat (defaults to `false`). Put the content in one child. Optional. |
21
23
 
22
24
  ## Returns
23
25
 
@@ -9,6 +9,8 @@ The `space` variant prop sets a block-level element's `margin-block` (top + bott
9
9
 
10
10
  `getSpaceClass({ space })` maps the prop to a margin class (e.g. `space="large"` → `large`). The same scale also backs `getPaddingClass()` (block padding), `getIndentClass()` (inline padding), and `getGapClass()`, so they all move together when you change `--space-normal`.
11
11
 
12
+ `space="auto"` sets `margin-block: auto`. In a flex or grid container, such as a `<Column>`, the auto margins take the free space, so the block sits in the middle (it still keeps auto margins as a first or last child). In normal block flow they do nothing: to centre a block vertically there, use `height="full" middle` (see `getHeightClass()`). `padding` and `gap` have no `auto`.
13
+
12
14
  Alongside the named scale, `space`, `padding`, and `indent` also accept numeric multiples of `--space-normal` — `1x` … `10x` (e.g. `padding="5x"` → `calc(var(--space-normal) * 5)`) — for larger one-off blocks like hero panels.
13
15
 
14
16
  ## Theme variables
@@ -22,7 +22,8 @@ mergeMeta(meta1: Meta, meta2: PossibleMeta, caller: AnyCaller = mergeMeta): Meta
22
22
  | --- | --- | --- |
23
23
  | `meta1` | `Meta` | The existing fully-resolved `Meta` to merge into. |
24
24
  | `.root` | `ImmutableURL \| undefined` | Base URL for the app (used to resolve `url` and set as `<base>` tag in `<Head>`). Read only. Optional. |
25
- | `.url` | `ImmutableURL \| undefined` | URL of the current page (used to update history API and as the initial URL for routing). Read only. Optional. |
25
+ | `.url` | `ImmutableURL \| undefined` | URL of the current page (used as the initial URL for routing, and as the page's canonical URL in `<Head>`). Read only. Optional. |
26
+ | `.stack` | `AbsolutePath \| undefined` | Root path of the current stack (for example `"/home"`). Set it above `<Navigation>` to choose the stack the app opens in. `<Navigation>` publishes the live stack, which is `"/"` for an unstacked page. Read only. Optional. |
26
27
  | `.app` | `string \| undefined` | Title of the entire application. Read only. Optional. |
27
28
  | `.title` | `string \| undefined` | Title of the current page (set as `<title>` in `<Head>` Read only. Optional. |
28
29
  | `.description` | `string \| undefined` | Description of the current page. Read only. Optional. |
package/docs/ui.md CHANGED
@@ -62,7 +62,7 @@ The components below are listed in the index following this page; this is the sh
62
62
 
63
63
  **Content.** Block-level structure starts with `<Card>`, `<Section>`, and the `<Heading>` / `<Title>` family, with `<Table>`, `<List>`, and `<Figure>` for specific shapes; wrap longform copy in `<Prose>`. Inline pieces — `<Link>`, `<Code>`, `<Strong>`, `<Mark>` — live inside that block content. To render a Markdown string as components, use `<Markup>`.
64
64
 
65
- **Structure.** Mount a client app with `<App>`, or render a full server document with `<HTML>` and `<Page>`. Arrange the screen with `<CenteredLayout>` or `<SidebarLayout>`, and drive URLs with `<Navigation>` and `<Router>`.
65
+ **Structure.** Mount a client app with `<App>`, or render a full server document with `<HTML>` and `<Page>`. Arrange the screen with `<AppLayout>`, `<SidebarLayout>` or `<FixedLayout>`, and drive URLs with `<Navigation>` and `<Router>`. A layout is a frame: it sits above the router, and the app fills its content slot with `<RouteCache>` and `<Scroll>`. See "Composing an app" on `<App>`.
66
66
 
67
67
  **Interaction.** Forms start at `<Form>`, which wires `<Field>` and the typed inputs to a `FormStore`; `<Button>` is the standalone action. Overlays are `<Dialog>` and `<Modal>`; navigation menus are `<Menu>` and `<MenuItem>`; transient feedback is `<Notice>` (and the global `<Notices>` list); animate enter/leave with `<Transition>`.
68
68
 
@@ -176,14 +176,15 @@ The components below are listed in the index following this page; this is the sh
176
176
  - [DataSchemaInput](ui/DataSchemaInput.md): Show a DataInput for a nested DataSchema.
177
177
  - [SchemaField](ui/SchemaField.md): Show the appropriate input for a schema, wrapped in a <Field> with its label and message.
178
178
  - [SelectInput](ui/SelectInput.md): Dropdown input bound to a string value, rendered as a <select> of the provided options.
179
- - [CenteredLayout](ui/CenteredLayout.md): Layout that centres its content with no header/footer and a narrow max-width.
180
- - [SidebarLayout](ui/SidebarLayout.md): Layout with a fixed-width side column (typically navigation) next to a scrollable main content column.
179
+ - [AppLayout](ui/AppLayout.md): Layout with a content slot above a bar of the app's main sections, like the tab bar of a phone app.
180
+ - [FixedLayout](ui/FixedLayout.md): Layout with no chrome: the whole screen is one content slot.
181
+ - [SidebarLayout](ui/SidebarLayout.md): Layout with a fixed-width side column (typically navigation) next to a content slot.
181
182
  - [Menu](ui/Menu.md): A <menu> list of <MenuItem> children.
182
183
  - [MenuItem](ui/MenuItem.md): A <li> containing an <a> link, plus optional submenu content shown when this item is "proud".
183
184
  - [Catcher](ui/Catcher.md): React error boundary that renders a fallback component when any descendant throws.
184
185
  - [ErrorNotice](ui/ErrorNotice.md): Render a caught error as an inline <Notice> with a retry button.
185
186
  - [PageCatcher](ui/PageCatcher.md): Error boundary for a whole page that renders a full <ErrorPage> fallback on error.
186
- - [ErrorPage](ui/ErrorPage.md): Render a caught error as a full-page <Page> with a centered <ErrorNotice>.
187
+ - [ErrorPage](ui/ErrorPage.md): Render a caught error as a <Page> with an <ErrorNotice> in a narrow column, centred in the middle of the screen.
187
188
  - [Icon](ui/Icon.md): Render the icon for a given status, coloured to match.
188
189
  - [Loader](ui/Loader.md): Load a component.
189
190
  - [PageLoader](ui/PageLoader.md): Load a page.
@@ -193,13 +194,14 @@ The components below are listed in the index following this page; this is the sh
193
194
  - [Empty](ui/Empty.md): Message for a list with nothing in it: centred, grey content with space around it.
194
195
  - [Notice](ui/Notice.md): Block-level status callout with an icon and message, used to highlight feedback.
195
196
  - [Notices](ui/Notices.md): Render the global list of notices and subscribe to incoming "notice" events.
196
- - [Head](ui/Head.md): Emit the current page's head metadata and sync browser history to its URL.
197
+ - [Head](ui/Head.md): Emit the current page's head metadata, and replace the browser URL with the page's canonical URL.
197
198
  - [HTML](ui/HTML.md): Render the full <html> document shell wrapping <head> and <body>.
198
199
  - [Page](ui/Page.md): Wrap a single page (or screen) within an app, applying its meta and head tags.
199
- - [Navigation](ui/Navigation.md): Top-level navigation provider.
200
- - [RouteCache](ui/RouteCache.md): Keep-alive page cache keyed by the current URL — drop it into a layout around its scrolling content region.
201
- - [RouteConfig](ui/RouteConfig.md): Configure the current page for the surrounding <Router> (and <RouteCache>).
200
+ - [BackButton](ui/BackButton.md): Back button for the current stack.
201
+ - [Navigation](ui/Navigation.md): Top-level navigation provider, with one stack of pages for each tab.
202
+ - [RouteCache](ui/RouteCache.md): Keep-alive page cache for the pages in the navigation stacks. Put it in a layout's content slot, around a <Scroll vertical cover> box.
202
203
  - [Router](ui/Router.md): Match the current URL against routes and render the matched element.
204
+ - [StackButton](ui/StackButton.md): Button for one stack in a tab bar.
203
205
  - [Scroll](ui/Scroll.md): Wrap children in a scrollable container with horizontal and/or vertical scrolling enabled.
204
206
  - [Cell](ui/Cell.md): Table cell.
205
207
  - [Table](ui/Table.md): Table block — rendered as <table>.
@@ -270,10 +272,11 @@ The components below are listed in the index following this page; this is the sh
270
272
  - [getFlexClass()](ui/getFlexClass.md): Get the flex layout class for a component from its flex variant props.
271
273
  - [getGapClass()](ui/getGapClass.md): Get the gap class for a component from its gap variant prop.
272
274
  - [getGridClass()](ui/getGridClass.md): Get the grid layout class for a component from its grid variant props.
275
+ - [getHeightClass()](ui/getHeightClass.md): Get the height class for a component from its height, top, middle and bottom variant props.
273
276
  - [getIndentClass()](ui/getIndentClass.md): Get the inline-padding ("indent") class for a component from its indent variant prop.
274
277
  - [getPaddingClass()](ui/getPaddingClass.md): Get the block-padding class for a component from its padding variant prop.
275
278
  - [getRadiusClass()](ui/getRadiusClass.md): Get the corner-radius class for a component from its radius variant prop.
276
- - [getScrollClass()](ui/getScrollClass.md): Get the scroll class for a component from its horizontal / vertical variant props.
279
+ - [getScrollClass()](ui/getScrollClass.md): Get the scroll class for a component from its horizontal, vertical, cover and reverse variant props.
277
280
  - [getShadowClass()](ui/getShadowClass.md): Get the drop-shadow class for a component from its shadow variant prop.
278
281
  - [getSpaceClass()](ui/getSpaceClass.md): Get the block spacing class for a component from its space="" variant prop.
279
282
  - [getStatusClass()](ui/getStatusClass.md): Get the status tint class for a component from its status variant prop.
@@ -321,7 +324,7 @@ The components below are listed in the index following this page; this is the sh
321
324
  - [FormStore](ui/FormStore.md): Reactive store holding the current (possibly partial and invalid) value of a form, plus its field messages.
322
325
  - [NoticesStore](ui/NoticesStore.md): Store holding the live list of NoticeStore notices currently shown.
323
326
  - [NoticeStore](ui/NoticeStore.md): Store holding a single notice's content and status, owned by a NoticesStore.
324
- - [NavigationStore](ui/NavigationStore.md): Store holding the current navigation URL and driving browser history.
327
+ - [NavigationStore](ui/NavigationStore.md): Store that holds the current navigation URL, drives browser history, and keeps a stack of pages for each tab.
325
328
 
326
329
  ## Interfaces
327
330
 
@@ -435,7 +438,8 @@ The components below are listed in the index following this page; this is the sh
435
438
  - [SelectProps](ui/SelectProps.md): Props for SelectInput, a dropdown <select> bound to a string value.
436
439
  - [TextareaInputProps](ui/TextareaInputProps.md): Props for TextareaInput, a multiline text input bound to a string value.
437
440
  - [TextInputProps](ui/TextInputProps.md): Props for TextInput, a single-line text input bound to a string value.
438
- - [CenteredLayoutProps](ui/CenteredLayoutProps.md): Props for <CenteredLayout> — optional children plus width (of the centred column) and padding / indent (block / inline padding of the scroll area) variants.
441
+ - [AppLayoutProps](ui/AppLayoutProps.md): Props for <AppLayout>: the nav bar content and the content slot children.
442
+ - [FixedLayoutProps](ui/FixedLayoutProps.md): Props for <FixedLayout>: the content slot children.
439
443
  - [SidebarLayoutProps](ui/SidebarLayoutProps.md): Props for <SidebarLayout> — the sidebar column content, main children, and a right placement flag.
440
444
  - [MenuProps](ui/MenuProps.md): Props for <Menu> — optional <MenuItem> children.
441
445
  - [MenuItemProps](ui/MenuItemProps.md): Props for <MenuItem> — <Clickable> props plus children whose first node is the label and the rest the submenu.
@@ -455,21 +459,24 @@ The components below are listed in the index following this page; this is the sh
455
459
  - [NoticesProps](ui/NoticesProps.md): Props for <Notices> — the place for the list, and flex styling variants for the notices container.
456
460
  - [HTMLProps](ui/HTMLProps.md): Props for <HTML> — initial Meta (language/root/app) plus the page children.
457
461
  - [PageProps](ui/PageProps.md): Props for <Page> — per-page Meta (title, description, etc.) plus the page children.
458
- - [NavigationProps](ui/NavigationProps.md): Props for <Navigation> — initial Meta (url/base) plus optional children.
459
- - [RouteCacheProps](ui/RouteCacheProps.md): Props for <RouteCache> — the maxCached size and the content children to keep alive per URL.
460
- - [RouteConfigProps](ui/RouteConfigProps.md): Props for <RouteConfig> — the settings of a page for the surrounding <Router> and <RouteCache>, and the page content.
461
- - [RouteState](ui/RouteState.md): The route state of one page, shared by <Router>, <RouteCache> and <RouteConfig>.
462
+ - [BackButtonProps](ui/BackButtonProps.md): Props for <BackButton>: the href to go back to when the stack has no page before this one, plus the usual Button props except onClick.
463
+ - [NavigationProps](ui/NavigationProps.md): Props for <Navigation>: the initial Meta (url, root and stack), the stacks, and optional children.
464
+ - [NavigationEntryState](ui/NavigationEntryState.md): State that NavigationStore saves on each browser history entry.
465
+ - [NavigationPosition](ui/NavigationPosition.md): Where the app is now in its stacks: the current stack and depth, the top depth of each stack, and the page before the current one.
466
+ - [RouteCacheProps](ui/RouteCacheProps.md): Props for <RouteCache>: the maxCached size and the content children to keep alive for each page in the stacks.
462
467
  - [RouterProps](ui/RouterProps.md): Props for <Router> — the routes to match against plus an optional fallback.
468
+ - [StackButtonProps](ui/StackButtonProps.md): Props for <StackButton>: the stack it opens, plus the usual Button props except href and onClick.
463
469
  - [BlockVariants](ui/BlockVariants.md): Variants for block level elements.
464
470
  - [ColorVariants](ui/ColorVariants.md): Variant props for colouring an element, e.g. color="purple".
465
471
  - [DurationVariants](ui/DurationVariants.md): Variant props for the transition duration of an element, e.g. duration="fast".
466
472
  - [FlexVariants](ui/FlexVariants.md): Variant props for flex layout — opt-in modifiers any component can mix in via getFlexClass().
467
473
  - [GapVariants](ui/GapVariants.md): Variant props for the gap between a component's children, e.g. gap="large".
468
474
  - [GridVariants](ui/GridVariants.md): Variant props for grid layout, e.g. columns={3} gap="normal".
475
+ - [HeightVariants](ui/HeightVariants.md): Variant props that set a component's height, and where its content sits inside that height, e.g. height="full" middle.
469
476
  - [IndentVariants](ui/IndentVariants.md): Variant props for the inline-padding ("indent", left + right) of a component, e.g. indent="normal".
470
477
  - [PaddingVariants](ui/PaddingVariants.md): Variant props for the block-padding (top + bottom) of a component, e.g. padding="large".
471
478
  - [RadiusVariants](ui/RadiusVariants.md): Variant props for the corner radius of an element, e.g. radius="large".
472
- - [ScrollVariants](ui/ScrollVariants.md): Variant props selecting which scroll axes are enabled on an element.
479
+ - [ScrollVariants](ui/ScrollVariants.md): Variant props for a scroll region: which axes scroll, plus cover and reverse.
473
480
  - [ScrollComponentProps](ui/ScrollComponentProps.md): Props for the Scroll component — children plus scroll-axis variants.
474
481
  - [ShadowVariants](ui/ShadowVariants.md): Variant props for the drop shadow of an element, e.g. shadow="large".
475
482
  - [SpaceVariants](ui/SpaceVariants.md): Variants to control block spacing on components, e.g. space="large".
@@ -518,6 +525,7 @@ The components below are listed in the index following this page; this is the sh
518
525
  - [ColorVariant](ui/ColorVariant.md): Enumerated colour names selectable via the color="purple" prop for components that support that support ColorVariants
519
526
  - [DurationValue](ui/DurationValue.md): Allowed values for transition timing for components that support DurationVariants
520
527
  - [ColumnsVariant](ui/ColumnsVariant.md): Number of equal-width columns selectable via the columns variant prop.
528
+ - [HeightVariant](ui/HeightVariant.md): Enumerated height selectable via the height variant prop.
521
529
  - [IndentVariant](ui/IndentVariant.md): Allowed values for inline-padding ("indent") for components that support IndentVariants
522
530
  - [RadiusVariant](ui/RadiusVariant.md): Allowed values for border radius for components that support RadiusVariants
523
531
  - [ShadowVariant](ui/ShadowVariant.md): Enumerated drop-shadow scale selectable via the shadow="normal" variant prop.
@@ -560,7 +568,7 @@ The components below are listed in the index following this page; this is the sh
560
568
  - [LOADING_NOTICE](ui/LOADING_NOTICE.md): Shared loading <Notice> element showing the loading spinner.
561
569
  - [NOTICES](ui/NOTICES.md): Global NoticesStore shown by <Notices>, accepting any of the default statuses.
562
570
  - [NavigationContext](ui/NavigationContext.md): React context holding the current NavigationStore, provided by <Navigation>.
563
- - [RouteContext](ui/RouteContext.md): React context holding the RouteState of the current page, provided by <Router> and <RouteCache>.
571
+ - [NavigationPositionContext](ui/NavigationPositionContext.md): React context holding where the app is in its stacks, published by <Navigation> with each URL change.
564
572
  - [STATUSES](ui/STATUSES.md): Tuple of the status names selectable via the status variant prop.
565
573
  - [TINT_CLASS](ui/TINT_CLASS.md): CSS class that (re)calculates the full ladder of tint shades from the current global tint colour.
566
574
  - [FADE_TRANSITION_CLASS](ui/FADE_TRANSITION_CLASS.md): View transition class that fades content in and out.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shelving",
3
- "version": "1.320.0",
3
+ "version": "1.322.0",
4
4
  "author": "Dave Houlbrooke <dave@shax.com>",
5
5
  "repository": {
6
6
  "type": "git",
package/ui/README.md CHANGED
@@ -59,7 +59,7 @@ The components below are listed in the index following this page; this is the sh
59
59
 
60
60
  **Content.** Block-level structure starts with `<Card>`, `<Section>`, and the `<Heading>` / `<Title>` family, with `<Table>`, `<List>`, and `<Figure>` for specific shapes; wrap longform copy in `<Prose>`. Inline pieces — `<Link>`, `<Code>`, `<Strong>`, `<Mark>` — live inside that block content. To render a Markdown string as components, use `<Markup>`.
61
61
 
62
- **Structure.** Mount a client app with `<App>`, or render a full server document with `<HTML>` and `<Page>`. Arrange the screen with `<CenteredLayout>` or `<SidebarLayout>`, and drive URLs with `<Navigation>` and `<Router>`.
62
+ **Structure.** Mount a client app with `<App>`, or render a full server document with `<HTML>` and `<Page>`. Arrange the screen with `<AppLayout>`, `<SidebarLayout>` or `<FixedLayout>`, and drive URLs with `<Navigation>` and `<Router>`. A layout is a frame: it sits above the router, and the app fills its content slot with `<RouteCache>` and `<Scroll>`. See "Composing an app" on `<App>`.
63
63
 
64
64
  **Interaction.** Forms start at `<Form>`, which wires `<Field>` and the typed inputs to a `FormStore`; `<Button>` is the standalone action. Overlays are `<Dialog>` and `<Modal>`; navigation menus are `<Menu>` and `<MenuItem>`; transient feedback is `<Notice>` (and the global `<Notices>` list); animate enter/leave with `<Transition>`.
65
65
 
package/ui/app/App.md CHANGED
@@ -9,17 +9,19 @@ Use `<App>` when mounting into an existing HTML page on the client. For server-s
9
9
  The smallest single-screen app — `<App>` wraps a layout and some content:
10
10
 
11
11
  ```tsx
12
- import { App, CenteredLayout, Section, Title, Paragraph } from "shelving/ui";
12
+ import { App, FixedLayout, Paragraph, Scroll, Section, Title } from "shelving/ui";
13
13
 
14
14
  function HelloApp() {
15
15
  return (
16
16
  <App app="My app">
17
- <CenteredLayout>
18
- <Section width="narrow">
19
- <Title>Hello</Title>
20
- <Paragraph>Welcome to the app.</Paragraph>
21
- </Section>
22
- </CenteredLayout>
17
+ <FixedLayout>
18
+ <Scroll vertical cover>
19
+ <Section width="narrow">
20
+ <Title>Hello</Title>
21
+ <Paragraph>Welcome to the app.</Paragraph>
22
+ </Section>
23
+ </Scroll>
24
+ </FixedLayout>
23
25
  </App>
24
26
  );
25
27
  }
@@ -50,4 +52,100 @@ export function MyApp() {
50
52
 
51
53
  `<App>` accepts all `PossibleMeta` props (`app`, `root`, `url`, `title`, `language`, `tags`, etc.) and merges them into the context it provides to children. On mount it adds the theme class to `document.body`, which activates the CSS custom property tokens defined in `App.module.css`; on unmount it removes it.
52
54
 
55
+ ## Composing an app
56
+
57
+ An app is built from layers, each with one job. Write them in plain sight in `App.tsx`, from the outside in:
58
+
59
+ 1. **Contexts**: `<App>`, your data contexts, `<Navigation>`, `<DialogsContext>`.
60
+ 2. **App-level catcher**: a last resort, outside every layout.
61
+ 3. **Layout picker**: your own component that picks the layout (and its props) from the session, the path, or any other state.
62
+ 4. **Layout**: `<AppLayout>`, `<SidebarLayout>` or `<FixedLayout>`. It draws the chrome (tab bar, sidebar) and gives a content slot. It knows nothing about the cache.
63
+ 5. **Content**: transition, then `<RouteCache>`, then `<Scroll vertical cover>`, then `<PageLoader>`, then `<Router>`. Put it in a small component of your own, and reuse it in each layout.
64
+ 6. **Page**: `<Page>` with its title, then the page content. A page renders no layout.
65
+
66
+ Nesting rules:
67
+
68
+ - The layout sits **above** the router. A page, an error page or a loading state never renders a layout.
69
+ - The transition goes **around** `<RouteCache>`, not inside it.
70
+ - `<Scroll vertical cover>` goes **inside** `<RouteCache>`, so each page keeps its own scroll.
71
+ - Chrome that keeps state or animates (a tab bar, a sidebar) stays in the layout, **outside** the cache.
72
+ - All pages in one stack must share one layout, because they share one `<RouteCache>`. To change the chrome for some pages (hide the tab bar), change a layout prop from the picker, for example `nav={false}`. Swap to another layout only between sections you do not move back and forth in, such as log-in and the main app.
73
+
74
+ ```tsx
75
+ import { useStore } from "shelving/react";
76
+ import {
77
+ App, AppLayout, Catcher, DialogsContext, Dialogs, ErrorPage, FixedLayout, HorizontalTransition,
78
+ Navigation, Notices, PageLoader, requireMetaURL, RouteCache, Router, type ErrorProps, type Routes,
79
+ Scroll, StackButton,
80
+ } from "shelving/ui";
81
+
82
+ const STACKS = ["/home", "/discover", "/profile"] as const;
83
+
84
+ /** 1–2. Contexts and the app-level catcher. No layout here. */
85
+ export function MyApp() {
86
+ const session = useStore(SESSION).value;
87
+ return (
88
+ <App key={session?.id ?? "out"} app="My app" root="https://example.com/">
89
+ <Navigation stacks={STACKS} stack="/home">
90
+ <DialogsContext>
91
+ <Catcher as={AppError}>
92
+ <Shell signedIn={!!session} />
93
+ </Catcher>
94
+ <Dialogs />
95
+ <Notices />
96
+ </DialogsContext>
97
+ </Navigation>
98
+ </App>
99
+ );
100
+ }
101
+
102
+ /** 3–4. Pick the layout. Plain React, so any rule works. */
103
+ function Shell({ signedIn }: { signedIn: boolean }) {
104
+ const { path } = requireMetaURL();
105
+ if (!signedIn) return <FixedLayout><Content routes={LOGIN_ROUTES} /></FixedLayout>;
106
+ return (
107
+ <AppLayout nav={path.startsWith("/squad/") ? false : <StackBar />}>
108
+ <Content routes={ROUTES} />
109
+ </AppLayout>
110
+ );
111
+ }
112
+
113
+ /** 5. The content of a layout's slot. */
114
+ function Content({ routes }: { routes: Routes }) {
115
+ return (
116
+ <HorizontalTransition>
117
+ <RouteCache>
118
+ <Scroll vertical cover>
119
+ <PageLoader>
120
+ <Router routes={routes} />
121
+ </PageLoader>
122
+ </Scroll>
123
+ </RouteCache>
124
+ </HorizontalTransition>
125
+ );
126
+ }
127
+
128
+ /** The tab bar, in the layout, outside the cache. */
129
+ function StackBar() {
130
+ return <>
131
+ <StackButton stack="/home" title="Home"><HomeIcon /></StackButton>
132
+ <StackButton stack="/discover" title="Discover"><SearchIcon /></StackButton>
133
+ <StackButton stack="/profile" title="Profile"><ProfileIcon /></StackButton>
134
+ </>;
135
+ }
136
+
137
+ /** An error outside every layout: the app picks one here. */
138
+ function AppError({ reason }: ErrorProps) {
139
+ return (
140
+ <FixedLayout>
141
+ <Scroll vertical cover>
142
+ <ErrorPage reason={reason} />
143
+ </Scroll>
144
+ </FixedLayout>
145
+ );
146
+ }
147
+ ```
148
+
149
+ Layouts are optional. With no layout, the document body scrolls, which is fine for a simple site. Use a layout when the app scrolls inside its own boxes: it locks the body and gives a content slot. Every layout is a frame: none of them scroll or centre. A page centres its own content, for example with `<Block height="full" middle width="narrow">`.
150
+
53
151
  For a documentation site, hand an extracted tree to `<TreeApp>` instead — see the `shelving/extract` guide.
@@ -32,8 +32,6 @@ export interface ClickableProps extends OptionalChildProps {
32
32
  title?: string | undefined;
33
33
  /** Whether this is the selected item in a group. Sets `aria-pressed` on a `<button>`, or `aria-current` on an `<a>`. */
34
34
  selected?: boolean | undefined;
35
- /** If `href` is present, then `<Navigation>` opens the link with a back transition. Use it for a "back to" link. Sets `data-back` on the `<a>`. */
36
- back?: boolean | undefined;
37
35
  }
38
36
  /**
39
37
  * Props for a clickable that also accepts a `className` for styling.
@@ -62,7 +60,7 @@ export declare function Clickable(props: StylableClickableProps): ReactElement;
62
60
  * @example <LinkClickable href="/about" className="link">About</LinkClickable>
63
61
  * @see https://shelving.cc/ui/LinkClickable
64
62
  */
65
- export declare function LinkClickable({ href, disabled, target, download, title, selected, back, children, className, }: StylableClickableProps): ReactElement;
63
+ export declare function LinkClickable({ href, disabled, target, download, title, selected, children, className, }: StylableClickableProps): ReactElement;
66
64
  /**
67
65
  * Render a `<button>` element that runs its `onClick` handler through a `BusyStore` and shows a loading spinner while busy.
68
66
  * - Notifies the user of the handler's returned value (success) or thrown value (error).
@@ -30,13 +30,13 @@ export function Clickable(props) {
30
30
  * @example <LinkClickable href="/about" className="link">About</LinkClickable>
31
31
  * @see https://shelving.cc/ui/LinkClickable
32
32
  */
33
- export function LinkClickable({ href, disabled = !href, target, download, title, selected, back, children = "Go", className, }) {
33
+ export function LinkClickable({ href, disabled = !href, target, download, title, selected, children = "Go", className, }) {
34
34
  // Resolve `href` against the current page URL and site root so site-absolute paths (`/foo`) honour the base subfolder.
35
35
  const { url, root } = requireMeta();
36
36
  const link = disabled ? undefined : getLink(href, url, root);
37
37
  // Is this link "active" compared to the current URL?
38
38
  const active = isURLActive(link, url);
39
- return (_jsx("a", { href: link?.href, title: title, download: download, target: target, className: getClass(className) || undefined, "aria-current": active ? "page" : selected ? "true" : undefined, "data-back": back || undefined, children: children }));
39
+ return (_jsx("a", { href: link?.href, title: title, download: download, target: target, className: getClass(className) || undefined, "aria-current": active ? "page" : selected ? "true" : undefined, children: children }));
40
40
  }
41
41
  /**
42
42
  * Render a `<button>` element that runs its `onClick` handler through a `BusyStore` and shows a loading spinner while busy.
@@ -43,8 +43,6 @@ export interface ClickableProps extends OptionalChildProps {
43
43
  title?: string | undefined;
44
44
  /** Whether this is the selected item in a group. Sets `aria-pressed` on a `<button>`, or `aria-current` on an `<a>`. */
45
45
  selected?: boolean | undefined;
46
- /** If `href` is present, then `<Navigation>` opens the link with a back transition. Use it for a "back to" link. Sets `data-back` on the `<a>`. */
47
- back?: boolean | undefined;
48
46
  }
49
47
 
50
48
  /**
@@ -90,7 +88,6 @@ export function LinkClickable({
90
88
  download,
91
89
  title,
92
90
  selected,
93
- back,
94
91
  children = "Go",
95
92
  className,
96
93
  }: StylableClickableProps): ReactElement {
@@ -109,7 +106,6 @@ export function LinkClickable({
109
106
  target={target}
110
107
  className={getClass(className) || undefined}
111
108
  aria-current={active ? "page" : selected ? "true" : undefined}
112
- data-back={back || undefined}
113
109
  >
114
110
  {children}
115
111
  </a>
@@ -3,8 +3,11 @@ import { App } from "../app/App.js";
3
3
  import { SidebarLayout } from "../layout/SidebarLayout.js";
4
4
  import { Menu, MenuItem } from "../menu/Menu.js";
5
5
  import { PageCatcher } from "../misc/Catcher.js";
6
+ import { PageLoader } from "../misc/Loader.js";
6
7
  import { Navigation } from "../router/Navigation.js";
8
+ import { RouteCache } from "../router/RouteCache.js";
7
9
  import { Router } from "../router/Router.js";
10
+ import { Scroll } from "../style/Scroll.js";
8
11
  import { TreeProvider } from "../tree/TreeContext.js";
9
12
  import { TreeRouter } from "../tree/TreeRouter.js";
10
13
  import { TreeSidebar } from "../tree/TreeSidebar.js";
@@ -22,6 +25,6 @@ import { PLAYGROUND_PAGE_PATH } from "./playground.js";
22
25
  export function DocumentationApp({ tree, routes = {
23
26
  "/search": DocumentationSearchPage,
24
27
  }, sidebar = (_jsx(TreeSidebar, { children: _jsxs(Menu, { small: true, children: [_jsx(MenuItem, { href: "/search", children: "Search" }), _jsx(MenuItem, { href: `/${PLAYGROUND_PAGE_PATH}`, children: "Playground" })] }) })), ...meta }) {
25
- const layout = (_jsx(SidebarLayout, { sidebar: sidebar, children: _jsx(TreeRouter, { fallback: _jsx(Router, { routes: routes }) }) }));
28
+ const layout = (_jsx(SidebarLayout, { sidebar: sidebar, children: _jsx(RouteCache, { children: _jsx(Scroll, { vertical: true, cover: true, children: _jsx(PageLoader, { children: _jsx(TreeRouter, { fallback: _jsx(Router, { routes: routes }) }) }) }) }) }));
26
29
  return (_jsx(App, { ...meta, children: _jsx(Navigation, { children: _jsx(PageCatcher, { children: _jsx(TreeProvider, { tree: tree, children: _jsx(Router, { routes: { [`/${PLAYGROUND_PAGE_PATH}`]: DocumentationPlaygroundPage }, fallback: layout }) }) }) }) }));
27
30
  }
@@ -3,8 +3,11 @@ import { App } from "../app/App.js";
3
3
  import { SidebarLayout } from "../layout/SidebarLayout.js";
4
4
  import { Menu, MenuItem } from "../menu/Menu.js";
5
5
  import { PageCatcher } from "../misc/Catcher.js";
6
+ import { PageLoader } from "../misc/Loader.js";
6
7
  import { Navigation } from "../router/Navigation.js";
8
+ import { RouteCache } from "../router/RouteCache.js";
7
9
  import { Router } from "../router/Router.js";
10
+ import { Scroll } from "../style/Scroll.js";
8
11
  import type { TreeAppProps } from "../tree/TreeApp.js";
9
12
  import { TreeProvider } from "../tree/TreeContext.js";
10
13
  import { TreeRouter } from "../tree/TreeRouter.js";
@@ -38,7 +41,13 @@ export function DocumentationApp({
38
41
  }: TreeAppProps): ReactElement {
39
42
  const layout = (
40
43
  <SidebarLayout sidebar={sidebar}>
41
- <TreeRouter fallback={<Router routes={routes} />} />
44
+ <RouteCache>
45
+ <Scroll vertical cover>
46
+ <PageLoader>
47
+ <TreeRouter fallback={<Router routes={routes} />} />
48
+ </PageLoader>
49
+ </Scroll>
50
+ </RouteCache>
42
51
  </SidebarLayout>
43
52
  );
44
53
  return (
@@ -0,0 +1,21 @@
1
+ import type { ReactElement, ReactNode } from "react";
2
+ import type { OptionalChildProps } from "../util/props.js";
3
+ /**
4
+ * Props for `<AppLayout>`: the `nav` bar content and the content slot `children`.
5
+ *
6
+ * @see https://shelving.cc/ui/AppLayoutProps
7
+ */
8
+ export interface AppLayoutProps extends OptionalChildProps {
9
+ /** Items for the bar below the content, for example a `<StackButton>` for each tab. Set `false` (or leave it out) to show no bar. */
10
+ nav?: ReactNode;
11
+ }
12
+ /**
13
+ * Layout with a content slot above a bar of the app's main sections, like the tab bar of a phone app.
14
+ * - It is a frame only: the content slot does not scroll. Fill it with `<Scroll vertical cover>`, inside `<RouteCache>`, so each page scrolls in its own box.
15
+ * - The bar sits below the content slot, not over it, and it stays still while a page slides.
16
+ * - Set `nav={false}` to hide the bar, for example for a full-screen page. Change the prop in place (from the URL), so the layout and its page cache stay mounted.
17
+ *
18
+ * @kind component
19
+ * @see https://shelving.cc/ui/AppLayout
20
+ */
21
+ export declare function AppLayout({ nav, children }: AppLayoutProps): ReactElement;
@@ -0,0 +1,18 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { getModuleClass } from "../util/css.js";
3
+ import LAYOUT_CSS from "./AppLayout.module.css";
4
+ const LAYOUT_CLASS = getModuleClass(LAYOUT_CSS, "layout");
5
+ const LAYOUT_CONTENT_CLASS = getModuleClass(LAYOUT_CSS, "content");
6
+ const LAYOUT_NAV_CLASS = getModuleClass(LAYOUT_CSS, "nav");
7
+ /**
8
+ * Layout with a content slot above a bar of the app's main sections, like the tab bar of a phone app.
9
+ * - It is a frame only: the content slot does not scroll. Fill it with `<Scroll vertical cover>`, inside `<RouteCache>`, so each page scrolls in its own box.
10
+ * - The bar sits below the content slot, not over it, and it stays still while a page slides.
11
+ * - Set `nav={false}` to hide the bar, for example for a full-screen page. Change the prop in place (from the URL), so the layout and its page cache stay mounted.
12
+ *
13
+ * @kind component
14
+ * @see https://shelving.cc/ui/AppLayout
15
+ */
16
+ export function AppLayout({ nav, children }) {
17
+ return (_jsxs("div", { className: LAYOUT_CLASS, children: [_jsx("main", { className: LAYOUT_CONTENT_CLASS, children: children }), nav ? _jsx("nav", { className: LAYOUT_NAV_CLASS, children: nav }) : null] }));
18
+ }
@@ -0,0 +1,57 @@
1
+ # AppLayout
2
+
3
+ A full-viewport layout with a content slot above a bar of the app's main sections, like the tab bar of a phone app. It is a frame only: it draws the bar and gives the content slot, and the app fills the slot.
4
+
5
+ **Things to know:**
6
+
7
+ - The content slot does not scroll. Fill it with `<Scroll vertical cover>` inside `<RouteCache>`, so each page scrolls in its own box and keeps its own scroll position.
8
+ - The bar sits below the content slot, not over it. So pages need no extra space at the bottom for the bar.
9
+ - The bar shows at every screen size.
10
+ - The content slot stays clear of the notch and the rounded screen corners, and the bar stays clear of the home bar (safe-area insets).
11
+ - Each item in the bar takes an equal share of its width, up to `--app-layout-nav-item-width` each.
12
+ - The bar is outside the page cache, so it has one copy. It keeps its state, and the CSS transitions of its items (an active tab) still play while a page slides.
13
+ - The bar has its own view-transition group, so it stays still while the page slides under it.
14
+ - Leave out `nav`, or set it to `false`, to show no bar. The content slot then fills the screen. To hide the bar for some pages, change the prop from the URL, so the layout and its page cache stay mounted: `nav={path.startsWith("/squad/") ? false : <StackBar />}`.
15
+ - Pages, error pages and loading states never render it themselves. Pick it above the router. See "Composing an app" on `<App>`.
16
+
17
+ ## Usage
18
+
19
+ ```tsx
20
+ import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll, StackButton } from "shelving/ui";
21
+
22
+ function StackBar() {
23
+ return <>
24
+ <StackButton stack="/home" title="Home"><HomeIcon /></StackButton>
25
+ <StackButton stack="/discover" title="Discover"><SearchIcon /></StackButton>
26
+ <StackButton stack="/profile" title="Profile"><ProfileIcon /></StackButton>
27
+ </>;
28
+ }
29
+
30
+ <AppLayout nav={<StackBar />}>
31
+ <HorizontalTransition>
32
+ <RouteCache>
33
+ <Scroll vertical cover>
34
+ <PageLoader>
35
+ <Router routes={ROUTES} />
36
+ </PageLoader>
37
+ </Scroll>
38
+ </RouteCache>
39
+ </HorizontalTransition>
40
+ </AppLayout>
41
+ ```
42
+
43
+ ## Styling
44
+
45
+ | Variable | Styles | Default |
46
+ |---|---|---|
47
+ | `--app-layout-background` | Page background while the layout is mounted | `var(--tint-100)` (white) |
48
+ | `--app-layout-color` | Text colour for the layout | `var(--tint-00)` (black) |
49
+ | `--app-layout-nav-background` | Bar fill (also fills the home-bar area below it) | `var(--tint-100)` (white) |
50
+ | `--app-layout-nav-color` | Bar text and icon colour | `var(--tint-00)` (black) |
51
+ | `--app-layout-nav-border` | Line above the bar | `var(--stroke-normal) solid var(--tint-90)` |
52
+ | `--app-layout-nav-shadow` | Shadow of the bar, for example a soft shadow above it | `none` |
53
+ | `--app-layout-nav-item-width` | Largest width of one bar item | `6rem` |
54
+
55
+ The bar keeps its items clear of the home bar and the rounded screen corners with safe-area insets.
56
+
57
+ **Global tokens it reads** — `--tint-00`, `--tint-90`, `--tint-100`, and `--stroke-normal`.