shelving 1.293.0 → 1.294.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shelving",
3
- "version": "1.293.0",
3
+ "version": "1.294.0",
4
4
  "author": "Dave Houlbrooke <dave@shax.com>",
5
5
  "repository": {
6
6
  "type": "git",
@@ -32,6 +32,8 @@ export interface ClickableProps extends OptionalChildProps {
32
32
  title?: string | undefined;
33
33
  /** Whether this is the selected item in a group. Sets `aria-pressed` on a `<button>`, or `aria-current` on an `<a>`. */
34
34
  selected?: boolean | undefined;
35
+ /** If `href` is present, then `<Navigation>` opens the link with a back transition. Use it for a "back to" link. Sets `data-back` on the `<a>`. */
36
+ back?: boolean | undefined;
35
37
  }
36
38
  /**
37
39
  * Props for a clickable that also accepts a `className` for styling.
@@ -59,7 +61,7 @@ export declare function Clickable(props: StylableClickableProps): ReactElement;
59
61
  * @example <LinkClickable href="/about" className="link">About</LinkClickable>
60
62
  * @see https://shelving.cc/ui/LinkClickable
61
63
  */
62
- export declare function LinkClickable({ href, disabled, target, download, title, selected, children, className, }: StylableClickableProps): ReactElement;
64
+ export declare function LinkClickable({ href, disabled, target, download, title, selected, back, children, className, }: StylableClickableProps): ReactElement;
63
65
  /**
64
66
  * Render a `<button>` element that runs its `onClick` handler through a `BusyStore` and shows a loading spinner while busy.
65
67
  * - Notifies the user of the handler's returned value (success) or thrown value (error).
@@ -29,13 +29,13 @@ export function Clickable(props) {
29
29
  * @example <LinkClickable href="/about" className="link">About</LinkClickable>
30
30
  * @see https://shelving.cc/ui/LinkClickable
31
31
  */
32
- export function LinkClickable({ href, disabled = !href, target, download, title, selected, children = "Go", className, }) {
32
+ export function LinkClickable({ href, disabled = !href, target, download, title, selected, back, children = "Go", className, }) {
33
33
  // Resolve `href` against the current page URL and site root so site-absolute paths (`/foo`) honour the base subfolder.
34
34
  const { url, root } = requireMeta();
35
35
  const link = disabled ? undefined : getLink(href, url, root);
36
36
  // Is this link "active" compared to the current URL?
37
37
  const active = isURLActive(link, url);
38
- return (_jsx("a", { href: link?.href, title: title, download: download, target: target, className: getClass(className) || undefined, "aria-current": active ? "page" : selected ? "true" : undefined, children: children }));
38
+ return (_jsx("a", { href: link?.href, title: title, download: download, target: target, className: getClass(className) || undefined, "aria-current": active ? "page" : selected ? "true" : undefined, "data-back": back || undefined, children: children }));
39
39
  }
40
40
  /**
41
41
  * Render a `<button>` element that runs its `onClick` handler through a `BusyStore` and shows a loading spinner while busy.
@@ -43,6 +43,8 @@ export interface ClickableProps extends OptionalChildProps {
43
43
  title?: string | undefined;
44
44
  /** Whether this is the selected item in a group. Sets `aria-pressed` on a `<button>`, or `aria-current` on an `<a>`. */
45
45
  selected?: boolean | undefined;
46
+ /** If `href` is present, then `<Navigation>` opens the link with a back transition. Use it for a "back to" link. Sets `data-back` on the `<a>`. */
47
+ back?: boolean | undefined;
46
48
  }
47
49
 
48
50
  /**
@@ -87,6 +89,7 @@ export function LinkClickable({
87
89
  download,
88
90
  title,
89
91
  selected,
92
+ back,
90
93
  children = "Go",
91
94
  className,
92
95
  }: StylableClickableProps): ReactElement {
@@ -105,6 +108,7 @@ export function LinkClickable({
105
108
  target={target}
106
109
  className={getClass(className) || undefined}
107
110
  aria-current={active ? "page" : selected ? "true" : undefined}
111
+ data-back={back || undefined}
108
112
  >
109
113
  {children}
110
114
  </a>
@@ -11,7 +11,7 @@ export interface NavigationProps extends PossibleMeta, OptionalChildProps {
11
11
  /**
12
12
  * Top-level navigation provider.
13
13
  * - Owns a single `NavigationStore` initialised from the surrounding `<Meta>` url/base.
14
- * - Intercepts same-origin anchor clicks (excluding `download` anchors) and turns them into `forward()` calls.
14
+ * - Intercepts same-origin anchor clicks (excluding `download` anchors) and turns them into `forward()` calls, or `back()` calls for an anchor with a `data-back` attribute.
15
15
  * - Listens for `popstate` to sync the store with browser back/forward.
16
16
  * - Publishes the live URL into the `Meta` context via `mergeMeta()`, so descendant `<Router>`s re-render on navigation and merge invariants hold (e.g. `root` defaults to the live URL's origin when unset).
17
17
  * - Publishes each URL change inside `startTransition()` with a `"forward"` or `"back"` transition type, so a `<Transition>` around the routes runs a view transition.
@@ -9,7 +9,7 @@ import { NavigationStore } from "./NavigationStore.js";
9
9
  /**
10
10
  * Top-level navigation provider.
11
11
  * - Owns a single `NavigationStore` initialised from the surrounding `<Meta>` url/base.
12
- * - Intercepts same-origin anchor clicks (excluding `download` anchors) and turns them into `forward()` calls.
12
+ * - Intercepts same-origin anchor clicks (excluding `download` anchors) and turns them into `forward()` calls, or `back()` calls for an anchor with a `data-back` attribute.
13
13
  * - Listens for `popstate` to sync the store with browser back/forward.
14
14
  * - Publishes the live URL into the `Meta` context via `mergeMeta()`, so descendant `<Router>`s re-render on navigation and merge invariants hold (e.g. `root` defaults to the live URL's origin when unset).
15
15
  * - Publishes each URL change inside `startTransition()` with a `"forward"` or `"back"` transition type, so a `<Transition>` around the routes runs a view transition.
@@ -31,12 +31,10 @@ export function Navigation({ children, ...meta }) {
31
31
  useEffect(() => {
32
32
  if (typeof document === "undefined" || typeof window === "undefined")
33
33
  return;
34
- // Type of the next transition: `"back"` for a `popstate`, else `"forward"` (link click, `forward()`, `redirect()`).
35
- // `null` means no transition, because the browser already animated the change (e.g. a swipe-back gesture).
36
- let type = "forward";
34
+ // Read the transition type the store set for this change, then reset it.
37
35
  const stop = nav.subscribe(value => {
38
- const t = type;
39
- type = "forward";
36
+ const t = nav.transition;
37
+ nav.transition = "forward";
40
38
  if (!t)
41
39
  return setURL(value);
42
40
  // React renders a transition that starts inside a `popstate` event as a sync update with no view transition, so leave the event first.
@@ -51,15 +49,19 @@ export function Navigation({ children, ...meta }) {
51
49
  (!e.target.closest("button, label") && e.target.closest(".targeted")?.querySelector("a.target[href]"));
52
50
  if (anchor instanceof HTMLAnchorElement && anchor.origin === window.location.origin && !anchor.hasAttribute("download")) {
53
51
  e.preventDefault();
54
- nav.forward(anchor.href);
52
+ if (anchor.hasAttribute("data-back"))
53
+ nav.back(anchor.href);
54
+ else
55
+ nav.forward(anchor.href);
55
56
  return false; // `return false` stops iOS web app opening every link in a new window.
56
57
  }
57
58
  }
58
59
  };
59
60
  const onPopState = (e) => {
60
61
  const href = window.location.href;
62
+ // `"back"` for a `popstate`. `null` means no transition, because the browser already animated the change (e.g. a swipe-back gesture).
61
63
  if (href !== nav.value.href)
62
- type = e.hasUAVisualTransition ? null : "back";
64
+ nav.transition = e.hasUAVisualTransition ? null : "back";
63
65
  nav.value = href;
64
66
  };
65
67
  document.addEventListener("click", onClick);
@@ -5,8 +5,9 @@ The top-level navigation provider for a client-side app. It owns a single `Navig
5
5
  **Things to know:**
6
6
 
7
7
  - Same-origin anchor clicks are intercepted automatically and turned into `forward()` calls. Add a `download` attribute to an anchor to opt out.
8
+ - An anchor with a `data-back` attribute calls `back()` instead, so the page slides back. Set it with the `back` prop on `<Button>` or `<Link>`, e.g. on a "Back to profile" button.
8
9
  - It listens for `popstate` so the store stays in sync with browser back/forward.
9
- - It publishes each page change inside `startTransition()`, so a `<Transition>` around the routes animates it. A link click, `NavigationStore.forward()` or `NavigationStore.redirect()` sets the `"forward"` transition type. The browser back or forward button sets `"back"` (`popstate` does not say which way it went).
10
+ - It publishes each page change inside `startTransition()`, so a `<Transition>` around the routes animates it. A link click, `NavigationStore.forward()` or `NavigationStore.redirect()` sets the `"forward"` transition type. A `data-back` link click, `NavigationStore.back()`, and the browser back or forward button set `"back"` (`popstate` does not say which way it went).
10
11
  - When the browser already animated the change, for example a swipe-back gesture on a phone, there is no view transition, so the page does not slide twice. The browser says so with `hasUAVisualTransition` on the `popstate` event. Other browsers still slide.
11
12
  - The `popstate` update waits for the next task (`setTimeout()`). React renders a transition that starts inside `popstate` as a sync update with no view transition.
12
13
  - It initialises the store from the surrounding `<Meta>` url/base, so set those on an ancestor `<App>` / `<HTML>` / `<Page>`. In the browser the store falls back to `window.location.href` when no url is set.
@@ -30,12 +31,15 @@ import { HTML, Navigation, Router } from "shelving/ui";
30
31
  ```tsx
31
32
  import { HorizontalTransition, Navigation, Router } from "shelving/ui";
32
33
 
33
- // Links slide right, the browser back button slides left.
34
+ // Links slide right. Back links and the browser back button slide left.
34
35
  <Navigation>
35
36
  <HorizontalTransition>
36
37
  <Router routes={ROUTES}/>
37
38
  </HorizontalTransition>
38
39
  </Navigation>
40
+
41
+ // A "back to" link slides left too.
42
+ <Button href="/profile" back>Back to profile</Button>
39
43
  ```
40
44
 
41
45
  ### Imperative navigation
@@ -48,4 +52,5 @@ import { requireNavigation } from "shelving/ui";
48
52
  const nav = requireNavigation();
49
53
  nav.forward("/users/123"); // push a new history entry
50
54
  nav.redirect("/login"); // replace the current history entry
55
+ nav.back("/users"); // push a new history entry that slides back
51
56
  ```
@@ -1,7 +1,7 @@
1
1
  import { describe, expect, test } from "bun:test";
2
2
  import type { ReactNode } from "react";
3
3
  import { renderToStaticMarkup } from "react-dom/server";
4
- import { Navigation, requireMetaURL } from "shelving/ui";
4
+ import { Button, Navigation, requireMetaURL } from "shelving/ui";
5
5
 
6
6
  /** Render `requireMetaURL().path` from inside a component so its `use(MetaContext)` call is valid. */
7
7
  function Probe(): ReactNode {
@@ -26,4 +26,15 @@ describe("Navigation", () => {
26
26
  );
27
27
  expect(html).toBe("/sub");
28
28
  });
29
+
30
+ test("marks a back link with a data-back attribute", () => {
31
+ const html = renderToStaticMarkup(
32
+ <Navigation url="http://x.com/a">
33
+ <Button href="/b" back>
34
+ Back
35
+ </Button>
36
+ </Navigation>,
37
+ );
38
+ expect(html).toContain('data-back="true"');
39
+ });
29
40
  });
@@ -1,7 +1,7 @@
1
1
  import { type ReactElement, startTransition, useEffect, useState } from "react";
2
2
  import { useInstance } from "../../react/useInstance.js";
3
3
  import { MetaContext, requireMeta } from "../misc/MetaContext.js";
4
- import { setTransitionType, type TransitionType } from "../transition/util.js";
4
+ import { setTransitionType } from "../transition/util.js";
5
5
  import { mergeMeta, type PossibleMeta } from "../util/index.js";
6
6
  import type { OptionalChildProps } from "../util/props.js";
7
7
  import { NavigationContext } from "./NavigationContext.js";
@@ -17,7 +17,7 @@ export interface NavigationProps extends PossibleMeta, OptionalChildProps {}
17
17
  /**
18
18
  * Top-level navigation provider.
19
19
  * - Owns a single `NavigationStore` initialised from the surrounding `<Meta>` url/base.
20
- * - Intercepts same-origin anchor clicks (excluding `download` anchors) and turns them into `forward()` calls.
20
+ * - Intercepts same-origin anchor clicks (excluding `download` anchors) and turns them into `forward()` calls, or `back()` calls for an anchor with a `data-back` attribute.
21
21
  * - Listens for `popstate` to sync the store with browser back/forward.
22
22
  * - Publishes the live URL into the `Meta` context via `mergeMeta()`, so descendant `<Router>`s re-render on navigation and merge invariants hold (e.g. `root` defaults to the live URL's origin when unset).
23
23
  * - Publishes each URL change inside `startTransition()` with a `"forward"` or `"back"` transition type, so a `<Transition>` around the routes runs a view transition.
@@ -41,12 +41,10 @@ export function Navigation({ children, ...meta }: NavigationProps): ReactElement
41
41
  useEffect(() => {
42
42
  if (typeof document === "undefined" || typeof window === "undefined") return;
43
43
 
44
- // Type of the next transition: `"back"` for a `popstate`, else `"forward"` (link click, `forward()`, `redirect()`).
45
- // `null` means no transition, because the browser already animated the change (e.g. a swipe-back gesture).
46
- let type: TransitionType | null = "forward";
44
+ // Read the transition type the store set for this change, then reset it.
47
45
  const stop = nav.subscribe(value => {
48
- const t = type;
49
- type = "forward";
46
+ const t = nav.transition;
47
+ nav.transition = "forward";
50
48
  if (!t) return setURL(value);
51
49
  // React renders a transition that starts inside a `popstate` event as a sync update with no view transition, so leave the event first.
52
50
  setTimeout(() =>
@@ -64,14 +62,16 @@ export function Navigation({ children, ...meta }: NavigationProps): ReactElement
64
62
  (!e.target.closest("button, label") && e.target.closest(".targeted")?.querySelector<HTMLAnchorElement>("a.target[href]"));
65
63
  if (anchor instanceof HTMLAnchorElement && anchor.origin === window.location.origin && !anchor.hasAttribute("download")) {
66
64
  e.preventDefault();
67
- nav.forward(anchor.href);
65
+ if (anchor.hasAttribute("data-back")) nav.back(anchor.href);
66
+ else nav.forward(anchor.href);
68
67
  return false; // `return false` stops iOS web app opening every link in a new window.
69
68
  }
70
69
  }
71
70
  };
72
71
  const onPopState = (e: PopStateEvent) => {
73
72
  const href = window.location.href;
74
- if (href !== nav.value.href) type = e.hasUAVisualTransition ? null : "back";
73
+ // `"back"` for a `popstate`. `null` means no transition, because the browser already animated the change (e.g. a swipe-back gesture).
74
+ if (href !== nav.value.href) nav.transition = e.hasUAVisualTransition ? null : "back";
75
75
  nav.value = href;
76
76
  };
77
77
 
@@ -1,15 +1,19 @@
1
1
  import { URLStore } from "../../store/URLStore.js";
2
2
  import { type PossibleURL } from "../../util/url.js";
3
+ import type { TransitionType } from "../transition/util.js";
3
4
  /**
4
5
  * Store holding the current navigation URL and driving browser history.
5
6
  *
6
7
  * - Extends `URLStore`; the current location is its `value`.
7
8
  * - `forward()` pushes a new history entry; `redirect()` replaces the current one.
9
+ * - `back()` pushes a new history entry like `forward()`, but `<Navigation>` animates it as a back transition.
8
10
  * - TODO: switch to the browser Navigation API when broadly supported.
9
11
  *
10
12
  * @see https://shelving.cc/ui/NavigationStore
11
13
  */
12
14
  export declare class NavigationStore extends URLStore {
15
+ /** Transition type of the next URL change. `null` means no transition. `<Navigation>` reads it, then sets it back to `"forward"`. */
16
+ transition: TransitionType | null;
13
17
  constructor(url?: PossibleURL, base?: PossibleURL);
14
18
  /**
15
19
  * Navigate forward to a URL, pushing a new browser history entry.
@@ -29,4 +33,15 @@ export declare class NavigationStore extends URLStore {
29
33
  * @see https://shelving.cc/ui/NavigationStore/redirect
30
34
  */
31
35
  redirect(possible: PossibleURL): void;
36
+ /**
37
+ * Navigate back to a URL, pushing a new browser history entry with the `"back"` transition type.
38
+ * - Use it for a "back to" link, so the page slides back, not forward.
39
+ * - It does not go back in the browser history, so it also works when the page was opened directly.
40
+ *
41
+ * @param possible The destination URL, resolved against `base`.
42
+ * @throws RequiredError If `possible` cannot be resolved to a valid URL.
43
+ * @example nav.back("/profile");
44
+ * @see https://shelving.cc/ui/NavigationStore/back
45
+ */
46
+ back(possible: PossibleURL): void;
32
47
  }
@@ -5,11 +5,14 @@ import { requireURL } from "../../util/url.js";
5
5
  *
6
6
  * - Extends `URLStore`; the current location is its `value`.
7
7
  * - `forward()` pushes a new history entry; `redirect()` replaces the current one.
8
+ * - `back()` pushes a new history entry like `forward()`, but `<Navigation>` animates it as a back transition.
8
9
  * - TODO: switch to the browser Navigation API when broadly supported.
9
10
  *
10
11
  * @see https://shelving.cc/ui/NavigationStore
11
12
  */
12
13
  export class NavigationStore extends URLStore {
14
+ /** Transition type of the next URL change. `null` means no transition. `<Navigation>` reads it, then sets it back to `"forward"`. */
15
+ transition = "forward";
13
16
  constructor(url = typeof window === "undefined" ? "/" : window.location.href, base) {
14
17
  super(url, base);
15
18
  }
@@ -22,6 +25,7 @@ export class NavigationStore extends URLStore {
22
25
  * @see https://shelving.cc/ui/NavigationStore/forward
23
26
  */
24
27
  forward(possible) {
28
+ this.transition = "forward";
25
29
  this.value = requireURL(possible, this.base, this.forward);
26
30
  window.history.pushState(null, "", this.value);
27
31
  }
@@ -34,7 +38,23 @@ export class NavigationStore extends URLStore {
34
38
  * @see https://shelving.cc/ui/NavigationStore/redirect
35
39
  */
36
40
  redirect(possible) {
41
+ this.transition = "forward";
37
42
  this.value = requireURL(possible, this.base, this.redirect);
38
43
  window.history.replaceState(null, "", this.value);
39
44
  }
45
+ /**
46
+ * Navigate back to a URL, pushing a new browser history entry with the `"back"` transition type.
47
+ * - Use it for a "back to" link, so the page slides back, not forward.
48
+ * - It does not go back in the browser history, so it also works when the page was opened directly.
49
+ *
50
+ * @param possible The destination URL, resolved against `base`.
51
+ * @throws RequiredError If `possible` cannot be resolved to a valid URL.
52
+ * @example nav.back("/profile");
53
+ * @see https://shelving.cc/ui/NavigationStore/back
54
+ */
55
+ back(possible) {
56
+ this.transition = "back";
57
+ this.value = requireURL(possible, this.base, this.back);
58
+ window.history.pushState(null, "", this.value);
59
+ }
40
60
  }
@@ -5,6 +5,7 @@ The store holding the current navigation URL and driving browser history. It ext
5
5
  **Things to know:**
6
6
 
7
7
  - `forward()` pushes a new browser history entry; `redirect()` replaces the current one. Both resolve the destination against the store's `base`.
8
+ - `back()` pushes a new browser history entry like `forward()`, but `<Navigation>` gives it the `"back"` transition type, so the page slides back. It does not go back in the browser history, so it works when the page was opened directly.
8
9
  - It is a `shelving/store` `URLStore`, so components can subscribe to it for re-renders.
9
10
 
10
11
  ## Usage
@@ -1,16 +1,21 @@
1
1
  import { URLStore } from "../../store/URLStore.js";
2
2
  import { type PossibleURL, requireURL } from "../../util/url.js";
3
+ import type { TransitionType } from "../transition/util.js";
3
4
 
4
5
  /**
5
6
  * Store holding the current navigation URL and driving browser history.
6
7
  *
7
8
  * - Extends `URLStore`; the current location is its `value`.
8
9
  * - `forward()` pushes a new history entry; `redirect()` replaces the current one.
10
+ * - `back()` pushes a new history entry like `forward()`, but `<Navigation>` animates it as a back transition.
9
11
  * - TODO: switch to the browser Navigation API when broadly supported.
10
12
  *
11
13
  * @see https://shelving.cc/ui/NavigationStore
12
14
  */
13
15
  export class NavigationStore extends URLStore {
16
+ /** Transition type of the next URL change. `null` means no transition. `<Navigation>` reads it, then sets it back to `"forward"`. */
17
+ transition: TransitionType | null = "forward";
18
+
14
19
  constructor(url: PossibleURL = typeof window === "undefined" ? "/" : window.location.href, base?: PossibleURL) {
15
20
  super(url, base);
16
21
  }
@@ -24,6 +29,7 @@ export class NavigationStore extends URLStore {
24
29
  * @see https://shelving.cc/ui/NavigationStore/forward
25
30
  */
26
31
  forward(possible: PossibleURL): void {
32
+ this.transition = "forward";
27
33
  this.value = requireURL(possible, this.base, this.forward);
28
34
  window.history.pushState(null, "", this.value);
29
35
  }
@@ -37,7 +43,24 @@ export class NavigationStore extends URLStore {
37
43
  * @see https://shelving.cc/ui/NavigationStore/redirect
38
44
  */
39
45
  redirect(possible: PossibleURL): void {
46
+ this.transition = "forward";
40
47
  this.value = requireURL(possible, this.base, this.redirect);
41
48
  window.history.replaceState(null, "", this.value);
42
49
  }
50
+
51
+ /**
52
+ * Navigate back to a URL, pushing a new browser history entry with the `"back"` transition type.
53
+ * - Use it for a "back to" link, so the page slides back, not forward.
54
+ * - It does not go back in the browser history, so it also works when the page was opened directly.
55
+ *
56
+ * @param possible The destination URL, resolved against `base`.
57
+ * @throws RequiredError If `possible` cannot be resolved to a valid URL.
58
+ * @example nav.back("/profile");
59
+ * @see https://shelving.cc/ui/NavigationStore/back
60
+ */
61
+ back(possible: PossibleURL): void {
62
+ this.transition = "back";
63
+ this.value = requireURL(possible, this.base, this.back);
64
+ window.history.pushState(null, "", this.value);
65
+ }
43
66
  }