@tristan2828/ui-foundation 4.52.0 → 4.53.0

package/conventions/docs/design-language.md

@@ -21,7 +21,7 @@
 - [A list as cards](#a-list-as-cards) · lines 749–795
 - [Key numbers on a record](#key-numbers-on-a-record) · lines 797–819
 - [Picking at random](#picking-at-random) · lines 821–852
-- [Filling in what's missing](#filling-in-whats-missing) · lines 854–904
+- [Filling in what's missing](#filling-in-whats-missing) · lines 854–921
 
 <!-- /index -->
 
@@ -902,3 +902,20 @@ size"); the list stays where a record is edited one field at a time.
 - A refused save keeps the record and says why under the buttons, not
   in a toast. It owns its states: skeletons, `ErrorState`, and the
   empty queue, which is the good news ("Every project has a size").
+- **Other kinds of value** (4.53): `FillInInput` is the row for text,
+  long text, a number, money (the currency's symbol before it) or a date
+  (`DateField`), and `FillInSelect` for a list too long for buttons (a
+  reference to another record). Each has the label above and a
+  suggestion under it as a dashed "Use $249.00" button, never filled in
+  for the person.
+- **Fields as data:** `FillInField` takes a field as an API describes it
+  (`{ name, label, kind, choices, suggestion }`, `kind` one of choice,
+  reference, text, longText, number, money, date) and draws the row its
+  kind calls for: `FillInChoice` for up to nine choices, `FillInSelect`
+  for more, `FillInInput` for the rest. Its value is a choice's value, a
+  number for number and money, text otherwise, null for none. For a page
+  that draws records it doesn't know in advance.
+- **Records from several places:** `groups` (`{ id, label, icon,
+  progress }`) and `getGroup` name a record's source above its heading,
+  with that group's own count; with more than one group counted, each
+  one's count is listed under the bar.

package/dist/components/app/fill-in-field.d.ts

@@ -0,0 +1,65 @@
+import { type ReactNode } from 'react';
+export type FillInInputKind = 'text' | 'longText' | 'number' | 'money' | 'date';
+export interface FillInSuggestion<V> {
+    value: V;
+    /** Why it's suggested: "from similar purchases". */
+    note?: ReactNode;
+}
+export interface FillInInputProps {
+    label: string;
+    kind: FillInInputKind;
+    /** The control's text: `'YYYY-MM-DD'` for a date, a number as typed; `''` for none. */
+    value: string;
+    onChange: (value: string) => void;
+    /** Offered as a dashed "Use …" button under the control. */
+    suggestion?: FillInSuggestion<string>;
+    /** The currency of a money value, for its symbol and the suggestion. Default "USD". */
+    currency?: string;
+    locale?: string;
+    placeholder?: string;
+    className?: string;
+}
+/** One text, number, money or date field of a FillInQueue record. */
+export declare function FillInInput({ label, kind, value, onChange, suggestion, currency, locale, placeholder, className, }: FillInInputProps): import("react").JSX.Element;
+export interface FillInSelectProps<V extends string | number> {
+    label: string;
+    choices: readonly {
+        value: V;
+        label: ReactNode;
+    }[];
+    value: V | null | undefined;
+    onChange: (value: V | null) => void;
+    suggestion?: FillInSuggestion<V>;
+    /** What the trigger says with nothing picked. Default "Pick one". */
+    placeholder?: string;
+    className?: string;
+}
+/** One field of a FillInQueue record picked from a long list. */
+export declare function FillInSelect<V extends string | number>({ label, choices, value, onChange, suggestion, placeholder, className, }: FillInSelectProps<V>): import("react").JSX.Element;
+export type FillInFieldKind = 'choice' | 'reference' | FillInInputKind;
+export type FillInValue = string | number | null;
+/** A field described as data, as an API sends it. */
+export interface FillInFieldSpec {
+    name: string;
+    label: string;
+    kind: FillInFieldKind;
+    /** For `choice` and `reference`. */
+    choices?: readonly {
+        value: string | number;
+        label: string;
+    }[];
+    suggestion?: FillInSuggestion<string | number>;
+}
+export interface FillInFieldProps {
+    field: FillInFieldSpec;
+    /** The draft's value: a choice's value, a number for number and money, text for the rest; null for none. */
+    value: FillInValue | undefined;
+    onChange: (value: FillInValue) => void;
+    /** The number keys pick in this field when it's drawn as a row of choices. One per record. */
+    shortcut?: boolean;
+    currency?: string;
+    locale?: string;
+    className?: string;
+}
+/** The row a field's kind calls for: FillInChoice, FillInSelect or FillInInput. */
+export declare function FillInField({ field, value, onChange, shortcut, currency, locale, className }: FillInFieldProps): import("react").JSX.Element;

package/dist/components/app/fill-in-field.js

@@ -0,0 +1,99 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// FillInQueue's rows for values that aren't a short choice: text, a number,
+// money, a date, and a long list to pick from. Each looks like FillInChoice
+// (a label, the control, a suggestion under it) so a record mixes them.
+//
+// - FillInInput: one text, number, money or date value. The value is the
+//   control's own text (`'YYYY-MM-DD'` for a date, `''` for none); the app
+//   reads it. A suggestion is a dashed button under it ("Use $12.00"),
+//   never filled in for the person.
+// - FillInSelect: one value from a list too long for a row of buttons
+//   (a reference to another record, a long enum), as a Select.
+// - FillInField: given a field as data (`{ name, label, kind, choices }`,
+//   as an API describes it), the right row: FillInChoice for up to nine
+//   choices, FillInSelect for more, FillInInput for the rest. For a page
+//   that draws records it doesn't know in advance.
+import { useId, useState } from 'react';
+import { cn } from 'cn';
+import { DateField } from './date-field.js';
+import { FillInChoice } from './fill-in-queue.js';
+import { Button } from '../ui/button.js';
+import { Input } from '../ui/input.js';
+import { InputGroup, InputGroupAddon, InputGroupInput, InputGroupText } from '../ui/input-group.js';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select.js';
+import { Textarea } from '../ui/textarea.js';
+import { formatPlainDate } from '../../lib/plain-date.js';
+const currencySymbol = (currency, locale) => new Intl.NumberFormat(locale, { style: 'currency', currency }).formatToParts(0).find((part) => part.type === 'currency')
+    ?.value ?? currency;
+function shown(kind, value, currency, locale) {
+    if (kind === 'date')
+        return formatPlainDate(value, { dateStyle: 'medium' }, locale);
+    const number = Number(value);
+    if (value.trim() === '' || !Number.isFinite(number))
+        return value;
+    if (kind === 'money')
+        return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(number);
+    if (kind === 'number')
+        return new Intl.NumberFormat(locale).format(number);
+    return value;
+}
+/** One text, number, money or date field of a FillInQueue record. */
+export function FillInInput({ label, kind, value, onChange, suggestion, currency = 'USD', locale, placeholder, className, }) {
+    const id = useId();
+    const control = (() => {
+        switch (kind) {
+            case 'date':
+                return _jsx(DateField, { id: id, value: value, onChange: onChange, clearable: true, locale: locale });
+            case 'longText':
+                return _jsx(Textarea, { id: id, value: value, placeholder: placeholder, onChange: (event) => onChange(event.target.value) });
+            case 'money':
+                return (_jsxs(InputGroup, { children: [_jsx(InputGroupAddon, { children: _jsx(InputGroupText, { children: currencySymbol(currency, locale) }) }), _jsx(InputGroupInput, { id: id, inputMode: "decimal", value: value, placeholder: placeholder, onChange: (event) => onChange(event.target.value) })] }));
+            case 'number':
+                return (_jsx(Input, { id: id, type: "number", inputMode: "decimal", value: value, placeholder: placeholder, onChange: (event) => onChange(event.target.value) }));
+            default:
+                return _jsx(Input, { id: id, value: value, placeholder: placeholder, onChange: (event) => onChange(event.target.value) });
+        }
+    })();
+    return (_jsxs("div", { "data-slot": "fill-in-input", className: cn('flex flex-col gap-2', className), children: [_jsx("label", { htmlFor: id, className: "type-label", children: label }), control, suggestion !== undefined && suggestion.value !== '' && (_jsx(SuggestionButton, { text: shown(kind, suggestion.value, currency, locale), note: suggestion.note, used: value === suggestion.value, onUse: () => onChange(suggestion.value) }))] }));
+}
+/** One field of a FillInQueue record picked from a long list. */
+export function FillInSelect({ label, choices, value, onChange, suggestion, placeholder = 'Pick one', className, }) {
+    const id = useId();
+    const keyOf = (v) => String(v);
+    const byKey = new Map(choices.map((choice) => [keyOf(choice.value), choice]));
+    const suggested = suggestion ? byKey.get(keyOf(suggestion.value)) : undefined;
+    return (_jsxs("div", { "data-slot": "fill-in-select", className: cn('flex flex-col gap-2', className), children: [_jsx("label", { htmlFor: id, className: "type-label", children: label }), _jsxs(Select, { value: value === null || value === undefined ? null : keyOf(value), onValueChange: (next) => onChange(next === null ? null : (byKey.get(String(next))?.value ?? null)), children: [_jsx(SelectTrigger, { id: id, className: "w-full", children: _jsx(SelectValue, { placeholder: placeholder, children: (key) => (key === null ? placeholder : (byKey.get(key)?.label ?? key)) }) }), _jsx(SelectContent, { children: choices.map((choice) => (_jsx(SelectItem, { value: keyOf(choice.value), children: choice.label }, keyOf(choice.value)))) })] }), suggested !== undefined && (_jsx(SuggestionButton, { text: suggested.label, note: suggestion?.note, used: value !== null && value !== undefined && keyOf(value) === keyOf(suggested.value), onUse: () => onChange(suggested.value) }))] }));
+}
+function SuggestionButton({ text, note, used, onUse }) {
+    return (_jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [_jsxs(Button, { type: "button", size: "sm", variant: "outline", disabled: used, onClick: onUse, "data-slot": "fill-in-suggestion", className: "border-dashed border-info-text", children: ["Use ", text] }), note !== undefined && note !== null && _jsxs("span", { className: "type-caption text-muted-foreground", children: ["(", note, ")"] })] }));
+}
+const isNumeric = (kind) => kind === 'number' || kind === 'money';
+const toText = (value) => (value === null || value === undefined ? '' : String(value));
+/** The row a field's kind calls for: FillInChoice, FillInSelect or FillInInput. */
+export function FillInField({ field, value, onChange, shortcut, currency, locale, className }) {
+    const { kind, label, choices = [], suggestion } = field;
+    // A number's text as typed ("1." on the way to "1.5"), kept while it
+    // still reads as the draft's value; replaced when the draft changes.
+    const [text, setText] = useState(() => toText(value));
+    const keeps = value === null || value === undefined
+        ? text.trim() === '' || !Number.isFinite(Number(text))
+        : text.trim() !== '' && Number(text) === value;
+    if (isNumeric(kind) && !keeps)
+        setText(toText(value));
+    if (kind === 'choice' || kind === 'reference') {
+        const pick = (next) => onChange(next);
+        const current = value === undefined ? null : value;
+        if (choices.length <= 9) {
+            return (_jsx(FillInChoice, { label: label, choices: choices, value: current, onChange: pick, suggestion: suggestion, shortcut: shortcut, className: className }));
+        }
+        return (_jsx(FillInSelect, { label: label, choices: choices, value: current, onChange: pick, suggestion: suggestion, className: className }));
+    }
+    const numeric = isNumeric(kind);
+    return (_jsx(FillInInput, { label: label, kind: kind, value: numeric ? text : toText(value), onChange: (next) => {
+            if (!numeric)
+                return onChange(next === '' ? null : next);
+            setText(next);
+            const number = Number(next);
+            onChange(next.trim() === '' || !Number.isFinite(number) ? null : number);
+        }, suggestion: suggestion === undefined ? undefined : { value: String(suggestion.value), note: suggestion.note }, currency: currency, locale: locale, className: className }));
+}

package/dist/components/app/fill-in-queue.d.ts

@@ -1,5 +1,6 @@
 import { type ReactNode } from 'react';
 import type { AppError } from '../../api/contracts.js';
+import type { IconComponent } from './icon-component.js';
 export interface FillInQueueProgress {
     /** Records filled so far. */
     done: number;
@@ -8,6 +9,13 @@ export interface FillInQueueProgress {
     /** The word after the count: "12 of 160 <label>". Default "filled". */
     label?: string;
 }
+export interface FillInQueueGroup {
+    id: string;
+    label: string;
+    icon?: IconComponent;
+    /** This group's own count, said beside its name on its records. */
+    progress?: Omit<FillInQueueProgress, 'label'>;
+}
 export interface FillInQueueProps<T> {
     /** The records still missing something, in order. */
     items: readonly T[];
@@ -22,6 +30,10 @@ export interface FillInQueueProps<T> {
     onSkip?: (item: T) => void;
     /** A bar and "12 of 160 filled" at the top. The app counts. */
     progress?: FillInQueueProgress;
+    /** Where records come from: named above each record's heading. */
+    groups?: readonly FillInQueueGroup[];
+    /** The id of the record's group in `groups`. */
+    getGroup?: (item: T) => string;
     /** Default "Save and next". */
     saveLabel?: string;
     /** Default "Skip". */
@@ -38,7 +50,7 @@ export interface FillInQueueProps<T> {
     onIndexChange?: (index: number, item: T) => void;
     className?: string;
 }
-export declare function FillInQueue<T>({ items, getKey, renderItem, onSave, canSave, onSkip, progress, saveLabel, skipLabel, loading, error, onRetry, empty, index: indexProp, onIndexChange, className, }: FillInQueueProps<T>): import("react").JSX.Element;
+export declare function FillInQueue<T>({ items, getKey, renderItem, onSave, canSave, onSkip, progress, groups, getGroup, saveLabel, skipLabel, loading, error, onRetry, empty, index: indexProp, onIndexChange, className, }: FillInQueueProps<T>): import("react").JSX.Element;
 export interface FillInChoiceProps<V extends string | number> {
     /** Names the row of choices. */
     label: string;

package/dist/components/app/fill-in-queue.js

@@ -21,6 +21,11 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // - Saving: the button shows it's pending; a refusal keeps the record and
 //   says why under the buttons, not in a toast.
 // - Progress: the app counts (`progress`): a bar and "12 of 160 filled".
+// - Groups: records from several sources (a module, a list) name theirs
+//   above the heading with `groups` and `getGroup`: its icon and label,
+//   and, when the group has its own `progress`, "3 of 12 filled" beside
+//   it. With more than one group counted, each one's count is listed
+//   under the bar.
 // - States: `loading` (skeletons), `error` (ErrorState, with `onRetry`),
 //   and an empty queue (`empty`, default "Nothing left to fill in").
 //
@@ -68,7 +73,7 @@ function ownsEnter(element) {
         return true;
     return (element.closest('button, a[href], summary, [role=button], [role=link], [role=combobox], [role=listbox], [role=option], [role=menu], [role=menuitem], [role=menuitemradio], [role=menuitemcheckbox], [role=switch], [role=checkbox], [role=radio], [role=tab]') !== null);
 }
-export function FillInQueue({ items, getKey, renderItem, onSave, canSave = true, onSkip, progress, saveLabel = 'Save and next', skipLabel = 'Skip', loading = false, error, onRetry, empty = 'Nothing left to fill in', index: indexProp, onIndexChange, className, }) {
+export function FillInQueue({ items, getKey, renderItem, onSave, canSave = true, onSkip, progress, groups, getGroup, saveLabel = 'Save and next', skipLabel = 'Skip', loading = false, error, onRetry, empty = 'Nothing left to fill in', index: indexProp, onIndexChange, className, }) {
     const keys = items.map(getKey);
     const [held, setHeld] = useState(() => ({
         key: indexProp !== undefined ? (keys[indexProp] ?? null) : null,
@@ -181,7 +186,8 @@ export function FillInQueue({ items, getKey, renderItem, onSave, canSave = true,
             }
         }
     };
-    const progressBar = progress && _jsx(ProgressLine, { progress: progress });
+    const counted = groups?.filter((group) => group.progress !== undefined) ?? [];
+    const progressBar = (progress || counted.length > 1) && (_jsxs("div", { className: "flex flex-col gap-1.5", children: [progress && _jsx(ProgressLine, { progress: progress }), counted.length > 1 && (_jsx("ul", { className: "flex flex-wrap gap-x-4 gap-y-1 type-caption text-muted-foreground tabular-nums", "data-slot": "fill-in-queue-groups", children: counted.map((group) => (_jsxs("li", { children: [group.label, " ", group.progress?.done, " of ", group.progress?.total] }, group.id))) }))] }));
     if (error !== undefined && error !== null && error !== false) {
         return (_jsx("div", { "data-slot": "fill-in-queue", "data-state": "error", className: className, children: isAppError(error) ? (_jsx(ErrorState, { error: error, onRetry: onRetry })) : (_jsxs(Empty, { "data-state": "error", children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyTitle, { children: "Something went wrong" }), _jsx(EmptyDescription, { children: error })] }), onRetry && (_jsx(Button, { size: "sm", variant: "outline", onClick: onRetry, children: "Try again" }))] })) }));
     }
@@ -192,7 +198,13 @@ export function FillInQueue({ items, getKey, renderItem, onSave, canSave = true,
         return (_jsxs("div", { ref: rootRef, tabIndex: -1, "data-slot": "fill-in-queue", "data-state": "empty", className: cn('flex flex-col gap-6 outline-none', className), children: [progressBar, _jsx(Empty, { children: _jsx(EmptyHeader, { children: _jsx(EmptyTitle, { children: empty }) }) })] }));
     }
     const position = `Record ${index + 1} of ${items.length}`;
-    return (_jsx(ShortcutContext.Provider, { value: register, children: _jsxs("div", { ref: rootRef, tabIndex: -1, "data-slot": "fill-in-queue", "data-state": "success", onKeyDown: onKeyDown, className: cn('flex flex-col gap-6 outline-none', className), children: [_jsxs("div", { className: "flex flex-col gap-2", children: [progressBar, _jsx("p", { className: "type-caption text-muted-foreground tabular-nums", "data-slot": "fill-in-queue-position", children: position })] }), _jsxs("div", { className: "mx-auto flex w-full max-w-[40rem] flex-col gap-6", children: [_jsx("div", { ref: recordRef, role: "group", "aria-label": position, tabIndex: -1, "data-slot": "fill-in-queue-record", className: "flex flex-col gap-6 rounded-lg outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50", children: renderItem(current) }, currentKey ?? undefined), _jsxs("div", { className: "flex flex-col gap-2 border-t border-border pt-4", children: [_jsxs("div", { className: "flex items-center justify-between gap-3", children: [_jsx(Button, { variant: "ghost", onClick: skip, disabled: saving, children: skipLabel }), _jsxs(Button, { onClick: () => void save(), disabled: !savable || saving, "aria-busy": saving || undefined, children: [saving && _jsx(Spinner, { "aria-hidden": "true", role: "presentation", "aria-label": undefined, "data-icon": "inline-start" }), saveLabel] })] }), saveError !== null && (_jsx("p", { role: "alert", className: "text-end type-caption text-destructive-text", children: saveError }))] })] })] }) }));
+    const groupId = getGroup?.(current);
+    const group = groupId === undefined ? undefined : groups?.find((g) => g.id === groupId);
+    return (_jsx(ShortcutContext.Provider, { value: register, children: _jsxs("div", { ref: rootRef, tabIndex: -1, "data-slot": "fill-in-queue", "data-state": "success", onKeyDown: onKeyDown, className: cn('flex flex-col gap-6 outline-none', className), children: [_jsxs("div", { className: "flex flex-col gap-2", children: [progressBar, _jsx("p", { className: "type-caption text-muted-foreground tabular-nums", "data-slot": "fill-in-queue-position", children: position })] }), _jsxs("div", { className: "mx-auto flex w-full max-w-[40rem] flex-col gap-6", children: [_jsxs("div", { ref: recordRef, role: "group", "aria-label": position, tabIndex: -1, "data-slot": "fill-in-queue-record", className: "flex flex-col gap-6 rounded-lg outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50", children: [group && _jsx(GroupLine, { group: group, label: progress?.label }), renderItem(current)] }, currentKey ?? undefined), _jsxs("div", { className: "flex flex-col gap-2 border-t border-border pt-4", children: [_jsxs("div", { className: "flex items-center justify-between gap-3", children: [_jsx(Button, { variant: "ghost", onClick: skip, disabled: saving, children: skipLabel }), _jsxs(Button, { onClick: () => void save(), disabled: !savable || saving, "aria-busy": saving || undefined, children: [saving && _jsx(Spinner, { "aria-hidden": "true", role: "presentation", "aria-label": undefined, "data-icon": "inline-start" }), saveLabel] })] }), saveError !== null && (_jsx("p", { role: "alert", className: "text-end type-caption text-destructive-text", children: saveError }))] })] })] }) }));
+}
+function GroupLine({ group, label = 'filled' }) {
+    const Icon = group.icon;
+    return (_jsxs("p", { className: "-mb-4 flex items-center gap-1.5 type-caption text-muted-foreground", "data-slot": "fill-in-queue-group", children: [Icon && _jsx(Icon, { className: "size-4", "aria-hidden": "true" }), _jsx("span", { className: "font-medium", children: group.label }), group.progress && (_jsxs("span", { className: "tabular-nums", children: ["\u00B7 ", group.progress.done, " of ", group.progress.total, " ", label] }))] }));
 }
 function ProgressLine({ progress }) {
     const { done, total, label = 'filled' } = progress;

package/dist/index.d.ts

@@ -3,7 +3,8 @@ export type { IconComponent } from './components/app/icon-component.js';
 export { Board, type BoardColumn, type BoardMoveTarget, type BoardProps } from './components/app/board.js';
 export { SpinWheel, type SpinWheelProps } from './components/app/spin-wheel.js';
 export { pickSpinWheelIndex, type SpinWheelItem } from './components/app/spin-wheel-pick.js';
-export { FillInChoice, FillInQueue, type FillInChoiceProps, type FillInQueueProgress, type FillInQueueProps, } from './components/app/fill-in-queue.js';
+export { FillInChoice, FillInQueue, type FillInChoiceProps, type FillInQueueGroup, type FillInQueueProgress, type FillInQueueProps, } from './components/app/fill-in-queue.js';
+export { FillInField, FillInInput, FillInSelect, type FillInFieldKind, type FillInFieldProps, type FillInFieldSpec, type FillInInputKind, type FillInInputProps, type FillInSelectProps, type FillInSuggestion, type FillInValue, } from './components/app/fill-in-field.js';
 export { Artwork, ArtworkTag, ArtworkToggle, type ArtworkAspect, type ArtworkProps, type ArtworkToggleProps, } from './components/app/artwork.js';
 export { CountLink, type CountLinkProps } from './components/app/count-link.js';
 export { DataTable, type DataTableCardLayout, type DataTableGrouping, type DataTableProps, type DataTableTotals, type DataTableWidth, type SortingState, } from './components/app/data-table.js';

package/dist/index.js

@@ -8,6 +8,7 @@ export { Board } from './components/app/board.js';
 export { SpinWheel } from './components/app/spin-wheel.js';
 export { pickSpinWheelIndex } from './components/app/spin-wheel-pick.js';
 export { FillInChoice, FillInQueue, } from './components/app/fill-in-queue.js';
+export { FillInField, FillInInput, FillInSelect, } from './components/app/fill-in-field.js';
 export { Artwork, ArtworkTag, ArtworkToggle, } from './components/app/artwork.js';
 export { CountLink } from './components/app/count-link.js';
 export { DataTable, } from './components/app/data-table.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.52.0",
+  "version": "4.53.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": {