shelving 1.292.3 → 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.292.3",
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>
@@ -9,6 +9,6 @@ import { DocumentationSearchPage } from "./DocumentationSearchPage.js";
9
9
  */
10
10
  export function DocumentationApp({ tree, routes = {
11
11
  "/search": DocumentationSearchPage,
12
- }, sidebar = (_jsx(TreeSidebar, { children: _jsx(Menu, { children: _jsx(MenuItem, { href: "/search", children: "Search" }) }) })), ...meta }) {
12
+ }, sidebar = (_jsx(TreeSidebar, { children: _jsx(Menu, { small: true, children: _jsx(MenuItem, { href: "/search", children: "Search" }) }) })), ...meta }) {
13
13
  return _jsx(TreeApp, { tree: tree, routes: routes, sidebar: sidebar, ...meta });
14
14
  }
@@ -15,7 +15,7 @@ export function DocumentationApp({
15
15
  },
16
16
  sidebar = (
17
17
  <TreeSidebar>
18
- <Menu>
18
+ <Menu small>
19
19
  <MenuItem href="/search">Search</MenuItem>
20
20
  </Menu>
21
21
  </TreeSidebar>
package/ui/menu/Menu.d.ts CHANGED
@@ -8,16 +8,19 @@ import type { ClassProps, OptionalChildProps } from "../util/props.js";
8
8
  * @see https://shelving.cc/ui/MenuProps
9
9
  */
10
10
  export interface MenuProps extends BlockVariants, OptionalChildProps, ClassProps {
11
+ /** Make every item in the menu (and in any nested menu) small, as if each `<MenuItem>` had `small`. */
12
+ readonly small?: boolean | undefined;
11
13
  }
12
14
  /**
13
15
  * A `<menu>` list of `<MenuItem>` children.
14
16
  * - Renders as a bare `<menu>` element — semantically equivalent to `<ul>` per HTML spec but more meaningful for menu contexts. Place inside a `<nav>` (or use the sidebar-style nav at the layout level) if a navigation landmark is needed.
15
17
  * - Nested `<Menu>` instances (typically inside a `<MenuItem>`) get indented via the `.menu .menu` CSS rule.
18
+ * - Pass `small` to make every item smaller, for example in a dense sidebar.
16
19
  *
17
20
  * @kind component
18
21
  * @see https://shelving.cc/ui/Menu
19
22
  */
20
- export declare function Menu({ children, className, ...props }: MenuProps): ReactNode;
23
+ export declare function Menu({ children, small, className, ...props }: MenuProps): ReactNode;
21
24
  /**
22
25
  * Props for `<MenuItem>` — `<Clickable>` props plus `children` whose first node is the label and the rest the submenu.
23
26
  *
@@ -29,13 +32,16 @@ export interface MenuItemProps extends ClickableProps, ClassProps {
29
32
  * - Any additional children form the submenu — only rendered when this item is "proud" (an ancestor of the current page). The caller is responsible for wrapping the submenu in a nested `<Menu>` if it wants the CSS `.menu .menu` descendant rules to apply.
30
33
  */
31
34
  readonly children: ReactNode | readonly [ReactNode, ...ReactNode[]];
35
+ /** Make the item smaller: less padding and no minimum height. By default an item is as tall as a `<Button>`, so it is easy to tap. */
36
+ readonly small?: boolean | undefined;
32
37
  }
33
38
  /**
34
39
  * A `<li>` containing an `<a>` link, plus optional submenu content shown when this item is "proud".
35
40
  * - Reads the current page URL from `<Meta>` and computes `active` / `proud` against its own `href`.
36
41
  * - Splits `children` into `[label, ...after]`: label goes inside the `<a>`; `after` is rendered as siblings below it, only when proud.
42
+ * - As tall as a `<Button>` by default, so it is easy to tap. Pass `small` for a denser item.
37
43
  *
38
44
  * @kind component
39
45
  * @see https://shelving.cc/ui/MenuItem
40
46
  */
41
- export declare function MenuItem({ href, children, className, ...props }: MenuItemProps): ReactNode;
47
+ export declare function MenuItem({ href, children, small, className, ...props }: MenuItemProps): ReactNode;
package/ui/menu/Menu.js CHANGED
@@ -11,32 +11,35 @@ const MENU_ITEM_CLASS = getModuleClass(MENU_CSS, "item");
11
11
  const MENU_LINK_CLASS = getModuleClass(MENU_CSS, "link");
12
12
  const MENU_PROUD_CLASS = getModuleClass(MENU_CSS, "proud");
13
13
  const MENU_ACTIVE_CLASS = getModuleClass(MENU_CSS, "active");
14
+ const MENU_SMALL_CLASS = getModuleClass(MENU_CSS, "small");
14
15
  /**
15
16
  * A `<menu>` list of `<MenuItem>` children.
16
17
  * - Renders as a bare `<menu>` element — semantically equivalent to `<ul>` per HTML spec but more meaningful for menu contexts. Place inside a `<nav>` (or use the sidebar-style nav at the layout level) if a navigation landmark is needed.
17
18
  * - Nested `<Menu>` instances (typically inside a `<MenuItem>`) get indented via the `.menu .menu` CSS rule.
19
+ * - Pass `small` to make every item smaller, for example in a dense sidebar.
18
20
  *
19
21
  * @kind component
20
22
  * @see https://shelving.cc/ui/Menu
21
23
  */
22
- export function Menu({ children, className, ...props }) {
24
+ export function Menu({ children, small, className, ...props }) {
23
25
  return (_jsx("menu", { className: getClass(MENU_CLASS, //
24
- getBlockClass(props), className), children: children }));
26
+ small && MENU_SMALL_CLASS, getBlockClass(props), className), children: children }));
25
27
  }
26
28
  /**
27
29
  * A `<li>` containing an `<a>` link, plus optional submenu content shown when this item is "proud".
28
30
  * - Reads the current page URL from `<Meta>` and computes `active` / `proud` against its own `href`.
29
31
  * - Splits `children` into `[label, ...after]`: label goes inside the `<a>`; `after` is rendered as siblings below it, only when proud.
32
+ * - As tall as a `<Button>` by default, so it is easy to tap. Pass `small` for a denser item.
30
33
  *
31
34
  * @kind component
32
35
  * @see https://shelving.cc/ui/MenuItem
33
36
  */
34
- export function MenuItem({ href, children, className, ...props }) {
37
+ export function MenuItem({ href, children, small, className, ...props }) {
35
38
  const { url, root } = requireMeta();
36
39
  const link = getLink(href, url, root);
37
40
  const proud = isURLProud(url, link);
38
41
  const active = isURLActive(url, link);
39
42
  const [label, ...after] = isArray(children) ? children : [children];
40
43
  return (_jsxs("li", { className: getClass(MENU_ITEM_CLASS, className), children: [_jsx(Clickable, { href: href, ...props, className: getClass(MENU_LINK_CLASS, //
41
- proud && MENU_PROUD_CLASS, active && MENU_ACTIVE_CLASS), children: label }), proud && after] }));
44
+ small && MENU_SMALL_CLASS, proud && MENU_PROUD_CLASS, active && MENU_ACTIVE_CLASS), children: label }), proud && after] }));
42
45
  }
package/ui/menu/Menu.md CHANGED
@@ -6,6 +6,7 @@ A `<menu>` list of `<MenuItem>` children — the container for URL-aware navigat
6
6
 
7
7
  - Renders as a bare `<menu>` element (semantically equivalent to `<ul>` but more meaningful for menus). Place it inside a `<nav>` — or a `<SidebarLayout>` sidebar, which is already a `<nav>` landmark — if a navigation landmark is needed.
8
8
  - Nesting a `<Menu>` inside a `<MenuItem>` gets indented automatically via the `.menu .menu` descendant rule.
9
+ - Pass `small` to make every item inside it small, including items in nested menus. See `<MenuItem>`.
9
10
 
10
11
  ## Usage
11
12
 
@@ -35,12 +36,13 @@ import { Menu, MenuItem } from "shelving/ui";
35
36
  | `--menu-leading` | Line height | `var(--leading)` |
36
37
  | `--menu-color` | Text colour | `var(--tint-00)` |
37
38
  | `--menu-nested-space` | Block margin around a nested submenu | `var(--space-xxsmall)` |
38
- | `--menu-padding` | Item link top and bottom padding (one length) | `var(--space-xsmall)` |
39
- | `--menu-indent` | Item link left and right padding (one length; also insets the nested border) | `var(--space-xsmall)` |
39
+ | `--menu-padding` | Item link top and bottom padding (one length) | `var(--space-small)` |
40
+ | `--menu-indent` | Item link left and right padding (one length; with `--menu-stroke`, also insets the nested border) | `var(--space-small)` |
41
+ | `--menu-small-indent` | Small item link left and right padding (one length; also insets the nested border of a small item) | `var(--space-xsmall)` |
40
42
  | `--menu-nested-border` | Nested submenu left-border width | `var(--stroke-focus)` |
41
43
  | `--menu-nested-color-border` | Nested submenu left-border colour | `var(--tint-50)` |
42
44
  | `--menu-nested-indent` | Nested submenu left padding | `var(--space-xsmall)` |
43
45
 
44
- Item-state hooks (`--menu-hover-*`, `--menu-proud-*`, `--menu-active-*`, `--menu-radius`, `--menu-focus-border`) are documented on `<MenuItem>`.
46
+ Item-size and item-state hooks (`--menu-stroke`, `--menu-height`, `--menu-small-*`, `--menu-hover-*`, `--menu-proud-*`, `--menu-active-*`, `--menu-radius`, `--menu-focus-border`) are documented on `<MenuItem>`.
45
47
 
46
- **Global tokens it reads** — the tint ladder `--tint-00` / `--tint-50`, plus `--space-xxsmall` / `--space-xsmall`, `--font-body`, `--size-normal`, `--leading`, and `--stroke-focus`.
48
+ **Global tokens it reads** — the tint ladder `--tint-00` / `--tint-50`, plus `--space-xxsmall` / `--space-xsmall` / `--space-small`, `--stroke-normal`, `--font-body`, `--size-normal`, `--leading`, and `--stroke-focus`.
@@ -25,11 +25,17 @@
25
25
  .menu {
26
26
  margin-block: var(--menu-nested-space, var(--space-xxsmall));
27
27
 
28
- /* Inset the border by the link's inline padding so it lines up with the parent item's label. */
29
- margin-inline-start: var(--menu-indent, var(--space-xsmall));
28
+ /* Inset the border by the link's border and inline padding so it lines up with the parent item's label. */
29
+ margin-inline-start: calc(var(--menu-stroke, var(--stroke-normal)) + var(--menu-indent, var(--space-small)));
30
30
  border-inline-start: var(--menu-nested-border, var(--stroke-focus)) solid var(--menu-nested-color-border, var(--tint-50));
31
31
  padding-inline-start: var(--menu-nested-indent, var(--space-xsmall));
32
32
  }
33
+
34
+ /* A small parent item has no border and a smaller indent. */
35
+ &.small .menu,
36
+ .link.small ~ .menu {
37
+ margin-inline-start: var(--menu-small-indent, var(--space-xsmall));
38
+ }
33
39
  }
34
40
 
35
41
  .item {
@@ -41,11 +47,23 @@
41
47
  display: block;
42
48
  box-sizing: border-box;
43
49
  inline-size: 100%;
44
- padding-block: var(--menu-padding, var(--space-xsmall));
45
- padding-inline: var(--menu-indent, var(--space-xsmall));
46
- border: none;
50
+ padding-block: var(--menu-padding, var(--space-small));
51
+ padding-inline: var(--menu-indent, var(--space-small));
52
+ border: var(--menu-stroke, var(--stroke-normal)) solid transparent;
47
53
  border-radius: var(--menu-radius, var(--radius-xsmall));
48
54
 
55
+ /* Match `--button-height` and `--input-height`, so an item is as easy to tap as a button. */
56
+ min-block-size: var(
57
+ --menu-height,
58
+ calc(
59
+ var(--menu-icon-size, var(--size-icon)) +
60
+ 2 *
61
+ var(--menu-padding, var(--space-small)) +
62
+ 2 *
63
+ var(--menu-stroke, var(--stroke-normal))
64
+ )
65
+ );
66
+
49
67
  /* Style — `background`, `font`, `text-align` and `cursor` reset the native button look. */
50
68
  background: none;
51
69
  color: inherit;
@@ -68,7 +86,15 @@
68
86
  outline-color: transparent;
69
87
  }
70
88
 
71
- /* Variants */
89
+ /* Variants — `small` applies to one item, or to every item inside a small `<Menu>`. */
90
+ &.small,
91
+ :where(.menu.small) & {
92
+ padding-block: var(--menu-small-padding, var(--space-xsmall));
93
+ padding-inline: var(--menu-small-indent, var(--space-xsmall));
94
+ border: none;
95
+ min-block-size: var(--menu-small-height, 0);
96
+ }
97
+
72
98
  &.proud {
73
99
  background: var(--menu-proud-background, transparent);
74
100
  color: var(--menu-proud, var(--tint-00));
package/ui/menu/Menu.tsx CHANGED
@@ -13,27 +13,33 @@ const MENU_ITEM_CLASS = getModuleClass(MENU_CSS, "item");
13
13
  const MENU_LINK_CLASS = getModuleClass(MENU_CSS, "link");
14
14
  const MENU_PROUD_CLASS = getModuleClass(MENU_CSS, "proud");
15
15
  const MENU_ACTIVE_CLASS = getModuleClass(MENU_CSS, "active");
16
+ const MENU_SMALL_CLASS = getModuleClass(MENU_CSS, "small");
16
17
 
17
18
  /**
18
19
  * Props for `<Menu>` — optional `<MenuItem>` `children`.
19
20
  *
20
21
  * @see https://shelving.cc/ui/MenuProps
21
22
  */
22
- export interface MenuProps extends BlockVariants, OptionalChildProps, ClassProps {}
23
+ export interface MenuProps extends BlockVariants, OptionalChildProps, ClassProps {
24
+ /** Make every item in the menu (and in any nested menu) small, as if each `<MenuItem>` had `small`. */
25
+ readonly small?: boolean | undefined;
26
+ }
23
27
 
24
28
  /**
25
29
  * A `<menu>` list of `<MenuItem>` children.
26
30
  * - Renders as a bare `<menu>` element — semantically equivalent to `<ul>` per HTML spec but more meaningful for menu contexts. Place inside a `<nav>` (or use the sidebar-style nav at the layout level) if a navigation landmark is needed.
27
31
  * - Nested `<Menu>` instances (typically inside a `<MenuItem>`) get indented via the `.menu .menu` CSS rule.
32
+ * - Pass `small` to make every item smaller, for example in a dense sidebar.
28
33
  *
29
34
  * @kind component
30
35
  * @see https://shelving.cc/ui/Menu
31
36
  */
32
- export function Menu({ children, className, ...props }: MenuProps): ReactNode {
37
+ export function Menu({ children, small, className, ...props }: MenuProps): ReactNode {
33
38
  return (
34
39
  <menu
35
40
  className={getClass(
36
41
  MENU_CLASS, //
42
+ small && MENU_SMALL_CLASS,
37
43
  getBlockClass(props),
38
44
  className,
39
45
  )}
@@ -54,17 +60,20 @@ export interface MenuItemProps extends ClickableProps, ClassProps {
54
60
  * - Any additional children form the submenu — only rendered when this item is "proud" (an ancestor of the current page). The caller is responsible for wrapping the submenu in a nested `<Menu>` if it wants the CSS `.menu .menu` descendant rules to apply.
55
61
  */
56
62
  readonly children: ReactNode | readonly [ReactNode, ...ReactNode[]];
63
+ /** Make the item smaller: less padding and no minimum height. By default an item is as tall as a `<Button>`, so it is easy to tap. */
64
+ readonly small?: boolean | undefined;
57
65
  }
58
66
 
59
67
  /**
60
68
  * A `<li>` containing an `<a>` link, plus optional submenu content shown when this item is "proud".
61
69
  * - Reads the current page URL from `<Meta>` and computes `active` / `proud` against its own `href`.
62
70
  * - Splits `children` into `[label, ...after]`: label goes inside the `<a>`; `after` is rendered as siblings below it, only when proud.
71
+ * - As tall as a `<Button>` by default, so it is easy to tap. Pass `small` for a denser item.
63
72
  *
64
73
  * @kind component
65
74
  * @see https://shelving.cc/ui/MenuItem
66
75
  */
67
- export function MenuItem({ href, children, className, ...props }: MenuItemProps): ReactNode {
76
+ export function MenuItem({ href, children, small, className, ...props }: MenuItemProps): ReactNode {
68
77
  const { url, root } = requireMeta();
69
78
  const link = getLink(href, url, root);
70
79
  const proud = isURLProud(url, link);
@@ -77,6 +86,7 @@ export function MenuItem({ href, children, className, ...props }: MenuItemProps)
77
86
  {...props}
78
87
  className={getClass(
79
88
  MENU_LINK_CLASS, //
89
+ small && MENU_SMALL_CLASS,
80
90
  proud && MENU_PROUD_CLASS,
81
91
  active && MENU_ACTIVE_CLASS,
82
92
  )}
@@ -7,6 +7,7 @@ A single `<li>` link entry inside a `<Menu>`. It reads the current page URL from
7
7
  - The first child is the link label (rendered inside the `<a>`). Any additional children form the submenu and are rendered only when the item is proud (the current URL starts with the item's `href`). Wrap that submenu in a nested `<Menu>` to get the `.menu .menu` indentation.
8
8
  - It forwards all `ClickableProps` — `href`, `onClick`, `disabled`, and so on — to the underlying `<Clickable>`.
9
9
  - `active` and `proud` are computed against the URL from `<Router>` / `<Navigation>` context.
10
+ - By default an item is as tall as a `<Button>` or an `<Input>`, so it is easy to tap. Pass `small` for a denser item (the size before this change). Pass `small` to `<Menu>` to make all of its items small.
10
11
 
11
12
  ## Usage
12
13
 
@@ -25,14 +26,37 @@ import { Menu, MenuItem } from "shelving/ui";
25
26
  </Menu>
26
27
  ```
27
28
 
29
+ ### Small items
30
+
31
+ ```tsx
32
+ import { Menu, MenuItem } from "shelving/ui";
33
+
34
+ // One small item.
35
+ <Menu>
36
+ <MenuItem href="/help" small>Help</MenuItem>
37
+ </Menu>
38
+
39
+ // Every item small, including nested menus.
40
+ <Menu small>
41
+ <MenuItem href="/users">Users</MenuItem>
42
+ <MenuItem href="/settings">Settings</MenuItem>
43
+ </Menu>
44
+ ```
45
+
28
46
  ## Styling
29
47
 
30
48
  The item link's hooks (defined in `Menu.module.css`):
31
49
 
32
50
  | Variable | Styles | Default |
33
51
  |---|---|---|
34
- | `--menu-padding` | Link top and bottom padding (one length) | `var(--space-xsmall)` |
35
- | `--menu-indent` | Link left and right padding (one length) | `var(--space-xsmall)` |
52
+ | `--menu-padding` | Link top and bottom padding (one length) | `var(--space-small)` |
53
+ | `--menu-indent` | Link left and right padding (one length) | `var(--space-small)` |
54
+ | `--menu-stroke` | Link transparent border width (one length) | `var(--stroke-normal)` |
55
+ | `--menu-icon-size` | Content height used for the minimum height (one length) | `var(--size-icon)` |
56
+ | `--menu-height` | Link minimum height | `--menu-icon-size` + 2 × `--menu-padding` + 2 × `--menu-stroke`, the same as `--button-height` |
57
+ | `--menu-small-padding` | Small link top and bottom padding (one length) | `var(--space-xsmall)` |
58
+ | `--menu-small-indent` | Small link left and right padding (one length) | `var(--space-xsmall)` |
59
+ | `--menu-small-height` | Small link minimum height | `0` |
36
60
  | `--menu-radius` | Link corner radius | `var(--radius-xsmall)` |
37
61
  | `--menu-focus-border` | Focus outline | `var(--stroke-focus) solid var(--color-focus)` |
38
62
  | `--menu-hover-background` | Link fill on hover/focus | `var(--tint-90)` |
@@ -46,4 +70,4 @@ The item link's hooks (defined in `Menu.module.css`):
46
70
 
47
71
  List-level hooks (`--menu-gap`, `--menu-color`, the nested-submenu hooks, etc.) are documented on `<Menu>`.
48
72
 
49
- **Global tokens it reads** — the tint ladder `--tint-00` / `--tint-90` / `--tint-100`, plus `--space-xsmall`, `--radius-xsmall`, `--stroke-focus`, `--color-focus`, and `--weight-strong`.
73
+ **Global tokens it reads** — the tint ladder `--tint-00` / `--tint-90` / `--tint-100`, plus `--space-small`, `--space-xsmall`, `--size-icon`, `--radius-xsmall`, `--stroke-normal`, `--stroke-focus`, `--color-focus`, and `--weight-strong`.
@@ -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
  }
@@ -12,6 +12,7 @@ export interface TreeSidebarProps extends OptionalChildProps {
12
12
  *
13
13
  * - **Middle:** a `<TextInput>` search-as-you-type filter.
14
14
  * - **Bottom:** the root's children as a `<TreeMenuMapper>` — swapped for a flat ranked list of results (capped at 20) while the search holds a query.
15
+ * - Both menus are `small`, so the long list of pages stays dense.
15
16
  *
16
17
  * Reads the flattened tree from the surrounding `<TreeProvider>` (`useTreeMap().get("/")`), so child and result hrefs use each element's stamped canonical `path`. To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
17
18
  *
@@ -12,6 +12,7 @@ import { matchMenuElement, TreeMenuMapper } from "./TreeMenu.js";
12
12
  *
13
13
  * - **Middle:** a `<TextInput>` search-as-you-type filter.
14
14
  * - **Bottom:** the root's children as a `<TreeMenuMapper>` — swapped for a flat ranked list of results (capped at 20) while the search holds a query.
15
+ * - Both menus are `small`, so the long list of pages stays dense.
15
16
  *
16
17
  * Reads the flattened tree from the surrounding `<TreeProvider>` (`useTreeMap().get("/")`), so child and result hrefs use each element's stamped canonical `path`. To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
17
18
  *
@@ -24,5 +25,5 @@ export function TreeSidebar({ children }) {
24
25
  // The flattened root from context — its children (and descendants) already carry their canonical `path` and unique `key`.
25
26
  const root = useTreeMap().get("/");
26
27
  const results = root && trimmed ? searchTree(root, trimmed, { limit: 20 }) : null;
27
- return (_jsxs(_Fragment, { children: [_jsx(Menu, { children: _jsx(MenuItem, { href: "/", children: "Home" }) }), children, _jsx(Divider, {}), _jsx(TextInput, { name: "search", title: "Search", placeholder: "Search\u2026", value: query, onValue: v => setQuery(v ?? "") }), _jsx(Divider, {}), _jsx(Menu, { children: results ? (results.map(el => (_jsx(MenuItem, { href: el.props.path ?? "/", children: el.props.title ?? el.props.name }, el.key)))) : (_jsx(TreeMenuMapper, { children: filterElements(root?.props.children, matchMenuElement) })) })] }));
28
+ return (_jsxs(_Fragment, { children: [_jsx(Menu, { small: true, children: _jsx(MenuItem, { href: "/", children: "Home" }) }), children, _jsx(Divider, {}), _jsx(TextInput, { name: "search", title: "Search", placeholder: "Search\u2026", value: query, onValue: v => setQuery(v ?? "") }), _jsx(Divider, {}), _jsx(Menu, { small: true, children: results ? (results.map(el => (_jsx(MenuItem, { href: el.props.path ?? "/", children: el.props.title ?? el.props.name }, el.key)))) : (_jsx(TreeMenuMapper, { children: filterElements(root?.props.children, matchMenuElement) })) })] }));
28
29
  }
@@ -20,6 +20,7 @@ export interface TreeSidebarProps extends OptionalChildProps {}
20
20
  *
21
21
  * - **Middle:** a `<TextInput>` search-as-you-type filter.
22
22
  * - **Bottom:** the root's children as a `<TreeMenuMapper>` — swapped for a flat ranked list of results (capped at 20) while the search holds a query.
23
+ * - Both menus are `small`, so the long list of pages stays dense.
23
24
  *
24
25
  * Reads the flattened tree from the surrounding `<TreeProvider>` (`useTreeMap().get("/")`), so child and result hrefs use each element's stamped canonical `path`. To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
25
26
  *
@@ -36,14 +37,14 @@ export function TreeSidebar({ children }: TreeSidebarProps): ReactNode {
36
37
 
37
38
  return (
38
39
  <>
39
- <Menu>
40
+ <Menu small>
40
41
  <MenuItem href="/">Home</MenuItem>
41
42
  </Menu>
42
43
  {children}
43
44
  <Divider />
44
45
  <TextInput name="search" title="Search" placeholder="Search…" value={query} onValue={v => setQuery(v ?? "")} />
45
46
  <Divider />
46
- <Menu>
47
+ <Menu small>
47
48
  {results ? (
48
49
  results.map(el => (
49
50
  <MenuItem key={el.key} href={el.props.path ?? "/"}>