@tristan2828/ui-foundation 4.51.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/emoji-field-data.d.ts

@@ -0,0 +1,11 @@
+export type EmojiEntry = {
+    emoji: string;
+    name: string;
+    keywords?: string;
+};
+export type EmojiGroup = {
+    label: string;
+    emojis: EmojiEntry[];
+};
+export declare const EMOJI_GROUPS: EmojiGroup[];
+export declare function filterEmojiGroups(query: string): EmojiGroup[];

package/dist/components/app/emoji-field-data.js

@@ -0,0 +1,157 @@
+export const EMOJI_GROUPS = [
+    {
+        label: 'Morning and sleep',
+        emojis: [
+            { emoji: '☀️', name: 'Sun', keywords: 'morning day bright' },
+            { emoji: '🌅', name: 'Sunrise', keywords: 'morning dawn' },
+            { emoji: '⏰', name: 'Alarm clock', keywords: 'wake time' },
+            { emoji: '🌙', name: 'Moon', keywords: 'night evening' },
+            { emoji: '😴', name: 'Sleeping face', keywords: 'sleep bed rest' },
+            { emoji: '🛏️', name: 'Bed', keywords: 'sleep bedroom' },
+            { emoji: '🌄', name: 'Sunrise over mountains', keywords: 'morning' },
+            { emoji: '🌃', name: 'Night with stars', keywords: 'evening' },
+        ],
+    },
+    {
+        label: 'Body and health',
+        emojis: [
+            { emoji: '🧘', name: 'Person in lotus position', keywords: 'yoga meditate breathe calm' },
+            { emoji: '🏃', name: 'Person running', keywords: 'run exercise workout cardio' },
+            { emoji: '🏋️', name: 'Person lifting weights', keywords: 'gym strength workout' },
+            { emoji: '🚴', name: 'Person biking', keywords: 'cycling exercise' },
+            { emoji: '🏊', name: 'Person swimming', keywords: 'pool exercise' },
+            { emoji: '🤸', name: 'Person cartwheeling', keywords: 'stretch gymnastics' },
+            { emoji: '💪', name: 'Flexed biceps', keywords: 'strength muscle' },
+            { emoji: '🦷', name: 'Tooth', keywords: 'dentist brush teeth' },
+            { emoji: '🪥', name: 'Toothbrush', keywords: 'brush teeth' },
+            { emoji: '💊', name: 'Pill', keywords: 'medicine vitamins' },
+            { emoji: '🩺', name: 'Stethoscope', keywords: 'doctor health' },
+            { emoji: '❤️', name: 'Red heart', keywords: 'love health' },
+            { emoji: '🫁', name: 'Lungs', keywords: 'breathe breath' },
+            { emoji: '🧠', name: 'Brain', keywords: 'mind think' },
+        ],
+    },
+    {
+        label: 'Self-care',
+        emojis: [
+            { emoji: '🚿', name: 'Shower', keywords: 'wash clean' },
+            { emoji: '🛁', name: 'Bathtub', keywords: 'bath wash' },
+            { emoji: '🧼', name: 'Soap', keywords: 'wash clean hands' },
+            { emoji: '🧴', name: 'Lotion bottle', keywords: 'skincare moisturizer sunscreen' },
+            { emoji: '🪒', name: 'Razor', keywords: 'shave' },
+            { emoji: '💇', name: 'Person getting haircut', keywords: 'hair' },
+            { emoji: '🧖', name: 'Person in steamy room', keywords: 'sauna spa relax' },
+            { emoji: '🕯️', name: 'Candle', keywords: 'calm relax' },
+        ],
+    },
+    {
+        label: 'Food and drink',
+        emojis: [
+            { emoji: '🍳', name: 'Cooking', keywords: 'breakfast egg pan' },
+            { emoji: '🥣', name: 'Bowl with spoon', keywords: 'cereal oatmeal breakfast' },
+            { emoji: '🥗', name: 'Green salad', keywords: 'lunch healthy' },
+            { emoji: '🍽️', name: 'Plate with cutlery', keywords: 'meal dinner eat' },
+            { emoji: '🍎', name: 'Red apple', keywords: 'fruit snack' },
+            { emoji: '🥑', name: 'Avocado', keywords: 'food' },
+            { emoji: '☕', name: 'Hot beverage', keywords: 'coffee tea' },
+            { emoji: '🍵', name: 'Teacup', keywords: 'tea' },
+            { emoji: '💧', name: 'Droplet', keywords: 'water drink hydrate' },
+            { emoji: '🥤', name: 'Cup with straw', keywords: 'drink' },
+            { emoji: '🛒', name: 'Shopping cart', keywords: 'groceries store' },
+        ],
+    },
+    {
+        label: 'Home and chores',
+        emojis: [
+            { emoji: '🏠', name: 'House', keywords: 'home' },
+            { emoji: '🧹', name: 'Broom', keywords: 'sweep clean chores' },
+            { emoji: '🧽', name: 'Sponge', keywords: 'scrub clean dishes' },
+            { emoji: '🧺', name: 'Basket', keywords: 'laundry' },
+            { emoji: '👕', name: 'T-shirt', keywords: 'laundry clothes' },
+            { emoji: '🗑️', name: 'Wastebasket', keywords: 'trash garbage' },
+            { emoji: '🛠️', name: 'Hammer and wrench', keywords: 'repair fix tools' },
+            { emoji: '🔧', name: 'Wrench', keywords: 'repair fix' },
+            { emoji: '🔑', name: 'Key', keywords: 'lock keys' },
+            { emoji: '🪴', name: 'Potted plant', keywords: 'garden water plants' },
+            { emoji: '🌱', name: 'Seedling', keywords: 'garden grow plant' },
+            { emoji: '🌿', name: 'Herb', keywords: 'garden plant' },
+            { emoji: '🐕', name: 'Dog', keywords: 'pet walk' },
+            { emoji: '🐈', name: 'Cat', keywords: 'pet' },
+        ],
+    },
+    {
+        label: 'Work and learning',
+        emojis: [
+            { emoji: '💻', name: 'Laptop', keywords: 'computer work code' },
+            { emoji: '📧', name: 'Email', keywords: 'mail inbox' },
+            { emoji: '📅', name: 'Calendar', keywords: 'date plan schedule' },
+            { emoji: '📝', name: 'Memo', keywords: 'notes write journal' },
+            { emoji: '✅', name: 'Check mark', keywords: 'done task todo' },
+            { emoji: '📋', name: 'Clipboard', keywords: 'list checklist' },
+            { emoji: '📚', name: 'Books', keywords: 'read study learn' },
+            { emoji: '📖', name: 'Open book', keywords: 'read' },
+            { emoji: '🎓', name: 'Graduation cap', keywords: 'study school learn' },
+            { emoji: '✏️', name: 'Pencil', keywords: 'write draw' },
+            { emoji: '🎯', name: 'Bullseye', keywords: 'goal focus target' },
+            { emoji: '💡', name: 'Light bulb', keywords: 'idea' },
+            { emoji: '🧾', name: 'Receipt', keywords: 'bills budget' },
+            { emoji: '💰', name: 'Money bag', keywords: 'finance budget savings' },
+        ],
+    },
+    {
+        label: 'Play and music',
+        emojis: [
+            { emoji: '🎵', name: 'Musical note', keywords: 'music song' },
+            { emoji: '🎧', name: 'Headphones', keywords: 'music podcast listen' },
+            { emoji: '🎸', name: 'Guitar', keywords: 'music practice' },
+            { emoji: '🎹', name: 'Piano keyboard', keywords: 'music practice' },
+            { emoji: '🎨', name: 'Artist palette', keywords: 'paint draw art' },
+            { emoji: '🎮', name: 'Video game', keywords: 'play controller' },
+            { emoji: '📺', name: 'Television', keywords: 'tv watch show' },
+            { emoji: '🎬', name: 'Clapper board', keywords: 'movie film' },
+            { emoji: '📷', name: 'Camera', keywords: 'photo picture' },
+            { emoji: '🧩', name: 'Puzzle piece', keywords: 'game' },
+        ],
+    },
+    {
+        label: 'Outside and travel',
+        emojis: [
+            { emoji: '🚶', name: 'Person walking', keywords: 'walk steps' },
+            { emoji: '🥾', name: 'Hiking boot', keywords: 'hike trail' },
+            { emoji: '🌳', name: 'Tree', keywords: 'park nature' },
+            { emoji: '⛰️', name: 'Mountain', keywords: 'hike' },
+            { emoji: '🌧️', name: 'Rain cloud', keywords: 'weather' },
+            { emoji: '❄️', name: 'Snowflake', keywords: 'winter cold' },
+            { emoji: '🚗', name: 'Car', keywords: 'drive commute' },
+            { emoji: '🚌', name: 'Bus', keywords: 'commute transit' },
+            { emoji: '✈️', name: 'Airplane', keywords: 'travel flight trip' },
+            { emoji: '🧳', name: 'Luggage', keywords: 'travel pack trip' },
+        ],
+    },
+    {
+        label: 'Symbols',
+        emojis: [
+            { emoji: '⭐', name: 'Star', keywords: 'favorite' },
+            { emoji: '✨', name: 'Sparkles', keywords: 'new clean' },
+            { emoji: '🔥', name: 'Fire', keywords: 'streak hot' },
+            { emoji: '🎉', name: 'Party popper', keywords: 'celebrate' },
+            { emoji: '🏆', name: 'Trophy', keywords: 'win goal' },
+            { emoji: '🔔', name: 'Bell', keywords: 'reminder notify' },
+            { emoji: '⏱️', name: 'Stopwatch', keywords: 'timer time' },
+            { emoji: '⏳', name: 'Hourglass', keywords: 'wait time' },
+            { emoji: '🔄', name: 'Counterclockwise arrows', keywords: 'repeat again refresh' },
+            { emoji: '🙏', name: 'Folded hands', keywords: 'gratitude thanks pray' },
+            { emoji: '😊', name: 'Smiling face', keywords: 'happy' },
+            { emoji: '🌈', name: 'Rainbow', keywords: 'colour' },
+        ],
+    },
+];
+export function filterEmojiGroups(query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return EMOJI_GROUPS;
+    return EMOJI_GROUPS.map((group) => ({
+        ...group,
+        emojis: group.emojis.filter((e) => `${e.name} ${e.keywords ?? ''}`.toLowerCase().includes(q)),
+    })).filter((group) => group.emojis.length > 0);
+}

package/dist/components/app/emoji-field.d.ts

@@ -0,0 +1,23 @@
+export type EmojiFieldProps = {
+    /** The trigger button's id, for the field's `<FieldLabel htmlFor>`. */
+    id?: string;
+    /** The emoji, or `''` for none. */
+    value: string;
+    /** Called with the picked emoji, or `''` when cleared. */
+    onChange: (value: string) => void;
+    /** What the button says with none picked. Defaults to "Pick an emoji". */
+    placeholder?: string;
+    /** Offer Clear in the popup, for an optional field. */
+    clearable?: boolean;
+    /** The value was refused: `aria-invalid` on the button. */
+    invalid?: boolean;
+    /** Saving: the button shows the emoji but won't open. */
+    readOnly?: boolean;
+    /** Open on mount (for stories and editing in place). */
+    defaultOpen?: boolean;
+    className?: string;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    'aria-describedby'?: string;
+};
+export declare function EmojiField({ id, value, onChange, placeholder, clearable, invalid, readOnly, defaultOpen, className, ...aria }: EmojiFieldProps): import("react").JSX.Element;

package/dist/components/app/emoji-field.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+// One emoji on a form: a routine's mark, a list's icon. The value is the
+// emoji itself, or `''` for none. A button showing the choice, opening a
+// Popover with a search box and a curated set of emoji in groups (not the
+// whole of Unicode: `emoji-field-data.ts`). Like DateField it is one
+// control for a react-hook-form `Controller`; `clearable` adds Clear.
+import { useState } from 'react';
+import { SmilePlus } from 'lucide-react';
+import { cn } from 'cn';
+import { Button } from '../ui/button.js';
+import { Input } from '../ui/input.js';
+import { Popover, PopoverContent, PopoverTrigger } from '../ui/popover.js';
+import { filterEmojiGroups } from './emoji-field-data.js';
+export function EmojiField({ id, value, onChange, placeholder = 'Pick an emoji', clearable = false, invalid = false, readOnly = false, defaultOpen = false, className, ...aria }) {
+    const [open, setOpen] = useState(defaultOpen && !readOnly);
+    const [query, setQuery] = useState('');
+    const groups = filterEmojiGroups(query);
+    const changeOpen = (next) => {
+        if (next && readOnly)
+            return;
+        setOpen(next);
+        if (!next)
+            setQuery('');
+    };
+    const pick = (next) => {
+        onChange(next);
+        changeOpen(false);
+    };
+    return (_jsxs(Popover, { open: open, onOpenChange: changeOpen, children: [_jsx(PopoverTrigger, { render: _jsx(Button, { id: id, type: "button", variant: "outline", "aria-invalid": invalid || undefined, "aria-readonly": readOnly || undefined, className: cn('w-full justify-start font-normal', !value && 'text-muted-foreground', className), ...aria }), children: value ? (_jsx("span", { className: "text-base leading-none", children: value })) : (_jsxs(_Fragment, { children: [_jsx(SmilePlus, { "aria-hidden": "true", className: "size-4" }), placeholder] })) }), _jsxs(PopoverContent, { className: "w-72 gap-2 p-2", align: "start", "data-slot": "emoji-field-popup", "aria-label": "Emoji", children: [_jsx(Input, { type: "search", autoComplete: "off", "aria-label": "Search emoji", placeholder: "Search", value: query, onChange: (event) => setQuery(event.target.value) }), _jsx("div", { className: "max-h-64 overflow-y-auto", children: groups.length === 0 ? (_jsxs("p", { className: "p-2 text-sm text-muted-foreground", children: ["No emoji match \"", query.trim(), "\"."] })) : (groups.map((group) => (_jsxs("section", { "aria-label": group.label, className: "mb-2 last:mb-0", children: [_jsx("h3", { className: "px-1 py-1 text-xs font-medium text-muted-foreground", children: group.label }), _jsx("div", { className: "grid grid-cols-7 gap-0.5", children: group.emojis.map((entry) => (_jsx("button", { type: "button", "aria-label": entry.name, title: entry.name, "aria-pressed": entry.emoji === value, onClick: () => pick(entry.emoji), className: "flex size-8 items-center justify-center rounded-md text-xl leading-none outline-none hover:bg-muted focus-visible:ring-3 focus-visible:ring-ring/50 aria-pressed:bg-accent", children: entry.emoji }, entry.emoji))) })] }, group.label)))) }), clearable && value && (_jsx("div", { className: "border-t border-border pt-2", children: _jsx(Button, { type: "button", variant: "ghost", size: "sm", className: "w-full", onClick: () => pick(''), children: "Clear" }) }))] })] }));
+}

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';
@@ -41,6 +42,7 @@ export { MultiLineChart, type ChartSeries, type ChartTone, type MultiLineChartPr
 export { StepBar, type StepBarProps } from './components/app/step-bar.js';
 export { RatingStar, type RatingStarProps, type RatingStarValue } from './components/app/rating-star.js';
 export { DateField, type DateFieldProps } from './components/app/date-field.js';
+export { EmojiField, type EmojiFieldProps } from './components/app/emoji-field.js';
 export { ImageField, type ImageFieldProps } from './components/app/image-field.js';
 export { DEFAULT_IMAGE_TYPES, type ImageUpload, type ImageUploadResult } from './lib/image-file.js';
 export { formatPlainDate, type PlainDate } from './lib/plain-date.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';
@@ -44,6 +45,7 @@ export { MultiLineChart, } from './components/app/multi-line-chart.js';
 export { StepBar } from './components/app/step-bar.js';
 export { RatingStar } from './components/app/rating-star.js';
 export { DateField } from './components/app/date-field.js';
+export { EmojiField } from './components/app/emoji-field.js';
 export { ImageField } from './components/app/image-field.js';
 export { DEFAULT_IMAGE_TYPES } from './lib/image-file.js';
 export { formatPlainDate } from './lib/plain-date.js';

package/package.json

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