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 +1 -1
- package/ui/input/QueryInput.d.ts +14 -6
- package/ui/input/QueryInput.js +19 -6
- package/ui/input/QueryInput.md +38 -0
- package/ui/input/QueryInput.test.tsx +18 -0
- package/ui/input/QueryInput.tsx +48 -22
package/package.json
CHANGED
package/ui/input/QueryInput.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type
|
|
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) =>
|
|
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;
|
package/ui/input/QueryInput.js
CHANGED
|
@@ -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
|
-
} }),
|
|
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
|
+
});
|
package/ui/input/QueryInput.tsx
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type
|
|
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) =>
|
|
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
|
-
{
|
|
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
|
}
|