shelving 1.319.0 → 1.320.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 (42) hide show
  1. package/docs/llms-full.txt +171 -20
  2. package/docs/ui/Dialog.md +11 -8
  3. package/docs/ui/DialogProps.md +1 -1
  4. package/docs/ui/FADE_TRANSITION_CLASS.md +9 -0
  5. package/docs/ui/FadeTransition.md +13 -0
  6. package/docs/ui/Form.md +1 -1
  7. package/docs/ui/HorizontalTransition.md +20 -4
  8. package/docs/ui/Modal.md +1 -1
  9. package/docs/ui/Notices.md +1 -1
  10. package/docs/ui/SLIDE_DOWN_TRANSITION_CLASS.md +9 -0
  11. package/docs/ui/SLIDE_LEFT_TRANSITION_CLASS.md +9 -0
  12. package/docs/ui/SLIDE_RIGHT_TRANSITION_CLASS.md +9 -0
  13. package/docs/ui/SLIDE_UP_TRANSITION_CLASS.md +9 -0
  14. package/docs/ui/VerticalTransition.md +20 -4
  15. package/docs/ui/requestDialogClose.md +28 -0
  16. package/docs/ui.md +6 -0
  17. package/package.json +1 -1
  18. package/ui/dialog/Dialog.d.ts +15 -4
  19. package/ui/dialog/Dialog.js +19 -12
  20. package/ui/dialog/Dialog.md +9 -6
  21. package/ui/dialog/Dialog.tsx +20 -13
  22. package/ui/dialog/Modal.md +1 -1
  23. package/ui/form/Form.js +4 -3
  24. package/ui/form/Form.md +1 -1
  25. package/ui/form/Form.tsx +3 -2
  26. package/ui/notice/Notices.md +1 -1
  27. package/ui/notice/NoticesTransition.module.css +1 -1
  28. package/ui/transition/FadeTransition.d.ts +9 -1
  29. package/ui/transition/FadeTransition.js +12 -2
  30. package/ui/transition/FadeTransition.md +13 -0
  31. package/ui/transition/{FadeTransition.css → FadeTransition.module.css} +9 -2
  32. package/ui/transition/FadeTransition.tsx +13 -2
  33. package/ui/transition/HorizontalTransition.d.ts +18 -1
  34. package/ui/transition/HorizontalTransition.js +21 -2
  35. package/ui/transition/HorizontalTransition.md +20 -4
  36. package/ui/transition/{HorizontalTransition.css → HorizontalTransition.module.css} +17 -5
  37. package/ui/transition/HorizontalTransition.tsx +30 -2
  38. package/ui/transition/VerticalTransition.d.ts +18 -1
  39. package/ui/transition/VerticalTransition.js +21 -2
  40. package/ui/transition/VerticalTransition.md +20 -4
  41. package/ui/transition/{VerticalTransition.css → VerticalTransition.module.css} +17 -5
  42. package/ui/transition/VerticalTransition.tsx +25 -2
@@ -20205,6 +20205,7 @@ The components below are listed in the index following this page; this is the sh
20205
20205
  - [ButtonClickable()](ui/ButtonClickable.md): Render a <button> element that runs its onClick handler through a BusyStore and shows a loading spinner while busy.
20206
20206
  - [SpanClickable()](ui/SpanClickable.md): Render a non-interactive <span> element, used as the fallback when none of href, onClick or disabled is provided, e.g. a plain tag.
20207
20207
  - [SubmitButton()](ui/SubmitButton.md): Submit button for a form that disables itself and shows a spinner while the form is busy.
20208
+ - [requestDialogClose()](ui/requestDialogClose.md): Ask a <dialog> element to close, the same way as the Escape key.
20208
20209
  - [requireDialogs()](ui/requireDialogs.md): Read the current DialogsStore from the nearest <DialogsContext>.
20209
20210
  - [getDocumentationKindColor()](ui/getDocumentationKindColor.md): Get the raw colour variant for a documented symbol's kind, or undefined for an unknown kind.
20210
20211
  - [splitType()](ui/splitType.md): Split a type expression on | into its individual union members.
@@ -20536,6 +20537,11 @@ The components below are listed in the index following this page; this is the sh
20536
20537
  - [RouteContext](ui/RouteContext.md): React context holding the RouteState of the current page, provided by <Router> and <RouteCache>.
20537
20538
  - [STATUSES](ui/STATUSES.md): Tuple of the status names selectable via the status variant prop.
20538
20539
  - [TINT_CLASS](ui/TINT_CLASS.md): CSS class that (re)calculates the full ladder of tint shades from the current global tint colour.
20540
+ - [FADE_TRANSITION_CLASS](ui/FADE_TRANSITION_CLASS.md): View transition class that fades content in and out.
20541
+ - [SLIDE_RIGHT_TRANSITION_CLASS](ui/SLIDE_RIGHT_TRANSITION_CLASS.md): View transition class that slides content right: the new content comes in from the right and the old content leaves to the left.
20542
+ - [SLIDE_LEFT_TRANSITION_CLASS](ui/SLIDE_LEFT_TRANSITION_CLASS.md): View transition class that slides content left: the new content comes in from the left and the old content leaves to the right.
20543
+ - [SLIDE_DOWN_TRANSITION_CLASS](ui/SLIDE_DOWN_TRANSITION_CLASS.md): View transition class that slides content down: the new content comes in from the top and the old content leaves to the bottom.
20544
+ - [SLIDE_UP_TRANSITION_CLASS](ui/SLIDE_UP_TRANSITION_CLASS.md): View transition class that slides content up: the new content comes in from the bottom and the old content leaves to the top.
20539
20545
  - [TreeContext](ui/TreeContext.md): React context holding a flattened key → element map of the surrounding tree(s).
20540
20546
  - [TREE_CODE_RULE](ui/TREE_CODE_RULE.md): Markup rule that renders an inline code span as a tree-resolved <TreeLink> instead of a plain <code>.
20541
20547
  - [TREE_MARKUP_RULES](ui/TREE_MARKUP_RULES.md): Default markup rules with the inline-code rule swapped for TREE_CODE_RULE — every backtick span auto-links to its documented token.
@@ -23489,7 +23495,7 @@ Props for `<Dialog>` — optional `children` content and an `onClose` callback.
23489
23495
 
23490
23496
  | Property | Type | Description |
23491
23497
  | --- | --- | --- |
23492
- | `onClose` | `Callback` | Called when the user closes the dialog. It must unmount the `<Dialog>`, and it runs inside `startTransition()` so the dialog animates out. Optional. |
23498
+ | `onClose` | `Callback` | Called when the user asks to close the dialog. It must unmount the `<Dialog>`. Unmount it inside `startTransition()` to animate it out (`<Dialogs>` does this for you). Optional. |
23493
23499
 
23494
23500
 
23495
23501
  ---
@@ -23503,9 +23509,9 @@ Modal `<dialog>` element that opens on mount and includes a close button.
23503
23509
 
23504
23510
  - Opens via `showModal()` when mounted, and closes on a tap anywhere on it, the close button, or the Escape key.
23505
23511
  - A tap on a control (button, input, select, textarea, label) or inside a `<Modal>` panel does not close it. A tap on a link or a `<nav>` button always closes it.
23506
- - The whole dialog fades in and out in one view transition. A `<Modal>` pinned to an edge leaves that layer and slides in its own.
23512
+ - It knows nothing about transitions. It fades in and out only when the update that mounts or unmounts it is a transition, e.g. from `<Dialogs>` or your own `startTransition()`. A `<Modal>` pinned to an edge then slides in its own layer.
23507
23513
  - A change inside an open dialog (new content, a Suspense reveal) runs no view transition. The page ignores taps while one runs.
23508
- - With `onClose`, a close request calls `onClose()` and the dialog stays open until it unmounts, so the view transition can capture it as it leaves.
23514
+ - With `onClose`, it is declarative: a close request calls `onClose()`, and the dialog stays open until it unmounts, so a view transition can capture it as it leaves.
23509
23515
  - Children sit in one wrapper in normal block layout, `--dialog-width` wide and centred on the screen. Content taller than the screen scrolls from its top.
23510
23516
  - Wraps content in `<Suspense>` so lazy children can stream in.
23511
23517
 
@@ -23519,10 +23525,13 @@ A native `<dialog>` element opened in modal mode. It opens via `showModal()` whe
23519
23525
  - Children sit in one wrapper in normal block layout, so several children stack as they would on the page. The wrapper is `--dialog-width` wide (never wider than the screen) and centred on the screen. A centred `<Modal>` fills it. Content taller than the screen starts at the top, and the dialog scrolls.
23520
23526
  - While a dialog is open, the page behind it does not scroll. A scroll inside the dialog never passes on to the page.
23521
23527
  - `Dialog` only dims the page. Its text is white (`--tint-100`) so it reads on the dark overlay. Wrap the content in `<Modal>` to give it a panel with dark text on a light surface.
23522
- - `onClose` fires when the user closes the dialog. It must unmount the `Dialog`: clear the React state that mounts it, or (when pushed via a store) remove it from the list. `Dialog` calls `onClose` inside `startTransition()`, and the dialog stays open until it unmounts.
23523
- - The dialog animates with [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). The whole dialog fades in and out as one layer. A `<Modal>` pinned to an edge takes its own layer and slides.
23528
+ - `Dialog` is declarative. While it is mounted, it is open. When the user asks to close it, it calls `onClose` and stays open until it unmounts. `onClose` must unmount it: clear the React state that mounts it, or (when pushed via a store) remove it from the list.
23529
+ - To close a dialog from your own code, call `requestDialogClose()` on the `<dialog>` element, not `dialog.close()`. `requestDialogClose()` goes through `onClose` like the Escape key, so the dialog can animate out. `dialog.close()` closes it at once. A successful `<Form>` submit inside a dialog uses `requestDialogClose()`.
23530
+ - The dialog can animate with [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). The whole dialog fades in and out as one layer. A `<Modal>` pinned to an edge takes its own layer and slides.
23524
23531
  - A change inside an open dialog (new content, a Suspense reveal) runs no view transition, so the dialog never ignores a tap while its content changes. The page ignores taps while a view transition runs.
23525
- - A view transition only runs for a React transition update. `DialogsStore` and `onClose` do this for you. To animate a declarative `Dialog` as it opens, set the state that mounts it inside `startTransition()`.
23532
+ - `Dialog` knows nothing about transitions. React runs a view transition only for an update made inside `startTransition()`, so the code that mounts and unmounts the dialog decides if it animates:
23533
+ - `<Dialogs>` renders a `DialogsStore` inside transitions, so a dialog opened with `DialogsStore.show()` animates in and out for you.
23534
+ - A `Dialog` you mount yourself appears and goes at once, unless you set the state that mounts and unmounts it inside `startTransition()`. See the declarative example below.
23526
23535
  - A browser without view transitions shows and hides the dialog at once.
23527
23536
  - Pair with `DialogsStore`, `<DialogsContext>`, and `<Dialogs>` to open dialogs imperatively from anywhere in the app.
23528
23537
 
@@ -23546,9 +23555,9 @@ function ConfirmDelete({ onConfirm, onClose }: { onConfirm: () => void; onClose:
23546
23555
  );
23547
23556
  }
23548
23557
 
23549
- // In the parent. Open inside `startTransition()` so the dialog animates in.
23558
+ // In the parent. Open and close inside `startTransition()` so the dialog animates in and out.
23550
23559
  <button type="button" onClick={() => startTransition(() => setShowConfirm(true))}>Delete</button>
23551
- {showConfirm && <ConfirmDelete onConfirm={handleDelete} onClose={() => setShowConfirm(false)} />}
23560
+ {showConfirm && <ConfirmDelete onConfirm={handleDelete} onClose={() => startTransition(() => setShowConfirm(false))} />}
23552
23561
  ```
23553
23562
 
23554
23563
  ### Imperative
@@ -23571,7 +23580,7 @@ function DeleteButton({ onConfirm }: { onConfirm: () => void }) {
23571
23580
  }
23572
23581
  ```
23573
23582
 
23574
- `dialogs.show()` wraps the content in a `<Dialog>` for you, so you pass plain children rather than a `<Dialog>` element. It does not add a `<Modal>`; include one in the content if you want a panel.
23583
+ `dialogs.show()` wraps the content in a `<Dialog>` for you, so you pass plain children rather than a `<Dialog>` element. It does not add a `<Modal>`; include one in the content if you want a panel. `<Dialogs>` renders the list inside transitions, so the dialog animates in and out with no `startTransition()` of your own.
23575
23584
 
23576
23585
  ## Styling
23577
23586
 
@@ -23592,6 +23601,38 @@ The fade uses the `fade` class from `<FadeTransition>`, so `--fade-transition-du
23592
23601
 
23593
23602
 
23594
23603
 
23604
+ ---
23605
+
23606
+ # requestDialogClose()
23607
+
23608
+ - Kind: function
23609
+ - Import: `import { requestDialogClose } from "shelving/ui";`
23610
+
23611
+ Ask a `<dialog>` element to close, the same way as the Escape key.
23612
+ - Fires a cancelable `cancel` event, so a `<Dialog>` keeps itself open and calls its `onClose`. Its parent then unmounts it, and it can animate out.
23613
+ - Closes the dialog at once only if nothing cancels the event.
23614
+ - Use it instead of `dialog.close()`, which closes at once and fires no `cancel` event, so the dialog vanishes with no transition.
23615
+ - Not `requestClose()`: some browsers lack it, and Safari fires its `cancel` event as not cancelable. Both close the dialog at once.
23616
+
23617
+ ## Signatures
23618
+
23619
+ ```ts
23620
+ requestDialogClose(dialog: HTMLDialogElement): void
23621
+ ```
23622
+
23623
+ ## Parameters
23624
+
23625
+ | Param | Type | Description |
23626
+ | --- | --- | --- |
23627
+ | `dialog` | `HTMLDialogElement` | The `<dialog>` element to close. |
23628
+
23629
+ ## Examples
23630
+
23631
+ ```ts
23632
+ requestDialogClose(dialog) // Like pressing Escape.
23633
+ ```
23634
+
23635
+
23595
23636
  ---
23596
23637
 
23597
23638
  # DialogCloseButtonProps
@@ -23874,7 +23915,7 @@ The panel inside a `<Dialog>`. `<Dialog>` dims the page; `Modal` gives the conte
23874
23915
  - The `radius` variant sets the corner radius. On a pinned panel, corners that touch a screen edge stay square.
23875
23916
  - It has a `--shadow-large` drop shadow by default. Set `shadow="none"`, `shadow="small"` or `shadow="normal"` to change it, the same as on `<Card>`.
23876
23917
  - Set `top`, `right`, `bottom`, or `left` to pin the panel to that edge of the screen. A top or bottom panel is full width up to `--modal-width`, and centred on a wider screen. A left or right panel is full height. Use these for mobile menus, bottom sheets, and side menus.
23877
- - A centred panel fades in and out with its `<Dialog>`. A pinned panel slides in from its edge and out to it, in its own view-transition layer. With reduced motion, a pinned panel fades in place.
23918
+ - A centred panel fades in and out with its `<Dialog>`. A pinned panel slides in from its edge and out to it, in its own view-transition layer. With reduced motion, a pinned panel fades in place. `Modal` has no transition of its own: it animates only when its `<Dialog>` does (see `Dialog`).
23878
23919
 
23879
23920
  ## Usage
23880
23921
 
@@ -25848,7 +25889,7 @@ The entry point for shelving forms. `Form` creates a `FormStore` from a `schema`
25848
25889
  - If you provide no `children`, `Form` renders `<FormFields>` (one auto-input per schema property) followed by `<FormFooter>` (submit button + error message), so a usable form is one prop away.
25849
25890
  - Pass `data` to pre-populate an edit form. Pass `messages` (a string or dictionary) to seed initial field errors — useful when a server returns validation failures.
25850
25891
  - The whole `<fieldset>` is disabled while a submit is in flight, so inputs and buttons lock automatically.
25851
- - A successful submit inside a `<dialog>` closes the dialog automatically.
25892
+ - A successful submit inside a `<dialog>` closes the dialog automatically, through `requestDialogClose()`, so a `<Dialog>` can animate out.
25852
25893
  - Notices are surfaced from the `onSubmit` return/throw — see [Notices and error surfacing](#notices-and-error-surfacing) below.
25853
25894
 
25854
25895
  ## Usage
@@ -32138,7 +32179,7 @@ Renders the global list of active notices and subscribes to incoming `"notice"`
32138
32179
  - Notices auto-dismiss after a short delay unless they carry a `"loading"` status.
32139
32180
  - Backed by the `NOTICES` store singleton; for advanced use you can keep a reference to a notice to update or close it manually.
32140
32181
  - The list shows in the bottom-right corner. Set `position` to `"top-left"`, `"top-center"`, `"top-right"`, `"bottom-left"`, `"bottom-center"`, or `"bottom-right"` to choose a different place.
32141
- - Notices animate with [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). A new notice slides in from the side of its corner, and a closed notice slides out to that side. In a centred list, notices slide in and out from the top or bottom edge. The other notices move to their new places. A notice that changes in place (for example from loading to success) changes at once, with no animation.
32182
+ - Notices animate with [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). `Notices` renders the store inside transitions, so a notice animates with no `startTransition()` of your own. A single `<Notice>` knows nothing about transitions, the same as `<Dialog>`. A new notice slides in from the side of its corner, and a closed notice slides out to that side. In a centred list, notices slide in and out from the top or bottom edge. The other notices move to their new places. A notice that changes in place (for example from loading to success) changes at once, with no animation.
32142
32183
  - With reduced motion, notices fade in and out in place, and the others move at once. A browser without view transitions shows the changes at once.
32143
32184
 
32144
32185
  ## Usage
@@ -35493,6 +35534,19 @@ CollapseTransition(props: CollapseTransitionProps): ReactElement
35493
35534
  | `ReactElement` | |
35494
35535
 
35495
35536
 
35537
+ ---
35538
+
35539
+ # FADE_TRANSITION_CLASS
35540
+
35541
+ - Kind: constant
35542
+ - Import: `import { FADE_TRANSITION_CLASS } from "shelving/ui";`
35543
+
35544
+ View transition class that fades content in and out.
35545
+
35546
+ - Pass it to React's `<ViewTransition>` (for example `enter` or `exit`) to use this animation without the component.
35547
+ - Also adds the plain global `fade` class, so app CSS can target it with `::view-transition-group(.fade)`.
35548
+
35549
+
35496
35550
  ---
35497
35551
 
35498
35552
  # FadeTransitionProps
@@ -35541,6 +35595,19 @@ function Panel({ visible }: { visible: boolean }) {
35541
35595
  }
35542
35596
  ```
35543
35597
 
35598
+ ## Use the class without the component
35599
+
35600
+ The CSS is a CSS module, so its class names are hashed. To use the same animation on your own `<ViewTransition>`, import `FADE_TRANSITION_CLASS`. Each one also holds a plain global class name, so your CSS can still target it.
35601
+
35602
+ ```tsx
35603
+ import { ViewTransition } from "react";
35604
+ import { FADE_TRANSITION_CLASS } from "shelving/ui";
35605
+
35606
+ <ViewTransition enter={FADE_TRANSITION_CLASS} exit={FADE_TRANSITION_CLASS}>
35607
+ <div className="panel">…</div>
35608
+ </ViewTransition>
35609
+ ```
35610
+
35544
35611
  ## Styling
35545
35612
 
35546
35613
  | Variable | Styles | Default |
@@ -35569,6 +35636,32 @@ FadeTransition(props: FadeTransitionProps): ReactElement
35569
35636
  | `ReactElement` | |
35570
35637
 
35571
35638
 
35639
+ ---
35640
+
35641
+ # SLIDE_RIGHT_TRANSITION_CLASS
35642
+
35643
+ - Kind: constant
35644
+ - Import: `import { SLIDE_RIGHT_TRANSITION_CLASS } from "shelving/ui";`
35645
+
35646
+ View transition class that slides content right: the new content comes in from the right and the old content leaves to the left.
35647
+
35648
+ - Pass it to React's `<ViewTransition>` (for example `enter` or `exit`) to use this animation without the component.
35649
+ - Also adds the plain global `slide-right` class, so app CSS can target it with `::view-transition-group(.slide-right)`.
35650
+
35651
+
35652
+ ---
35653
+
35654
+ # SLIDE_LEFT_TRANSITION_CLASS
35655
+
35656
+ - Kind: constant
35657
+ - Import: `import { SLIDE_LEFT_TRANSITION_CLASS } from "shelving/ui";`
35658
+
35659
+ View transition class that slides content left: the new content comes in from the left and the old content leaves to the right.
35660
+
35661
+ - Pass it to React's `<ViewTransition>` (for example `enter` or `exit`) to use this animation without the component.
35662
+ - Also adds the plain global `slide-left` class, so app CSS can target it with `::view-transition-group(.slide-left)`.
35663
+
35664
+
35572
35665
  ---
35573
35666
 
35574
35667
  # HorizontalTransitionProps
@@ -35604,12 +35697,15 @@ A direction-aware `<Transition>` preset that slides its children horizontally
35604
35697
  - Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
35605
35698
  - The old and new content slide a full width apart, so they sit edge to edge and never overlap.
35606
35699
  - The slide is clipped to the element's own box (`overflow: clip` on the group), so it does not paint over the content around it.
35607
- - During the slide, the snapshots paint above fixed elements such as a bottom bar. To keep a fixed element on top, give it its own `view-transition-name` and put the slide groups below it:
35700
+ - During the slide, the snapshots paint above fixed elements such as a bottom bar. To keep a fixed element on top, give it its own `view-transition-name` and raise its group:
35608
35701
 
35609
35702
  ```css
35610
- ::view-transition-group(.slide-right),
35611
- ::view-transition-group(.slide-left) {
35612
- z-index: -1;
35703
+ .bottom-bar {
35704
+ view-transition-name: bottom-bar;
35705
+ }
35706
+
35707
+ ::view-transition-group(bottom-bar) {
35708
+ z-index: 1;
35613
35709
  }
35614
35710
  ```
35615
35711
 
@@ -35628,6 +35724,19 @@ import { HorizontalTransition, Navigation, Router } from "shelving/ui";
35628
35724
  </Navigation>
35629
35725
  ```
35630
35726
 
35727
+ ## Use the class without the component
35728
+
35729
+ The CSS is a CSS module, so its class names are hashed. To use the same animation on your own `<ViewTransition>`, import `SLIDE_RIGHT_TRANSITION_CLASS` and `SLIDE_LEFT_TRANSITION_CLASS`. Each one also holds a plain global class name, so your CSS can still target it.
35730
+
35731
+ ```tsx
35732
+ import { ViewTransition } from "react";
35733
+ import { SLIDE_RIGHT_TRANSITION_CLASS } from "shelving/ui";
35734
+
35735
+ <ViewTransition enter={SLIDE_RIGHT_TRANSITION_CLASS} exit={SLIDE_RIGHT_TRANSITION_CLASS}>
35736
+ <div className="panel">…</div>
35737
+ </ViewTransition>
35738
+ ```
35739
+
35631
35740
  ## Styling
35632
35741
 
35633
35742
  | Variable | Styles | Default |
@@ -35937,6 +36046,32 @@ setTransitionType("forward")
35937
36046
  ```
35938
36047
 
35939
36048
 
36049
+ ---
36050
+
36051
+ # SLIDE_DOWN_TRANSITION_CLASS
36052
+
36053
+ - Kind: constant
36054
+ - Import: `import { SLIDE_DOWN_TRANSITION_CLASS } from "shelving/ui";`
36055
+
36056
+ View transition class that slides content down: the new content comes in from the top and the old content leaves to the bottom.
36057
+
36058
+ - Pass it to React's `<ViewTransition>` (for example `enter` or `exit`) to use this animation without the component.
36059
+ - Also adds the plain global `slide-down` class, so app CSS can target it with `::view-transition-group(.slide-down)`.
36060
+
36061
+
36062
+ ---
36063
+
36064
+ # SLIDE_UP_TRANSITION_CLASS
36065
+
36066
+ - Kind: constant
36067
+ - Import: `import { SLIDE_UP_TRANSITION_CLASS } from "shelving/ui";`
36068
+
36069
+ View transition class that slides content up: the new content comes in from the bottom and the old content leaves to the top.
36070
+
36071
+ - Pass it to React's `<ViewTransition>` (for example `enter` or `exit`) to use this animation without the component.
36072
+ - Also adds the plain global `slide-up` class, so app CSS can target it with `::view-transition-group(.slide-up)`.
36073
+
36074
+
35940
36075
  ---
35941
36076
 
35942
36077
  # VerticalTransitionProps
@@ -35972,12 +36107,15 @@ A direction-aware `<Transition>` preset that slides its children vertically —
35972
36107
  - Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
35973
36108
  - The old and new content slide a full height apart, so they sit edge to edge and never overlap.
35974
36109
  - The slide is clipped to the element's own box (`overflow: clip` on the group), so it does not paint over the content around it.
35975
- - During the slide, the snapshots paint above fixed elements such as a bottom bar. To keep a fixed element on top, give it its own `view-transition-name` and put the slide groups below it:
36110
+ - During the slide, the snapshots paint above fixed elements such as a bottom bar. To keep a fixed element on top, give it its own `view-transition-name` and raise its group:
35976
36111
 
35977
36112
  ```css
35978
- ::view-transition-group(.slide-up),
35979
- ::view-transition-group(.slide-down) {
35980
- z-index: -1;
36113
+ .bottom-bar {
36114
+ view-transition-name: bottom-bar;
36115
+ }
36116
+
36117
+ ::view-transition-group(bottom-bar) {
36118
+ z-index: 1;
35981
36119
  }
35982
36120
  ```
35983
36121
 
@@ -35993,6 +36131,19 @@ import { VerticalTransition } from "shelving/ui";
35993
36131
  </VerticalTransition>
35994
36132
  ```
35995
36133
 
36134
+ ## Use the class without the component
36135
+
36136
+ The CSS is a CSS module, so its class names are hashed. To use the same animation on your own `<ViewTransition>`, import `SLIDE_DOWN_TRANSITION_CLASS` and `SLIDE_UP_TRANSITION_CLASS`. Each one also holds a plain global class name, so your CSS can still target it.
36137
+
36138
+ ```tsx
36139
+ import { ViewTransition } from "react";
36140
+ import { SLIDE_DOWN_TRANSITION_CLASS } from "shelving/ui";
36141
+
36142
+ <ViewTransition enter={SLIDE_DOWN_TRANSITION_CLASS} exit={SLIDE_DOWN_TRANSITION_CLASS}>
36143
+ <div className="panel">…</div>
36144
+ </ViewTransition>
36145
+ ```
36146
+
35996
36147
  ## Styling
35997
36148
 
35998
36149
  | Variable | Styles | Default |
package/docs/ui/Dialog.md CHANGED
@@ -7,9 +7,9 @@ Modal `<dialog>` element that opens on mount and includes a close button.
7
7
 
8
8
  - Opens via `showModal()` when mounted, and closes on a tap anywhere on it, the close button, or the Escape key.
9
9
  - A tap on a control (button, input, select, textarea, label) or inside a `<Modal>` panel does not close it. A tap on a link or a `<nav>` button always closes it.
10
- - The whole dialog fades in and out in one view transition. A `<Modal>` pinned to an edge leaves that layer and slides in its own.
10
+ - It knows nothing about transitions. It fades in and out only when the update that mounts or unmounts it is a transition, e.g. from `<Dialogs>` or your own `startTransition()`. A `<Modal>` pinned to an edge then slides in its own layer.
11
11
  - A change inside an open dialog (new content, a Suspense reveal) runs no view transition. The page ignores taps while one runs.
12
- - With `onClose`, a close request calls `onClose()` and the dialog stays open until it unmounts, so the view transition can capture it as it leaves.
12
+ - With `onClose`, it is declarative: a close request calls `onClose()`, and the dialog stays open until it unmounts, so a view transition can capture it as it leaves.
13
13
  - Children sit in one wrapper in normal block layout, `--dialog-width` wide and centred on the screen. Content taller than the screen scrolls from its top.
14
14
  - Wraps content in `<Suspense>` so lazy children can stream in.
15
15
 
@@ -23,10 +23,13 @@ A native `<dialog>` element opened in modal mode. It opens via `showModal()` whe
23
23
  - Children sit in one wrapper in normal block layout, so several children stack as they would on the page. The wrapper is `--dialog-width` wide (never wider than the screen) and centred on the screen. A centred `<Modal>` fills it. Content taller than the screen starts at the top, and the dialog scrolls.
24
24
  - While a dialog is open, the page behind it does not scroll. A scroll inside the dialog never passes on to the page.
25
25
  - `Dialog` only dims the page. Its text is white (`--tint-100`) so it reads on the dark overlay. Wrap the content in `<Modal>` to give it a panel with dark text on a light surface.
26
- - `onClose` fires when the user closes the dialog. It must unmount the `Dialog`: clear the React state that mounts it, or (when pushed via a store) remove it from the list. `Dialog` calls `onClose` inside `startTransition()`, and the dialog stays open until it unmounts.
27
- - The dialog animates with [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). The whole dialog fades in and out as one layer. A `<Modal>` pinned to an edge takes its own layer and slides.
26
+ - `Dialog` is declarative. While it is mounted, it is open. When the user asks to close it, it calls `onClose` and stays open until it unmounts. `onClose` must unmount it: clear the React state that mounts it, or (when pushed via a store) remove it from the list.
27
+ - To close a dialog from your own code, call `requestDialogClose()` on the `<dialog>` element, not `dialog.close()`. `requestDialogClose()` goes through `onClose` like the Escape key, so the dialog can animate out. `dialog.close()` closes it at once. A successful `<Form>` submit inside a dialog uses `requestDialogClose()`.
28
+ - The dialog can animate with [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). The whole dialog fades in and out as one layer. A `<Modal>` pinned to an edge takes its own layer and slides.
28
29
  - A change inside an open dialog (new content, a Suspense reveal) runs no view transition, so the dialog never ignores a tap while its content changes. The page ignores taps while a view transition runs.
29
- - A view transition only runs for a React transition update. `DialogsStore` and `onClose` do this for you. To animate a declarative `Dialog` as it opens, set the state that mounts it inside `startTransition()`.
30
+ - `Dialog` knows nothing about transitions. React runs a view transition only for an update made inside `startTransition()`, so the code that mounts and unmounts the dialog decides if it animates:
31
+ - `<Dialogs>` renders a `DialogsStore` inside transitions, so a dialog opened with `DialogsStore.show()` animates in and out for you.
32
+ - A `Dialog` you mount yourself appears and goes at once, unless you set the state that mounts and unmounts it inside `startTransition()`. See the declarative example below.
30
33
  - A browser without view transitions shows and hides the dialog at once.
31
34
  - Pair with `DialogsStore`, `<DialogsContext>`, and `<Dialogs>` to open dialogs imperatively from anywhere in the app.
32
35
 
@@ -50,9 +53,9 @@ function ConfirmDelete({ onConfirm, onClose }: { onConfirm: () => void; onClose:
50
53
  );
51
54
  }
52
55
 
53
- // In the parent. Open inside `startTransition()` so the dialog animates in.
56
+ // In the parent. Open and close inside `startTransition()` so the dialog animates in and out.
54
57
  <button type="button" onClick={() => startTransition(() => setShowConfirm(true))}>Delete</button>
55
- {showConfirm && <ConfirmDelete onConfirm={handleDelete} onClose={() => setShowConfirm(false)} />}
58
+ {showConfirm && <ConfirmDelete onConfirm={handleDelete} onClose={() => startTransition(() => setShowConfirm(false))} />}
56
59
  ```
57
60
 
58
61
  ### Imperative
@@ -75,7 +78,7 @@ function DeleteButton({ onConfirm }: { onConfirm: () => void }) {
75
78
  }
76
79
  ```
77
80
 
78
- `dialogs.show()` wraps the content in a `<Dialog>` for you, so you pass plain children rather than a `<Dialog>` element. It does not add a `<Modal>`; include one in the content if you want a panel.
81
+ `dialogs.show()` wraps the content in a `<Dialog>` for you, so you pass plain children rather than a `<Dialog>` element. It does not add a `<Modal>`; include one in the content if you want a panel. `<Dialogs>` renders the list inside transitions, so the dialog animates in and out with no `startTransition()` of your own.
79
82
 
80
83
  ## Styling
81
84
 
@@ -18,4 +18,4 @@ Props for `<Dialog>` — optional `children` content and an `onClose` callback.
18
18
 
19
19
  | Property | Type | Description |
20
20
  | --- | --- | --- |
21
- | `onClose` | `Callback` | Called when the user closes the dialog. It must unmount the `<Dialog>`, and it runs inside `startTransition()` so the dialog animates out. Optional. |
21
+ | `onClose` | `Callback` | Called when the user asks to close the dialog. It must unmount the `<Dialog>`. Unmount it inside `startTransition()` to animate it out (`<Dialogs>` does this for you). Optional. |
@@ -0,0 +1,9 @@
1
+ # FADE_TRANSITION_CLASS
2
+
3
+ - Kind: constant
4
+ - Import: `import { FADE_TRANSITION_CLASS } from "shelving/ui";`
5
+
6
+ View transition class that fades content in and out.
7
+
8
+ - Pass it to React's `<ViewTransition>` (for example `enter` or `exit`) to use this animation without the component.
9
+ - Also adds the plain global `fade` class, so app CSS can target it with `::view-transition-group(.fade)`.
@@ -27,6 +27,19 @@ function Panel({ visible }: { visible: boolean }) {
27
27
  }
28
28
  ```
29
29
 
30
+ ## Use the class without the component
31
+
32
+ The CSS is a CSS module, so its class names are hashed. To use the same animation on your own `<ViewTransition>`, import `FADE_TRANSITION_CLASS`. Each one also holds a plain global class name, so your CSS can still target it.
33
+
34
+ ```tsx
35
+ import { ViewTransition } from "react";
36
+ import { FADE_TRANSITION_CLASS } from "shelving/ui";
37
+
38
+ <ViewTransition enter={FADE_TRANSITION_CLASS} exit={FADE_TRANSITION_CLASS}>
39
+ <div className="panel">…</div>
40
+ </ViewTransition>
41
+ ```
42
+
30
43
  ## Styling
31
44
 
32
45
  | Variable | Styles | Default |
package/docs/ui/Form.md CHANGED
@@ -14,7 +14,7 @@ The entry point for shelving forms. `Form` creates a `FormStore` from a `schema`
14
14
  - If you provide no `children`, `Form` renders `<FormFields>` (one auto-input per schema property) followed by `<FormFooter>` (submit button + error message), so a usable form is one prop away.
15
15
  - Pass `data` to pre-populate an edit form. Pass `messages` (a string or dictionary) to seed initial field errors — useful when a server returns validation failures.
16
16
  - The whole `<fieldset>` is disabled while a submit is in flight, so inputs and buttons lock automatically.
17
- - A successful submit inside a `<dialog>` closes the dialog automatically.
17
+ - A successful submit inside a `<dialog>` closes the dialog automatically, through `requestDialogClose()`, so a `<Dialog>` can animate out.
18
18
  - Notices are surfaced from the `onSubmit` return/throw — see [Notices and error surfacing](#notices-and-error-surfacing) below.
19
19
 
20
20
  ## Usage
@@ -14,12 +14,15 @@ A direction-aware `<Transition>` preset that slides its children horizontally
14
14
  - Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
15
15
  - The old and new content slide a full width apart, so they sit edge to edge and never overlap.
16
16
  - The slide is clipped to the element's own box (`overflow: clip` on the group), so it does not paint over the content around it.
17
- - During the slide, the snapshots paint above fixed elements such as a bottom bar. To keep a fixed element on top, give it its own `view-transition-name` and put the slide groups below it:
17
+ - During the slide, the snapshots paint above fixed elements such as a bottom bar. To keep a fixed element on top, give it its own `view-transition-name` and raise its group:
18
18
 
19
19
  ```css
20
- ::view-transition-group(.slide-right),
21
- ::view-transition-group(.slide-left) {
22
- z-index: -1;
20
+ .bottom-bar {
21
+ view-transition-name: bottom-bar;
22
+ }
23
+
24
+ ::view-transition-group(bottom-bar) {
25
+ z-index: 1;
23
26
  }
24
27
  ```
25
28
 
@@ -38,6 +41,19 @@ import { HorizontalTransition, Navigation, Router } from "shelving/ui";
38
41
  </Navigation>
39
42
  ```
40
43
 
44
+ ## Use the class without the component
45
+
46
+ The CSS is a CSS module, so its class names are hashed. To use the same animation on your own `<ViewTransition>`, import `SLIDE_RIGHT_TRANSITION_CLASS` and `SLIDE_LEFT_TRANSITION_CLASS`. Each one also holds a plain global class name, so your CSS can still target it.
47
+
48
+ ```tsx
49
+ import { ViewTransition } from "react";
50
+ import { SLIDE_RIGHT_TRANSITION_CLASS } from "shelving/ui";
51
+
52
+ <ViewTransition enter={SLIDE_RIGHT_TRANSITION_CLASS} exit={SLIDE_RIGHT_TRANSITION_CLASS}>
53
+ <div className="panel">…</div>
54
+ </ViewTransition>
55
+ ```
56
+
41
57
  ## Styling
42
58
 
43
59
  | Variable | Styles | Default |
package/docs/ui/Modal.md CHANGED
@@ -23,7 +23,7 @@ The panel inside a `<Dialog>`. `<Dialog>` dims the page; `Modal` gives the conte
23
23
  - The `radius` variant sets the corner radius. On a pinned panel, corners that touch a screen edge stay square.
24
24
  - It has a `--shadow-large` drop shadow by default. Set `shadow="none"`, `shadow="small"` or `shadow="normal"` to change it, the same as on `<Card>`.
25
25
  - Set `top`, `right`, `bottom`, or `left` to pin the panel to that edge of the screen. A top or bottom panel is full width up to `--modal-width`, and centred on a wider screen. A left or right panel is full height. Use these for mobile menus, bottom sheets, and side menus.
26
- - A centred panel fades in and out with its `<Dialog>`. A pinned panel slides in from its edge and out to it, in its own view-transition layer. With reduced motion, a pinned panel fades in place.
26
+ - A centred panel fades in and out with its `<Dialog>`. A pinned panel slides in from its edge and out to it, in its own view-transition layer. With reduced motion, a pinned panel fades in place. `Modal` has no transition of its own: it animates only when its `<Dialog>` does (see `Dialog`).
27
27
 
28
28
  ## Usage
29
29
 
@@ -17,7 +17,7 @@ Renders the global list of active notices and subscribes to incoming `"notice"`
17
17
  - Notices auto-dismiss after a short delay unless they carry a `"loading"` status.
18
18
  - Backed by the `NOTICES` store singleton; for advanced use you can keep a reference to a notice to update or close it manually.
19
19
  - The list shows in the bottom-right corner. Set `position` to `"top-left"`, `"top-center"`, `"top-right"`, `"bottom-left"`, `"bottom-center"`, or `"bottom-right"` to choose a different place.
20
- - Notices animate with [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). A new notice slides in from the side of its corner, and a closed notice slides out to that side. In a centred list, notices slide in and out from the top or bottom edge. The other notices move to their new places. A notice that changes in place (for example from loading to success) changes at once, with no animation.
20
+ - Notices animate with [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). `Notices` renders the store inside transitions, so a notice animates with no `startTransition()` of your own. A single `<Notice>` knows nothing about transitions, the same as `<Dialog>`. A new notice slides in from the side of its corner, and a closed notice slides out to that side. In a centred list, notices slide in and out from the top or bottom edge. The other notices move to their new places. A notice that changes in place (for example from loading to success) changes at once, with no animation.
21
21
  - With reduced motion, notices fade in and out in place, and the others move at once. A browser without view transitions shows the changes at once.
22
22
 
23
23
  ## Usage
@@ -0,0 +1,9 @@
1
+ # SLIDE_DOWN_TRANSITION_CLASS
2
+
3
+ - Kind: constant
4
+ - Import: `import { SLIDE_DOWN_TRANSITION_CLASS } from "shelving/ui";`
5
+
6
+ View transition class that slides content down: the new content comes in from the top and the old content leaves to the bottom.
7
+
8
+ - Pass it to React's `<ViewTransition>` (for example `enter` or `exit`) to use this animation without the component.
9
+ - Also adds the plain global `slide-down` class, so app CSS can target it with `::view-transition-group(.slide-down)`.
@@ -0,0 +1,9 @@
1
+ # SLIDE_LEFT_TRANSITION_CLASS
2
+
3
+ - Kind: constant
4
+ - Import: `import { SLIDE_LEFT_TRANSITION_CLASS } from "shelving/ui";`
5
+
6
+ View transition class that slides content left: the new content comes in from the left and the old content leaves to the right.
7
+
8
+ - Pass it to React's `<ViewTransition>` (for example `enter` or `exit`) to use this animation without the component.
9
+ - Also adds the plain global `slide-left` class, so app CSS can target it with `::view-transition-group(.slide-left)`.
@@ -0,0 +1,9 @@
1
+ # SLIDE_RIGHT_TRANSITION_CLASS
2
+
3
+ - Kind: constant
4
+ - Import: `import { SLIDE_RIGHT_TRANSITION_CLASS } from "shelving/ui";`
5
+
6
+ View transition class that slides content right: the new content comes in from the right and the old content leaves to the left.
7
+
8
+ - Pass it to React's `<ViewTransition>` (for example `enter` or `exit`) to use this animation without the component.
9
+ - Also adds the plain global `slide-right` class, so app CSS can target it with `::view-transition-group(.slide-right)`.
@@ -0,0 +1,9 @@
1
+ # SLIDE_UP_TRANSITION_CLASS
2
+
3
+ - Kind: constant
4
+ - Import: `import { SLIDE_UP_TRANSITION_CLASS } from "shelving/ui";`
5
+
6
+ View transition class that slides content up: the new content comes in from the bottom and the old content leaves to the top.
7
+
8
+ - Pass it to React's `<ViewTransition>` (for example `enter` or `exit`) to use this animation without the component.
9
+ - Also adds the plain global `slide-up` class, so app CSS can target it with `::view-transition-group(.slide-up)`.
@@ -14,12 +14,15 @@ A direction-aware `<Transition>` preset that slides its children vertically —
14
14
  - Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
15
15
  - The old and new content slide a full height apart, so they sit edge to edge and never overlap.
16
16
  - The slide is clipped to the element's own box (`overflow: clip` on the group), so it does not paint over the content around it.
17
- - During the slide, the snapshots paint above fixed elements such as a bottom bar. To keep a fixed element on top, give it its own `view-transition-name` and put the slide groups below it:
17
+ - During the slide, the snapshots paint above fixed elements such as a bottom bar. To keep a fixed element on top, give it its own `view-transition-name` and raise its group:
18
18
 
19
19
  ```css
20
- ::view-transition-group(.slide-up),
21
- ::view-transition-group(.slide-down) {
22
- z-index: -1;
20
+ .bottom-bar {
21
+ view-transition-name: bottom-bar;
22
+ }
23
+
24
+ ::view-transition-group(bottom-bar) {
25
+ z-index: 1;
23
26
  }
24
27
  ```
25
28
 
@@ -35,6 +38,19 @@ import { VerticalTransition } from "shelving/ui";
35
38
  </VerticalTransition>
36
39
  ```
37
40
 
41
+ ## Use the class without the component
42
+
43
+ The CSS is a CSS module, so its class names are hashed. To use the same animation on your own `<ViewTransition>`, import `SLIDE_DOWN_TRANSITION_CLASS` and `SLIDE_UP_TRANSITION_CLASS`. Each one also holds a plain global class name, so your CSS can still target it.
44
+
45
+ ```tsx
46
+ import { ViewTransition } from "react";
47
+ import { SLIDE_DOWN_TRANSITION_CLASS } from "shelving/ui";
48
+
49
+ <ViewTransition enter={SLIDE_DOWN_TRANSITION_CLASS} exit={SLIDE_DOWN_TRANSITION_CLASS}>
50
+ <div className="panel">…</div>
51
+ </ViewTransition>
52
+ ```
53
+
38
54
  ## Styling
39
55
 
40
56
  | Variable | Styles | Default |
@@ -0,0 +1,28 @@
1
+ # requestDialogClose()
2
+
3
+ - Kind: function
4
+ - Import: `import { requestDialogClose } from "shelving/ui";`
5
+
6
+ Ask a `<dialog>` element to close, the same way as the Escape key.
7
+ - Fires a cancelable `cancel` event, so a `<Dialog>` keeps itself open and calls its `onClose`. Its parent then unmounts it, and it can animate out.
8
+ - Closes the dialog at once only if nothing cancels the event.
9
+ - Use it instead of `dialog.close()`, which closes at once and fires no `cancel` event, so the dialog vanishes with no transition.
10
+ - Not `requestClose()`: some browsers lack it, and Safari fires its `cancel` event as not cancelable. Both close the dialog at once.
11
+
12
+ ## Signatures
13
+
14
+ ```ts
15
+ requestDialogClose(dialog: HTMLDialogElement): void
16
+ ```
17
+
18
+ ## Parameters
19
+
20
+ | Param | Type | Description |
21
+ | --- | --- | --- |
22
+ | `dialog` | `HTMLDialogElement` | The `<dialog>` element to close. |
23
+
24
+ ## Examples
25
+
26
+ ```ts
27
+ requestDialogClose(dialog) // Like pressing Escape.
28
+ ```