@tristan2828/ui-foundation 4.18.4 → 4.19.0

package/conventions/docs/add-an-entity.md

@@ -367,7 +367,10 @@ is a filled-in example while the Widgets demo is still here).
      `defaultOpen`, non-modal, `onChange={(v) => props.commit(v)}`,
      `onOpenChange={(open) => !open && props.cancel()}`; a yes/no switch
      commits on change), `multi` (a multi reference; `isEqual` comparing
-     ids as a set). A field gets `edit`, a `content` section gets `edit`,
+     ids as a set; a field the plan marks `small` is `MultiPick`, on the
+     form too, every option loaded once, and saves each click itself:
+     `value` is the record's, `onPick` the single-field save as a
+     function of the record, cell pattern 18 "A small set"). A field gets `edit`, a `content` section gets `edit`,
      the title gets `titleEdit={{ label, ...edit }}`, and a header badge
      wraps itself in `<EditableValue label edit layout="inline">`. The
      shown value stays exactly as before. A sub-record list the line

package/conventions/docs/cell-patterns.md

@@ -740,6 +740,7 @@ Save button, no Undo:
 | `long-text`: notes, rich text for Markdown | Ctrl/Cmd+Enter, or leaving it (Enter is a new line); with `autosave`, also a pause in typing | the same; with `autosave`, saves what's left and closes |
 | `choice`: a select, a switch, a single reference | the pick (its list opens with the field, non-modal) | closes the list with nothing picked: gives up |
 | `multi`: a multi reference | leaving it, or Ctrl/Cmd+Enter (Enter picks) | closes the list first; Esc again gives up |
+| `multi` over a small set (`MultiPick`) | each click, on its own | closes it: every pick is already saved |
 
 In either multi picker (`MultiChoice`, `MultiReference`), on a form, in
 a toolbar filter or in place, Escape never removes a pick: it closes the
@@ -747,6 +748,59 @@ list when it's open and leaves the value alone when it's closed (Base UI
 would empty it). A pick comes off only by its chip's remove button,
 Backspace in the empty input, or unpicking it in the list.
 
+**A small set (`MultiPick`): every option shown, each click saves.** A
+multi field whose options are few (up to about 25) and all loaded (a
+dozen labels, a short tag list) uses `MultiPick` instead, on the form
+and in place: every option a toggle chip with its icon or colour where
+the app draws one (`icon`), the picked ones pressed with a check, and a
+filter box above them, not in front of them. Larger sets, or ones that
+grow with the data, keep `MultiReference` (typing searches the server)
+or `MultiChoice`.
+
+- **The plan says which**, by marking the field `small`; the control
+  isn't switched by option count. The two save differently in place
+  (each pick here, the whole set on leaving there) and load differently
+  (every option here, a search there), so a set crossing 25 would change
+  how saving works under the user.
+- **Each click saves that one pick** (`onPick`), like a quick action
+  (pattern 17): the chip shows the pick at once with a spinner beside it
+  (`aria-busy`) until the server agrees. Nothing is disabled, and quick
+  picks each save, one after another, each built on the record's latest
+  value (a function change, as a sub-record list's is).
+- **A refusal puts back that one pick**, with its reason under the chips
+  in the destructive text tone ("Couldn't add Archived: <the server's
+  reason>"), the chip described by it. Picks still saving carry on. If
+  the field closed before the answer, the reason is a toast.
+- **Nothing is drafted**, so leaving the field (a click or Tab
+  elsewhere), Esc or Ctrl/Cmd+Enter only close it: there's no "Saving…"
+  under the field and nothing to give up.
+- **Keyboard:** opening puts the caret in the filter box; Down goes to
+  the chips, Left/Right (Home/End) move along them, Space or Enter
+  toggles one, Up goes back to the box.
+- Pass the record's value as `value`, not the control's `props.value`
+  (the draft, which never moves here), and keep the field's `save`: the
+  form's whole-set save, never called in place.
+
+```tsx
+const editField = useEditWidgetField(widget.id) // optimistic: false, toastOnError: false
+labels: editInPlace({
+  kind: 'multi',
+  value: widget.labelIds,
+  isEqual: sameIds,
+  save: (labelIds) => editField.mutateAsync({ labelIds }),
+  control: (props) => (
+    <WidgetLabelsPicker id={props.id} value={widget.labelIds}
+      onPick={(id, picked) => editField.mutateAsync((current) => ({
+        labelIds: [...current.labelIds.filter((other) => other !== id), ...(picked ? [id] : [])],
+      }))}
+      aria-label={props.label} aria-describedby={props.describedBy} />
+  ),
+}),
+// WidgetLabelsPicker: <MultiPick options={labels.map((l) => ({ id: l.id, label: l.name,
+//   icon: <TagIcon className={LABEL_COLOUR[l.slot]} /> }))} value onPick aria-label aria-describedby />
+// On the form, the same control with onValueChange={field.onChange} instead of onPick.
+```
+
 Leaving means clicking or tabbing anywhere else. Unchanged closes with no
 request; a value the form's schema refuses never leaves the browser and
 shows the schema's message. Opening another value saves the open one

package/conventions/docs/entity-plan-template.md

@@ -39,6 +39,9 @@ One or two sentences: what one record is, and who uses the screens.
     (to any number of records of another entity — name it; chips with a
     searchable dropdown, names as badges in the table, an any-of filter;
     the other entity's list endpoint must also accept `ids`),
+    either multi marked `small` when its options are few and stay few (up
+    to about 25: a dozen labels): every option shown at once as chips,
+    and editing in place saves each click,
     `computed` (read-only: the server works it out from other data on
     every read and never stores it — give its rule, and if it's a choice,
     its values in sort order with a label for each; a read-only column, a filter and a sort the

package/dist/components/app/multi-pick.d.ts

@@ -0,0 +1,43 @@
+import { type ReactNode } from 'react';
+export type MultiPickOption<Id extends string | number> = {
+    id: Id;
+    label: string;
+    /**
+     * The icon or colour the app draws for this value elsewhere (its
+     * category glyph in its categorical slot), shown before the label. Drawn
+     * `aria-hidden`: the label names it.
+     */
+    icon?: ReactNode;
+};
+export type MultiPickProps<Id extends string | number> = {
+    /** Every option, in display order. */
+    options: readonly MultiPickOption<Id>[];
+    /**
+     * The picked ids. Edited in place, the record's saved value
+     * (`widget.tagIds`), not the control's `props.value`: nothing is drafted.
+     */
+    value: readonly Id[];
+    /** On a form: the value changed. */
+    onValueChange?: (value: Id[]) => void;
+    /**
+     * Edited in place: saves one pick (`picked` true adds `id`, false removes
+     * it), resolving once saved and rejecting with the AppError. Build it on
+     * the record's latest value, so quick picks don't lose each other:
+     * `(id, picked) => save((widget) => ({ tags: toggled(widget.tags, id, picked) }))`.
+     */
+    onPick?: (id: Id, picked: boolean) => Promise<unknown>;
+    /** The field's label: the chips' group is named by it, the filter box "Filter <label>". */
+    'aria-label': string;
+    /** The id of a line under the control (an edit in place's status line). */
+    'aria-describedby'?: string;
+    /** Id for the filter box, so a <FieldLabel htmlFor> labels it on a form. */
+    id?: string;
+    /** The filter box's placeholder. */
+    placeholder?: string;
+    /** Shown when there are no options at all. */
+    emptyText?: string;
+    /** Shown, not changeable. */
+    readOnly?: boolean;
+    className?: string;
+};
+export declare function MultiPick<Id extends string | number>({ options, value, onValueChange, onPick, 'aria-label': label, 'aria-describedby': describedBy, id, placeholder, emptyText, readOnly, className, }: MultiPickProps<Id>): import("react").JSX.Element;

package/dist/components/app/multi-pick.js

@@ -0,0 +1,125 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A picker for a small set (up to about 25 options): every option shown
+// at once as a toggle chip, with a box above that filters them. The
+// control for a multi field whose options are few and all loaded (tags, a
+// dozen categories), on a form and edited in place (cell-patterns.md
+// "Editable value", "A small set"). A large set keeps MultiReference:
+// typing searches the server.
+//
+// Which one is the app's choice, by the control it renders, not switched
+// here by option count: the two save differently in place (each pick at
+// once here, the whole set on leaving there) and load differently (every
+// option here, a server search there), so a set crossing 25 would change
+// how saving works under the user. The plan names the set small.
+//
+// - **Edited in place, each pick saves on its own** (`onPick`), like a
+//   quick action (pattern 17): the chip shows the pick at once with a
+//   spinner beside it until the server answers. A refusal puts that one
+//   chip back, with its reason under the chips; picks still saving carry
+//   on. Nothing is drafted, so leaving the field or Esc only closes it.
+// - **On a form** (`onValueChange`): a click changes the value, saved
+//   with the form.
+// - Keyboard: the filter box first; Down goes to the chips, Left/Right
+//   (Home/End) move along them, Up goes back to the box, and Space or
+//   Enter toggles a chip.
+import { CheckIcon } from 'lucide-react';
+import { useEffect, useId, useRef, useState } from 'react';
+import { toast } from 'sonner';
+import { cn } from 'cn';
+import { FieldError } from '../ui/field.js';
+import { Input } from '../ui/input.js';
+import { Spinner } from '../ui/spinner.js';
+import { ToggleGroup, ToggleGroupItem } from '../ui/toggle-group.js';
+import { messageOf } from './edit-in-place-store.js';
+export function MultiPick({ options, value, onValueChange, onPick, 'aria-label': label, 'aria-describedby': describedBy, id, placeholder = 'Filter', emptyText = 'No options.', readOnly = false, className, }) {
+    const key = useId();
+    const [filter, setFilter] = useState('');
+    const [pending, setPending] = useState(() => new Map());
+    const [refused, setRefused] = useState(() => new Map());
+    const filterBox = useRef(null);
+    const chips = useRef(null);
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+        };
+    }, []);
+    // The saved value moved (a save's record arrived): answered picks give
+    // way to it. Picks still saving keep showing.
+    const [seenValue, setSeenValue] = useState(value);
+    if (seenValue !== value) {
+        setSeenValue(value);
+        if ([...pending.values()].some((entry) => entry.inFlight === 0))
+            setPending(new Map([...pending].filter(([, entry]) => entry.inFlight > 0)));
+    }
+    const isPicked = (option) => pending.get(option)?.picked ?? value.includes(option);
+    const shown = options.filter((option) => isPicked(option.id)).map((option) => option.id);
+    const settle = (option, ok) => setPending((current) => {
+        const entry = current.get(option);
+        if (!entry)
+            return current;
+        const next = new Map(current);
+        const inFlight = entry.inFlight - 1;
+        // Refused with nothing else of this pick out: back to the saved value.
+        if (!ok && inFlight === 0)
+            next.delete(option);
+        else
+            next.set(option, { ...entry, inFlight });
+        return next;
+    });
+    const toggle = (option, picked) => {
+        if (!onPick) {
+            // In the options' order, keeping any picked id with no option.
+            const known = new Set(options.map((other) => other.id));
+            onValueChange?.([
+                ...options.filter((other) => (other.id === option.id ? picked : isPicked(other.id))).map((other) => other.id),
+                ...value.filter((other) => !known.has(other)),
+            ]);
+            return;
+        }
+        setRefused((current) => without(current, option.id));
+        setPending((current) => new Map(current).set(option.id, { picked, inFlight: (current.get(option.id)?.inFlight ?? 0) + 1 }));
+        onPick(option.id, picked).then(() => settle(option.id, true), (error) => {
+            settle(option.id, false);
+            const reason = `Couldn't ${picked ? 'add' : 'remove'} ${option.label}: ${messageOf(error)}`;
+            // Closed before the answer: the reason has nowhere else to show.
+            if (mounted.current)
+                setRefused((current) => new Map(current).set(option.id, reason));
+            else
+                toast.error(reason);
+        });
+    };
+    const needle = filter.trim().toLowerCase();
+    const visible = needle ? options.filter((option) => option.label.toLowerCase().includes(needle)) : options;
+    // Down from the box: into the chips, at the one the group would tab to.
+    const onFilterKeyDown = (event) => {
+        if (event.key !== 'ArrowDown')
+            return;
+        const items = [...(chips.current?.querySelectorAll('[data-slot="toggle-group-item"]') ?? [])];
+        const target = items.find((item) => item.tabIndex === 0) ?? items[0];
+        if (!target)
+            return;
+        event.preventDefault();
+        target.focus();
+    };
+    const onChipsKeyDown = (event) => {
+        if (event.key !== 'ArrowUp')
+            return;
+        event.preventDefault();
+        filterBox.current?.focus();
+    };
+    const errorId = (option) => `${key}-refused-${String(option)}`;
+    return (_jsxs("div", { "data-slot": "multi-pick", className: cn('flex w-full min-w-0 flex-col gap-2', className), children: [_jsx(Input, { ref: filterBox, id: id, type: "search", value: filter, onChange: (event) => setFilter(event.target.value), onKeyDown: onFilterKeyDown, placeholder: placeholder, "aria-label": `Filter ${label}`, "aria-describedby": describedBy, autoComplete: "off", readOnly: readOnly, className: "max-w-xs" }), visible.length === 0 ? (_jsx("p", { className: "type-caption text-muted-foreground", children: options.length === 0 ? emptyText : 'No matches.' })) : (_jsx(ToggleGroup, { ref: chips, multiple: true, variant: "outline", size: "sm", spacing: 1.5, value: shown.map(String), disabled: readOnly, onKeyDown: onChipsKeyDown, "aria-label": label, "aria-describedby": describedBy, className: "flex-wrap", children: visible.map((option) => {
+                    const picked = isPicked(option.id);
+                    const saving = (pending.get(option.id)?.inFlight ?? 0) > 0;
+                    return (_jsxs(ToggleGroupItem, { value: String(option.id), onPressedChange: (next) => toggle(option, next), "aria-busy": saving || undefined, "aria-describedby": refused.has(option.id) ? errorId(option.id) : undefined, children: [option.icon && (_jsx("span", { "aria-hidden": "true", className: "inline-flex shrink-0", children: option.icon })), option.label, _jsx("span", { "aria-hidden": "true", className: "inline-flex size-3.5 shrink-0 items-center justify-center", children: saving ? (_jsx(Spinner, { className: "size-3.5 text-muted-foreground" })) : (picked && _jsx(CheckIcon, { className: "size-3.5" })) })] }, option.id));
+                }) })), refused.size > 0 && (_jsx(FieldError, { className: "type-caption flex flex-col gap-0.5", children: [...refused].map(([option, reason]) => (_jsx("span", { id: errorId(option), children: reason }, String(option)))) }))] }));
+}
+function without(map, key) {
+    if (!map.has(key))
+        return map;
+    const next = new Map(map);
+    next.delete(key);
+    return next;
+}

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export { FoundationProviders } from './components/app/foundation-providers.js';
 export { Markdown, type MarkdownProps } from './components/app/markdown.js';
 export { MockModeBanner } from './components/app/mock-mode-banner.js';
 export { MultiChoice } from './components/app/multi-choice.js';
+export { MultiPick, type MultiPickOption, type MultiPickProps } from './components/app/multi-pick.js';
 export { MultiReference } from './components/app/multi-reference.js';
 export { ListEditor } from './components/app/list-editor.js';
 export { PasswordInput } from './components/app/password-input.js';

package/dist/index.js

@@ -19,6 +19,7 @@ export { FoundationProviders } from './components/app/foundation-providers.js';
 export { Markdown } from './components/app/markdown.js';
 export { MockModeBanner } from './components/app/mock-mode-banner.js';
 export { MultiChoice } from './components/app/multi-choice.js';
+export { MultiPick } from './components/app/multi-pick.js';
 export { MultiReference } from './components/app/multi-reference.js';
 export { ListEditor } from './components/app/list-editor.js';
 export { PasswordInput } from './components/app/password-input.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.18.4",
+  "version": "4.19.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {