shelving 1.312.1 → 1.313.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.
@@ -11524,6 +11524,7 @@ QUERY(PERSON).validate({ "address.street": "Main" }); // throws "address.street:
11524
11524
 
11525
11525
  - [ChoiceOptions](schema/ChoiceOptions.md): Dictionary of allowed options for a ChoiceSchema in { key: title } format.
11526
11526
  - [PossibleChoiceOptions](schema/PossibleChoiceOptions.md): Things that can be converted to a ChoiceOptions dictionary.
11527
+ - [ChoiceGroups](schema/ChoiceGroups.md): Named groups of option keys for a ChoiceSchema in { group: [key] } format, e.g. { Fruit: ["apple", "pear"] }.
11527
11528
  - [ChoiceInputType](schema/ChoiceInputType.md): Input control hint for a ChoiceSchema: "radio" for radio inputs, or "select" for a <select>.
11528
11529
  - [DateInputType](schema/DateInputType.md): type="" prop for HTML <input /> tags that are relevant for dates.
11529
11530
  - [SchemaOptions](schema/SchemaOptions.md): Options allowed by a Schema instance.
@@ -12008,6 +12009,31 @@ ImmutableArray<K> | ChoiceOptions<K>
12008
12009
  - [ChoiceOptions](schema/ChoiceOptions.md): Dictionary of allowed options for a ChoiceSchema in { key: title } format.
12009
12010
 
12010
12011
 
12012
+ ---
12013
+
12014
+ # ChoiceGroups
12015
+
12016
+ - Kind: type
12017
+ - Import: `import { ChoiceGroups } from "shelving/schema";`
12018
+
12019
+ Named groups of option keys for a `ChoiceSchema` in `{ group: [key] }` format, e.g. `{ Fruit: ["apple", "pear"] }`.
12020
+
12021
+ - Groups are a display hint only: validation and `format()` use `options`, and do not change.
12022
+ - The group order and the key order in each group set the display order.
12023
+
12024
+ ## Signatures
12025
+
12026
+ ```ts
12027
+ {
12028
+ readonly [group: string]: ImmutableArray<K>;
12029
+ }
12030
+ ```
12031
+
12032
+ ## Types
12033
+
12034
+ - [ImmutableArray](util/array/ImmutableArray.md): Immutable array: an array that cannot be changed.
12035
+
12036
+
12011
12037
  ---
12012
12038
 
12013
12039
  # ChoiceInputType
@@ -12037,6 +12063,7 @@ Options for `ChoiceSchema`.
12037
12063
  - `options` — the allowed choices, as a `{ key: title }` dictionary or an array of keys.
12038
12064
  - `value` — default option used when the input is `undefined`.
12039
12065
  - `input` — control hint for downstream UIs (radios or a select).
12066
+ - `groups` — display hint that puts options under named headings (a select shows each group as an `<optgroup>`).
12040
12067
 
12041
12068
  ## Signatures
12042
12069
 
@@ -12045,6 +12072,7 @@ Options for `ChoiceSchema`.
12045
12072
  readonly options: PossibleChoiceOptions<O>;
12046
12073
  readonly value?: O | I;
12047
12074
  readonly input?: ChoiceInputType | undefined;
12075
+ readonly groups?: ChoiceGroups<O> | undefined;
12048
12076
  }
12049
12077
  ```
12050
12078
 
@@ -12055,6 +12083,7 @@ Options for `ChoiceSchema`.
12055
12083
  | `options` | `PossibleChoiceOptions<O>` | Specify correct options using a dictionary of entries. Read only. |
12056
12084
  | `value` | `O \| I` | Default option for the value. Read only. Optional. |
12057
12085
  | `input` | `ChoiceInputType \| undefined` | Input control hint for downstream UIs. Read only. Defaults to `"radio" for 8 or fewer options, otherwise "select"`. |
12086
+ | `groups` | `ChoiceGroups<O> \| undefined` | Show the options under named headings, as a `{ group: [key] }` dictionary. Options in no group show first. Read only. Optional. |
12058
12087
 
12059
12088
 
12060
12089
  ---
@@ -12101,11 +12130,34 @@ const UNIT = new ChoiceSchema({ options: ["kg", "g", "lb"], input: "select" });
12101
12130
  const SIZE = new ChoiceSchema({ options: ["s", "m", "l", "xl"], input: "radio" }); // Always radios.
12102
12131
  ```
12103
12132
 
12133
+ ## Groups
12134
+
12135
+ `groups` puts options under named headings. A select shows each group as an `<optgroup>`, after the options that are in no group. The group order and the key order in each group set the display order. Groups are a display hint only: validation and `format()` still use `options`.
12136
+
12137
+ ```ts
12138
+ import { ChoiceSchema } from "shelving/schema";
12139
+
12140
+ const FOOD = new ChoiceSchema({
12141
+ options: { none: "Nothing", apple: "Apple", pear: "Pear", carrot: "Carrot" },
12142
+ groups: { Fruit: ["apple", "pear"], Vegetables: ["carrot"] },
12143
+ input: "select",
12144
+ });
12145
+ ```
12146
+
12104
12147
 
12105
12148
  ## Signatures
12106
12149
 
12107
12150
  ```ts
12108
- new ChoiceSchema<O, I>({ one = "choice", title = "Choice", placeholder = `No ${one}`, options, value, input, ...rest }: ChoiceSchemaOptions<O, I>)
12151
+ new ChoiceSchema<O, I>({
12152
+ one = "choice",
12153
+ title = "Choice",
12154
+ placeholder = `No ${one}`,
12155
+ options,
12156
+ value,
12157
+ input,
12158
+ groups,
12159
+ ...rest
12160
+ }: ChoiceSchemaOptions<O, I>)
12109
12161
  ```
12110
12162
 
12111
12163
  ## Parameters
@@ -12116,6 +12168,7 @@ new ChoiceSchema<O, I>({ one = "choice", title = "Choice", placeholder = `No ${o
12116
12168
  | `.options` | `PossibleChoiceOptions<O>` | Specify correct options using a dictionary of entries. Read only. |
12117
12169
  | `.value` | `O \| I` | Default option for the value. Read only. Optional. |
12118
12170
  | `.input` | `ChoiceInputType \| undefined` | Input control hint for downstream UIs. Read only. Defaults to `"radio" for 8 or fewer options, otherwise "select"`. |
12171
+ | `.groups` | `ChoiceGroups<O> \| undefined` | Show the options under named headings, as a `{ group: [key] }` dictionary. Options in no group show first. Read only. Optional. |
12119
12172
 
12120
12173
  ## Returns
12121
12174
 
@@ -12129,6 +12182,7 @@ new ChoiceSchema<O, I>({ one = "choice", title = "Choice", placeholder = `No ${o
12129
12182
  | --- | --- | --- |
12130
12183
  | `options` | `ChoiceOptions<O>` | Read only. |
12131
12184
  | `input` | `ChoiceInputType` | Read only. |
12185
+ | `groups` | `ChoiceGroups<O> \| undefined` | Read only. |
12132
12186
 
12133
12187
  ## Methods
12134
12188
 
@@ -19511,7 +19565,7 @@ The components below are listed in the index following this page; this is the sh
19511
19565
  - [Title](ui/Title.md): Page title — renders an <h1>.
19512
19566
  - [Video](ui/Video.md): Video container element.
19513
19567
  - [Button](ui/Button.md): Render either a <button> or an <a href=""> styled as a button, based on whether an onClick or href prop is provided.
19514
- - [Clickable](ui/Clickable.md): Render either a <button>, an <a href="">, or a plain <span> based on whether an onClick or href prop is provided.
19568
+ - [Clickable](ui/Clickable.md): Render an <a href="">, a <button>, or a plain <span>, from the href, onClick and disabled props.
19515
19569
  - [FullscreenButton](ui/FullscreenButton.md): Button to toggle the surrounding <figure> element or <body> element in/out of fullscreen mode.
19516
19570
  - [RetryButton](ui/RetryButton.md): Button that retries the nearest <Catcher> error boundary when clicked.
19517
19571
  - [Dialog](ui/Dialog.md): Modal <dialog> element that opens on mount and includes a close button.
@@ -19546,7 +19600,7 @@ The components below are listed in the index following this page; this is the sh
19546
19600
  - [Deleted](ui/Deleted.md): Deleted text — renders a <del> element to mark content removed from a document.
19547
19601
  - [Emphasis](ui/Emphasis.md): Emphasised text — renders an <em> element for stress emphasis (typically italic).
19548
19602
  - [Inserted](ui/Inserted.md): Inserted text — renders an <ins> element to mark content added to a document.
19549
- - [Link](ui/Link.md): Inline link — delegates to <Clickable>, rendering an <a> (when href is set) or <button> (when onClick is set).
19603
+ - [Link](ui/Link.md): Inline link — delegates to <Clickable>, rendering an <a> (when href is set), a <button> (when onClick or disabled is set), or a <span>.
19550
19604
  - [Mark](ui/Mark.md): Highlighted text — renders a <mark> element to call attention to a run of text.
19551
19605
  - [Small](ui/Small.md): Small print — renders a <small> element for side comments and fine print.
19552
19606
  - [Span](ui/Span.md): Styled inline text — renders a <span> carrying only the colour and typography variant classes, with no styling of its own.
@@ -19633,7 +19687,7 @@ The components below are listed in the index following this page; this is the sh
19633
19687
  - [getButtonClass()](ui/getButtonClass.md): Get the full combined className string for a button from its styling variants.
19634
19688
  - [LinkClickable()](ui/LinkClickable.md): Render an <a href=""> element, resolving its href against the current page URL and marking it active when it matches.
19635
19689
  - [ButtonClickable()](ui/ButtonClickable.md): Render a <button> element that runs its onClick handler through a BusyStore and shows a loading spinner while busy.
19636
- - [SpanClickable()](ui/SpanClickable.md): Render a non-interactive <span> element, used as the fallback when neither href nor onClick is provided.
19690
+ - [SpanClickable()](ui/SpanClickable.md): Render a non-interactive <span> element, used as the fallback when none of href, onClick or disabled is provided, e.g. a plain tag.
19637
19691
  - [SubmitButton()](ui/SubmitButton.md): Submit button for a form that disables itself and shows a spinner while the form is busy.
19638
19692
  - [requireDialogs()](ui/requireDialogs.md): Read the current DialogsStore from the nearest <DialogsContext>.
19639
19693
  - [DocumentationApp()](ui/DocumentationApp.md): Documentation app.
@@ -22527,8 +22581,9 @@ Props for a clickable that also accepts a `className` for styling.
22527
22581
  - Kind: component
22528
22582
  - Import: `import { Clickable } from "shelving/ui";`
22529
22583
 
22530
- Render either a `<button>`, an `<a href="">`, or a plain `<span>` based on whether an `onClick` or `href` prop is provided.
22531
- - `href` renders a `LinkClickable`; `onClick` renders a `ButtonClickable`; neither renders a `SpanClickable`.
22584
+ Render an `<a href="">`, a `<button>`, or a plain `<span>`, from the `href`, `onClick` and `disabled` props.
22585
+ - `href` renders a `LinkClickable`; `onClick` or `disabled` renders a `ButtonClickable`; neither renders a `SpanClickable`.
22586
+ - `disabled` with no `onClick` is a disabled `<button>`, e.g. a "Locked" button that can never be pressed.
22532
22587
  - Dispatches on defined values (not key presence) so wrappers can always spread `href={href}` through, even when it's `undefined`.
22533
22588
 
22534
22589
  ## Signatures
@@ -22655,7 +22710,7 @@ ButtonClickable({
22655
22710
  - Kind: function
22656
22711
  - Import: `import { SpanClickable } from "shelving/ui";`
22657
22712
 
22658
- Render a non-interactive `<span>` element, used as the fallback when neither `href` nor `onClick` is provided.
22713
+ Render a non-interactive `<span>` element, used as the fallback when none of `href`, `onClick` or `disabled` is provided, e.g. a plain tag.
22659
22714
 
22660
22715
  ## Signatures
22661
22716
 
@@ -25882,7 +25937,7 @@ Props for `Link` — `ClickableProps` (`href` for navigation or `onClick` for ac
25882
25937
  - Kind: component
25883
25938
  - Import: `import { Link } from "shelving/ui";`
25884
25939
 
25885
- Inline link — delegates to `<Clickable>`, rendering an `<a>` (when `href` is set) or `<button>` (when `onClick` is set).
25940
+ Inline link — delegates to `<Clickable>`, rendering an `<a>` (when `href` is set), a `<button>` (when `onClick` or `disabled` is set), or a `<span>`.
25886
25941
 
25887
25942
  An inline link or action. Delegates to `<Clickable>`, rendering an `<a>` when `href` is provided or a `<button>` when `onClick` is provided — so the same component covers both navigation and in-page actions. Prefer it over a raw `<a>` inside React components.
25888
25943
 
@@ -28913,6 +28968,7 @@ Props for `SelectInput`, a dropdown `<select>` bound to a string value.
28913
28968
  ```ts
28914
28969
  {
28915
28970
  options: ChoiceOptions<T>;
28971
+ groups?: ChoiceGroups<T> | undefined;
28916
28972
  }
28917
28973
  ```
28918
28974
 
@@ -28921,6 +28977,7 @@ Props for `SelectInput`, a dropdown `<select>` bound to a string value.
28921
28977
  | Property | Type | Description |
28922
28978
  | --- | --- | --- |
28923
28979
  | `options` | `ChoiceOptions<T>` | The options for the select. |
28980
+ | `groups` | `ChoiceGroups<T> \| undefined` | Show the options under named headings, as `<optgroup>` elements. Options in no group show first. Optional. |
28924
28981
 
28925
28982
 
28926
28983
  ---
@@ -28932,6 +28989,7 @@ Props for `SelectInput`, a dropdown `<select>` bound to a string value.
28932
28989
 
28933
28990
  Dropdown input bound to a string value, rendered as a `<select>` of the provided `options`.
28934
28991
  - Shows a placeholder empty option unless the field is required and already has a value.
28992
+ - With `groups`, shows each group as an `<optgroup>`, after the options that are in no group. A group key that is not in `options` is skipped.
28935
28993
 
28936
28994
  ## Signatures
28937
28995
 
@@ -28945,6 +29003,7 @@ SelectInput(props: SelectProps<T>): ReactElement
28945
29003
  | --- | --- | --- |
28946
29004
  | `props` | `SelectProps<T>` | |
28947
29005
  | `.options` | `ChoiceOptions<T>` | The options for the select. |
29006
+ | `.groups` | `ChoiceGroups<T> \| undefined` | Show the options under named headings, as `<optgroup>` elements. Options in no group show first. Optional. |
28948
29007
 
28949
29008
  ## Returns
28950
29009
 
@@ -30485,7 +30544,7 @@ Props for `<Tag>` — `TagVariants` styling options plus `<Clickable>` props (`h
30485
30544
  - Import: `import { Tag } from "shelving/ui";`
30486
30545
 
30487
30546
  Small inline label used to annotate other content.
30488
- - Delegates to `getClickable()` — renders as `<a>` when `href` is set, otherwise `<button>`.
30547
+ - Delegates to `<Clickable>` — renders as `<a>` when `href` is set, `<button>` when `onClick` or `disabled` is set, otherwise `<span>`.
30489
30548
  - Accepts a status variant (`success`, `info`, `error`, etc.) _or_ a raw colour (`color="red"`, `color="purple"`, etc.).
30490
30549
 
30491
30550
  A small inline label used to annotate other content. Accepts a status variant or a raw colour, and can be static or interactive depending on whether `href` / `onClick` is set.
@@ -0,0 +1,21 @@
1
+ # ChoiceGroups
2
+
3
+ - Kind: type
4
+ - Import: `import { ChoiceGroups } from "shelving/schema";`
5
+
6
+ Named groups of option keys for a `ChoiceSchema` in `{ group: [key] }` format, e.g. `{ Fruit: ["apple", "pear"] }`.
7
+
8
+ - Groups are a display hint only: validation and `format()` use `options`, and do not change.
9
+ - The group order and the key order in each group set the display order.
10
+
11
+ ## Signatures
12
+
13
+ ```ts
14
+ {
15
+ readonly [group: string]: ImmutableArray<K>;
16
+ }
17
+ ```
18
+
19
+ ## Types
20
+
21
+ - [ImmutableArray](../util/array/ImmutableArray.md): Immutable array: an array that cannot be changed.
@@ -40,11 +40,34 @@ const UNIT = new ChoiceSchema({ options: ["kg", "g", "lb"], input: "select" });
40
40
  const SIZE = new ChoiceSchema({ options: ["s", "m", "l", "xl"], input: "radio" }); // Always radios.
41
41
  ```
42
42
 
43
+ ## Groups
44
+
45
+ `groups` puts options under named headings. A select shows each group as an `<optgroup>`, after the options that are in no group. The group order and the key order in each group set the display order. Groups are a display hint only: validation and `format()` still use `options`.
46
+
47
+ ```ts
48
+ import { ChoiceSchema } from "shelving/schema";
49
+
50
+ const FOOD = new ChoiceSchema({
51
+ options: { none: "Nothing", apple: "Apple", pear: "Pear", carrot: "Carrot" },
52
+ groups: { Fruit: ["apple", "pear"], Vegetables: ["carrot"] },
53
+ input: "select",
54
+ });
55
+ ```
56
+
43
57
 
44
58
  ## Signatures
45
59
 
46
60
  ```ts
47
- new ChoiceSchema<O, I>({ one = "choice", title = "Choice", placeholder = `No ${one}`, options, value, input, ...rest }: ChoiceSchemaOptions<O, I>)
61
+ new ChoiceSchema<O, I>({
62
+ one = "choice",
63
+ title = "Choice",
64
+ placeholder = `No ${one}`,
65
+ options,
66
+ value,
67
+ input,
68
+ groups,
69
+ ...rest
70
+ }: ChoiceSchemaOptions<O, I>)
48
71
  ```
49
72
 
50
73
  ## Parameters
@@ -55,6 +78,7 @@ new ChoiceSchema<O, I>({ one = "choice", title = "Choice", placeholder = `No ${o
55
78
  | `.options` | `PossibleChoiceOptions<O>` | Specify correct options using a dictionary of entries. Read only. |
56
79
  | `.value` | `O \| I` | Default option for the value. Read only. Optional. |
57
80
  | `.input` | `ChoiceInputType \| undefined` | Input control hint for downstream UIs. Read only. Defaults to `"radio" for 8 or fewer options, otherwise "select"`. |
81
+ | `.groups` | `ChoiceGroups<O> \| undefined` | Show the options under named headings, as a `{ group: [key] }` dictionary. Options in no group show first. Read only. Optional. |
58
82
 
59
83
  ## Returns
60
84
 
@@ -68,6 +92,7 @@ new ChoiceSchema<O, I>({ one = "choice", title = "Choice", placeholder = `No ${o
68
92
  | --- | --- | --- |
69
93
  | `options` | `ChoiceOptions<O>` | Read only. |
70
94
  | `input` | `ChoiceInputType` | Read only. |
95
+ | `groups` | `ChoiceGroups<O> \| undefined` | Read only. |
71
96
 
72
97
  ## Methods
73
98
 
@@ -9,6 +9,7 @@ Options for `ChoiceSchema`.
9
9
  - `options` — the allowed choices, as a `{ key: title }` dictionary or an array of keys.
10
10
  - `value` — default option used when the input is `undefined`.
11
11
  - `input` — control hint for downstream UIs (radios or a select).
12
+ - `groups` — display hint that puts options under named headings (a select shows each group as an `<optgroup>`).
12
13
 
13
14
  ## Signatures
14
15
 
@@ -17,6 +18,7 @@ Options for `ChoiceSchema`.
17
18
  readonly options: PossibleChoiceOptions<O>;
18
19
  readonly value?: O | I;
19
20
  readonly input?: ChoiceInputType | undefined;
21
+ readonly groups?: ChoiceGroups<O> | undefined;
20
22
  }
21
23
  ```
22
24
 
@@ -27,3 +29,4 @@ Options for `ChoiceSchema`.
27
29
  | `options` | `PossibleChoiceOptions<O>` | Specify correct options using a dictionary of entries. Read only. |
28
30
  | `value` | `O \| I` | Default option for the value. Read only. Optional. |
29
31
  | `input` | `ChoiceInputType \| undefined` | Input control hint for downstream UIs. Read only. Defaults to `"radio" for 8 or fewer options, otherwise "select"`. |
32
+ | `groups` | `ChoiceGroups<O> \| undefined` | Show the options under named headings, as a `{ group: [key] }` dictionary. Options in no group show first. Read only. Optional. |
package/docs/schema.md CHANGED
@@ -190,6 +190,7 @@ QUERY(PERSON).validate({ "address.street": "Main" }); // throws "address.street:
190
190
 
191
191
  - [ChoiceOptions](schema/ChoiceOptions.md): Dictionary of allowed options for a ChoiceSchema in { key: title } format.
192
192
  - [PossibleChoiceOptions](schema/PossibleChoiceOptions.md): Things that can be converted to a ChoiceOptions dictionary.
193
+ - [ChoiceGroups](schema/ChoiceGroups.md): Named groups of option keys for a ChoiceSchema in { group: [key] } format, e.g. { Fruit: ["apple", "pear"] }.
193
194
  - [ChoiceInputType](schema/ChoiceInputType.md): Input control hint for a ChoiceSchema: "radio" for radio inputs, or "select" for a <select>.
194
195
  - [DateInputType](schema/DateInputType.md): type="" prop for HTML <input /> tags that are relevant for dates.
195
196
  - [SchemaOptions](schema/SchemaOptions.md): Options allowed by a Schema instance.
@@ -3,8 +3,9 @@
3
3
  - Kind: component
4
4
  - Import: `import { Clickable } from "shelving/ui";`
5
5
 
6
- Render either a `<button>`, an `<a href="">`, or a plain `<span>` based on whether an `onClick` or `href` prop is provided.
7
- - `href` renders a `LinkClickable`; `onClick` renders a `ButtonClickable`; neither renders a `SpanClickable`.
6
+ Render an `<a href="">`, a `<button>`, or a plain `<span>`, from the `href`, `onClick` and `disabled` props.
7
+ - `href` renders a `LinkClickable`; `onClick` or `disabled` renders a `ButtonClickable`; neither renders a `SpanClickable`.
8
+ - `disabled` with no `onClick` is a disabled `<button>`, e.g. a "Locked" button that can never be pressed.
8
9
  - Dispatches on defined values (not key presence) so wrappers can always spread `href={href}` through, even when it's `undefined`.
9
10
 
10
11
  ## Signatures
package/docs/ui/Link.md CHANGED
@@ -3,7 +3,7 @@
3
3
  - Kind: component
4
4
  - Import: `import { Link } from "shelving/ui";`
5
5
 
6
- Inline link — delegates to `<Clickable>`, rendering an `<a>` (when `href` is set) or `<button>` (when `onClick` is set).
6
+ Inline link — delegates to `<Clickable>`, rendering an `<a>` (when `href` is set), a `<button>` (when `onClick` or `disabled` is set), or a `<span>`.
7
7
 
8
8
  An inline link or action. Delegates to `<Clickable>`, rendering an `<a>` when `href` is provided or a `<button>` when `onClick` is provided — so the same component covers both navigation and in-page actions. Prefer it over a raw `<a>` inside React components.
9
9
 
@@ -5,6 +5,7 @@
5
5
 
6
6
  Dropdown input bound to a string value, rendered as a `<select>` of the provided `options`.
7
7
  - Shows a placeholder empty option unless the field is required and already has a value.
8
+ - With `groups`, shows each group as an `<optgroup>`, after the options that are in no group. A group key that is not in `options` is skipped.
8
9
 
9
10
  ## Signatures
10
11
 
@@ -18,6 +19,7 @@ SelectInput(props: SelectProps<T>): ReactElement
18
19
  | --- | --- | --- |
19
20
  | `props` | `SelectProps<T>` | |
20
21
  | `.options` | `ChoiceOptions<T>` | The options for the select. |
22
+ | `.groups` | `ChoiceGroups<T> \| undefined` | Show the options under named headings, as `<optgroup>` elements. Options in no group show first. Optional. |
21
23
 
22
24
  ## Returns
23
25
 
@@ -11,6 +11,7 @@ Props for `SelectInput`, a dropdown `<select>` bound to a string value.
11
11
  ```ts
12
12
  {
13
13
  options: ChoiceOptions<T>;
14
+ groups?: ChoiceGroups<T> | undefined;
14
15
  }
15
16
  ```
16
17
 
@@ -19,3 +20,4 @@ Props for `SelectInput`, a dropdown `<select>` bound to a string value.
19
20
  | Property | Type | Description |
20
21
  | --- | --- | --- |
21
22
  | `options` | `ChoiceOptions<T>` | The options for the select. |
23
+ | `groups` | `ChoiceGroups<T> \| undefined` | Show the options under named headings, as `<optgroup>` elements. Options in no group show first. Optional. |
@@ -3,7 +3,7 @@
3
3
  - Kind: function
4
4
  - Import: `import { SpanClickable } from "shelving/ui";`
5
5
 
6
- Render a non-interactive `<span>` element, used as the fallback when neither `href` nor `onClick` is provided.
6
+ Render a non-interactive `<span>` element, used as the fallback when none of `href`, `onClick` or `disabled` is provided, e.g. a plain tag.
7
7
 
8
8
  ## Signatures
9
9
 
package/docs/ui/Tag.md CHANGED
@@ -4,7 +4,7 @@
4
4
  - Import: `import { Tag } from "shelving/ui";`
5
5
 
6
6
  Small inline label used to annotate other content.
7
- - Delegates to `getClickable()` — renders as `<a>` when `href` is set, otherwise `<button>`.
7
+ - Delegates to `<Clickable>` — renders as `<a>` when `href` is set, `<button>` when `onClick` or `disabled` is set, otherwise `<span>`.
8
8
  - Accepts a status variant (`success`, `info`, `error`, etc.) _or_ a raw colour (`color="red"`, `color="purple"`, etc.).
9
9
 
10
10
  A small inline label used to annotate other content. Accepts a status variant or a raw colour, and can be static or interactive depending on whether `href` / `onClick` is set.
package/docs/ui.md CHANGED
@@ -100,7 +100,7 @@ The components below are listed in the index following this page; this is the sh
100
100
  - [Title](ui/Title.md): Page title — renders an <h1>.
101
101
  - [Video](ui/Video.md): Video container element.
102
102
  - [Button](ui/Button.md): Render either a <button> or an <a href=""> styled as a button, based on whether an onClick or href prop is provided.
103
- - [Clickable](ui/Clickable.md): Render either a <button>, an <a href="">, or a plain <span> based on whether an onClick or href prop is provided.
103
+ - [Clickable](ui/Clickable.md): Render an <a href="">, a <button>, or a plain <span>, from the href, onClick and disabled props.
104
104
  - [FullscreenButton](ui/FullscreenButton.md): Button to toggle the surrounding <figure> element or <body> element in/out of fullscreen mode.
105
105
  - [RetryButton](ui/RetryButton.md): Button that retries the nearest <Catcher> error boundary when clicked.
106
106
  - [Dialog](ui/Dialog.md): Modal <dialog> element that opens on mount and includes a close button.
@@ -135,7 +135,7 @@ The components below are listed in the index following this page; this is the sh
135
135
  - [Deleted](ui/Deleted.md): Deleted text — renders a <del> element to mark content removed from a document.
136
136
  - [Emphasis](ui/Emphasis.md): Emphasised text — renders an <em> element for stress emphasis (typically italic).
137
137
  - [Inserted](ui/Inserted.md): Inserted text — renders an <ins> element to mark content added to a document.
138
- - [Link](ui/Link.md): Inline link — delegates to <Clickable>, rendering an <a> (when href is set) or <button> (when onClick is set).
138
+ - [Link](ui/Link.md): Inline link — delegates to <Clickable>, rendering an <a> (when href is set), a <button> (when onClick or disabled is set), or a <span>.
139
139
  - [Mark](ui/Mark.md): Highlighted text — renders a <mark> element to call attention to a run of text.
140
140
  - [Small](ui/Small.md): Small print — renders a <small> element for side comments and fine print.
141
141
  - [Span](ui/Span.md): Styled inline text — renders a <span> carrying only the colour and typography variant classes, with no styling of its own.
@@ -222,7 +222,7 @@ The components below are listed in the index following this page; this is the sh
222
222
  - [getButtonClass()](ui/getButtonClass.md): Get the full combined className string for a button from its styling variants.
223
223
  - [LinkClickable()](ui/LinkClickable.md): Render an <a href=""> element, resolving its href against the current page URL and marking it active when it matches.
224
224
  - [ButtonClickable()](ui/ButtonClickable.md): Render a <button> element that runs its onClick handler through a BusyStore and shows a loading spinner while busy.
225
- - [SpanClickable()](ui/SpanClickable.md): Render a non-interactive <span> element, used as the fallback when neither href nor onClick is provided.
225
+ - [SpanClickable()](ui/SpanClickable.md): Render a non-interactive <span> element, used as the fallback when none of href, onClick or disabled is provided, e.g. a plain tag.
226
226
  - [SubmitButton()](ui/SubmitButton.md): Submit button for a form that disables itself and shows a spinner while the form is busy.
227
227
  - [requireDialogs()](ui/requireDialogs.md): Read the current DialogsStore from the nearest <DialogsContext>.
228
228
  - [DocumentationApp()](ui/DocumentationApp.md): Documentation app.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shelving",
3
- "version": "1.312.1",
3
+ "version": "1.313.0",
4
4
  "author": "Dave Houlbrooke <dave@shax.com>",
5
5
  "repository": {
6
6
  "type": "git",
@@ -18,6 +18,17 @@ export type ChoiceOptions<K extends string> = {
18
18
  * @see https://shelving.cc/schema/PossibleChoiceOptions
19
19
  */
20
20
  export type PossibleChoiceOptions<K extends string> = ImmutableArray<K> | ChoiceOptions<K>;
21
+ /**
22
+ * Named groups of option keys for a `ChoiceSchema` in `{ group: [key] }` format, e.g. `{ Fruit: ["apple", "pear"] }`.
23
+ *
24
+ * - Groups are a display hint only: validation and `format()` use `options`, and do not change.
25
+ * - The group order and the key order in each group set the display order.
26
+ *
27
+ * @see https://shelving.cc/schema/ChoiceGroups
28
+ */
29
+ export type ChoiceGroups<K extends string> = {
30
+ readonly [group: string]: ImmutableArray<K>;
31
+ };
21
32
  /**
22
33
  * Input control hint for a `ChoiceSchema`: `"radio"` for radio inputs, or `"select"` for a `<select>`.
23
34
  *
@@ -30,6 +41,7 @@ export type ChoiceInputType = "radio" | "select";
30
41
  * - `options` — the allowed choices, as a `{ key: title }` dictionary or an array of keys.
31
42
  * - `value` — default option used when the input is `undefined`.
32
43
  * - `input` — control hint for downstream UIs (radios or a select).
44
+ * - `groups` — display hint that puts options under named headings (a select shows each group as an `<optgroup>`).
33
45
  *
34
46
  * @see https://shelving.cc/schema/ChoiceSchemaOptions
35
47
  */
@@ -43,6 +55,8 @@ export interface ChoiceSchemaOptions<O extends string, I = never> extends Schema
43
55
  * @default "radio" for 8 or fewer options, otherwise "select"
44
56
  */
45
57
  readonly input?: ChoiceInputType | undefined;
58
+ /** Show the options under named headings, as a `{ group: [key] }` dictionary. Options in no group show first. */
59
+ readonly groups?: ChoiceGroups<O> | undefined;
46
60
  }
47
61
  /**
48
62
  * Schema that validates a value against a fixed set of allowed string choices.
@@ -56,7 +70,8 @@ export declare class ChoiceSchema<O extends string, I = never> extends Schema<O>
56
70
  readonly value: O | I | undefined;
57
71
  readonly options: ChoiceOptions<O>;
58
72
  readonly input: ChoiceInputType;
59
- constructor({ one, title, placeholder, options, value, input, ...rest }: ChoiceSchemaOptions<O, I>);
73
+ readonly groups: ChoiceGroups<O> | undefined;
74
+ constructor({ one, title, placeholder, options, value, input, groups, ...rest }: ChoiceSchemaOptions<O, I>);
60
75
  /**
61
76
  * Get an unknown value as one of the allowed choices, or `undefined` if it isn't one.
62
77
  *
@@ -21,9 +21,11 @@ const MAX_RADIO_OPTIONS = 8;
21
21
  export class ChoiceSchema extends Schema {
22
22
  options;
23
23
  input;
24
- constructor({ one = "choice", title = "Choice", placeholder = `No ${one}`, options, value, input, ...rest }) {
24
+ groups;
25
+ constructor({ one = "choice", title = "Choice", placeholder = `No ${one}`, options, value, input, groups, ...rest }) {
25
26
  super({ one, title, value, placeholder, ...rest });
26
27
  this.options = _getChoiceOptions(options);
28
+ this.groups = groups;
27
29
  this.input = input ?? (getKeys(this.options).length <= MAX_RADIO_OPTIONS ? "radio" : "select");
28
30
  }
29
31
  /**
@@ -43,8 +43,9 @@ export interface ClickableProps extends OptionalChildProps {
43
43
  export interface StylableClickableProps extends ClickableProps, ClassProps {
44
44
  }
45
45
  /**
46
- * Render either a `<button>`, an `<a href="">`, or a plain `<span>` based on whether an `onClick` or `href` prop is provided.
47
- * - `href` renders a `LinkClickable`; `onClick` renders a `ButtonClickable`; neither renders a `SpanClickable`.
46
+ * Render an `<a href="">`, a `<button>`, or a plain `<span>`, from the `href`, `onClick` and `disabled` props.
47
+ * - `href` renders a `LinkClickable`; `onClick` or `disabled` renders a `ButtonClickable`; neither renders a `SpanClickable`.
48
+ * - `disabled` with no `onClick` is a disabled `<button>`, e.g. a "Locked" button that can never be pressed.
48
49
  * - Dispatches on defined values (not key presence) so wrappers can always spread `href={href}` through, even when it's `undefined`.
49
50
  *
50
51
  * @kind component
@@ -72,7 +73,7 @@ export declare function LinkClickable({ href, disabled, target, download, title,
72
73
  */
73
74
  export declare function ButtonClickable({ onClick, disabled, title, selected, children, className, }: StylableClickableProps): ReactElement;
74
75
  /**
75
- * Render a non-interactive `<span>` element, used as the fallback when neither `href` nor `onClick` is provided.
76
+ * Render a non-interactive `<span>` element, used as the fallback when none of `href`, `onClick` or `disabled` is provided, e.g. a plain tag.
76
77
  *
77
78
  * @example <SpanClickable className="label">Static</SpanClickable>
78
79
  * @see https://shelving.cc/ui/SpanClickable
@@ -9,8 +9,9 @@ import { requireMeta } from "../misc/MetaContext.js";
9
9
  import { getClass } from "../util/css.js";
10
10
  import { callNotifiedElement } from "../util/notice.js";
11
11
  /**
12
- * Render either a `<button>`, an `<a href="">`, or a plain `<span>` based on whether an `onClick` or `href` prop is provided.
13
- * - `href` renders a `LinkClickable`; `onClick` renders a `ButtonClickable`; neither renders a `SpanClickable`.
12
+ * Render an `<a href="">`, a `<button>`, or a plain `<span>`, from the `href`, `onClick` and `disabled` props.
13
+ * - `href` renders a `LinkClickable`; `onClick` or `disabled` renders a `ButtonClickable`; neither renders a `SpanClickable`.
14
+ * - `disabled` with no `onClick` is a disabled `<button>`, e.g. a "Locked" button that can never be pressed.
14
15
  * - Dispatches on defined values (not key presence) so wrappers can always spread `href={href}` through, even when it's `undefined`.
15
16
  *
16
17
  * @kind component
@@ -19,7 +20,7 @@ import { callNotifiedElement } from "../util/notice.js";
19
20
  * @see https://shelving.cc/ui/Clickable
20
21
  */
21
22
  export function Clickable(props) {
22
- return props.href !== undefined ? (_jsx(LinkClickable, { ...props })) : props.onClick !== undefined ? (_jsx(ButtonClickable, { ...props })) : (_jsx(SpanClickable, { ...props }));
23
+ return props.href !== undefined ? (_jsx(LinkClickable, { ...props })) : props.onClick !== undefined || props.disabled ? (_jsx(ButtonClickable, { ...props })) : (_jsx(SpanClickable, { ...props }));
23
24
  }
24
25
  /**
25
26
  * Render an `<a href="">` element, resolving its `href` against the current page URL and marking it active when it matches.
@@ -60,7 +61,7 @@ export function ButtonClickable({ onClick, disabled = !onClick, title, selected,
60
61
  }, children: busy ? LOADING : children }));
61
62
  }
62
63
  /**
63
- * Render a non-interactive `<span>` element, used as the fallback when neither `href` nor `onClick` is provided.
64
+ * Render a non-interactive `<span>` element, used as the fallback when none of `href`, `onClick` or `disabled` is provided, e.g. a plain tag.
64
65
  *
65
66
  * @example <SpanClickable className="label">Static</SpanClickable>
66
67
  * @see https://shelving.cc/ui/SpanClickable
@@ -55,8 +55,9 @@ export interface ClickableProps extends OptionalChildProps {
55
55
  export interface StylableClickableProps extends ClickableProps, ClassProps {}
56
56
 
57
57
  /**
58
- * Render either a `<button>`, an `<a href="">`, or a plain `<span>` based on whether an `onClick` or `href` prop is provided.
59
- * - `href` renders a `LinkClickable`; `onClick` renders a `ButtonClickable`; neither renders a `SpanClickable`.
58
+ * Render an `<a href="">`, a `<button>`, or a plain `<span>`, from the `href`, `onClick` and `disabled` props.
59
+ * - `href` renders a `LinkClickable`; `onClick` or `disabled` renders a `ButtonClickable`; neither renders a `SpanClickable`.
60
+ * - `disabled` with no `onClick` is a disabled `<button>`, e.g. a "Locked" button that can never be pressed.
60
61
  * - Dispatches on defined values (not key presence) so wrappers can always spread `href={href}` through, even when it's `undefined`.
61
62
  *
62
63
  * @kind component
@@ -67,7 +68,7 @@ export interface StylableClickableProps extends ClickableProps, ClassProps {}
67
68
  export function Clickable(props: StylableClickableProps): ReactElement {
68
69
  return props.href !== undefined ? (
69
70
  <LinkClickable {...props} />
70
- ) : props.onClick !== undefined ? (
71
+ ) : props.onClick !== undefined || props.disabled ? (
71
72
  <ButtonClickable {...props} />
72
73
  ) : (
73
74
  <SpanClickable {...props} />
@@ -161,7 +162,7 @@ export function ButtonClickable({
161
162
  }
162
163
 
163
164
  /**
164
- * Render a non-interactive `<span>` element, used as the fallback when neither `href` nor `onClick` is provided.
165
+ * Render a non-interactive `<span>` element, used as the fallback when none of `href`, `onClick` or `disabled` is provided, e.g. a plain tag.
165
166
  *
166
167
  * @example <SpanClickable className="label">Static</SpanClickable>
167
168
  * @see https://shelving.cc/ui/SpanClickable
@@ -12,7 +12,7 @@ export interface LinkProps extends ClickableProps, TypographyVariants, ClassProp
12
12
  plain?: boolean | undefined;
13
13
  }
14
14
  /**
15
- * Inline link — delegates to `<Clickable>`, rendering an `<a>` (when `href` is set) or `<button>` (when `onClick` is set).
15
+ * Inline link — delegates to `<Clickable>`, rendering an `<a>` (when `href` is set), a `<button>` (when `onClick` or `disabled` is set), or a `<span>`.
16
16
  *
17
17
  * @kind component
18
18
  * @see https://shelving.cc/ui/Link
package/ui/inline/Link.js CHANGED
@@ -4,7 +4,7 @@ import { getTypographyClass } from "../style/Typography.js";
4
4
  import { getClass, getModuleClass } from "../util/css.js";
5
5
  import LINK_CSS from "./Link.module.css";
6
6
  /**
7
- * Inline link — delegates to `<Clickable>`, rendering an `<a>` (when `href` is set) or `<button>` (when `onClick` is set).
7
+ * Inline link — delegates to `<Clickable>`, rendering an `<a>` (when `href` is set), a `<button>` (when `onClick` or `disabled` is set), or a `<span>`.
8
8
  *
9
9
  * @kind component
10
10
  * @see https://shelving.cc/ui/Link
@@ -16,7 +16,7 @@ export interface LinkProps extends ClickableProps, TypographyVariants, ClassProp
16
16
  }
17
17
 
18
18
  /**
19
- * Inline link — delegates to `<Clickable>`, rendering an `<a>` (when `href` is set) or `<button>` (when `onClick` is set).
19
+ * Inline link — delegates to `<Clickable>`, rendering an `<a>` (when `href` is set), a `<button>` (when `onClick` or `disabled` is set), or a `<span>`.
20
20
  *
21
21
  * @kind component
22
22
  * @see https://shelving.cc/ui/Link
@@ -1,6 +1,6 @@
1
1
  import { describe, expect, test } from "bun:test";
2
2
  import type { ReactElement } from "react";
3
- import { DateInput, FileInput, ImageInput, NumberInput, TextareaInput, TextInput } from "shelving/ui";
3
+ import { DateInput, FileInput, ImageInput, NumberInput, SelectInput, TextareaInput, TextInput } from "shelving/ui";
4
4
  import { PASSTHROUGH } from "shelving/util/function";
5
5
 
6
6
  /** The props of the rendered element that the tests read. */
@@ -68,3 +68,35 @@ describe("ImageInput", () => {
68
68
  expect(values).toEqual([file, undefined]);
69
69
  });
70
70
  });
71
+
72
+ describe("SelectInput", () => {
73
+ /** The `[type, key or label]` of each child of a rendered select, with an optgroup's options after it. */
74
+ function _getChildren(element: ReactElement): string[] {
75
+ const out: string[] = [];
76
+ const children = (element.props as { children: unknown[] }).children.flat();
77
+ for (const c of children) {
78
+ if (!c || typeof c !== "object") continue;
79
+ const el = c as ReactElement<{ value?: string; label?: string; children?: unknown }>;
80
+ if (el.type === "optgroup") {
81
+ out.push(`group:${el.props.label}`);
82
+ for (const o of [el.props.children].flat()) if (o) out.push(`option:${(o as ReactElement<{ value: string }>).props.value}`);
83
+ } else out.push(`option:${el.props.value}`);
84
+ }
85
+ return out;
86
+ }
87
+ test("shows options in no group first, then each group as an optgroup", () => {
88
+ const element = SelectInput<string>({
89
+ name: "x",
90
+ required: true,
91
+ value: "a",
92
+ options: { a: "A", b: "B", c: "C", d: "D" },
93
+ groups: { Second: ["d", "b"], Missing: ["z"] },
94
+ onValue: PASSTHROUGH,
95
+ });
96
+ expect(_getChildren(element)).toEqual(["option:a", "option:c", "group:Second", "option:d", "option:b", "group:Missing"]);
97
+ });
98
+ test("shows a flat list with no groups", () => {
99
+ const element = SelectInput<string>({ name: "x", required: true, value: "a", options: { a: "A", b: "B" }, onValue: PASSTHROUGH });
100
+ expect(_getChildren(element)).toEqual(["option:a", "option:b"]);
101
+ });
102
+ });
@@ -1,5 +1,5 @@
1
1
  import type { ReactElement } from "react";
2
- import type { ChoiceOptions } from "../../schema/ChoiceSchema.js";
2
+ import type { ChoiceGroups, ChoiceOptions } from "../../schema/ChoiceSchema.js";
3
3
  import { type InputVariants, type ValueInputProps } from "./Input.js";
4
4
  /**
5
5
  * Props for `SelectInput`, a dropdown `<select>` bound to a string value.
@@ -9,10 +9,13 @@ import { type InputVariants, type ValueInputProps } from "./Input.js";
9
9
  export interface SelectProps<T extends string> extends ValueInputProps<T>, InputVariants {
10
10
  /** The options for the select. */
11
11
  options: ChoiceOptions<T>;
12
+ /** Show the options under named headings, as `<optgroup>` elements. Options in no group show first. */
13
+ groups?: ChoiceGroups<T> | undefined;
12
14
  }
13
15
  /**
14
16
  * Dropdown input bound to a string value, rendered as a `<select>` of the provided `options`.
15
17
  * - Shows a placeholder empty option unless the field is required and already has a value.
18
+ * - With `groups`, shows each group as an `<optgroup>`, after the options that are in no group. A group key that is not in `options` is skipped.
16
19
  *
17
20
  * @returns A `<select>` element.
18
21
  * @kind component
@@ -3,6 +3,17 @@ import { getProps } from "../../util/object.js";
3
3
  import { getClass, getModuleClass } from "../util/css.js";
4
4
  import { getInputClass } from "./Input.js";
5
5
  import INPUT_CSS from "./Input.module.css";
6
- export function SelectInput({ name, placeholder = "Choose...", required = false, disabled = false, message = "", value = "", onValue, options, className, ...variants }) {
7
- return (_jsxs("select", { name: name, defaultValue: value, onChange: e => onValue(e.currentTarget.value || undefined), className: getClass(getInputClass(variants), getModuleClass(INPUT_CSS, "select"), className), title: message, "aria-invalid": !!message, disabled: disabled, required: required, children: [!required || !value ? (_jsx("option", { value: "", className: getModuleClass(INPUT_CSS, "empty"), children: placeholder })) : null, getProps(options).map(([k, t]) => (_jsx("option", { value: k, className: getModuleClass(INPUT_CSS, "value"), children: t }, k)))] }));
6
+ const OPTION_CLASS = getModuleClass(INPUT_CSS, "value");
7
+ export function SelectInput({ name, placeholder = "Choose...", required = false, disabled = false, message = "", value = "", onValue, options, groups, className, ...variants }) {
8
+ const grouped = groups ? new Set(Object.values(groups).flat()) : undefined;
9
+ return (_jsxs("select", { name: name, defaultValue: value, onChange: e => onValue(e.currentTarget.value || undefined), className: getClass(getInputClass(variants), getModuleClass(INPUT_CSS, "select"), className), title: message, "aria-invalid": !!message, disabled: disabled, required: required, children: [!required || !value ? (_jsx("option", { value: "", className: getModuleClass(INPUT_CSS, "empty"), children: placeholder })) : null, getProps(options).map(([k, t]) => (grouped?.has(k) ? null : _renderOption(k, t))), groups
10
+ ? Object.entries(groups).map(([g, keys]) => (_jsx("optgroup", { label: g, children: keys.map(k => _renderGroupOption(options, k)) }, g)))
11
+ : null] }));
12
+ }
13
+ function _renderOption(key, title) {
14
+ return (_jsx("option", { value: key, className: OPTION_CLASS, children: title }, key));
15
+ }
16
+ function _renderGroupOption(options, key) {
17
+ const title = options[key];
18
+ return title === undefined ? null : _renderOption(key, title);
8
19
  }
@@ -1,5 +1,5 @@
1
1
  import type { ReactElement } from "react";
2
- import type { ChoiceOptions } from "../../schema/ChoiceSchema.js";
2
+ import type { ChoiceGroups, ChoiceOptions } from "../../schema/ChoiceSchema.js";
3
3
  import { getProps } from "../../util/object.js";
4
4
  import { getClass, getModuleClass } from "../util/css.js";
5
5
  import { getInputClass, type InputVariants, type ValueInputProps } from "./Input.js";
@@ -13,11 +13,16 @@ import INPUT_CSS from "./Input.module.css";
13
13
  export interface SelectProps<T extends string> extends ValueInputProps<T>, InputVariants {
14
14
  /** The options for the select. */
15
15
  options: ChoiceOptions<T>;
16
+ /** Show the options under named headings, as `<optgroup>` elements. Options in no group show first. */
17
+ groups?: ChoiceGroups<T> | undefined;
16
18
  }
17
19
 
20
+ const OPTION_CLASS = getModuleClass(INPUT_CSS, "value");
21
+
18
22
  /**
19
23
  * Dropdown input bound to a string value, rendered as a `<select>` of the provided `options`.
20
24
  * - Shows a placeholder empty option unless the field is required and already has a value.
25
+ * - With `groups`, shows each group as an `<optgroup>`, after the options that are in no group. A group key that is not in `options` is skipped.
21
26
  *
22
27
  * @returns A `<select>` element.
23
28
  * @kind component
@@ -34,9 +39,11 @@ export function SelectInput({
34
39
  value = "",
35
40
  onValue,
36
41
  options,
42
+ groups,
37
43
  className,
38
44
  ...variants
39
45
  }: SelectProps<string>): ReactElement {
46
+ const grouped = groups ? new Set(Object.values(groups).flat()) : undefined;
40
47
  return (
41
48
  <select
42
49
  name={name}
@@ -53,11 +60,27 @@ export function SelectInput({
53
60
  {placeholder}
54
61
  </option>
55
62
  ) : null}
56
- {getProps(options).map(([k, t]) => (
57
- <option key={k} value={k} className={getModuleClass(INPUT_CSS, "value")}>
58
- {t}
59
- </option>
60
- ))}
63
+ {getProps(options).map(([k, t]) => (grouped?.has(k) ? null : _renderOption(k, t)))}
64
+ {groups
65
+ ? Object.entries(groups).map(([g, keys]) => (
66
+ <optgroup key={g} label={g}>
67
+ {keys.map(k => _renderGroupOption(options, k))}
68
+ </optgroup>
69
+ ))
70
+ : null}
61
71
  </select>
62
72
  );
63
73
  }
74
+
75
+ function _renderOption(key: string, title: string): ReactElement {
76
+ return (
77
+ <option key={key} value={key} className={OPTION_CLASS}>
78
+ {title}
79
+ </option>
80
+ );
81
+ }
82
+
83
+ function _renderGroupOption(options: ChoiceOptions<string>, key: string): ReactElement | null {
84
+ const title = options[key];
85
+ return title === undefined ? null : _renderOption(key, title);
86
+ }
package/ui/misc/Tag.d.ts CHANGED
@@ -28,7 +28,7 @@ export interface TagProps extends TagVariants, ClickableProps, ClassProps {
28
28
  }
29
29
  /**
30
30
  * Small inline label used to annotate other content.
31
- * - Delegates to `getClickable()` — renders as `<a>` when `href` is set, otherwise `<button>`.
31
+ * - Delegates to `<Clickable>` — renders as `<a>` when `href` is set, `<button>` when `onClick` or `disabled` is set, otherwise `<span>`.
32
32
  * - Accepts a status variant (`success`, `info`, `error`, etc.) _or_ a raw colour (`color="red"`, `color="purple"`, etc.).
33
33
  *
34
34
  * @kind component
package/ui/misc/Tag.js CHANGED
@@ -19,7 +19,7 @@ export function getTagClass(variants) {
19
19
  }
20
20
  /**
21
21
  * Small inline label used to annotate other content.
22
- * - Delegates to `getClickable()` — renders as `<a>` when `href` is set, otherwise `<button>`.
22
+ * - Delegates to `<Clickable>` — renders as `<a>` when `href` is set, `<button>` when `onClick` or `disabled` is set, otherwise `<span>`.
23
23
  * - Accepts a status variant (`success`, `info`, `error`, etc.) _or_ a raw colour (`color="red"`, `color="purple"`, etc.).
24
24
  *
25
25
  * @kind component
package/ui/misc/Tag.tsx CHANGED
@@ -40,7 +40,7 @@ export interface TagProps extends TagVariants, ClickableProps, ClassProps {}
40
40
 
41
41
  /**
42
42
  * Small inline label used to annotate other content.
43
- * - Delegates to `getClickable()` — renders as `<a>` when `href` is set, otherwise `<button>`.
43
+ * - Delegates to `<Clickable>` — renders as `<a>` when `href` is set, `<button>` when `onClick` or `disabled` is set, otherwise `<span>`.
44
44
  * - Accepts a status variant (`success`, `info`, `error`, etc.) _or_ a raw colour (`color="red"`, `color="purple"`, etc.).
45
45
  *
46
46
  * @kind component
@@ -48,6 +48,11 @@ describe("ClassProps", () => {
48
48
  expect(html).not.toContain("<a ");
49
49
  });
50
50
 
51
+ test("clickable wrapper renders a disabled `<button>` when only `disabled` is set, and a `<span>` with nothing", () => {
52
+ expect(render(<Button disabled>Locked</Button>)).toContain('<button type="button" disabled=""');
53
+ expect(render(<Tag>New</Tag>)).toStartWith("<span");
54
+ });
55
+
51
56
  test("`className` lands on the component's own root, not on its inner elements", () => {
52
57
  // `Card` renders the class on its `<article>`, not on the stretched overlay `<a>` it also renders.
53
58
  const html = render(