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.
- package/docs/llms-full.txt +68 -9
- package/docs/schema/ChoiceGroups.md +21 -0
- package/docs/schema/ChoiceSchema.md +26 -1
- package/docs/schema/ChoiceSchemaOptions.md +3 -0
- package/docs/schema.md +1 -0
- package/docs/ui/Clickable.md +3 -2
- package/docs/ui/Link.md +1 -1
- package/docs/ui/SelectInput.md +2 -0
- package/docs/ui/SelectProps.md +2 -0
- package/docs/ui/SpanClickable.md +1 -1
- package/docs/ui/Tag.md +1 -1
- package/docs/ui.md +3 -3
- package/package.json +1 -1
- package/schema/ChoiceSchema.d.ts +16 -1
- package/schema/ChoiceSchema.js +3 -1
- package/ui/button/Clickable.d.ts +4 -3
- package/ui/button/Clickable.js +5 -4
- package/ui/button/Clickable.tsx +5 -4
- package/ui/inline/Link.d.ts +1 -1
- package/ui/inline/Link.js +1 -1
- package/ui/inline/Link.tsx +1 -1
- package/ui/input/Input.test.tsx +33 -1
- package/ui/input/SelectInput.d.ts +4 -1
- package/ui/input/SelectInput.js +13 -2
- package/ui/input/SelectInput.tsx +29 -6
- package/ui/misc/Tag.d.ts +1 -1
- package/ui/misc/Tag.js +1 -1
- package/ui/misc/Tag.tsx +1 -1
- package/ui/util/props.test.tsx +5 -0
package/docs/llms-full.txt
CHANGED
|
@@ -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>({
|
|
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
|
|
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)
|
|
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
|
|
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
|
|
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
|
|
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)
|
|
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
|
|
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>({
|
|
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.
|
package/docs/ui/Clickable.md
CHANGED
|
@@ -3,8 +3,9 @@
|
|
|
3
3
|
- Kind: component
|
|
4
4
|
- Import: `import { Clickable } from "shelving/ui";`
|
|
5
5
|
|
|
6
|
-
Render
|
|
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)
|
|
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
|
|
package/docs/ui/SelectInput.md
CHANGED
|
@@ -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
|
|
package/docs/ui/SelectProps.md
CHANGED
|
@@ -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. |
|
package/docs/ui/SpanClickable.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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)
|
|
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
|
|
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
package/schema/ChoiceSchema.d.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
*
|
package/schema/ChoiceSchema.js
CHANGED
|
@@ -21,9 +21,11 @@ const MAX_RADIO_OPTIONS = 8;
|
|
|
21
21
|
export class ChoiceSchema extends Schema {
|
|
22
22
|
options;
|
|
23
23
|
input;
|
|
24
|
-
|
|
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
|
/**
|
package/ui/button/Clickable.d.ts
CHANGED
|
@@ -43,8 +43,9 @@ export interface ClickableProps extends OptionalChildProps {
|
|
|
43
43
|
export interface StylableClickableProps extends ClickableProps, ClassProps {
|
|
44
44
|
}
|
|
45
45
|
/**
|
|
46
|
-
* Render
|
|
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
|
|
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
|
package/ui/button/Clickable.js
CHANGED
|
@@ -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
|
|
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
|
|
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
|
package/ui/button/Clickable.tsx
CHANGED
|
@@ -55,8 +55,9 @@ export interface ClickableProps extends OptionalChildProps {
|
|
|
55
55
|
export interface StylableClickableProps extends ClickableProps, ClassProps {}
|
|
56
56
|
|
|
57
57
|
/**
|
|
58
|
-
* Render
|
|
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
|
|
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
|
package/ui/inline/Link.d.ts
CHANGED
|
@@ -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)
|
|
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)
|
|
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
|
package/ui/inline/Link.tsx
CHANGED
|
@@ -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)
|
|
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
|
package/ui/input/Input.test.tsx
CHANGED
|
@@ -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
|
package/ui/input/SelectInput.js
CHANGED
|
@@ -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
|
-
|
|
7
|
-
|
|
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
|
}
|
package/ui/input/SelectInput.tsx
CHANGED
|
@@ -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
|
-
|
|
58
|
-
|
|
59
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
package/ui/util/props.test.tsx
CHANGED
|
@@ -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(
|