shelving 1.323.2 → 1.324.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.
- package/docs/guides/building-with-shelving.md +3 -3
- package/docs/llms-full.txt +345 -149
- package/docs/react/SequenceTransitionOptions.md +24 -0
- package/docs/react/useSequenceTransition.md +70 -0
- package/docs/react.md +2 -0
- package/docs/ui/BackButton.md +1 -1
- package/docs/ui/Head.md +1 -1
- package/docs/ui/HorizontalTransition.md +1 -1
- package/docs/ui/Image.md +3 -0
- package/docs/ui/Meta.md +2 -0
- package/docs/ui/Navigation.md +18 -17
- package/docs/ui/NavigationContext.md +2 -2
- package/docs/ui/NavigationDirection.md +12 -0
- package/docs/ui/NavigationEntryState.md +3 -3
- package/docs/ui/NavigationEvent.md +28 -0
- package/docs/ui/{NavigationStore → NavigationSequence}/back.md +6 -5
- package/docs/ui/NavigationSequence/committed.md +13 -0
- package/docs/ui/NavigationSequence/current.md +13 -0
- package/docs/ui/{NavigationStore → NavigationSequence}/forward.md +4 -4
- package/docs/ui/{NavigationStore → NavigationSequence}/history.md +3 -3
- package/docs/ui/{NavigationStore → NavigationSequence}/listen.md +3 -3
- package/docs/ui/NavigationSequence/publish.md +14 -0
- package/docs/ui/{NavigationStore → NavigationSequence}/replace.md +4 -4
- package/docs/ui/NavigationSequence.md +187 -0
- package/docs/ui/RouteCache.md +16 -15
- package/docs/ui/RouteCacheProps.md +1 -1
- package/docs/ui/Router.md +2 -2
- package/docs/ui/Transition.md +1 -1
- package/docs/ui/VerticalTransition.md +1 -1
- package/docs/ui/mergeMeta.md +1 -0
- package/docs/ui/requireContext.md +1 -1
- package/docs/ui/requireNavigation.md +3 -3
- package/docs/ui.md +6 -6
- package/package.json +1 -1
- package/react/index.d.ts +1 -0
- package/react/index.js +1 -0
- package/react/useSequenceTransition.d.ts +38 -0
- package/react/useSequenceTransition.js +44 -0
- package/ui/block/Image.d.ts +3 -0
- package/ui/block/Image.js +18 -1
- package/ui/block/Image.module.css +27 -0
- package/ui/block/Image.tsx +24 -1
- package/ui/page/Head.d.ts +1 -1
- package/ui/page/Head.js +9 -4
- package/ui/page/Head.tsx +8 -4
- package/ui/router/BackButton.js +6 -3
- package/ui/router/BackButton.md +1 -1
- package/ui/router/BackButton.tsx +6 -3
- package/ui/router/Navigation.d.ts +5 -5
- package/ui/router/Navigation.js +24 -49
- package/ui/router/Navigation.md +13 -12
- package/ui/router/Navigation.tsx +25 -59
- package/ui/router/NavigationContext.d.ts +7 -15
- package/ui/router/NavigationContext.js +4 -13
- package/ui/router/NavigationContext.tsx +7 -17
- package/ui/router/{NavigationStore.d.ts → NavigationSequence.d.ts} +93 -51
- package/ui/router/{NavigationStore.js → NavigationSequence.js} +132 -80
- package/ui/router/NavigationSequence.md +129 -0
- package/ui/router/{NavigationStore.test.ts → NavigationSequence.test.ts} +126 -61
- package/ui/router/{NavigationStore.tsx → NavigationSequence.tsx} +160 -92
- package/ui/router/RouteCache.d.ts +8 -7
- package/ui/router/RouteCache.js +34 -29
- package/ui/router/RouteCache.md +9 -8
- package/ui/router/RouteCache.tsx +39 -36
- package/ui/router/Router.d.ts +2 -2
- package/ui/router/Router.js +3 -5
- package/ui/router/Router.md +1 -1
- package/ui/router/Router.tsx +4 -5
- package/ui/router/StackButton.d.ts +1 -1
- package/ui/router/StackButton.js +5 -7
- package/ui/router/StackButton.tsx +6 -7
- package/ui/router/index.d.ts +1 -1
- package/ui/router/index.js +1 -1
- package/ui/router/index.ts +1 -1
- package/ui/transition/HorizontalTransition.md +1 -1
- package/ui/transition/Transition.md +1 -1
- package/ui/transition/VerticalTransition.md +1 -1
- package/ui/util/meta.d.ts +2 -0
- package/ui/util/meta.ts +2 -0
- package/ui/util/requireContext.md +1 -1
- package/docs/ui/NavigationPosition.md +0 -24
- package/docs/ui/NavigationPositionContext.md +0 -8
- package/docs/ui/NavigationStore.md +0 -164
- package/ui/router/NavigationStore.md +0 -110
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
# NavigationSequence
|
|
2
|
+
|
|
3
|
+
- Kind: class
|
|
4
|
+
- Import: `import { NavigationSequence } from "shelving/ui";`
|
|
5
|
+
- Extends: `DeferredSequence<NavigationEvent>`
|
|
6
|
+
|
|
7
|
+
Sequence of navigation events that drives browser history and keeps a stack of pages for each tab.
|
|
8
|
+
|
|
9
|
+
- It is not a store: it holds no "current page" for the UI. Each change of page (a move, a replace, or the browser back and forward buttons) publishes one `NavigationEvent`, and `<Navigation>` keeps the page it shows in its own state.
|
|
10
|
+
- `url`, `stack` and `ordinal` say where the browser history is now. The page on screen can differ for a moment, for example during a swipe-back preview. To read the page on screen, read `Meta`.
|
|
11
|
+
- `publish()` sends an event by hand, for example to show the page below during a swipe-back.
|
|
12
|
+
- With the browser Navigation API, each history entry saves a `NavigationEntryState`, and each stack is read from `navigation.entries()` when it is needed. Nothing else is kept.
|
|
13
|
+
- A page outside the listed stacks is floating: its stack is `null`. The floating stack has no root page and no tab.
|
|
14
|
+
- In a listed stack, ordinal `0` is always the stack's root path.
|
|
15
|
+
- Without the Navigation API (older browsers and server renders) there are no stacks: `stack` stays the starting stack, `history()` is empty, and `stack` arguments are ignored.
|
|
16
|
+
- Owned by `<Navigation>`. Read it with `requireNavigation()`.
|
|
17
|
+
|
|
18
|
+
The sequence of navigation events that drives browser history and keeps one stack of pages for each tab. It is not a store: it holds no "current page" for the UI. Each change of page publishes one `NavigationEvent`, and `<Navigation>` keeps the page it shows in its own state. `<Navigation>` owns it. Read it with `requireNavigation()`, and do not make your own.
|
|
19
|
+
|
|
20
|
+
**Things to know:**
|
|
21
|
+
|
|
22
|
+
- Each change of page (a link, a back button, a replace, or the browser back and forward buttons) publishes one `NavigationEvent`: `{ url, stack, ordinal, direction }`.
|
|
23
|
+
- A move has a `direction` (`"forward"` or `"back"`), so `<Navigation>` shows it in a view transition of that type. A replace has no `direction`, so it shows at once.
|
|
24
|
+
- To read the page on screen, read `Meta` (`requireMeta()` or `requireMetaURL()`), not the sequence. The two can differ for a moment, for example during a swipe-back.
|
|
25
|
+
- `NavigationSequence.url`, `NavigationSequence.stack` and `NavigationSequence.path` say where the browser history is now. `NavigationSequence.current()` returns the same as an event with no direction.
|
|
26
|
+
- `NavigationSequence.stacks` is the root path of each stack, in tab order, from the `stacks` prop on `<Navigation>`. `/` is a normal stack root, like any other path.
|
|
27
|
+
- A page that is not in a listed stack is **floating**: its stack is `null`. See [Floating pages](#floating-pages).
|
|
28
|
+
- In a listed stack, ordinal `0` is always the stack's root path. A deeper page always has the root below it.
|
|
29
|
+
- `NavigationSequence.history()` returns the pages in the current stack (or a given stack), root first.
|
|
30
|
+
- `NavigationSequence.publish()` sends an event by hand, for example to show the page below during a swipe-back. It returns a promise that resolves when `<Navigation>` has committed the event.
|
|
31
|
+
- Events sent in the same microtask merge: only the last one is shown.
|
|
32
|
+
- All URLs resolve against the sequence's `base`. Each method also takes a full same-origin URL.
|
|
33
|
+
- Without the browser Navigation API there is no stack history: `stack` stays the starting stack, `history()` returns `[]`, `ordinal` is `undefined`, and every `stack` argument is ignored. `forward()` and `back()` push a history entry, and `replace()` replaces it.
|
|
34
|
+
|
|
35
|
+
## Methods
|
|
36
|
+
|
|
37
|
+
| Method | What it does | Slide |
|
|
38
|
+
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
|
|
39
|
+
| `forward(href, stack?)` | Opens `href` as a new page on top of the stack. If `href` is the top page of another stack, it switches to that stack (a tab switch). If `href` is the current URL, it is a replace. | Forward. Across stacks, by tab order. |
|
|
40
|
+
| `back(href, stack?)` | Goes back to `href`. If `href` is in the stack, the stack goes back to it, and the pages above it leave the stack. If `href` is the root of the stack, the stack goes to its root. Otherwise `href` takes the place of the top page of the stack. If the browser refuses the Navigation API back, it uses `history.back()`. | Back |
|
|
41
|
+
| `replace(href, stack?)` | Changes the URL of the current page. The stack, the ordinal and the mounted page stay the same. No new history entry. With another `stack`, the page moves into that stack: at its root if `href` is the root, else on top of its pages. | None |
|
|
42
|
+
| `history(stack?)` | Returns the pages in `stack`, root first. | — |
|
|
43
|
+
| `current()` | Returns where the browser history is now, as an event with no direction. | — |
|
|
44
|
+
| `publish(event)` | Sends an event by hand. Resolves when `<Navigation>` has committed it. | The event's `direction` |
|
|
45
|
+
|
|
46
|
+
`stack` defaults to the current stack. Pass `null` to name the floating stack.
|
|
47
|
+
|
|
48
|
+
## Floating pages
|
|
49
|
+
|
|
50
|
+
A page changes stack only when you say so: with a `<StackButton>`, or with a `stack` argument to `forward()`, `back()` or `replace()`. Links never change stack. The page the app opens at starts in the `stack` set on `<Navigation>` (or the surrounding `<Meta>`), else it **floats**: its stack is `null`. For example: a deep link into the app, a fresh open of `/post/9`, or a login page.
|
|
51
|
+
|
|
52
|
+
- The floating stack is outside every tab. It has no root page and no `<StackButton>`, so no stack button is selected on a floating page.
|
|
53
|
+
- Links from a floating page push deeper in the floating stack, even a link to a stack root.
|
|
54
|
+
- To leave the floating stack, tap a `<StackButton>`, or name the stack. To move a page back into it, pass `null` as the `stack`.
|
|
55
|
+
- `<RouteCache>` gives floating pages no protection: they are dropped like any other page past `maxCached`.
|
|
56
|
+
- With no `stacks`, every page floats.
|
|
57
|
+
|
|
58
|
+
## Opening the app
|
|
59
|
+
|
|
60
|
+
- To select a tab when the app starts, set `stack` on `<Navigation>`. The app decides which stack the opening URL belongs to. After a reload, each history entry keeps the stack it had.
|
|
61
|
+
- A deep page the app opens at, in a listed stack, starts at ordinal 1, so the stack root is its parent. A `<StackButton>` or a back gesture then goes to the root. A stack root starts at ordinal 0.
|
|
62
|
+
- A `stack` that is not in `stacks` is ignored: the page floats.
|
|
63
|
+
|
|
64
|
+
For example, a login page sends the user home after they log in, and names the Home stack:
|
|
65
|
+
|
|
66
|
+
```tsx
|
|
67
|
+
const nav = requireNavigation();
|
|
68
|
+
nav.replace("/home", "/home");
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## How stacks work
|
|
72
|
+
|
|
73
|
+
The sequence saves a small state on each browser history entry: the `stack` the page is in, and its `ordinal` in that stack (`0` is the root). See `NavigationEntryState`. To read a stack, the sequence walks back through the browser history from the current entry. It takes the newest entry in that stack, then the newest earlier entry with a lower ordinal, and so on down to ordinal `0`.
|
|
74
|
+
|
|
75
|
+
Why ordinal? A browser history entry cannot be changed or removed. So when you go back in one stack while another stack's pages are after it in the history, the sequence cannot go back in the browser. It pushes a new entry for the page you went back to, at that page's ordinal. The pages that were above it now have a higher ordinal than the newest entry, so they are no longer in the stack.
|
|
76
|
+
|
|
77
|
+
For example, with tabs `/home` and `/profile`:
|
|
78
|
+
|
|
79
|
+
| Step | New history entry | Home stack | Profile stack |
|
|
80
|
+
| ------------------- | -------------------------- | ----------------------- | ------------- |
|
|
81
|
+
| Start at `/home` | `/home` (ordinal 0) | `/home` | — |
|
|
82
|
+
| Open a post | `/home/post/1` (ordinal 1) | `/home`, `/home/post/1` | — |
|
|
83
|
+
| Tap the Profile tab | `/profile` (ordinal 0) | `/home`, `/home/post/1` | `/profile` |
|
|
84
|
+
| Tap the Home tab | `/home/post/1` (ordinal 1) | `/home`, `/home/post/1` | `/profile` |
|
|
85
|
+
| Tap the back button | `/home` (ordinal 0) | `/home` | `/profile` |
|
|
86
|
+
|
|
87
|
+
When the page you go back to is the entry just before the current one, `back()` goes back in the browser history and pushes nothing.
|
|
88
|
+
|
|
89
|
+
The browser back and forward buttons walk the history entries one at a time, as usual. Each entry knows its stack and ordinal, so the stacks are always right and the slide goes the right way.
|
|
90
|
+
|
|
91
|
+
## Usage
|
|
92
|
+
|
|
93
|
+
```tsx
|
|
94
|
+
import { Button, requireNavigation } from "shelving/ui";
|
|
95
|
+
|
|
96
|
+
function LogoutButton() {
|
|
97
|
+
const nav = requireNavigation();
|
|
98
|
+
return <Button onClick={() => nav.replace("/login")}>Log out</Button>;
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Read the current stack in a component from `Meta`:
|
|
103
|
+
|
|
104
|
+
```tsx
|
|
105
|
+
import { requireMeta } from "shelving/ui";
|
|
106
|
+
|
|
107
|
+
function TabTitle() {
|
|
108
|
+
const { stack } = requireMeta();
|
|
109
|
+
return <h1>{stack === "/profile" ? "Profile" : "Home"}</h1>;
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Show the page below during a swipe-back. React runs the back transition, and the swipe scrubs it:
|
|
114
|
+
|
|
115
|
+
```tsx
|
|
116
|
+
const nav = requireNavigation();
|
|
117
|
+
const { stack = null, ordinal } = requireMetaURL();
|
|
118
|
+
const parent = ordinal ? nav.history(stack)[ordinal - 1] : undefined;
|
|
119
|
+
if (parent) {
|
|
120
|
+
// Start the swipe: show the page below with the back transition.
|
|
121
|
+
await nav.publish({ url: requireURL(parent, nav.base), stack, ordinal: ordinal - 1, direction: "back" });
|
|
122
|
+
// Release: go back for real. It publishes the same page, so it is skipped.
|
|
123
|
+
nav.back(parent);
|
|
124
|
+
// Or cancel: show the old page again, with no transition.
|
|
125
|
+
// await nav.publish({ ...from, direction: undefined });
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
List the pages in a stack (for example, for breadcrumbs):
|
|
130
|
+
|
|
131
|
+
```tsx
|
|
132
|
+
const nav = requireNavigation();
|
|
133
|
+
nav.history("/home"); // ["/home", "/home/post/1", "/home/post/1/comments"]
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Make a sequence by hand only in tests:
|
|
137
|
+
|
|
138
|
+
```tsx
|
|
139
|
+
import { NavigationSequence } from "shelving/ui";
|
|
140
|
+
|
|
141
|
+
// URL, root, starting stack, then the stacks in tab order.
|
|
142
|
+
const nav = new NavigationSequence("https://example.com/home", "https://example.com/", "/home", "/home", "/profile");
|
|
143
|
+
nav.forward("/home/post/1");
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
## Signatures
|
|
148
|
+
|
|
149
|
+
```ts
|
|
150
|
+
new NavigationSequence(url: PossibleURL = typeof window === "undefined" ? "/" : window.location.href, base?: PossibleURL, stack: AbsolutePath | null = null, ...stacks: AbsolutePath[])
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
## Parameters
|
|
154
|
+
|
|
155
|
+
| Param | Type | Description |
|
|
156
|
+
| --- | --- | --- |
|
|
157
|
+
| `url` | `PossibleURL` | Defaults to `typeof window === "undefined" ? "/" : window.location.href`. |
|
|
158
|
+
| `base` | `PossibleURL` | Optional. |
|
|
159
|
+
| `stack` | `AbsolutePath \| null` | Defaults to `null`. |
|
|
160
|
+
| `stacks` | `AbsolutePath[]` | |
|
|
161
|
+
|
|
162
|
+
## Returns
|
|
163
|
+
|
|
164
|
+
| Type | Description |
|
|
165
|
+
| --- | --- |
|
|
166
|
+
| `NavigationSequence` | |
|
|
167
|
+
|
|
168
|
+
## Properties
|
|
169
|
+
|
|
170
|
+
| Property | Type | Description |
|
|
171
|
+
| --- | --- | --- |
|
|
172
|
+
| `stacks` | `readonly AbsolutePath[]` | Root path of each stack, in tab order. With none, every page floats. Read only. |
|
|
173
|
+
| `base` | `ImmutableURL \| undefined` | Base URL of the app, used to resolve relative URLs and to work out paths. Read only. |
|
|
174
|
+
| `url` | `ImmutableURL` | URL the browser history is on now. Read only. |
|
|
175
|
+
| `stack` | `AbsolutePath \| null` | Root path of the stack the browser history is on now, or `null` for a floating page. Read only. |
|
|
176
|
+
| `path` | `AbsolutePath \| undefined` | Path of the current URL relative to the app root (without its `?query`), or `undefined` if the URL is outside the app. Read only. |
|
|
177
|
+
|
|
178
|
+
## Methods
|
|
179
|
+
|
|
180
|
+
- [NavigationSequence.current()](NavigationSequence/current.md): Where the browser history is now, as an event with no direction.
|
|
181
|
+
- [NavigationSequence.publish()](NavigationSequence/publish.md): Publish an event by hand, without changing history.
|
|
182
|
+
- [NavigationSequence.committed()](NavigationSequence/committed.md): Tell waiting publish() calls that <Navigation> has committed a page.
|
|
183
|
+
- [NavigationSequence.listen()](NavigationSequence/listen.md): Start listening to the browser (back, forward and swipe).
|
|
184
|
+
- [NavigationSequence.history()](NavigationSequence/history.md): Get the pages in a stack, root first, or every page in every stack.
|
|
185
|
+
- [NavigationSequence.forward()](NavigationSequence/forward.md): Go forward to a URL, as a link does.
|
|
186
|
+
- [NavigationSequence.back()](NavigationSequence/back.md): Go back to a URL, as a back button does.
|
|
187
|
+
- [NavigationSequence.replace()](NavigationSequence/replace.md): Replace the current URL, with no transition.
|
package/docs/ui/RouteCache.md
CHANGED
|
@@ -6,14 +6,14 @@
|
|
|
6
6
|
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.
|
|
7
7
|
|
|
8
8
|
- Put a page transition around it, and a `<Scroll vertical cover>` inside it, so each kept page scrolls in its own box.
|
|
9
|
-
- Keeps each page
|
|
10
|
-
- Each page is keyed by
|
|
11
|
-
-
|
|
12
|
-
- The root page and the
|
|
9
|
+
- Keeps each page mounted but hidden (with React's `<Activity>`), so going back to a page, or switching back to a tab, shows it exactly as you left it.
|
|
10
|
+
- Each page is keyed by the `stack` and `ordinal` in `Meta`, not by its URL. So `NavigationSequence.replace()` (a canonical URL, an in-page tab) keeps the same page mounted, and the same URL open in two tabs is two separate pages.
|
|
11
|
+
- It knows nothing about history. It only drops pages when it has more than `maxCached`: first the pages deeper than the current page in its stack (pages you went back from), then the least recently used. So after a back, a forward shows the page as you left it, and a cancelled swipe-back still has the page it started from.
|
|
12
|
+
- The root page and the last page you saw in each listed stack are never dropped. Floating pages (stack `null`) get no such protection.
|
|
13
13
|
- When the current page is deeper than its stack's root and the root page is not cached (for example after a deep link), the root page is rendered hidden, so a swipe-back can show it.
|
|
14
|
-
- Each kept page is frozen under its own `<MetaContext
|
|
14
|
+
- Each kept page is frozen under its own `<MetaContext>`, so the same `children` element renders a different page for each URL, and a hidden page never re-renders for another page's URL.
|
|
15
15
|
- `<Activity mode="hidden">` keeps a hidden page's state but unmounts its effects, so its subscriptions and timers pause and resume as it is hidden and shown.
|
|
16
|
-
-
|
|
16
|
+
- With no `ordinal` in `Meta` (older browsers, server renders), or with `maxCached` of `0`, it renders the current page directly with no cache.
|
|
17
17
|
|
|
18
18
|
A keep-alive cache for the pages in the navigation stacks. Put it in a layout's content slot, around a `<Scroll vertical cover>` box. It keeps each page in the stacks mounted but hidden (with React's [`<Activity>`](https://react.dev/reference/react/Activity)), so when you go back to a page, or switch back to a tab, the page is exactly as you left it: scroll position, toggles, searches, form input and focus.
|
|
19
19
|
|
|
@@ -21,21 +21,22 @@ Layouts do not include a cache. The app composes it, so it can also choose the t
|
|
|
21
21
|
|
|
22
22
|
**Things to know:**
|
|
23
23
|
|
|
24
|
-
- Each page is keyed by
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
- The root page and the
|
|
24
|
+
- Each page is keyed by the `stack` and `ordinal` in `Meta`, not by its URL. See `NavigationSequence` for how stacks work.
|
|
25
|
+
- It knows nothing about history. It drops pages only when it has more than `maxCached`: first the pages deeper than the current page in its stack (pages you went back from), then the least recently used.
|
|
26
|
+
- So after a back, the forward button shows the page as you left it, while the cache has room.
|
|
27
|
+
- The current page, the root page of each listed stack, and the last page you saw in each listed stack are never dropped. So each tab always shows the page you left, and always has its root below. Floating pages get no such protection.
|
|
28
|
+
- Keep `maxCached` at `2` or more, so a swipe-back can show the page below and still keep the page you are leaving.
|
|
28
29
|
- When the current page is deeper than its stack's root and the root page is not cached (for example after a deep link), the cache renders the root page hidden, so a swipe-back can show it. A hidden page runs no effects until it is shown.
|
|
29
|
-
- `
|
|
30
|
+
- `NavigationSequence.replace()` and `className="replace"` links keep the same page mounted. A replace to another URL for the same component (for example from `/post/1` to `/post/2`) keeps its state. To reset the state, wrap the page content in an element with a `key`, for example `<Fragment key={id}>`.
|
|
30
31
|
- The same URL open in two stacks is two separate pages.
|
|
31
32
|
- A form that makes something stays in the cache with its input. Clear it after a successful submit, so it is empty the next time you see it (see the example below).
|
|
32
|
-
- Each kept page is frozen under its own `<Meta
|
|
33
|
+
- Each kept page is frozen under its own `<Meta>`, so a hidden page never re-renders for another page's URL.
|
|
33
34
|
- `<Activity mode="hidden">` keeps a hidden page's state but unmounts its effects, so subscriptions, observers (for example infinite scroll) and timers pause and resume as the page is hidden and shown.
|
|
34
35
|
- **Nesting:** layout, then transition, then `<RouteCache>`, then `<Scroll vertical cover>`, then `<PageLoader>`, then `<Router>`. See the usage below.
|
|
35
36
|
- The scroll box goes **inside** the cache, so each kept page has its own scroll box and keeps its own scroll position. A scroll box outside the cache is shared by every page, so pages lose their scroll.
|
|
36
37
|
- Put a page `<Transition>` **around** the `<RouteCache>`, not inside it. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
|
|
37
38
|
- Keep the layout **outside** the cache. Chrome in the layout (a sidebar, a tab bar) then has one copy, keeps its own state, and plays its own CSS transitions. Chrome inside the cache gets one copy per kept page.
|
|
38
|
-
-
|
|
39
|
+
- With no `ordinal` in `Meta` (no browser Navigation API, or a server render), or with `maxCached={0}`, there is no cache: the current page renders directly and unmounts when you leave it.
|
|
39
40
|
|
|
40
41
|
## Usage
|
|
41
42
|
|
|
@@ -43,7 +44,7 @@ Layouts do not include a cache. The app composes it, so it can also choose the t
|
|
|
43
44
|
import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll } from "shelving/ui";
|
|
44
45
|
|
|
45
46
|
<AppLayout nav={<StackBar />}>
|
|
46
|
-
<HorizontalTransition>
|
|
47
|
+
<HorizontalTransition default="none">
|
|
47
48
|
<RouteCache>
|
|
48
49
|
<Scroll vertical cover>
|
|
49
50
|
<PageLoader>
|
|
@@ -102,7 +103,7 @@ RouteCache({ maxCached = 10, children }: RouteCacheProps): ReactNode
|
|
|
102
103
|
| Param | Type | Description |
|
|
103
104
|
| --- | --- | --- |
|
|
104
105
|
| `props` | `RouteCacheProps` | |
|
|
105
|
-
| `.maxCached` | `number \| undefined` | Number of pages to keep mounted (but hidden), so the whole state of each one (scroll position, toggles, searches, form input, focus) is still there when you come back to it. - The root page and the
|
|
106
|
+
| `.maxCached` | `number \| undefined` | Number of pages to keep mounted (but hidden), so the whole state of each one (scroll position, toggles, searches, form input, focus) is still there when you come back to it. - The root page and the last page you saw in each listed stack are never dropped, even past the limit, so a tab always shows the page you left and always has its root below. - Floating pages get no such protection. - Keep it at `2` or more, so a swipe-back can show the page below and still keep the page you are leaving. - Set to `0` (or less) to turn the cache off and unmount each page as you leave it. Read only. Defaults to `10`. |
|
|
106
107
|
| `.children` | `ReactNode` | The content to render for the current page and keep alive (hidden) for the other pages in the stacks. Read only. |
|
|
107
108
|
|
|
108
109
|
## Returns
|
|
@@ -18,5 +18,5 @@ Props for `<RouteCache>`: the `maxCached` size and the content `children` to kee
|
|
|
18
18
|
|
|
19
19
|
| Property | Type | Description |
|
|
20
20
|
| --- | --- | --- |
|
|
21
|
-
| `maxCached` | `number \| undefined` | Number of pages to keep mounted (but hidden), so the whole state of each one (scroll position, toggles, searches, form input, focus) is still there when you come back to it. - The root page and the
|
|
21
|
+
| `maxCached` | `number \| undefined` | Number of pages to keep mounted (but hidden), so the whole state of each one (scroll position, toggles, searches, form input, focus) is still there when you come back to it. - The root page and the last page you saw in each listed stack are never dropped, even past the limit, so a tab always shows the page you left and always has its root below. - Floating pages get no such protection. - Keep it at `2` or more, so a swipe-back can show the page below and still keep the page you are leaving. - Set to `0` (or less) to turn the cache off and unmount each page as you leave it. Read only. Defaults to `10`. |
|
|
22
22
|
| `children` | `ReactNode` | The content to render for the current page and keep alive (hidden) for the other pages in the stacks. Read only. |
|
package/docs/ui/Router.md
CHANGED
|
@@ -8,7 +8,7 @@ Match the current URL against `routes` and render the matched element.
|
|
|
8
8
|
- When `base` is set, the effective path is the URL after stripping the base prefix.
|
|
9
9
|
- Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
|
|
10
10
|
- Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
|
|
11
|
-
- Inside `<Navigation>` with the Navigation API, each page in a stack is a new page: a link mounts a new page, and `
|
|
11
|
+
- Inside `<Navigation>` with the Navigation API, each page in a stack is a new page: a link mounts a new page, and `NavigationSequence.replace()` keeps the same page mounted (it re-renders with the new URL). A replace that renders another component still mounts it fresh.
|
|
12
12
|
- Elsewhere, each path is a new page, so a component route remounts when the path changes.
|
|
13
13
|
- Returns `null` when there's no URL in context or the URL is outside the base.
|
|
14
14
|
|
|
@@ -20,7 +20,7 @@ A pure URL matcher: it reads the current URL from the surrounding `<Meta>` conte
|
|
|
20
20
|
- `<Router>` accepts `PossibleMeta` props (`url`, `base`, etc.) to override the surrounding context — this is how nested routers scope themselves.
|
|
21
21
|
- With a `base` set, the path used for matching is the URL after `matchURLPrefix()` strips the base prefix; URLs outside the base render as `null`.
|
|
22
22
|
- Pass `fallback` to control no-match behaviour. An explicit `null` renders nothing; leaving it `undefined` throws a `NotFoundError`.
|
|
23
|
-
- Inside `<Navigation>` with stacks, each page in a stack is a new page: a link mounts a new page, and `
|
|
23
|
+
- Inside `<Navigation>` with stacks, each page in a stack is a new page: a link mounts a new page, and `NavigationSequence.replace()` keeps the same page mounted (it re-renders with the new URL). Elsewhere each path is a new page.
|
|
24
24
|
- `<Router>` itself does not cache pages — wrap it in a `<RouteCache>` (with a `<Scroll vertical cover>` between them) to keep recently-visited pages mounted but hidden so back/forward navigation restores their state.
|
|
25
25
|
|
|
26
26
|
## Usage
|
package/docs/ui/Transition.md
CHANGED
|
@@ -15,7 +15,7 @@ The base View Transition wrapper. It wraps its children in React 19's `<ViewTran
|
|
|
15
15
|
|
|
16
16
|
- Set `default` for the base transition; `forward` and `back` default to it and let you pick a direction-aware variant. The class names must correspond to `::view-transition-old(.className)` / `::view-transition-new(.className)` rules in your CSS.
|
|
17
17
|
- Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`, from `Transition.module.css`).
|
|
18
|
-
- Direction is driven by the active view-transition type. `<Navigation>` sets it for each page change (`"forward"` for a link or `
|
|
18
|
+
- Direction is driven by the active view-transition type. `<Navigation>` sets it for each page change (`"forward"` for a link or `NavigationSequence.forward()`, `"back"` for the browser back button). For any other change, call `setTransitionType("forward")` (or `"back"`) inside a `startTransition()` callback; the variants read that type to choose the correct slide.
|
|
19
19
|
- React runs a view transition only for a transition update (`startTransition()`, `useDeferredValue()` or a Suspense reveal). A sync update, for example a `useStore()` change, swaps the content with no animation.
|
|
20
20
|
- The preset variants honour `prefers-reduced-motion: reduce` — positional movement (slides, collapse) is removed while opacity-only fades are kept (see each preset's page). Custom transition classes should ship their own `@media (prefers-reduced-motion: reduce)` override; `animation: none` on the `::view-transition-*` pseudo-elements makes the swap an instant cut while the DOM update still happens.
|
|
21
21
|
|
|
@@ -10,7 +10,7 @@ A direction-aware `<Transition>` preset that slides its children vertically —
|
|
|
10
10
|
**Things to know:**
|
|
11
11
|
|
|
12
12
|
- Slides down by default and when the type is `"forward"`; slides up when the type is `"back"`.
|
|
13
|
-
- Inside `<Navigation>` the direction is automatic: a link click or `
|
|
13
|
+
- Inside `<Navigation>` the direction is automatic: a link click or `NavigationSequence.forward()` sets the `"forward"` type, and a `className="back"` link or `NavigationSequence.back()` sets `"back"`. The browser back and forward buttons set the type from the page's place in its stack. `NavigationSequence.replace()` has no transition. Outside `<Navigation>`, set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback — see `<Transition>`.
|
|
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.
|
package/docs/ui/mergeMeta.md
CHANGED
|
@@ -24,6 +24,7 @@ mergeMeta(meta1: Meta, meta2: PossibleMeta, caller: AnyCaller = mergeMeta): Meta
|
|
|
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
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
26
|
| `.stack` | `AbsolutePath \| null \| 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 `null` for a floating page. Read only. Optional. |
|
|
27
|
+
| `.ordinal` | `number \| undefined` | Position of the current page in its stack, where `0` is the root. `<Navigation>` publishes it, and `<RouteCache>` and `<Router>` key each page by its stack and ordinal. `undefined` without the Navigation API. Read only. Optional. |
|
|
27
28
|
| `.app` | `string \| undefined` | Title of the entire application. Read only. Optional. |
|
|
28
29
|
| `.title` | `string \| undefined` | Title of the current page (set as `<title>` in `<Head>` Read only. Optional. |
|
|
29
30
|
| `.description` | `string \| undefined` | Description of the current page. Read only. Optional. |
|
|
@@ -21,7 +21,7 @@ Reads a React context and throws `RequiredError` if the value is `null` or `unde
|
|
|
21
21
|
```ts
|
|
22
22
|
import { requireContext } from "shelving/ui";
|
|
23
23
|
|
|
24
|
-
function requireNavigation():
|
|
24
|
+
function requireNavigation(): NavigationSequence {
|
|
25
25
|
return requireContext(NavigationContext, requireNavigation);
|
|
26
26
|
}
|
|
27
27
|
```
|
|
@@ -3,19 +3,19 @@
|
|
|
3
3
|
- Kind: function
|
|
4
4
|
- Import: `import { requireNavigation } from "shelving/ui";`
|
|
5
5
|
|
|
6
|
-
Read the current `
|
|
6
|
+
Read the current `NavigationSequence` from context, throwing if used outside `<Navigation>`.
|
|
7
7
|
|
|
8
8
|
## Signatures
|
|
9
9
|
|
|
10
10
|
```ts
|
|
11
|
-
requireNavigation():
|
|
11
|
+
requireNavigation(): NavigationSequence
|
|
12
12
|
```
|
|
13
13
|
|
|
14
14
|
## Returns
|
|
15
15
|
|
|
16
16
|
| Type | Description |
|
|
17
17
|
| --- | --- |
|
|
18
|
-
| `
|
|
18
|
+
| `NavigationSequence` | The current `NavigationSequence`. |
|
|
19
19
|
|
|
20
20
|
## Throws
|
|
21
21
|
|
package/docs/ui.md
CHANGED
|
@@ -265,7 +265,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
265
265
|
- [requireMetaURL()](ui/requireMetaURL.md): Read the current Meta context and derive URL helpers (path and params) from its url.
|
|
266
266
|
- [getTagClass()](ui/getTagClass.md): Build the combined className string for a <Tag> from its styling variants.
|
|
267
267
|
- [Message()](ui/Message.md): Status-coloured paragraph used for inline feedback messages.
|
|
268
|
-
- [requireNavigation()](ui/requireNavigation.md): Read the current
|
|
268
|
+
- [requireNavigation()](ui/requireNavigation.md): Read the current NavigationSequence from context, throwing if used outside <Navigation>.
|
|
269
269
|
- [getBlockClass()](ui/getBlockClass.md): Get the combined className string for a block from its styling variants.
|
|
270
270
|
- [getColorClass()](ui/getColorClass.md): CSS class that applies color tinting to an element.
|
|
271
271
|
- [getDurationClass()](ui/getDurationClass.md): Get the transition-duration class for a component from its duration variant prop.
|
|
@@ -324,7 +324,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
324
324
|
- [FormStore](ui/FormStore.md): Reactive store holding the current (possibly partial and invalid) value of a form, plus its field messages.
|
|
325
325
|
- [NoticesStore](ui/NoticesStore.md): Store holding the live list of NoticeStore notices currently shown.
|
|
326
326
|
- [NoticeStore](ui/NoticeStore.md): Store holding a single notice's content and status, owned by a NoticesStore.
|
|
327
|
-
- [
|
|
327
|
+
- [NavigationSequence](ui/NavigationSequence.md): Sequence of navigation events that drives browser history and keeps a stack of pages for each tab.
|
|
328
328
|
|
|
329
329
|
## Interfaces
|
|
330
330
|
|
|
@@ -461,8 +461,8 @@ The components below are listed in the index following this page; this is the sh
|
|
|
461
461
|
- [PageProps](ui/PageProps.md): Props for <Page> — per-page Meta (title, description, etc.) plus the page children.
|
|
462
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
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
|
|
465
|
-
- [
|
|
464
|
+
- [NavigationEntryState](ui/NavigationEntryState.md): State that NavigationSequence saves on each browser history entry.
|
|
465
|
+
- [NavigationEvent](ui/NavigationEvent.md): One change of page, published by NavigationSequence.
|
|
466
466
|
- [RouteCacheProps](ui/RouteCacheProps.md): Props for <RouteCache>: the maxCached size and the content children to keep alive for each page in the stacks.
|
|
467
467
|
- [RouterProps](ui/RouterProps.md): Props for <Router> — the routes to match against plus an optional fallback.
|
|
468
468
|
- [StackButtonProps](ui/StackButtonProps.md): Props for <StackButton>: the stack it opens, plus the usual Button props except href and onClick.
|
|
@@ -518,6 +518,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
518
518
|
- [TextFormatter](ui/TextFormatter.md): Formats a string for display in a text input.
|
|
519
519
|
- [Mapping](ui/Mapping.md): Dispatch table from a JSX.IntrinsicElements key to a renderer component.
|
|
520
520
|
- [NoticesPosition](ui/NoticesPosition.md): Place on the screen where <Notices> shows the list of notices: a corner, or the centre of the top or bottom edge.
|
|
521
|
+
- [NavigationDirection](ui/NavigationDirection.md): Direction of a move in a NavigationEvent: "forward" or "back".
|
|
521
522
|
- [RouteProps](ui/RouteProps.md): Props for a component that works as a route in the router.
|
|
522
523
|
- [RouteComponent](ui/RouteComponent.md): React component usable as a route value — a function or class component accepting RouteProps.
|
|
523
524
|
- [Route](ui/Route.md): Valid route values:
|
|
@@ -567,8 +568,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
567
568
|
- [EMPTY_LOADING](ui/EMPTY_LOADING.md): Loading spinner in an <Empty>, for a list or form that is still loading. The empty message replaces it in the same place.
|
|
568
569
|
- [LOADING_NOTICE](ui/LOADING_NOTICE.md): Shared loading <Notice> element showing the loading spinner.
|
|
569
570
|
- [NOTICES](ui/NOTICES.md): Global NoticesStore shown by <Notices>, accepting any of the default statuses.
|
|
570
|
-
- [NavigationContext](ui/NavigationContext.md): React context holding the current
|
|
571
|
-
- [NavigationPositionContext](ui/NavigationPositionContext.md): React context holding where the app is in its stacks, published by <Navigation> with each URL change.
|
|
571
|
+
- [NavigationContext](ui/NavigationContext.md): React context holding the current NavigationSequence, provided by <Navigation>.
|
|
572
572
|
- [STATUSES](ui/STATUSES.md): Tuple of the status names selectable via the status variant prop.
|
|
573
573
|
- [TINT_CLASS](ui/TINT_CLASS.md): CSS class that (re)calculates the full ladder of tint shades from the current global tint colour.
|
|
574
574
|
- [FADE_TRANSITION_CLASS](ui/FADE_TRANSITION_CLASS.md): View transition class that fades content in and out.
|
package/package.json
CHANGED
package/react/index.d.ts
CHANGED
package/react/index.js
CHANGED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Options for `useSequenceTransition()`.
|
|
3
|
+
*
|
|
4
|
+
* @see https://shelving.cc/react/SequenceTransitionOptions
|
|
5
|
+
*/
|
|
6
|
+
export interface SequenceTransitionOptions<T> {
|
|
7
|
+
/**
|
|
8
|
+
* Read the current value.
|
|
9
|
+
* - Called for the first render, and again when the subscription starts, to catch up on values sent before it started.
|
|
10
|
+
*/
|
|
11
|
+
readonly current: () => T;
|
|
12
|
+
/**
|
|
13
|
+
* Transition type for a value, or a fixed type for every value.
|
|
14
|
+
* - A value with a type is set inside `startTransition()` with that type, so a `<ViewTransition>` can animate it.
|
|
15
|
+
* - A value with no type (`undefined` or `null`) is set at once, with no transition.
|
|
16
|
+
*/
|
|
17
|
+
readonly transition?: string | ((value: T) => string | null | undefined) | undefined;
|
|
18
|
+
/**
|
|
19
|
+
* Is a new value the same as the shown value? A value that is the same is skipped, so it starts no second transition.
|
|
20
|
+
*
|
|
21
|
+
* @default Object.is
|
|
22
|
+
*/
|
|
23
|
+
readonly equal?: ((a: T, b: T) => boolean) | undefined;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Subscribe to an async iterable, and set each value it yields inside a React transition.
|
|
27
|
+
* - Like `useSequence()`, but each value is set with `setState()` inside `startTransition()`, with a transition type, so a `<ViewTransition>` runs for it.
|
|
28
|
+
* - It uses `useState()` and not `useSyncExternalStore()`, because React always renders a `useSyncExternalStore()` update at once, outside any transition.
|
|
29
|
+
* - The transition type is shared by the whole React root: the next transition commit takes every type that is waiting.
|
|
30
|
+
*
|
|
31
|
+
* @param sequence An object implementing the `AsyncIterable` interface.
|
|
32
|
+
* - Subscription is recreated every time this value changes.
|
|
33
|
+
* - Memoise this value to persist the subscription for the lifetime of the component.
|
|
34
|
+
* @returns The value shown now.
|
|
35
|
+
* @throws unknown Re-throws (during render) any error thrown by the sequence, for an error boundary to catch.
|
|
36
|
+
* @see https://shelving.cc/react/useSequenceTransition
|
|
37
|
+
*/
|
|
38
|
+
export declare function useSequenceTransition<T>(sequence: AsyncIterable<T>, options: SequenceTransitionOptions<T>): T;
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
/// <reference types="react/canary" />
|
|
2
|
+
import { addTransitionType, startTransition, useEffect, useRef, useState } from "react";
|
|
3
|
+
import { runSequence } from "../util/sequence.js";
|
|
4
|
+
/**
|
|
5
|
+
* Subscribe to an async iterable, and set each value it yields inside a React transition.
|
|
6
|
+
* - Like `useSequence()`, but each value is set with `setState()` inside `startTransition()`, with a transition type, so a `<ViewTransition>` runs for it.
|
|
7
|
+
* - It uses `useState()` and not `useSyncExternalStore()`, because React always renders a `useSyncExternalStore()` update at once, outside any transition.
|
|
8
|
+
* - The transition type is shared by the whole React root: the next transition commit takes every type that is waiting.
|
|
9
|
+
*
|
|
10
|
+
* @param sequence An object implementing the `AsyncIterable` interface.
|
|
11
|
+
* - Subscription is recreated every time this value changes.
|
|
12
|
+
* - Memoise this value to persist the subscription for the lifetime of the component.
|
|
13
|
+
* @returns The value shown now.
|
|
14
|
+
* @throws unknown Re-throws (during render) any error thrown by the sequence, for an error boundary to catch.
|
|
15
|
+
* @see https://shelving.cc/react/useSequenceTransition
|
|
16
|
+
*/
|
|
17
|
+
export function useSequenceTransition(sequence, options) {
|
|
18
|
+
const [value, setValue] = useState(options.current);
|
|
19
|
+
const [error, setError] = useState(undefined);
|
|
20
|
+
// Keep the latest options and value without starting a new subscription.
|
|
21
|
+
const optionsRef = useRef(options);
|
|
22
|
+
optionsRef.current = options;
|
|
23
|
+
const valueRef = useRef(value);
|
|
24
|
+
useEffect(() => {
|
|
25
|
+
const set = (next) => {
|
|
26
|
+
const { transition, equal = Object.is } = optionsRef.current;
|
|
27
|
+
if (equal(valueRef.current, next))
|
|
28
|
+
return;
|
|
29
|
+
valueRef.current = next;
|
|
30
|
+
const type = typeof transition === "function" ? transition(next) : transition;
|
|
31
|
+
if (!type)
|
|
32
|
+
return setValue(next);
|
|
33
|
+
startTransition(() => {
|
|
34
|
+
addTransitionType(type);
|
|
35
|
+
setValue(next);
|
|
36
|
+
});
|
|
37
|
+
};
|
|
38
|
+
set(optionsRef.current.current());
|
|
39
|
+
return runSequence(sequence, set, setError);
|
|
40
|
+
}, [sequence]);
|
|
41
|
+
if (error)
|
|
42
|
+
throw error;
|
|
43
|
+
return value;
|
|
44
|
+
}
|
package/ui/block/Image.d.ts
CHANGED
|
@@ -13,6 +13,9 @@ export interface ImageProps extends SpaceVariants, WidthVariants, ClassProps {
|
|
|
13
13
|
}
|
|
14
14
|
/**
|
|
15
15
|
* Image block — renders an `<img>` with space and width variants applied.
|
|
16
|
+
* - It loads `lazy`, and fades in once when it loads. An image that is already loaded when it mounts shows at once.
|
|
17
|
+
* - It never holds a transition (such as a page change): React waits only for an eager `<img>` with no `onLoad`.
|
|
18
|
+
* - The load state is the `data-loaded` attribute (none, `fade`, then `done`), set on the element directly, so a load never re-renders.
|
|
16
19
|
*
|
|
17
20
|
* @kind component
|
|
18
21
|
* @example <Image src="/logo.png" alt="Logo" width="narrow" />
|
package/ui/block/Image.js
CHANGED
|
@@ -5,12 +5,29 @@ import IMAGE_CSS from "./Image.module.css";
|
|
|
5
5
|
const IMAGE_CLASS = getModuleClass(IMAGE_CSS, "image");
|
|
6
6
|
/**
|
|
7
7
|
* Image block — renders an `<img>` with space and width variants applied.
|
|
8
|
+
* - It loads `lazy`, and fades in once when it loads. An image that is already loaded when it mounts shows at once.
|
|
9
|
+
* - It never holds a transition (such as a page change): React waits only for an eager `<img>` with no `onLoad`.
|
|
10
|
+
* - The load state is the `data-loaded` attribute (none, `fade`, then `done`), set on the element directly, so a load never re-renders.
|
|
8
11
|
*
|
|
9
12
|
* @kind component
|
|
10
13
|
* @example <Image src="/logo.png" alt="Logo" width="narrow" />
|
|
11
14
|
* @see https://shelving.cc/ui/Image
|
|
12
15
|
*/
|
|
13
16
|
export function Image({ src, alt, className, ...props }) {
|
|
14
|
-
return (_jsx("img", { src: src, alt: alt, className: getClass(IMAGE_CLASS, //
|
|
17
|
+
return (_jsx("img", { src: src, alt: alt, loading: "lazy", ref: _refImage, onLoad: _onImageLoad, onError: _onImageDone, onAnimationEnd: _onImageDone, className: getClass(IMAGE_CLASS, //
|
|
15
18
|
getBlockClass(props), className) }));
|
|
16
19
|
}
|
|
20
|
+
/** Show an image that loaded before it mounted (from the cache, or before hydration) at once, with no fade. */
|
|
21
|
+
function _refImage(img) {
|
|
22
|
+
if (img?.complete && !img.dataset.loaded)
|
|
23
|
+
img.dataset.loaded = "done";
|
|
24
|
+
}
|
|
25
|
+
/** Fade the image in when it loads. */
|
|
26
|
+
function _onImageLoad({ currentTarget }) {
|
|
27
|
+
if (!currentTarget.dataset.loaded)
|
|
28
|
+
currentTarget.dataset.loaded = "fade";
|
|
29
|
+
}
|
|
30
|
+
/** End the fade, or show an image that failed to load. */
|
|
31
|
+
function _onImageDone({ currentTarget }) {
|
|
32
|
+
currentTarget.dataset.loaded = "done";
|
|
33
|
+
}
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
@import url("../style/layers.css");
|
|
2
2
|
@import url("../style/Space.module.css");
|
|
3
|
+
@import url("../style/Duration.module.css");
|
|
3
4
|
|
|
4
5
|
@layer components {
|
|
5
6
|
.image,
|
|
@@ -13,4 +14,30 @@
|
|
|
13
14
|
object-position: center center;
|
|
14
15
|
object-fit: cover; /* Don't distort when resized. */
|
|
15
16
|
}
|
|
17
|
+
|
|
18
|
+
/* Hidden until it loads, then it fades in once. Only with scripts on: without them, `data-loaded` is never set. */
|
|
19
|
+
@media (scripting: enabled) {
|
|
20
|
+
.image:not([data-loaded]) {
|
|
21
|
+
opacity: 0;
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/* The fade is an animation only while `data-loaded="fade"`, so no opacity animation stays on the image after it. WebKit keeps a layer after an opacity animation, and that layer flickers during a view transition. */
|
|
26
|
+
.image[data-loaded="fade"] {
|
|
27
|
+
animation-name: image-fade;
|
|
28
|
+
animation-duration: var(--image-fade-duration, var(--duration-normal));
|
|
29
|
+
animation-timing-function: ease-out;
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
@keyframes image-fade {
|
|
34
|
+
from {
|
|
35
|
+
opacity: 0;
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
@media (prefers-reduced-motion: reduce) {
|
|
40
|
+
.image[data-loaded="fade"] {
|
|
41
|
+
animation-name: none;
|
|
42
|
+
}
|
|
16
43
|
}
|