shelving 1.312.2 → 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
 
@@ -28914,6 +28968,7 @@ Props for `SelectInput`, a dropdown `<select>` bound to a string value.
28914
28968
  ```ts
28915
28969
  {
28916
28970
  options: ChoiceOptions<T>;
28971
+ groups?: ChoiceGroups<T> | undefined;
28917
28972
  }
28918
28973
  ```
28919
28974
 
@@ -28922,6 +28977,7 @@ Props for `SelectInput`, a dropdown `<select>` bound to a string value.
28922
28977
  | Property | Type | Description |
28923
28978
  | --- | --- | --- |
28924
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. |
28925
28981
 
28926
28982
 
28927
28983
  ---
@@ -28933,6 +28989,7 @@ Props for `SelectInput`, a dropdown `<select>` bound to a string value.
28933
28989
 
28934
28990
  Dropdown input bound to a string value, rendered as a `<select>` of the provided `options`.
28935
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.
28936
28993
 
28937
28994
  ## Signatures
28938
28995
 
@@ -28946,6 +29003,7 @@ SelectInput(props: SelectProps<T>): ReactElement
28946
29003
  | --- | --- | --- |
28947
29004
  | `props` | `SelectProps<T>` | |
28948
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. |
28949
29007
 
28950
29008
  ## Returns
28951
29009
 
@@ -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.
@@ -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. |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shelving",
3
- "version": "1.312.2",
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
  /**
@@ -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
+ }