shelving 1.325.0 → 1.326.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.
@@ -20824,7 +20824,7 @@ The components below are listed in the index following this page; this is the sh
20824
20824
  - [NoticesProps](ui/NoticesProps.md): Props for <Notices> — the place for the list, and flex styling variants for the notices container.
20825
20825
  - [HTMLProps](ui/HTMLProps.md): Props for <HTML> — initial Meta (language/root/app) plus the page children.
20826
20826
  - [PageProps](ui/PageProps.md): Props for <Page> — per-page Meta (title, description, etc.) plus the page children.
20827
- - [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.
20827
+ - [BackButtonProps](ui/BackButtonProps.md): Props for <BackButton>: an optional href to go back to when the stack has no page before this one, plus the usual Button props except onClick.
20828
20828
  - [NavigationProps](ui/NavigationProps.md): Props for <Navigation>: the initial Meta (url, root and stack), the stacks, and optional children.
20829
20829
  - [NavigationEntryState](ui/NavigationEntryState.md): State that NavigationSequence saves on each browser history entry.
20830
20830
  - [NavigationEvent](ui/NavigationEvent.md): One change of page, published by NavigationSequence.
@@ -33393,13 +33393,13 @@ Page({ children, ...meta }: PageProps): ReactElement
33393
33393
  - Import: `import { BackButtonProps } from "shelving/ui";`
33394
33394
  - Extends: `Omit<ButtonProps, "href" | "onClick">`
33395
33395
 
33396
- 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`.
33396
+ Props for `<BackButton>`: an optional `href` to go back to when the stack has no page before this one, plus the usual `Button` props except `onClick`.
33397
33397
 
33398
33398
  ## Signatures
33399
33399
 
33400
33400
  ```ts
33401
33401
  {
33402
- readonly href: AbsolutePath;
33402
+ readonly href?: AbsolutePath | undefined;
33403
33403
  }
33404
33404
  ```
33405
33405
 
@@ -33407,7 +33407,7 @@ Props for `<BackButton>`: the `href` to go back to when the stack has no page be
33407
33407
 
33408
33408
  | Property | Type | Description |
33409
33409
  | --- | --- | --- |
33410
- | `href` | `AbsolutePath` | Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Read only. |
33410
+ | `href` | `AbsolutePath \| undefined` | Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Without it, the button does not show then. Read only. Optional. |
33411
33411
 
33412
33412
 
33413
33413
  ---
@@ -33420,6 +33420,7 @@ Props for `<BackButton>`: the `href` to go back to when the stack has no page be
33420
33420
  Back button for the current stack.
33421
33421
  - Goes back to the page before this one in the current stack, wherever you came from.
33422
33422
  - Goes to `href` when the stack has no page before this one: the app was opened at this page, or the browser has no Navigation API.
33423
+ - Renders nothing when the stack has no page before this one and there is no `href` (for example, at the root of a stack).
33423
33424
  - It is a plain link with `className="back"`, so it slides back, and it works in a server render and with a middle-click.
33424
33425
 
33425
33426
  The back button for a page header. It goes back to the page before this one in the current stack, wherever you came from.
@@ -33427,7 +33428,8 @@ The back button for a page header. It goes back to the page before this one in t
33427
33428
  **Things to know:**
33428
33429
 
33429
33430
  - It goes to the page before this one in the current stack. If you opened a post from a search, it goes back to the search.
33430
- - It goes to `href` when the stack has no page before this one: for example, when the app was opened at this page. So a back button always has somewhere to go. Set `href` to the page's natural parent. On a floating page (for example a deep link), it goes to `href` and stays floating. To go into a stack, the user taps a `<StackButton>`.
33431
+ - It goes to `href` when the stack has no page before this one: for example, when the app was opened at this page. Set `href` to the page's natural parent. On a floating page (for example a deep link), it goes to `href` and stays floating. To go into a stack, the user taps a `<StackButton>`.
33432
+ - Without `href`, it renders nothing when the stack has no page before this one: for example, at the root of a stack, or on a deep link. Use this for a back button that shows only when there is somewhere to go back to.
33431
33433
  - It is a plain link with `className="back"`. `<Navigation>` turns a click into `NavigationSequence.back()`, so the page slides back. A middle-click opens the link in a new browser tab.
33432
33434
  - Its default content is a `<LeftIcon>` and its default `title` is "Back". Pass `children` and `title` to change them.
33433
33435
  - It takes the usual `<Button>` props, except `onClick`.
@@ -33452,6 +33454,12 @@ function PostPage({ id }: { id: string }) {
33452
33454
  }
33453
33455
  ```
33454
33456
 
33457
+ Only when there is a page to go back to (nothing at the root of a stack):
33458
+
33459
+ ```tsx
33460
+ <BackButton />;
33461
+ ```
33462
+
33455
33463
  With a label:
33456
33464
 
33457
33465
  ```tsx
@@ -33474,7 +33482,7 @@ To go back to one fixed page (not to the page before), use a link with `classNam
33474
33482
  ## Signatures
33475
33483
 
33476
33484
  ```ts
33477
- BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props }: BackButtonProps): ReactElement
33485
+ BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props }: BackButtonProps): ReactElement | null
33478
33486
  ```
33479
33487
 
33480
33488
  ## Parameters
@@ -33482,13 +33490,13 @@ BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props
33482
33490
  | Param | Type | Description |
33483
33491
  | --- | --- | --- |
33484
33492
  | `props` | `BackButtonProps` | |
33485
- | `.href` | `AbsolutePath` | Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Read only. |
33493
+ | `.href` | `AbsolutePath \| undefined` | Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Without it, the button does not show then. Read only. Optional. |
33486
33494
 
33487
33495
  ## Returns
33488
33496
 
33489
33497
  | Type | Description |
33490
33498
  | --- | --- |
33491
- | `ReactElement` | |
33499
+ | `ReactElement \| null` | |
33492
33500
 
33493
33501
 
33494
33502
  ---
@@ -6,6 +6,7 @@
6
6
  Back button for the current stack.
7
7
  - Goes back to the page before this one in the current stack, wherever you came from.
8
8
  - Goes to `href` when the stack has no page before this one: the app was opened at this page, or the browser has no Navigation API.
9
+ - Renders nothing when the stack has no page before this one and there is no `href` (for example, at the root of a stack).
9
10
  - It is a plain link with `className="back"`, so it slides back, and it works in a server render and with a middle-click.
10
11
 
11
12
  The back button for a page header. It goes back to the page before this one in the current stack, wherever you came from.
@@ -13,7 +14,8 @@ The back button for a page header. It goes back to the page before this one in t
13
14
  **Things to know:**
14
15
 
15
16
  - It goes to the page before this one in the current stack. If you opened a post from a search, it goes back to the search.
16
- - It goes to `href` when the stack has no page before this one: for example, when the app was opened at this page. So a back button always has somewhere to go. Set `href` to the page's natural parent. On a floating page (for example a deep link), it goes to `href` and stays floating. To go into a stack, the user taps a `<StackButton>`.
17
+ - It goes to `href` when the stack has no page before this one: for example, when the app was opened at this page. Set `href` to the page's natural parent. On a floating page (for example a deep link), it goes to `href` and stays floating. To go into a stack, the user taps a `<StackButton>`.
18
+ - Without `href`, it renders nothing when the stack has no page before this one: for example, at the root of a stack, or on a deep link. Use this for a back button that shows only when there is somewhere to go back to.
17
19
  - It is a plain link with `className="back"`. `<Navigation>` turns a click into `NavigationSequence.back()`, so the page slides back. A middle-click opens the link in a new browser tab.
18
20
  - Its default content is a `<LeftIcon>` and its default `title` is "Back". Pass `children` and `title` to change them.
19
21
  - It takes the usual `<Button>` props, except `onClick`.
@@ -38,6 +40,12 @@ function PostPage({ id }: { id: string }) {
38
40
  }
39
41
  ```
40
42
 
43
+ Only when there is a page to go back to (nothing at the root of a stack):
44
+
45
+ ```tsx
46
+ <BackButton />;
47
+ ```
48
+
41
49
  With a label:
42
50
 
43
51
  ```tsx
@@ -60,7 +68,7 @@ To go back to one fixed page (not to the page before), use a link with `classNam
60
68
  ## Signatures
61
69
 
62
70
  ```ts
63
- BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props }: BackButtonProps): ReactElement
71
+ BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props }: BackButtonProps): ReactElement | null
64
72
  ```
65
73
 
66
74
  ## Parameters
@@ -68,10 +76,10 @@ BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props
68
76
  | Param | Type | Description |
69
77
  | --- | --- | --- |
70
78
  | `props` | `BackButtonProps` | |
71
- | `.href` | `AbsolutePath` | Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Read only. |
79
+ | `.href` | `AbsolutePath \| undefined` | Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Without it, the button does not show then. Read only. Optional. |
72
80
 
73
81
  ## Returns
74
82
 
75
83
  | Type | Description |
76
84
  | --- | --- |
77
- | `ReactElement` | |
85
+ | `ReactElement \| null` | |
@@ -4,13 +4,13 @@
4
4
  - Import: `import { BackButtonProps } from "shelving/ui";`
5
5
  - Extends: `Omit<ButtonProps, "href" | "onClick">`
6
6
 
7
- 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`.
7
+ Props for `<BackButton>`: an optional `href` to go back to when the stack has no page before this one, plus the usual `Button` props except `onClick`.
8
8
 
9
9
  ## Signatures
10
10
 
11
11
  ```ts
12
12
  {
13
- readonly href: AbsolutePath;
13
+ readonly href?: AbsolutePath | undefined;
14
14
  }
15
15
  ```
16
16
 
@@ -18,4 +18,4 @@ Props for `<BackButton>`: the `href` to go back to when the stack has no page be
18
18
 
19
19
  | Property | Type | Description |
20
20
  | --- | --- | --- |
21
- | `href` | `AbsolutePath` | Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Read only. |
21
+ | `href` | `AbsolutePath \| undefined` | Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Without it, the button does not show then. Read only. Optional. |
package/docs/ui.md CHANGED
@@ -461,7 +461,7 @@ The components below are listed in the index following this page; this is the sh
461
461
  - [NoticesProps](ui/NoticesProps.md): Props for <Notices> — the place for the list, and flex styling variants for the notices container.
462
462
  - [HTMLProps](ui/HTMLProps.md): Props for <HTML> — initial Meta (language/root/app) plus the page children.
463
463
  - [PageProps](ui/PageProps.md): Props for <Page> — per-page Meta (title, description, etc.) plus the page children.
464
- - [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.
464
+ - [BackButtonProps](ui/BackButtonProps.md): Props for <BackButton>: an optional href to go back to when the stack has no page before this one, plus the usual Button props except onClick.
465
465
  - [NavigationProps](ui/NavigationProps.md): Props for <Navigation>: the initial Meta (url, root and stack), the stacks, and optional children.
466
466
  - [NavigationEntryState](ui/NavigationEntryState.md): State that NavigationSequence saves on each browser history entry.
467
467
  - [NavigationEvent](ui/NavigationEvent.md): One change of page, published by NavigationSequence.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shelving",
3
- "version": "1.325.0",
3
+ "version": "1.326.0",
4
4
  "author": "Dave Houlbrooke <dave@shax.com>",
5
5
  "repository": {
6
6
  "type": "git",
@@ -2,21 +2,22 @@ import { type ReactElement } from "react";
2
2
  import type { AbsolutePath } from "../../util/path.js";
3
3
  import { type ButtonProps } from "../button/Button.js";
4
4
  /**
5
- * 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`.
5
+ * Props for `<BackButton>`: an optional `href` to go back to when the stack has no page before this one, plus the usual `Button` props except `onClick`.
6
6
  *
7
7
  * @see https://shelving.cc/ui/BackButtonProps
8
8
  */
9
9
  export interface BackButtonProps extends Omit<ButtonProps, "href" | "onClick"> {
10
- /** Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). */
11
- readonly href: AbsolutePath;
10
+ /** Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Without it, the button does not show then. */
11
+ readonly href?: AbsolutePath | undefined;
12
12
  }
13
13
  /**
14
14
  * Back button for the current stack.
15
15
  * - Goes back to the page before this one in the current stack, wherever you came from.
16
16
  * - Goes to `href` when the stack has no page before this one: the app was opened at this page, or the browser has no Navigation API.
17
+ * - Renders nothing when the stack has no page before this one and there is no `href` (for example, at the root of a stack).
17
18
  * - It is a plain link with `className="back"`, so it slides back, and it works in a server render and with a middle-click.
18
19
  *
19
20
  * @kind component
20
21
  * @see https://shelving.cc/ui/BackButton
21
22
  */
22
- export declare function BackButton({ href, className, title, children, ...props }: BackButtonProps): ReactElement;
23
+ export declare function BackButton({ href, className, title, children, ...props }: BackButtonProps): ReactElement | null;
@@ -9,6 +9,7 @@ import { NavigationContext } from "./NavigationContext.js";
9
9
  * Back button for the current stack.
10
10
  * - Goes back to the page before this one in the current stack, wherever you came from.
11
11
  * - Goes to `href` when the stack has no page before this one: the app was opened at this page, or the browser has no Navigation API.
12
+ * - Renders nothing when the stack has no page before this one and there is no `href` (for example, at the root of a stack).
12
13
  * - It is a plain link with `className="back"`, so it slides back, and it works in a server render and with a middle-click.
13
14
  *
14
15
  * @kind component
@@ -18,5 +19,8 @@ export function BackButton({ href, className, title = "Back", children = _jsx(Le
18
19
  const nav = use(NavigationContext);
19
20
  const { stack = null, ordinal } = requireMeta();
20
21
  const parent = nav && ordinal ? nav.history(stack)[ordinal - 1] : undefined;
21
- return (_jsx(Button, { ...props, title: title, href: parent ?? href, className: getClass("back", className), children: children }));
22
+ const target = parent ?? href;
23
+ if (!target)
24
+ return null;
25
+ return (_jsx(Button, { ...props, title: title, href: target, className: getClass("back", className), children: children }));
22
26
  }
@@ -5,7 +5,8 @@ The back button for a page header. It goes back to the page before this one in t
5
5
  **Things to know:**
6
6
 
7
7
  - It goes to the page before this one in the current stack. If you opened a post from a search, it goes back to the search.
8
- - It goes to `href` when the stack has no page before this one: for example, when the app was opened at this page. So a back button always has somewhere to go. Set `href` to the page's natural parent. On a floating page (for example a deep link), it goes to `href` and stays floating. To go into a stack, the user taps a `<StackButton>`.
8
+ - It goes to `href` when the stack has no page before this one: for example, when the app was opened at this page. Set `href` to the page's natural parent. On a floating page (for example a deep link), it goes to `href` and stays floating. To go into a stack, the user taps a `<StackButton>`.
9
+ - Without `href`, it renders nothing when the stack has no page before this one: for example, at the root of a stack, or on a deep link. Use this for a back button that shows only when there is somewhere to go back to.
9
10
  - It is a plain link with `className="back"`. `<Navigation>` turns a click into `NavigationSequence.back()`, so the page slides back. A middle-click opens the link in a new browser tab.
10
11
  - Its default content is a `<LeftIcon>` and its default `title` is "Back". Pass `children` and `title` to change them.
11
12
  - It takes the usual `<Button>` props, except `onClick`.
@@ -30,6 +31,12 @@ function PostPage({ id }: { id: string }) {
30
31
  }
31
32
  ```
32
33
 
34
+ Only when there is a page to go back to (nothing at the root of a stack):
35
+
36
+ ```tsx
37
+ <BackButton />;
38
+ ```
39
+
33
40
  With a label:
34
41
 
35
42
  ```tsx
@@ -7,30 +7,33 @@ import { getClass } from "../util/css.js";
7
7
  import { NavigationContext } from "./NavigationContext.js";
8
8
 
9
9
  /**
10
- * 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`.
10
+ * Props for `<BackButton>`: an optional `href` to go back to when the stack has no page before this one, plus the usual `Button` props except `onClick`.
11
11
  *
12
12
  * @see https://shelving.cc/ui/BackButtonProps
13
13
  */
14
14
  export interface BackButtonProps extends Omit<ButtonProps, "href" | "onClick"> {
15
- /** Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). */
16
- readonly href: AbsolutePath;
15
+ /** Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Without it, the button does not show then. */
16
+ readonly href?: AbsolutePath | undefined;
17
17
  }
18
18
 
19
19
  /**
20
20
  * Back button for the current stack.
21
21
  * - Goes back to the page before this one in the current stack, wherever you came from.
22
22
  * - Goes to `href` when the stack has no page before this one: the app was opened at this page, or the browser has no Navigation API.
23
+ * - Renders nothing when the stack has no page before this one and there is no `href` (for example, at the root of a stack).
23
24
  * - It is a plain link with `className="back"`, so it slides back, and it works in a server render and with a middle-click.
24
25
  *
25
26
  * @kind component
26
27
  * @see https://shelving.cc/ui/BackButton
27
28
  */
28
- export function BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props }: BackButtonProps): ReactElement {
29
+ export function BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props }: BackButtonProps): ReactElement | null {
29
30
  const nav = use(NavigationContext);
30
31
  const { stack = null, ordinal } = requireMeta();
31
32
  const parent = nav && ordinal ? nav.history(stack)[ordinal - 1] : undefined;
33
+ const target = parent ?? href;
34
+ if (!target) return null;
32
35
  return (
33
- <Button {...props} title={title} href={parent ?? href} className={getClass("back", className)}>
36
+ <Button {...props} title={title} href={target} className={getClass("back", className)}>
34
37
  {children}
35
38
  </Button>
36
39
  );
@@ -37,6 +37,15 @@ describe("Navigation", () => {
37
37
  expect(html).toContain('class="back"');
38
38
  });
39
39
 
40
+ test("renders no back button without an href when the stack has no page before this one", () => {
41
+ const html = renderToStaticMarkup(
42
+ <Navigation url="http://x.com/home" stacks={["/home", "/profile"]}>
43
+ <BackButton>Back</BackButton>
44
+ </Navigation>,
45
+ );
46
+ expect(html).toBe("");
47
+ });
48
+
40
49
  test("renders a stack button as a link to its root, selected in the starting stack", () => {
41
50
  const html = renderToStaticMarkup(
42
51
  <Navigation url="http://x.com/profile/settings" stacks={["/home", "/profile"]} stack="/profile">