shelving 1.298.0 → 1.300.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shelving",
3
- "version": "1.298.0",
3
+ "version": "1.300.0",
4
4
  "author": "Dave Houlbrooke <dave@shax.com>",
5
5
  "repository": {
6
6
  "type": "git",
@@ -0,0 +1,26 @@
1
+ import type { ReactElement, ReactNode } from "react";
2
+ import type { ImmutableArray } from "../../util/array.js";
3
+ import type { ValueInputProps } from "./Input.js";
4
+ /**
5
+ * Props for `ArrayCheckboxInputs`, which renders a checkbox for each item in an array of values.
6
+ *
7
+ * @see https://shelving.cc/ui/ArrayCheckboxInputsProps
8
+ */
9
+ export interface ArrayCheckboxInputsProps<T> extends ValueInputProps<ImmutableArray<T>> {
10
+ /** Array of values to show in the list of checkboxes. */
11
+ items: ImmutableArray<T>;
12
+ /** Function that formats an obscure item into a `ReactNode` for display. */
13
+ formatter?: ((value: T) => ReactNode) | undefined;
14
+ }
15
+ /**
16
+ * Output a list of `<CheckboxInput>` elements for each item in an array, to pick any number of them.
17
+ * - The value is the array of checked items, in the order they were checked. Items are compared with `===`.
18
+ * - Checked items that are not in `items` stay in the value.
19
+ * - The items can be any type, and can be formatted for output through an optional `formatter()` function.
20
+ *
21
+ * @kind component
22
+ * @returns Element rendering one checkbox per item.
23
+ * @example <ArrayCheckboxInputs name="sizes" items={["s", "m", "l"]} value={sizes} onValue={setSizes} />
24
+ * @see https://shelving.cc/ui/ArrayCheckboxInputs
25
+ */
26
+ export declare function ArrayCheckboxInputs<T>({ value, onValue, required, items, formatter, className, ...props }: ArrayCheckboxInputsProps<T>): ReactElement;
@@ -0,0 +1,23 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ import { formatValue } from "../../util/format.js";
3
+ import { Column } from "../block/Column.js";
4
+ import { CheckboxInput } from "./CheckboxInput.js";
5
+ /**
6
+ * Output a list of `<CheckboxInput>` elements for each item in an array, to pick any number of them.
7
+ * - The value is the array of checked items, in the order they were checked. Items are compared with `===`.
8
+ * - Checked items that are not in `items` stay in the value.
9
+ * - The items can be any type, and can be formatted for output through an optional `formatter()` function.
10
+ *
11
+ * @kind component
12
+ * @returns Element rendering one checkbox per item.
13
+ * @example <ArrayCheckboxInputs name="sizes" items={["s", "m", "l"]} value={sizes} onValue={setSizes} />
14
+ * @see https://shelving.cc/ui/ArrayCheckboxInputs
15
+ */
16
+ export function ArrayCheckboxInputs({ value = [], onValue, required = false, items, formatter = formatValue, className, ...props }) {
17
+ return (_jsx(Column, { className: className, children: items.map((v, i) => {
18
+ const checked = value.includes(v);
19
+ return (_jsx(CheckboxInput //
20
+ // The checkbox is uncontrolled, so the key includes `checked` to remount it when the value changes.
21
+ , { value: checked, onValue: on => onValue(on ? [...value, v] : value.filter(x => x !== v)), required: required && !value.length, ...props, children: formatter(v) }, `${i.toString()}:${checked ? "on" : "off"}`));
22
+ }) }));
23
+ }
@@ -0,0 +1,59 @@
1
+ import type { ReactElement, ReactNode } from "react";
2
+ import type { ImmutableArray } from "../../util/array.js";
3
+ import { formatValue } from "../../util/format.js";
4
+ import { Column } from "../block/Column.js";
5
+ import { CheckboxInput } from "./CheckboxInput.js";
6
+ import type { ValueInputProps } from "./Input.js";
7
+
8
+ /**
9
+ * Props for `ArrayCheckboxInputs`, which renders a checkbox for each item in an array of values.
10
+ *
11
+ * @see https://shelving.cc/ui/ArrayCheckboxInputsProps
12
+ */
13
+ export interface ArrayCheckboxInputsProps<T> extends ValueInputProps<ImmutableArray<T>> {
14
+ /** Array of values to show in the list of checkboxes. */
15
+ items: ImmutableArray<T>;
16
+ /** Function that formats an obscure item into a `ReactNode` for display. */
17
+ formatter?: ((value: T) => ReactNode) | undefined;
18
+ }
19
+
20
+ /**
21
+ * Output a list of `<CheckboxInput>` elements for each item in an array, to pick any number of them.
22
+ * - The value is the array of checked items, in the order they were checked. Items are compared with `===`.
23
+ * - Checked items that are not in `items` stay in the value.
24
+ * - The items can be any type, and can be formatted for output through an optional `formatter()` function.
25
+ *
26
+ * @kind component
27
+ * @returns Element rendering one checkbox per item.
28
+ * @example <ArrayCheckboxInputs name="sizes" items={["s", "m", "l"]} value={sizes} onValue={setSizes} />
29
+ * @see https://shelving.cc/ui/ArrayCheckboxInputs
30
+ */
31
+ export function ArrayCheckboxInputs<T>({
32
+ value = [],
33
+ onValue,
34
+ required = false,
35
+ items,
36
+ formatter = formatValue,
37
+ className,
38
+ ...props
39
+ }: ArrayCheckboxInputsProps<T>): ReactElement {
40
+ return (
41
+ <Column className={className}>
42
+ {items.map((v, i) => {
43
+ const checked = value.includes(v);
44
+ return (
45
+ <CheckboxInput //
46
+ // The checkbox is uncontrolled, so the key includes `checked` to remount it when the value changes.
47
+ key={`${i.toString()}:${checked ? "on" : "off"}`}
48
+ value={checked}
49
+ onValue={on => onValue(on ? [...value, v] : value.filter(x => x !== v))}
50
+ required={required && !value.length}
51
+ {...props}
52
+ >
53
+ {formatter(v)}
54
+ </CheckboxInput>
55
+ );
56
+ })}
57
+ </Column>
58
+ );
59
+ }
@@ -0,0 +1,24 @@
1
+ import type { ReactElement } from "react";
2
+ import type { ImmutableArray } from "../../util/array.js";
3
+ import type { ValueInputProps } from "./Input.js";
4
+ import { type QueryInputBaseProps } from "./QueryInputBase.js";
5
+ /**
6
+ * Props for `QueryCheckboxesInput`, a combo box that queries items of type `O` from an input of type `I`, and picks any number of them.
7
+ *
8
+ * @see https://shelving.cc/ui/QueryCheckboxesInputProps
9
+ */
10
+ export interface QueryCheckboxesInputProps<I, O> extends QueryInputBaseProps<I, O>, ValueInputProps<ImmutableArray<O>> {
11
+ }
12
+ /**
13
+ * Combo box that queries a list of items and lets the user pick any number of them, with checkboxes.
14
+ * - Shows an input based on a `schema` of type `I`; its values are piped to the `onQuery()` callback.
15
+ * - Shows a `<Popover>` with a checkbox list of returned items. The value is the array of checked items. The popover stays open while the user checks items.
16
+ * - With `popover={false}`, shows the checkbox list inline below the input instead.
17
+ * - Checked items stay checked when a new query does not return them. Items are compared with `===`, so `onQuery()` must return the same objects each time (or primitives).
18
+ * - Errors, loading, and empty states are handled automatically.
19
+ *
20
+ * @kind component
21
+ * @returns A combo box element wrapping the input and results popover (or the inline list).
22
+ * @see https://shelving.cc/ui/QueryCheckboxesInput
23
+ */
24
+ export declare function QueryCheckboxesInput<I, O>({ value, onValue, formatter, ...props }: QueryCheckboxesInputProps<I, O>): ReactElement;
@@ -0,0 +1,20 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ import { formatValue } from "../../util/format.js";
3
+ import { ArrayCheckboxInputs } from "./ArrayCheckboxInputs.js";
4
+ import { QueryInputBase } from "./QueryInputBase.js";
5
+ /**
6
+ * Combo box that queries a list of items and lets the user pick any number of them, with checkboxes.
7
+ * - Shows an input based on a `schema` of type `I`; its values are piped to the `onQuery()` callback.
8
+ * - Shows a `<Popover>` with a checkbox list of returned items. The value is the array of checked items. The popover stays open while the user checks items.
9
+ * - With `popover={false}`, shows the checkbox list inline below the input instead.
10
+ * - Checked items stay checked when a new query does not return them. Items are compared with `===`, so `onQuery()` must return the same objects each time (or primitives).
11
+ * - Errors, loading, and empty states are handled automatically.
12
+ *
13
+ * @kind component
14
+ * @returns A combo box element wrapping the input and results popover (or the inline list).
15
+ * @see https://shelving.cc/ui/QueryCheckboxesInput
16
+ */
17
+ export function QueryCheckboxesInput({ value, onValue, formatter = formatValue, ...props }) {
18
+ const { name, required, disabled } = props;
19
+ return (_jsx(QueryInputBase, { ...props, list: items => (_jsx(ArrayCheckboxInputs, { name: name, required: required, disabled: disabled, items: items, value: value, formatter: formatter, onValue: onValue })) }));
20
+ }
@@ -0,0 +1,38 @@
1
+ # QueryCheckboxesInput
2
+
3
+ Combo box that queries a list of items and lets the user pick any number of them. The text in the input goes to `onQuery()`, and the items it returns show as a checkbox list. The value is the array of checked items.
4
+
5
+ **Things to know:**
6
+
7
+ - It works like `<QueryRadiosInput>`: the same `schema`, `onQuery()`, `formatter`, `popover` and `empty` props, and the same loading, empty and error states.
8
+ - The popover stays open while the user checks items.
9
+ - Checked items stay in the value when a new search does not return them. Items are compared with `===`, so `onQuery()` must return the same objects each time (or primitives).
10
+ - Show your own button to act on the checked items, for example "Invite".
11
+
12
+ ## Usage
13
+
14
+ ### Inline list with a button
15
+
16
+ ```tsx
17
+ import { Button, QueryCheckboxesInput } from "shelving/ui";
18
+ import { StringSchema } from "shelving/schema";
19
+
20
+ const SEARCH = new StringSchema({ title: "Search", one: "user" });
21
+
22
+ const [users, setUsers] = useState<readonly User[]>([]);
23
+
24
+ <QueryCheckboxesInput
25
+ popover={false}
26
+ name="users"
27
+ schema={SEARCH}
28
+ onQuery={search}
29
+ formatter={user => <Avatar user={user} />}
30
+ value={users}
31
+ onValue={v => setUsers(v ?? [])}
32
+ />
33
+ <Button onClick={() => invite(users)}>Invite</Button>
34
+ ```
35
+
36
+ ## Styling
37
+
38
+ `<QueryCheckboxesInput>` has no own hooks. The popover version uses the `<Popover>` styles. The inline version is a `<Column>` with the input and the `<ArrayCheckboxInputs>` list, so it uses their styles.
@@ -0,0 +1,42 @@
1
+ import { describe, expect, test } from "bun:test";
2
+ import { renderToStaticMarkup } from "react-dom/server";
3
+ import { STRING } from "shelving/schema";
4
+ import { ArrayCheckboxInputs, QueryCheckboxesInput } from "shelving/ui";
5
+ import { PASSTHROUGH } from "shelving/util/function";
6
+
7
+ describe("QueryCheckboxesInput", () => {
8
+ test("shows the input with no popover when `popover={false}`", () => {
9
+ const html = renderToStaticMarkup(
10
+ <QueryCheckboxesInput popover={false} name="q" schema={STRING} onQuery={() => []} onValue={PASSTHROUGH} />,
11
+ );
12
+ expect(html).toContain('name="q"');
13
+ });
14
+ test("value is an array of items", () => {
15
+ const element = (
16
+ <QueryCheckboxesInput<string, string>
17
+ name="q"
18
+ schema={STRING}
19
+ onQuery={() => []}
20
+ value={["a"]}
21
+ onValue={(v: readonly string[] | undefined) => v}
22
+ />
23
+ );
24
+ expect(element).toBeTruthy();
25
+ });
26
+ });
27
+
28
+ describe("ArrayCheckboxInputs", () => {
29
+ test("renders a checked checkbox for each item in the value", () => {
30
+ const html = renderToStaticMarkup(<ArrayCheckboxInputs name="x" items={["a", "b", "c"]} value={["b"]} onValue={PASSTHROUGH} />);
31
+ expect(html.match(/type="checkbox"/g)?.length).toBe(3);
32
+ expect(html.match(/checked=""/g)?.length).toBe(1);
33
+ });
34
+ test("adds and removes items", () => {
35
+ const values: (readonly string[] | undefined)[] = [];
36
+ const element = ArrayCheckboxInputs({ name: "x", items: ["a", "b"], value: ["a"], onValue: v => values.push(v) });
37
+ const [a, b] = (element.props as { children: { props: { onValue(on: boolean): void } }[] }).children;
38
+ b?.props.onValue(true);
39
+ a?.props.onValue(false);
40
+ expect(values).toEqual([["a", "b"], []]);
41
+ });
42
+ });
@@ -0,0 +1,50 @@
1
+ import type { ReactElement } from "react";
2
+ import type { ImmutableArray } from "../../util/array.js";
3
+ import { formatValue } from "../../util/format.js";
4
+ import { ArrayCheckboxInputs } from "./ArrayCheckboxInputs.js";
5
+ import type { ValueInputProps } from "./Input.js";
6
+ import { QueryInputBase, type QueryInputBaseProps } from "./QueryInputBase.js";
7
+
8
+ /**
9
+ * Props for `QueryCheckboxesInput`, a combo box that queries items of type `O` from an input of type `I`, and picks any number of them.
10
+ *
11
+ * @see https://shelving.cc/ui/QueryCheckboxesInputProps
12
+ */
13
+ export interface QueryCheckboxesInputProps<I, O> extends QueryInputBaseProps<I, O>, ValueInputProps<ImmutableArray<O>> {}
14
+
15
+ /**
16
+ * Combo box that queries a list of items and lets the user pick any number of them, with checkboxes.
17
+ * - Shows an input based on a `schema` of type `I`; its values are piped to the `onQuery()` callback.
18
+ * - Shows a `<Popover>` with a checkbox list of returned items. The value is the array of checked items. The popover stays open while the user checks items.
19
+ * - With `popover={false}`, shows the checkbox list inline below the input instead.
20
+ * - Checked items stay checked when a new query does not return them. Items are compared with `===`, so `onQuery()` must return the same objects each time (or primitives).
21
+ * - Errors, loading, and empty states are handled automatically.
22
+ *
23
+ * @kind component
24
+ * @returns A combo box element wrapping the input and results popover (or the inline list).
25
+ * @see https://shelving.cc/ui/QueryCheckboxesInput
26
+ */
27
+ export function QueryCheckboxesInput<I, O>({
28
+ value,
29
+ onValue,
30
+ formatter = formatValue,
31
+ ...props
32
+ }: QueryCheckboxesInputProps<I, O>): ReactElement {
33
+ const { name, required, disabled } = props;
34
+ return (
35
+ <QueryInputBase<I, O>
36
+ {...props}
37
+ list={items => (
38
+ <ArrayCheckboxInputs
39
+ name={name}
40
+ required={required}
41
+ disabled={disabled}
42
+ items={items}
43
+ value={value}
44
+ formatter={formatter}
45
+ onValue={onValue}
46
+ />
47
+ )}
48
+ />
49
+ );
50
+ }
@@ -0,0 +1,48 @@
1
+ import { type ReactElement, type ReactNode } from "react";
2
+ import type { Schema } from "../../schema/Schema.js";
3
+ import { type PayloadFetchCallback } from "../../store/PayloadFetchStore.js";
4
+ import type { ImmutableArray } from "../../util/array.js";
5
+ import type { InputProps } from "./Input.js";
6
+ /**
7
+ * Props shared by `QueryRadiosInput` and `QueryCheckboxesInput`.
8
+ *
9
+ * @see https://shelving.cc/ui/QueryInputBaseProps
10
+ */
11
+ export interface QueryInputBaseProps<I, O> extends InputProps {
12
+ /** Schema for the text input. Its `one` and `many` name the items, e.g. `one: "user"` shows "No users". */
13
+ schema: Schema<I>;
14
+ /**
15
+ * Called with the current text value to return matching items whenever the text input changes.
16
+ * - Automatically debounced, so only called after a short delay.
17
+ * - Automatically shows a loading state while loading.
18
+ * - Returning `undefined` signals to close the popover (or, with `popover={false}`, to show no list).
19
+ */
20
+ onQuery: PayloadFetchCallback<I, ImmutableArray<O> | undefined>;
21
+ /** Format an item of type `O` for display in the list, for example as text or as an avatar. */
22
+ formatter?: ((value: O) => ReactNode) | undefined;
23
+ /**
24
+ * Show the results in a popover (the default), or set `false` to show them inline, as a list below the input.
25
+ * - Inline, the list shows at once: `onQuery()` is called with the schema's default value (e.g. `""`) on mount.
26
+ * - Inline, an empty input still queries.
27
+ */
28
+ popover?: boolean | undefined;
29
+ /**
30
+ * Message that shows in an `<Empty>` when the query returns `[]` (set to `""` to show no message).
31
+ * @default `No ${schema.many}`, e.g. "No users"
32
+ */
33
+ empty?: ReactNode | undefined;
34
+ }
35
+ /** Props for the internal `QueryInputBase`: the shared props, plus a function that renders the list of items. */
36
+ interface QueryInputBaseFrameProps<I, O> extends QueryInputBaseProps<I, O> {
37
+ /** Render the list for the items the query returned. `close()` closes the popover. */
38
+ list: (items: ImmutableArray<O>, close: () => void) => ReactNode;
39
+ }
40
+ /**
41
+ * Text input that queries a list of items, then shows the list in a popover or inline.
42
+ * - Shared by `QueryRadiosInput` and `QueryCheckboxesInput`, which each render their own list.
43
+ * - The text input is never required: the picked items are the value, not the text.
44
+ * - The store is kept when the parent renders again with a new `onQuery()`, so the list does not load again.
45
+ * - Errors show in an `<ErrorNotice>`. Loading and empty states show in an `<Empty>`.
46
+ */
47
+ export declare function QueryInputBase<I, O>({ schema, onQuery, popover, empty, list, className, ...props }: QueryInputBaseFrameProps<I, O>): ReactElement;
48
+ export {};
@@ -0,0 +1,48 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { useEffect, useRef } from "react";
3
+ import { useInstance } from "../../react/useInstance.js";
4
+ import { useStore } from "../../react/useStore.js";
5
+ import { PayloadFetchStore } from "../../store/PayloadFetchStore.js";
6
+ import { NONE, SECOND } from "../../util/constants.js";
7
+ import { Column } from "../block/Column.js";
8
+ import { Paragraph } from "../block/Paragraph.js";
9
+ import { ErrorNotice } from "../misc/Catcher.js";
10
+ import { EMPTY_LOADING, Empty } from "../notice/Empty.js";
11
+ import { Popover } from "./Popover.js";
12
+ import { SchemaInput } from "./SchemaInput.js";
13
+ /**
14
+ * Text input that queries a list of items, then shows the list in a popover or inline.
15
+ * - Shared by `QueryRadiosInput` and `QueryCheckboxesInput`, which each render their own list.
16
+ * - The text input is never required: the picked items are the value, not the text.
17
+ * - The store is kept when the parent renders again with a new `onQuery()`, so the list does not load again.
18
+ * - Errors show in an `<ErrorNotice>`. Loading and empty states show in an `<Empty>`.
19
+ */
20
+ export function QueryInputBase({ schema, onQuery, popover = true, empty = `No ${schema.many}`, list, className, ...props }) {
21
+ // Keep one store while the component lives. `onQuery()` is often a new function on each render, so the store calls the latest one through a ref.
22
+ const latest = useRef(onQuery);
23
+ latest.current = onQuery;
24
+ const query = (useRef(undefined).current ??= (payload, signal) => latest.current(payload, signal));
25
+ const store = useStore(useInstance(PayloadFetchStore, NONE, undefined, query, SECOND));
26
+ const busy = useStore(store.busy).value;
27
+ // Inline, query the schema's default value at once, so the list shows before anything is typed.
28
+ useEffect(() => {
29
+ if (!popover)
30
+ store.payload.value = schema.value;
31
+ }, [popover, store, schema]);
32
+ // Is popover open?
33
+ const isOpen = busy || !!store.reason || !!store.value;
34
+ // Close the popover and clear the results.
35
+ const close = () => {
36
+ store.payload.value = NONE;
37
+ store.value = undefined;
38
+ };
39
+ const results = busy ? (EMPTY_LOADING) : store.reason ? (_jsx(ErrorNotice, { reason: store.reason })) : store.value?.length ? (list(store.value, close)) : empty && store.value ? (_jsx(Empty, { children: typeof empty === "string" ? _jsx(Paragraph, { children: empty }) : empty })) : null;
40
+ if (!popover)
41
+ return (_jsxs(Column, { children: [_jsx(SchemaInput, { ...props, required: false, schema: schema, className: className, onValue: v => void (store.payload.value = v) }), results] }));
42
+ return (_jsxs(Popover, { open: isOpen, onClose: close, children: [_jsx(SchemaInput, { ...props, required: false, schema: schema, className: className, onValue: v => {
43
+ if (v)
44
+ store.payload.value = v;
45
+ else
46
+ close();
47
+ } }), results] }));
48
+ }
@@ -0,0 +1,126 @@
1
+ import { type ReactElement, type ReactNode, useEffect, useRef } from "react";
2
+ import { useInstance } from "../../react/useInstance.js";
3
+ import { useStore } from "../../react/useStore.js";
4
+ import type { Schema } from "../../schema/Schema.js";
5
+ import { type PayloadFetchCallback, PayloadFetchStore } from "../../store/PayloadFetchStore.js";
6
+ import type { ImmutableArray } from "../../util/array.js";
7
+ import { NONE, SECOND } from "../../util/constants.js";
8
+ import { Column } from "../block/Column.js";
9
+ import { Paragraph } from "../block/Paragraph.js";
10
+ import { ErrorNotice } from "../misc/Catcher.js";
11
+ import { EMPTY_LOADING, Empty } from "../notice/Empty.js";
12
+ import type { InputProps } from "./Input.js";
13
+ import { Popover } from "./Popover.js";
14
+ import { SchemaInput } from "./SchemaInput.js";
15
+
16
+ /**
17
+ * Props shared by `QueryRadiosInput` and `QueryCheckboxesInput`.
18
+ *
19
+ * @see https://shelving.cc/ui/QueryInputBaseProps
20
+ */
21
+ export interface QueryInputBaseProps<I, O> extends InputProps {
22
+ /** Schema for the text input. Its `one` and `many` name the items, e.g. `one: "user"` shows "No users". */
23
+ schema: Schema<I>;
24
+
25
+ /**
26
+ * Called with the current text value to return matching items whenever the text input changes.
27
+ * - Automatically debounced, so only called after a short delay.
28
+ * - Automatically shows a loading state while loading.
29
+ * - Returning `undefined` signals to close the popover (or, with `popover={false}`, to show no list).
30
+ */
31
+ onQuery: PayloadFetchCallback<I, ImmutableArray<O> | undefined>;
32
+
33
+ /** Format an item of type `O` for display in the list, for example as text or as an avatar. */
34
+ formatter?: ((value: O) => ReactNode) | undefined;
35
+
36
+ /**
37
+ * Show the results in a popover (the default), or set `false` to show them inline, as a list below the input.
38
+ * - Inline, the list shows at once: `onQuery()` is called with the schema's default value (e.g. `""`) on mount.
39
+ * - Inline, an empty input still queries.
40
+ */
41
+ popover?: boolean | undefined;
42
+
43
+ /**
44
+ * Message that shows in an `<Empty>` when the query returns `[]` (set to `""` to show no message).
45
+ * @default `No ${schema.many}`, e.g. "No users"
46
+ */
47
+ empty?: ReactNode | undefined;
48
+ }
49
+
50
+ /** Props for the internal `QueryInputBase`: the shared props, plus a function that renders the list of items. */
51
+ interface QueryInputBaseFrameProps<I, O> extends QueryInputBaseProps<I, O> {
52
+ /** Render the list for the items the query returned. `close()` closes the popover. */
53
+ list: (items: ImmutableArray<O>, close: () => void) => ReactNode;
54
+ }
55
+
56
+ /**
57
+ * Text input that queries a list of items, then shows the list in a popover or inline.
58
+ * - Shared by `QueryRadiosInput` and `QueryCheckboxesInput`, which each render their own list.
59
+ * - The text input is never required: the picked items are the value, not the text.
60
+ * - The store is kept when the parent renders again with a new `onQuery()`, so the list does not load again.
61
+ * - Errors show in an `<ErrorNotice>`. Loading and empty states show in an `<Empty>`.
62
+ */
63
+ export function QueryInputBase<I, O>({
64
+ schema,
65
+ onQuery,
66
+ popover = true,
67
+ empty = `No ${schema.many}`,
68
+ list,
69
+ className,
70
+ ...props
71
+ }: QueryInputBaseFrameProps<I, O>): ReactElement {
72
+ // Keep one store while the component lives. `onQuery()` is often a new function on each render, so the store calls the latest one through a ref.
73
+ const latest = useRef(onQuery);
74
+ latest.current = onQuery;
75
+ const query = (useRef<typeof onQuery>(undefined).current ??= (payload, signal) => latest.current(payload, signal));
76
+ const store = useStore(useInstance(PayloadFetchStore, NONE, undefined, query, SECOND));
77
+ const busy = useStore(store.busy).value;
78
+
79
+ // Inline, query the schema's default value at once, so the list shows before anything is typed.
80
+ useEffect(() => {
81
+ if (!popover) store.payload.value = schema.value as I;
82
+ }, [popover, store, schema]);
83
+
84
+ // Is popover open?
85
+ const isOpen = busy || !!store.reason || !!store.value;
86
+
87
+ // Close the popover and clear the results.
88
+ const close = () => {
89
+ store.payload.value = NONE;
90
+ store.value = undefined;
91
+ };
92
+
93
+ const results = busy ? (
94
+ EMPTY_LOADING
95
+ ) : store.reason ? (
96
+ <ErrorNotice reason={store.reason} />
97
+ ) : store.value?.length ? (
98
+ list(store.value, close)
99
+ ) : empty && store.value ? (
100
+ <Empty>{typeof empty === "string" ? <Paragraph>{empty}</Paragraph> : empty}</Empty>
101
+ ) : null;
102
+
103
+ if (!popover)
104
+ return (
105
+ <Column>
106
+ <SchemaInput {...props} required={false} schema={schema} className={className} onValue={v => void (store.payload.value = v as I)} />
107
+ {results}
108
+ </Column>
109
+ );
110
+
111
+ return (
112
+ <Popover open={isOpen} onClose={close}>
113
+ <SchemaInput
114
+ {...props}
115
+ required={false}
116
+ schema={schema}
117
+ className={className}
118
+ onValue={v => {
119
+ if (v) store.payload.value = v;
120
+ else close();
121
+ }}
122
+ />
123
+ {results}
124
+ </Popover>
125
+ );
126
+ }
@@ -0,0 +1,22 @@
1
+ import type { ReactElement } from "react";
2
+ import type { ValueInputProps } from "./Input.js";
3
+ import { type QueryInputBaseProps } from "./QueryInputBase.js";
4
+ /**
5
+ * Props for `QueryRadiosInput`, a combo box that queries items of type `O` from an input of type `I`, and picks one.
6
+ *
7
+ * @see https://shelving.cc/ui/QueryRadiosInputProps
8
+ */
9
+ export interface QueryRadiosInputProps<I, O> extends QueryInputBaseProps<I, O>, ValueInputProps<O> {
10
+ }
11
+ /**
12
+ * Combo box that queries a list of items and lets the user pick one, with radios.
13
+ * - Shows an input based on a `schema` of type `I`; its values are piped to the `onQuery()` callback.
14
+ * - Shows a `<Popover>` with a radio list of returned items to pick a final value of type `O`. Picking an item closes the popover.
15
+ * - With `popover={false}`, shows the radio list inline below the input instead, like a `<select>` list box.
16
+ * - Errors, loading, and empty states are handled automatically.
17
+ *
18
+ * @kind component
19
+ * @returns A combo box element wrapping the input and results popover (or the inline list).
20
+ * @see https://shelving.cc/ui/QueryRadiosInput
21
+ */
22
+ export declare function QueryRadiosInput<I, O>({ value, onValue, formatter, popover, ...props }: QueryRadiosInputProps<I, O>): ReactElement;
@@ -0,0 +1,23 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ import { formatValue } from "../../util/format.js";
3
+ import { ArrayRadioInputs } from "./ArrayRadioInputs.js";
4
+ import { QueryInputBase } from "./QueryInputBase.js";
5
+ /**
6
+ * Combo box that queries a list of items and lets the user pick one, with radios.
7
+ * - Shows an input based on a `schema` of type `I`; its values are piped to the `onQuery()` callback.
8
+ * - Shows a `<Popover>` with a radio list of returned items to pick a final value of type `O`. Picking an item closes the popover.
9
+ * - With `popover={false}`, shows the radio list inline below the input instead, like a `<select>` list box.
10
+ * - Errors, loading, and empty states are handled automatically.
11
+ *
12
+ * @kind component
13
+ * @returns A combo box element wrapping the input and results popover (or the inline list).
14
+ * @see https://shelving.cc/ui/QueryRadiosInput
15
+ */
16
+ export function QueryRadiosInput({ value, onValue, formatter = formatValue, popover = true, ...props }) {
17
+ const { name, required, disabled } = props;
18
+ return (_jsx(QueryInputBase, { ...props, popover: popover, list: (items, close) => (_jsx(ArrayRadioInputs, { name: name, required: required, disabled: disabled, items: items, value: value, formatter: formatter, onValue: v => {
19
+ onValue(v);
20
+ if (popover)
21
+ close();
22
+ } })) }));
23
+ }
@@ -0,0 +1,42 @@
1
+ # QueryRadiosInput
2
+
3
+ Combo box that queries a list of items and lets the user pick one. The text in the input goes to `onQuery()`, and the items it returns show as a radio list.
4
+
5
+ **Things to know:**
6
+
7
+ - `onQuery()` is debounced (one second). Loading and empty states show in an `<Empty>`, and errors in an `<ErrorNotice>`.
8
+ - By default the list shows in a `<Popover>`, which closes when the user picks an item.
9
+ - With `popover={false}` the list shows inline, below the input, like a `<select>` list box. It queries the schema's default value on mount, so the list shows before the user types. Picking an item keeps the list.
10
+ - `formatter` can return any `ReactNode`, for example an avatar, not only a string.
11
+ - The empty message is "No" plus the schema's `many`. Set `one: "user"` on the schema to show "No users", or set `empty` (`""` shows no message).
12
+ - To pick more than one item, use `<QueryCheckboxesInput>`.
13
+
14
+ ## Usage
15
+
16
+ ### Popover
17
+
18
+ ```tsx
19
+ import { QueryRadiosInput } from "shelving/ui";
20
+ import { StringSchema } from "shelving/schema";
21
+
22
+ const SEARCH = new StringSchema({ title: "Search", one: "user" });
23
+
24
+ <QueryRadiosInput name="user" schema={SEARCH} onQuery={search} value={user} onValue={setUser} />
25
+ ```
26
+
27
+ ### Inline list with avatars
28
+
29
+ ```tsx
30
+ <QueryRadiosInput
31
+ popover={false}
32
+ name="user"
33
+ schema={SEARCH}
34
+ onQuery={search}
35
+ formatter={user => <Avatar user={user} />}
36
+ onValue={setUser}
37
+ />
38
+ ```
39
+
40
+ ## Styling
41
+
42
+ `<QueryRadiosInput>` has no own hooks. The popover version uses the `<Popover>` styles. The inline version is a `<Column>` with the input and the `<ArrayRadioInputs>` list, so it uses their styles.
@@ -0,0 +1,26 @@
1
+ import { describe, expect, test } from "bun:test";
2
+ import { renderToStaticMarkup } from "react-dom/server";
3
+ import { STRING } from "shelving/schema";
4
+ import { QueryRadiosInput } from "shelving/ui";
5
+ import { PASSTHROUGH } from "shelving/util/function";
6
+
7
+ describe("QueryRadiosInput", () => {
8
+ test("shows the input with no popover when `popover={false}`", () => {
9
+ const html = renderToStaticMarkup(
10
+ <QueryRadiosInput popover={false} name="q" schema={STRING} onQuery={() => []} onValue={PASSTHROUGH} />,
11
+ );
12
+ expect(html).toContain('name="q"');
13
+ });
14
+ test("formatter can return a React element, not only a string", () => {
15
+ const element = (
16
+ <QueryRadiosInput<string, string>
17
+ name="q"
18
+ schema={STRING}
19
+ onQuery={() => []}
20
+ formatter={v => <strong>{v}</strong>}
21
+ onValue={PASSTHROUGH}
22
+ />
23
+ );
24
+ expect(element).toBeTruthy();
25
+ });
26
+ });
@@ -0,0 +1,53 @@
1
+ import type { ReactElement } from "react";
2
+ import { formatValue } from "../../util/format.js";
3
+ import { ArrayRadioInputs } from "./ArrayRadioInputs.js";
4
+ import type { ValueInputProps } from "./Input.js";
5
+ import { QueryInputBase, type QueryInputBaseProps } from "./QueryInputBase.js";
6
+
7
+ /**
8
+ * Props for `QueryRadiosInput`, a combo box that queries items of type `O` from an input of type `I`, and picks one.
9
+ *
10
+ * @see https://shelving.cc/ui/QueryRadiosInputProps
11
+ */
12
+ export interface QueryRadiosInputProps<I, O> extends QueryInputBaseProps<I, O>, ValueInputProps<O> {}
13
+
14
+ /**
15
+ * Combo box that queries a list of items and lets the user pick one, with radios.
16
+ * - Shows an input based on a `schema` of type `I`; its values are piped to the `onQuery()` callback.
17
+ * - Shows a `<Popover>` with a radio list of returned items to pick a final value of type `O`. Picking an item closes the popover.
18
+ * - With `popover={false}`, shows the radio list inline below the input instead, like a `<select>` list box.
19
+ * - Errors, loading, and empty states are handled automatically.
20
+ *
21
+ * @kind component
22
+ * @returns A combo box element wrapping the input and results popover (or the inline list).
23
+ * @see https://shelving.cc/ui/QueryRadiosInput
24
+ */
25
+ export function QueryRadiosInput<I, O>({
26
+ value,
27
+ onValue,
28
+ formatter = formatValue,
29
+ popover = true,
30
+ ...props
31
+ }: QueryRadiosInputProps<I, O>): ReactElement {
32
+ const { name, required, disabled } = props;
33
+ return (
34
+ <QueryInputBase<I, O>
35
+ {...props}
36
+ popover={popover}
37
+ list={(items, close) => (
38
+ <ArrayRadioInputs
39
+ name={name}
40
+ required={required}
41
+ disabled={disabled}
42
+ items={items}
43
+ value={value}
44
+ formatter={formatter}
45
+ onValue={v => {
46
+ onValue(v);
47
+ if (popover) close();
48
+ }}
49
+ />
50
+ )}
51
+ />
52
+ );
53
+ }
@@ -1,3 +1,4 @@
1
+ export * from "./ArrayCheckboxInputs.js";
1
2
  export * from "./ArrayInput.js";
2
3
  export * from "./ArrayRadioInputs.js";
3
4
  export * from "./ButtonInput.js";
@@ -13,7 +14,9 @@ export * from "./OutputInput.js";
13
14
  export * from "./Popover.js";
14
15
  export * from "./PopoverButton.js";
15
16
  export * from "./PopoverButtonInput.js";
16
- export * from "./QueryInput.js";
17
+ export * from "./QueryCheckboxesInput.js";
18
+ export * from "./QueryInputBase.js";
19
+ export * from "./QueryRadiosInput.js";
17
20
  export * from "./RadioInput.js";
18
21
  export * from "./SchemaInput.js";
19
22
  export * from "./SelectInput.js";
package/ui/input/index.js CHANGED
@@ -1,3 +1,4 @@
1
+ export * from "./ArrayCheckboxInputs.js";
1
2
  export * from "./ArrayInput.js";
2
3
  export * from "./ArrayRadioInputs.js";
3
4
  export * from "./ButtonInput.js";
@@ -13,7 +14,9 @@ export * from "./OutputInput.js";
13
14
  export * from "./Popover.js";
14
15
  export * from "./PopoverButton.js";
15
16
  export * from "./PopoverButtonInput.js";
16
- export * from "./QueryInput.js";
17
+ export * from "./QueryCheckboxesInput.js";
18
+ export * from "./QueryInputBase.js";
19
+ export * from "./QueryRadiosInput.js";
17
20
  export * from "./RadioInput.js";
18
21
  export * from "./SchemaInput.js";
19
22
  export * from "./SelectInput.js";
package/ui/input/index.ts CHANGED
@@ -1,3 +1,4 @@
1
+ export * from "./ArrayCheckboxInputs.js";
1
2
  export * from "./ArrayInput.js";
2
3
  export * from "./ArrayRadioInputs.js";
3
4
  export * from "./ButtonInput.js";
@@ -13,7 +14,9 @@ export * from "./OutputInput.js";
13
14
  export * from "./Popover.js";
14
15
  export * from "./PopoverButton.js";
15
16
  export * from "./PopoverButtonInput.js";
16
- export * from "./QueryInput.js";
17
+ export * from "./QueryCheckboxesInput.js";
18
+ export * from "./QueryInputBase.js";
19
+ export * from "./QueryRadiosInput.js";
17
20
  export * from "./RadioInput.js";
18
21
  export * from "./SchemaInput.js";
19
22
  export * from "./SelectInput.js";
@@ -0,0 +1,24 @@
1
+ import type { ReactElement } from "react";
2
+ import type { ChildProps, ClassProps } from "../util/props.js";
3
+ /**
4
+ * Props for `<Empty>` — the message content plus an optional `className`.
5
+ *
6
+ * @see https://shelving.cc/ui/EmptyProps
7
+ */
8
+ export interface EmptyProps extends ChildProps, ClassProps {
9
+ }
10
+ /**
11
+ * Message for a list with nothing in it: centred, grey content with space around it.
12
+ * - Use it for every empty list, so they all look the same.
13
+ * - Pass the text as `<Paragraph>` elements, plus any buttons. Each child keeps its own margins.
14
+ *
15
+ * @kind component
16
+ * @see https://shelving.cc/ui/Empty
17
+ */
18
+ export declare function Empty({ children, className }: EmptyProps): ReactElement;
19
+ /**
20
+ * Loading spinner in an `<Empty>`, for a list or form that is still loading. The empty message replaces it in the same place.
21
+ *
22
+ * @see https://shelving.cc/ui/EMPTY_LOADING
23
+ */
24
+ export declare const EMPTY_LOADING: import("react").JSX.Element;
@@ -0,0 +1,20 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ import { Block } from "../block/Block.js";
3
+ import { LOADING } from "../misc/Loading.js";
4
+ /**
5
+ * Message for a list with nothing in it: centred, grey content with space around it.
6
+ * - Use it for every empty list, so they all look the same.
7
+ * - Pass the text as `<Paragraph>` elements, plus any buttons. Each child keeps its own margins.
8
+ *
9
+ * @kind component
10
+ * @see https://shelving.cc/ui/Empty
11
+ */
12
+ export function Empty({ children, className }) {
13
+ return (_jsx(Block, { center: true, tint: "50", space: "xlarge", className: className, children: children }));
14
+ }
15
+ /**
16
+ * Loading spinner in an `<Empty>`, for a list or form that is still loading. The empty message replaces it in the same place.
17
+ *
18
+ * @see https://shelving.cc/ui/EMPTY_LOADING
19
+ */
20
+ export const EMPTY_LOADING = _jsx(Empty, { children: LOADING }, "loading");
@@ -0,0 +1,35 @@
1
+ # Empty
2
+
3
+ Message for a list with nothing in it. `<Empty>` shows its content centred and grey, with space around it, so every empty list looks the same.
4
+
5
+ **Things to know:**
6
+
7
+ - Pass the text as `<Paragraph>` elements, plus any buttons. Each child keeps its own margins.
8
+ - `EMPTY_LOADING` is a loading spinner in an `<Empty>`. Use it as the `fallback` of a `<Loader>` for a list, so the empty message later shows in the same place.
9
+ - `<QueryRadiosInput>` and `<QueryCheckboxesInput>` use both for their loading and empty states.
10
+
11
+ ## Usage
12
+
13
+ ### Empty list
14
+
15
+ ```tsx
16
+ import { Empty, Paragraph } from "shelving/ui";
17
+
18
+ <Empty>
19
+ <Paragraph>No challenges yet.</Paragraph>
20
+ </Empty>
21
+ ```
22
+
23
+ ### Loading list
24
+
25
+ ```tsx
26
+ import { EMPTY_LOADING, Loader } from "shelving/ui";
27
+
28
+ <Loader fallback={EMPTY_LOADING}>
29
+ <LoadChallenges />
30
+ </Loader>
31
+ ```
32
+
33
+ ## Styling
34
+
35
+ `<Empty>` has no own hooks. It is a `<Block>` with `center`, `tint="50"` and `space="xlarge"`, so it reads the `--tint-50` ladder step and `--space-xlarge`.
@@ -0,0 +1,18 @@
1
+ import { describe, expect, test } from "bun:test";
2
+ import { renderToStaticMarkup } from "react-dom/server";
3
+ import { EMPTY_LOADING, Empty, Paragraph } from "shelving/ui";
4
+
5
+ describe("Empty", () => {
6
+ test("renders its children in one block", () => {
7
+ const html = renderToStaticMarkup(
8
+ <Empty>
9
+ <Paragraph>No items yet.</Paragraph>
10
+ </Empty>,
11
+ );
12
+ expect(html).toMatch(/^<div[^>]*><p[^>]*>No items yet\.<\/p><\/div>$/);
13
+ });
14
+ test("EMPTY_LOADING renders a spinner in the same block", () => {
15
+ const html = renderToStaticMarkup(EMPTY_LOADING);
16
+ expect(html).toMatch(/^<div[^>]*><svg[^>]*>.*<\/svg><\/div>$/);
17
+ });
18
+ });
@@ -0,0 +1,34 @@
1
+ import type { ReactElement } from "react";
2
+ import { Block } from "../block/Block.js";
3
+ import { LOADING } from "../misc/Loading.js";
4
+ import type { ChildProps, ClassProps } from "../util/props.js";
5
+
6
+ /**
7
+ * Props for `<Empty>` — the message content plus an optional `className`.
8
+ *
9
+ * @see https://shelving.cc/ui/EmptyProps
10
+ */
11
+ export interface EmptyProps extends ChildProps, ClassProps {}
12
+
13
+ /**
14
+ * Message for a list with nothing in it: centred, grey content with space around it.
15
+ * - Use it for every empty list, so they all look the same.
16
+ * - Pass the text as `<Paragraph>` elements, plus any buttons. Each child keeps its own margins.
17
+ *
18
+ * @kind component
19
+ * @see https://shelving.cc/ui/Empty
20
+ */
21
+ export function Empty({ children, className }: EmptyProps): ReactElement {
22
+ return (
23
+ <Block center tint="50" space="xlarge" className={className}>
24
+ {children}
25
+ </Block>
26
+ );
27
+ }
28
+
29
+ /**
30
+ * Loading spinner in an `<Empty>`, for a list or form that is still loading. The empty message replaces it in the same place.
31
+ *
32
+ * @see https://shelving.cc/ui/EMPTY_LOADING
33
+ */
34
+ export const EMPTY_LOADING = <Empty key="loading">{LOADING}</Empty>;
@@ -1,3 +1,4 @@
1
+ export * from "./Empty.js";
1
2
  export * from "./Message.js";
2
3
  export * from "./Notice.js";
3
4
  export * from "./NoticeStore.js";
@@ -1,3 +1,4 @@
1
+ export * from "./Empty.js";
1
2
  export * from "./Message.js";
2
3
  export * from "./Notice.js";
3
4
  export * from "./NoticeStore.js";
@@ -1,3 +1,4 @@
1
+ export * from "./Empty.js";
1
2
  export * from "./Message.js";
2
3
  export * from "./Notice.js";
3
4
  export * from "./NoticeStore.js";
@@ -74,7 +74,7 @@ describe("ClassProps", () => {
74
74
  });
75
75
 
76
76
  test("popover wrapper components render their `className` on the trigger, not the floating panel", () => {
77
- // `PopoverButtonInput` (and `PopoverButton`/`QueryInput`) style their always-visible trigger — only a bare `<Popover>` styles the panel.
77
+ // `PopoverButtonInput` (and `PopoverButton`/`QueryRadiosInput`) style their always-visible trigger — only a bare `<Popover>` styles the panel.
78
78
  const html = render(
79
79
  <PopoverButtonInput name="pick" className="spongy">
80
80
  {["Pick", "Panel"]}
@@ -1,36 +0,0 @@
1
- import type { ReactElement, ReactNode } from "react";
2
- import type { Schema } from "../../schema/Schema.js";
3
- import { type PayloadFetchCallback } from "../../store/PayloadFetchStore.js";
4
- import type { ImmutableArray } from "../../util/array.js";
5
- import type { ValueInputProps } from "./Input.js";
6
- /**
7
- * Props for `QueryInput`, a combo box that queries items of type `O` from an input of type `I`.
8
- *
9
- * @see https://shelving.cc/ui/QueryInputProps
10
- */
11
- export interface QueryInputProps<I, O> extends ValueInputProps<O> {
12
- /** Schema input */
13
- schema: Schema<I>;
14
- /**
15
- * Called with the current text value to return matching items whenever the text input changes.
16
- * - Automatically debounced, so only called after a short delay.
17
- * - Automatically shows a loading state while loading.
18
- * - Returning `undefined` signals to close the popover.
19
- */
20
- onQuery: PayloadFetchCallback<I, ImmutableArray<O> | undefined>;
21
- /** Format an item of type `O` for display in the picker. */
22
- formatter?: ((value: O) => string) | undefined;
23
- /** Message that shows when query returns `[]` empty array (set to `""` empty string to show no message). */
24
- empty?: ReactNode | undefined;
25
- }
26
- /**
27
- * Combo box that queries a list of items and lets the user pick one from a popover.
28
- * - Shows an input based on a `schema` of type `I`; its values are piped to the `onQuery()` callback.
29
- * - Shows a `<Popover>` with a radio list of returned items to pick a final value of type `O`.
30
- * - Errors, loading, and empty states are handled automatically.
31
- *
32
- * @returns A combo box element wrapping the input and results popover.
33
- * @example <QueryInput schema={SEARCH} onQuery={search} value={user} onValue={setUser} />
34
- * @see https://shelving.cc/ui/QueryInput
35
- */
36
- export declare function QueryInput<I, O>({ empty, value, onValue, onQuery, formatter, className, ...props }: QueryInputProps<I, O>): ReactElement;
@@ -1,40 +0,0 @@
1
- import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
- import { useInstance } from "../../react/useInstance.js";
3
- import { useStore } from "../../react/useStore.js";
4
- import { PayloadFetchStore } from "../../store/PayloadFetchStore.js";
5
- import { NONE, SECOND } from "../../util/constants.js";
6
- import { formatValue } from "../../util/format.js";
7
- import { ErrorNotice } from "../misc/Catcher.js";
8
- import { LOADING_NOTICE, Notice } from "../notice/Notice.js";
9
- import { ArrayRadioInputs } from "./ArrayRadioInputs.js";
10
- import { Popover } from "./Popover.js";
11
- import { SchemaInput } from "./SchemaInput.js";
12
- /**
13
- * Combo box that queries a list of items and lets the user pick one from a popover.
14
- * - Shows an input based on a `schema` of type `I`; its values are piped to the `onQuery()` callback.
15
- * - Shows a `<Popover>` with a radio list of returned items to pick a final value of type `O`.
16
- * - Errors, loading, and empty states are handled automatically.
17
- *
18
- * @returns A combo box element wrapping the input and results popover.
19
- * @example <QueryInput schema={SEARCH} onQuery={search} value={user} onValue={setUser} />
20
- * @see https://shelving.cc/ui/QueryInput
21
- */
22
- export function QueryInput({ empty = "No results", value, onValue, onQuery, formatter = formatValue, className, ...props }) {
23
- const store = useStore(useInstance(PayloadFetchStore, NONE, undefined, onQuery, SECOND));
24
- const busy = useStore(store.busy).value;
25
- // Is popover open?
26
- const isOpen = busy || !!store.reason || !!store.value;
27
- const close = () => {
28
- store.payload.value = NONE;
29
- store.value = undefined;
30
- };
31
- return (_jsxs(Popover, { open: isOpen, onClose: close, children: [_jsx(SchemaInput, { ...props, className: className, value: value, onValue: v => {
32
- if (v)
33
- store.payload.value = v;
34
- else
35
- close();
36
- } }), busy ? (LOADING_NOTICE) : store.reason ? (_jsx(ErrorNotice, { reason: store.reason })) : store.value?.length ? (_jsx(ArrayRadioInputs, { items: store.value, onValue: v => {
37
- onValue(v); // Set the value.
38
- close();
39
- }, formatter: formatter, ...props })) : empty ? (_jsx(Notice, { children: empty })) : null] }));
40
- }
@@ -1,100 +0,0 @@
1
- import type { ReactElement, ReactNode } from "react";
2
- import { useInstance } from "../../react/useInstance.js";
3
- import { useStore } from "../../react/useStore.js";
4
- import type { Schema } from "../../schema/Schema.js";
5
- import { type PayloadFetchCallback, PayloadFetchStore } from "../../store/PayloadFetchStore.js";
6
- import type { ImmutableArray } from "../../util/array.js";
7
- import { NONE, SECOND } from "../../util/constants.js";
8
- import { formatValue } from "../../util/format.js";
9
- import { ErrorNotice } from "../misc/Catcher.js";
10
- import { LOADING_NOTICE, Notice } from "../notice/Notice.js";
11
- import { ArrayRadioInputs } from "./ArrayRadioInputs.js";
12
- import type { ValueInputProps } from "./Input.js";
13
- import { Popover } from "./Popover.js";
14
- import { SchemaInput } from "./SchemaInput.js";
15
-
16
- /**
17
- * Props for `QueryInput`, a combo box that queries items of type `O` from an input of type `I`.
18
- *
19
- * @see https://shelving.cc/ui/QueryInputProps
20
- */
21
- export interface QueryInputProps<I, O> extends ValueInputProps<O> {
22
- /** Schema input */
23
- schema: Schema<I>;
24
-
25
- /**
26
- * Called with the current text value to return matching items whenever the text input changes.
27
- * - Automatically debounced, so only called after a short delay.
28
- * - Automatically shows a loading state while loading.
29
- * - Returning `undefined` signals to close the popover.
30
- */
31
- onQuery: PayloadFetchCallback<I, ImmutableArray<O> | undefined>;
32
-
33
- /** Format an item of type `O` for display in the picker. */
34
- formatter?: ((value: O) => string) | undefined;
35
-
36
- /** Message that shows when query returns `[]` empty array (set to `""` empty string to show no message). */
37
- empty?: ReactNode | undefined;
38
- }
39
-
40
- /**
41
- * Combo box that queries a list of items and lets the user pick one from a popover.
42
- * - Shows an input based on a `schema` of type `I`; its values are piped to the `onQuery()` callback.
43
- * - Shows a `<Popover>` with a radio list of returned items to pick a final value of type `O`.
44
- * - Errors, loading, and empty states are handled automatically.
45
- *
46
- * @returns A combo box element wrapping the input and results popover.
47
- * @example <QueryInput schema={SEARCH} onQuery={search} value={user} onValue={setUser} />
48
- * @see https://shelving.cc/ui/QueryInput
49
- */
50
- export function QueryInput<I, O>({
51
- empty = "No results",
52
- value,
53
- onValue,
54
- onQuery,
55
- formatter = formatValue,
56
- className,
57
- ...props
58
- }: QueryInputProps<I, O>): ReactElement {
59
- const store = useStore(useInstance(PayloadFetchStore, NONE, undefined, onQuery, SECOND));
60
- const busy = useStore(store.busy).value;
61
-
62
- // Is popover open?
63
- const isOpen = busy || !!store.reason || !!store.value;
64
-
65
- const close = () => {
66
- store.payload.value = NONE;
67
- store.value = undefined;
68
- };
69
-
70
- return (
71
- <Popover open={isOpen} onClose={close}>
72
- <SchemaInput
73
- {...props}
74
- className={className}
75
- value={value as I}
76
- onValue={v => {
77
- if (v) store.payload.value = v;
78
- else close();
79
- }}
80
- />
81
- {busy ? (
82
- LOADING_NOTICE
83
- ) : store.reason ? (
84
- <ErrorNotice reason={store.reason} />
85
- ) : store.value?.length ? (
86
- <ArrayRadioInputs
87
- items={store.value}
88
- onValue={v => {
89
- onValue(v); // Set the value.
90
- close();
91
- }}
92
- formatter={formatter}
93
- {...props}
94
- />
95
- ) : empty ? (
96
- <Notice>{empty}</Notice>
97
- ) : null}
98
- </Popover>
99
- );
100
- }