shelving 1.298.0 → 1.299.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.299.0",
4
4
  "author": "Dave Houlbrooke <dave@shax.com>",
5
5
  "repository": {
6
6
  "type": "git",
@@ -1,4 +1,4 @@
1
- import type { ReactElement, ReactNode } from "react";
1
+ import { type ReactElement, type ReactNode } from "react";
2
2
  import type { Schema } from "../../schema/Schema.js";
3
3
  import { type PayloadFetchCallback } from "../../store/PayloadFetchStore.js";
4
4
  import type { ImmutableArray } from "../../util/array.js";
@@ -15,11 +15,17 @@ export interface QueryInputProps<I, O> extends ValueInputProps<O> {
15
15
  * Called with the current text value to return matching items whenever the text input changes.
16
16
  * - Automatically debounced, so only called after a short delay.
17
17
  * - Automatically shows a loading state while loading.
18
- * - Returning `undefined` signals to close the popover.
18
+ * - Returning `undefined` signals to close the popover (or, with `popover={false}`, to show no list).
19
19
  */
20
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;
21
+ /** Format an item of type `O` for display in the picker, 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, and picking an item keeps the list.
27
+ */
28
+ popover?: boolean | undefined;
23
29
  /** Message that shows when query returns `[]` empty array (set to `""` empty string to show no message). */
24
30
  empty?: ReactNode | undefined;
25
31
  }
@@ -27,10 +33,12 @@ export interface QueryInputProps<I, O> extends ValueInputProps<O> {
27
33
  * Combo box that queries a list of items and lets the user pick one from a popover.
28
34
  * - Shows an input based on a `schema` of type `I`; its values are piped to the `onQuery()` callback.
29
35
  * - Shows a `<Popover>` with a radio list of returned items to pick a final value of type `O`.
36
+ * - With `popover={false}`, shows the radio list inline below the input instead, like a `<select>` list box.
30
37
  * - Errors, loading, and empty states are handled automatically.
31
38
  *
32
- * @returns A combo box element wrapping the input and results popover.
39
+ * @returns A combo box element wrapping the input and results popover (or the inline list).
33
40
  * @example <QueryInput schema={SEARCH} onQuery={search} value={user} onValue={setUser} />
41
+ * @example <QueryInput popover={false} schema={SEARCH} onQuery={search} value={user} onValue={setUser} />
34
42
  * @see https://shelving.cc/ui/QueryInput
35
43
  */
36
- export declare function QueryInput<I, O>({ empty, value, onValue, onQuery, formatter, className, ...props }: QueryInputProps<I, O>): ReactElement;
44
+ export declare function QueryInput<I, O>({ empty, value, onValue, onQuery, formatter, popover, className, ...props }: QueryInputProps<I, O>): ReactElement;
@@ -1,9 +1,11 @@
1
1
  import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { useEffect } from "react";
2
3
  import { useInstance } from "../../react/useInstance.js";
3
4
  import { useStore } from "../../react/useStore.js";
4
5
  import { PayloadFetchStore } from "../../store/PayloadFetchStore.js";
5
6
  import { NONE, SECOND } from "../../util/constants.js";
6
7
  import { formatValue } from "../../util/format.js";
8
+ import { Column } from "../block/Column.js";
7
9
  import { ErrorNotice } from "../misc/Catcher.js";
8
10
  import { LOADING_NOTICE, Notice } from "../notice/Notice.js";
9
11
  import { ArrayRadioInputs } from "./ArrayRadioInputs.js";
@@ -13,28 +15,39 @@ import { SchemaInput } from "./SchemaInput.js";
13
15
  * Combo box that queries a list of items and lets the user pick one from a popover.
14
16
  * - Shows an input based on a `schema` of type `I`; its values are piped to the `onQuery()` callback.
15
17
  * - Shows a `<Popover>` with a radio list of returned items to pick a final value of type `O`.
18
+ * - With `popover={false}`, shows the radio list inline below the input instead, like a `<select>` list box.
16
19
  * - Errors, loading, and empty states are handled automatically.
17
20
  *
18
- * @returns A combo box element wrapping the input and results popover.
21
+ * @returns A combo box element wrapping the input and results popover (or the inline list).
19
22
  * @example <QueryInput schema={SEARCH} onQuery={search} value={user} onValue={setUser} />
23
+ * @example <QueryInput popover={false} schema={SEARCH} onQuery={search} value={user} onValue={setUser} />
20
24
  * @see https://shelving.cc/ui/QueryInput
21
25
  */
22
- export function QueryInput({ empty = "No results", value, onValue, onQuery, formatter = formatValue, className, ...props }) {
26
+ export function QueryInput({ empty = "No results", value, onValue, onQuery, formatter = formatValue, popover = true, className, ...props }) {
23
27
  const store = useStore(useInstance(PayloadFetchStore, NONE, undefined, onQuery, SECOND));
24
28
  const busy = useStore(store.busy).value;
29
+ // Inline, query the schema's default value at once, so the list shows before anything is typed.
30
+ useEffect(() => {
31
+ if (!popover)
32
+ store.payload.value = props.schema.value;
33
+ }, [popover, store, props.schema]);
25
34
  // Is popover open?
26
35
  const isOpen = busy || !!store.reason || !!store.value;
27
36
  const close = () => {
28
37
  store.payload.value = NONE;
29
38
  store.value = undefined;
30
39
  };
40
+ const results = busy ? (LOADING_NOTICE) : store.reason ? (_jsx(ErrorNotice, { reason: store.reason })) : store.value?.length ? (_jsx(ArrayRadioInputs, { items: store.value, onValue: v => {
41
+ onValue(v); // Set the value.
42
+ if (popover)
43
+ close();
44
+ }, formatter: formatter, ...props })) : empty && store.value ? (_jsx(Notice, { children: empty })) : null;
45
+ if (!popover)
46
+ return (_jsxs(Column, { children: [_jsx(SchemaInput, { ...props, className: className, value: value, onValue: v => void (store.payload.value = v) }), results] }));
31
47
  return (_jsxs(Popover, { open: isOpen, onClose: close, children: [_jsx(SchemaInput, { ...props, className: className, value: value, onValue: v => {
32
48
  if (v)
33
49
  store.payload.value = v;
34
50
  else
35
51
  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] }));
52
+ } }), results] }));
40
53
  }
@@ -0,0 +1,38 @@
1
+ # QueryInput
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), and loading, error and empty states show automatically.
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
+ - `empty` sets the message for no results (`""` shows no message).
12
+
13
+ ## Usage
14
+
15
+ ### Popover
16
+
17
+ ```tsx
18
+ import { QueryInput } from "shelving/ui";
19
+
20
+ <QueryInput name="user" schema={SEARCH} onQuery={search} value={user} onValue={setUser} />
21
+ ```
22
+
23
+ ### Inline list with avatars
24
+
25
+ ```tsx
26
+ <QueryInput
27
+ popover={false}
28
+ name="user"
29
+ schema={SEARCH}
30
+ onQuery={search}
31
+ formatter={user => <Avatar user={user} />}
32
+ onValue={setUser}
33
+ />
34
+ ```
35
+
36
+ ## Styling
37
+
38
+ 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,18 @@
1
+ import { describe, expect, test } from "bun:test";
2
+ import { renderToStaticMarkup } from "react-dom/server";
3
+ import { STRING } from "shelving/schema";
4
+ import { QueryInput } from "shelving/ui";
5
+ import { PASSTHROUGH } from "shelving/util/function";
6
+
7
+ describe("QueryInput", () => {
8
+ test("shows the input with no popover when `popover={false}`", () => {
9
+ const html = renderToStaticMarkup(<QueryInput popover={false} name="q" schema={STRING} onQuery={() => []} onValue={PASSTHROUGH} />);
10
+ expect(html).toContain('name="q"');
11
+ });
12
+ test("formatter can return a React element, not only a string", () => {
13
+ const element = (
14
+ <QueryInput<string, string> name="q" schema={STRING} onQuery={() => []} formatter={v => <strong>{v}</strong>} onValue={PASSTHROUGH} />
15
+ );
16
+ expect(element).toBeTruthy();
17
+ });
18
+ });
@@ -1,4 +1,4 @@
1
- import type { ReactElement, ReactNode } from "react";
1
+ import { type ReactElement, type ReactNode, useEffect } from "react";
2
2
  import { useInstance } from "../../react/useInstance.js";
3
3
  import { useStore } from "../../react/useStore.js";
4
4
  import type { Schema } from "../../schema/Schema.js";
@@ -6,6 +6,7 @@ import { type PayloadFetchCallback, PayloadFetchStore } from "../../store/Payloa
6
6
  import type { ImmutableArray } from "../../util/array.js";
7
7
  import { NONE, SECOND } from "../../util/constants.js";
8
8
  import { formatValue } from "../../util/format.js";
9
+ import { Column } from "../block/Column.js";
9
10
  import { ErrorNotice } from "../misc/Catcher.js";
10
11
  import { LOADING_NOTICE, Notice } from "../notice/Notice.js";
11
12
  import { ArrayRadioInputs } from "./ArrayRadioInputs.js";
@@ -26,12 +27,19 @@ export interface QueryInputProps<I, O> extends ValueInputProps<O> {
26
27
  * Called with the current text value to return matching items whenever the text input changes.
27
28
  * - Automatically debounced, so only called after a short delay.
28
29
  * - Automatically shows a loading state while loading.
29
- * - Returning `undefined` signals to close the popover.
30
+ * - Returning `undefined` signals to close the popover (or, with `popover={false}`, to show no list).
30
31
  */
31
32
  onQuery: PayloadFetchCallback<I, ImmutableArray<O> | undefined>;
32
33
 
33
- /** Format an item of type `O` for display in the picker. */
34
- formatter?: ((value: O) => string) | undefined;
34
+ /** Format an item of type `O` for display in the picker, for example as text or as an avatar. */
35
+ formatter?: ((value: O) => ReactNode) | undefined;
36
+
37
+ /**
38
+ * Show the results in a popover (the default), or set `false` to show them inline, as a list below the input.
39
+ * - Inline, the list shows at once: `onQuery()` is called with the schema's default value (e.g. `""`) on mount.
40
+ * - Inline, an empty input still queries, and picking an item keeps the list.
41
+ */
42
+ popover?: boolean | undefined;
35
43
 
36
44
  /** Message that shows when query returns `[]` empty array (set to `""` empty string to show no message). */
37
45
  empty?: ReactNode | undefined;
@@ -41,10 +49,12 @@ export interface QueryInputProps<I, O> extends ValueInputProps<O> {
41
49
  * Combo box that queries a list of items and lets the user pick one from a popover.
42
50
  * - Shows an input based on a `schema` of type `I`; its values are piped to the `onQuery()` callback.
43
51
  * - Shows a `<Popover>` with a radio list of returned items to pick a final value of type `O`.
52
+ * - With `popover={false}`, shows the radio list inline below the input instead, like a `<select>` list box.
44
53
  * - Errors, loading, and empty states are handled automatically.
45
54
  *
46
- * @returns A combo box element wrapping the input and results popover.
55
+ * @returns A combo box element wrapping the input and results popover (or the inline list).
47
56
  * @example <QueryInput schema={SEARCH} onQuery={search} value={user} onValue={setUser} />
57
+ * @example <QueryInput popover={false} schema={SEARCH} onQuery={search} value={user} onValue={setUser} />
48
58
  * @see https://shelving.cc/ui/QueryInput
49
59
  */
50
60
  export function QueryInput<I, O>({
@@ -53,12 +63,18 @@ export function QueryInput<I, O>({
53
63
  onValue,
54
64
  onQuery,
55
65
  formatter = formatValue,
66
+ popover = true,
56
67
  className,
57
68
  ...props
58
69
  }: QueryInputProps<I, O>): ReactElement {
59
70
  const store = useStore(useInstance(PayloadFetchStore, NONE, undefined, onQuery, SECOND));
60
71
  const busy = useStore(store.busy).value;
61
72
 
73
+ // Inline, query the schema's default value at once, so the list shows before anything is typed.
74
+ useEffect(() => {
75
+ if (!popover) store.payload.value = props.schema.value as I;
76
+ }, [popover, store, props.schema]);
77
+
62
78
  // Is popover open?
63
79
  const isOpen = busy || !!store.reason || !!store.value;
64
80
 
@@ -67,6 +83,32 @@ export function QueryInput<I, O>({
67
83
  store.value = undefined;
68
84
  };
69
85
 
86
+ const results = busy ? (
87
+ LOADING_NOTICE
88
+ ) : store.reason ? (
89
+ <ErrorNotice reason={store.reason} />
90
+ ) : store.value?.length ? (
91
+ <ArrayRadioInputs
92
+ items={store.value}
93
+ onValue={v => {
94
+ onValue(v); // Set the value.
95
+ if (popover) close();
96
+ }}
97
+ formatter={formatter}
98
+ {...props}
99
+ />
100
+ ) : empty && store.value ? (
101
+ <Notice>{empty}</Notice>
102
+ ) : null;
103
+
104
+ if (!popover)
105
+ return (
106
+ <Column>
107
+ <SchemaInput {...props} className={className} value={value as I} onValue={v => void (store.payload.value = v as I)} />
108
+ {results}
109
+ </Column>
110
+ );
111
+
70
112
  return (
71
113
  <Popover open={isOpen} onClose={close}>
72
114
  <SchemaInput
@@ -78,23 +120,7 @@ export function QueryInput<I, O>({
78
120
  else close();
79
121
  }}
80
122
  />
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}
123
+ {results}
98
124
  </Popover>
99
125
  );
100
126
  }