@tristan2828/ui-foundation 3.4.0 → 3.6.0

package/README.md

@@ -18,8 +18,8 @@ than installing this by hand:
 
 | Import | What |
 |---|---|
-| `@tristan2828/ui-foundation` | `AppShell`, `DataTable`, `EntityForm`, `ErrorState`, `MultiChoice`, `PasswordInput`, `RouteErrorBoundary`, `FoundationProviders`, `LoginRoute`, `RegisterRoute`, `useAuth`, `useTableUrlState`, `useDebouncedValue`, `createQueryClient`, `cn`; types `Page`, `AppError`, `QuerySpec` |
-| `@tristan2828/ui-foundation/ui/<name>` | shadcn primitives: badge, button, calendar, card, combobox, dialog, empty, field, input, input-group, label, popover, select, separator, sheet, sidebar, skeleton, sonner, spinner, switch, table, textarea, tooltip |
+| `@tristan2828/ui-foundation` | `AppShell`, `DataTable`, `EntityForm`, `ErrorState`, `MultiChoice`, `MultiReference`, `ListEditor`, `PasswordInput`, `RouteErrorBoundary`, `FoundationProviders`, `LoginRoute`, `RegisterRoute`, `useAuth`, `useTableUrlState`, `useDebouncedValue`, `createQueryClient`, `cn`; types `Page`, `AppError`, `QuerySpec` |
+| `@tristan2828/ui-foundation/ui/<name>` | shadcn primitives: badge, button, calendar, card, checkbox, combobox, dialog, empty, field, input, input-group, label, popover, select, separator, sheet, sidebar, skeleton, sonner, spinner, switch, table, textarea, tooltip |
 | `@tristan2828/ui-foundation/gateway` | `safeFetch`, `toAppError`, `networkError` — for an app's `src/api/gateway/` only |
 | `@tristan2828/ui-foundation/mocks` | MSW: `authHandlers`, `resetMockAuth`, `getMockCurrentUser`, `MOCK_USER`, `exposeMswForE2E` |
 | `@tristan2828/ui-foundation/testing` | Playwright: `defineA11ySuite`, `defineMockModeBannerSuite`, `forceMswOverride`, `forceLoggedOut`, `waitForMswReady` |

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

@@ -85,7 +85,25 @@ is a filled-in example while the Widgets demo is still here).
    `<MultiChoice>` control from the foundation on the
    form and as a toolbar filter via `useTableUrlState`'s multi filters,
    badges in the table, and a `filters` array the gateway sends as a
-   repeated parameter):
+   repeated parameter — and a `multi reference` copies Extra Categories:
+   the `<MultiReference>` control on the form and as a toolbar filter, an
+   array of ids on the wire, a repeated any-of list filter, and names from
+   a **lookup by id** on the referenced entity
+   (`GET /categories?ids=1&ids=3`, `getCategoriesByIds`,
+   `useCategoriesByIdsQuery`). Add that `ids` parameter to the referenced
+   entity's list endpoint if it lacks one. Never name a picked id from
+   search results alone: a saved pick the current search doesn't return
+   would show without a name. The table looks up every id on its page in
+   one request; the backend rejects an unknown id as a 422 on the field,
+   never a foreign-key 500 — and each **sub-records** list copies
+   Checklist: an array of item objects on the wire, read and written
+   whole and in order (no item ids), a child table with a `position`
+   column, react-hook-form's `useFieldArray` feeding the foundation's
+   `<ListEditor>` inside a `FieldSet`/`FieldLegend` on the form, each row's
+   controls named by position ("Item 2 text"), a per-item `FieldError`
+   (a server 422 at `["body", "checklist", 2, "text"]` arrives as
+   `fieldErrors["checklist.2.text"]` and binds to that row), and a summary
+   in the table, never the items):
    - `src/routes/widgets/use-widgets.ts`, `use-categories.ts` →
      `src/routes/<entity>/use-<entity>.ts` (TanStack Query hooks over the
      new gateway module)

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

@@ -30,7 +30,10 @@ One or two sentences: what one record is, and who uses the screens.
     order; see the note below if it is *optional*), `multi choice` (list
     the options; any number can be picked —
     chips on the form, badges in the table, an any-of filter), `reference`
-    (to another entity — name it; a searchable combobox).
+    (to another entity — name it; a searchable combobox), `multi reference`
+    (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`).
   - *Close variants* (built by a small, stated change to the nearest
     pattern): `integer` (from decimal), `url` (from email — a format
     check), `date` (from date-time — no time part).
@@ -51,6 +54,28 @@ One or two sentences: what one record is, and who uses the screens.
 - **Filter**: `search` (the text search box), `yes` (a filter control), or
   blank.
 
+## Sub-records
+
+Optional. A list of small items that belong to one record alone and are
+edited on its form, saved with it (a checklist, a set of links). One block
+per list; delete the section if there are none.
+
+### checklist — Checklist
+
+- Most items: 50.
+- In the table: a done-count (`2/6 done`), or blank if the list isn't
+  shown.
+
+| Field | Label | Type | Required | Options / rules |
+|---|---|---|---|---|
+| text | Text | text | yes | 1–300 chars, trimmed |
+| done | Done | yes/no | yes | default no |
+
+- Item fields use the same types as the main table (`text`, `url`,
+  `yes/no`… — not another sub-record or a reference). Items have no screen
+  of their own: they're added, edited, reordered and removed on the
+  record's form, and the order is kept.
+
 ## List screen
 
 - Default sort:

package/dist/api/gateway/errors.js

@@ -16,10 +16,7 @@ export function toAppError(status, body) {
         const detail = body?.detail ?? [];
         const fieldErrors = {};
         for (const issue of detail) {
-            // The field is the last *string* segment: integer segments index into
-            // an array field (["body", "tags", 0] is a bad tag), and a form binds
-            // errors by field name, never by position.
-            const field = String([...issue.loc].reverse().find((segment) => typeof segment === "string") ?? issue.loc[issue.loc.length - 1]);
+            const field = fieldKey(issue.loc);
             (fieldErrors[field] ??= []).push(issue.msg);
         }
         return { kind: "validation", message: "Validation failed", fieldErrors };
@@ -31,6 +28,22 @@ export function toAppError(status, body) {
         return { kind: "auth", message };
     return { kind: "server", message };
 }
+// The key a form binds a 422 to (react-hook-form's field path):
+// - ["body", "price"] → "price"
+// - ["body", "tags", 0] → "tags": an item of a list of values is the list's
+//   error, never a position.
+// - ["body", "checklist", 2, "text"] → "checklist.2.text": a field inside an
+//   item of a list of objects, so it lands on that row's input.
+// Anything else keeps the last string segment, as before nested paths
+// existed (["body", "address", "city"] → "city").
+function fieldKey(loc) {
+    const path = loc.slice(1); // drop "body" / "query"
+    const listIndex = path.findIndex((segment) => typeof segment === "number");
+    if (listIndex > 0 && path.slice(listIndex + 1).some((segment) => typeof segment === "string")) {
+        return path.join(".");
+    }
+    return String([...loc].reverse().find((segment) => typeof segment === "string") ?? loc[loc.length - 1]);
+}
 export function networkError() {
     return { kind: "network", message: "Network error — check your connection and try again." };
 }

package/dist/components/app/list-editor.d.ts

@@ -0,0 +1,25 @@
+import type { ReactNode } from 'react';
+export declare function ListEditor({ items, renderItem, onAdd, onRemove, onMove, itemName, addLabel, emptyText, max, 'aria-label': ariaLabel, }: {
+    /** One entry per item, with a stable key (useFieldArray's `fields`). */
+    items: readonly {
+        id: string;
+    }[];
+    /** The item's own fields, for the item at this index. */
+    renderItem: (index: number) => ReactNode;
+    onAdd: () => void;
+    onRemove: (index: number) => void;
+    onMove: (from: number, to: number) => void;
+    /**
+     * How the row buttons name an item for a screen reader, e.g.
+     * (i) => `item ${i + 1}` gives "Move item 2 up", "Remove item 2".
+     */
+    itemName: (index: number) => string;
+    /** The Add button's text, e.g. "Add item". */
+    addLabel: string;
+    /** Shown instead of the list when it's empty. */
+    emptyText?: string;
+    /** The most items allowed; Add is disabled once reached. */
+    max?: number;
+    /** Names the list (e.g. the field's label). */
+    'aria-label'?: string;
+}): import("react").JSX.Element;

package/dist/components/app/list-editor.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ArrowDownIcon, ArrowUpIcon, PlusIcon, Trash2Icon } from 'lucide-react';
+import { Button } from '../ui/button.js';
+export function ListEditor({ items, renderItem, onAdd, onRemove, onMove, itemName, addLabel, emptyText = 'Nothing added yet.', max, 'aria-label': ariaLabel, }) {
+    const atMax = max !== undefined && items.length >= max;
+    return (_jsxs("div", { className: "flex flex-col gap-2", children: [items.length === 0 ? (_jsx("p", { className: "type-caption text-muted-foreground", children: emptyText })) : (_jsx("ul", { "aria-label": ariaLabel, className: "flex flex-col gap-2", children: items.map((item, index) => {
+                    const name = itemName(index);
+                    return (_jsxs("li", { className: "flex items-start gap-1", children: [_jsx("div", { className: "flex min-w-0 flex-1 items-start gap-2", children: renderItem(index) }), _jsx(Button, { type: "button", variant: "ghost", size: "icon-sm", "aria-label": `Move ${name} up`, disabled: index === 0, onClick: () => onMove(index, index - 1), children: _jsx(ArrowUpIcon, {}) }), _jsx(Button, { type: "button", variant: "ghost", size: "icon-sm", "aria-label": `Move ${name} down`, disabled: index === items.length - 1, onClick: () => onMove(index, index + 1), children: _jsx(ArrowDownIcon, {}) }), _jsx(Button, { type: "button", variant: "ghost", size: "icon-sm", "aria-label": `Remove ${name}`, onClick: () => onRemove(index), children: _jsx(Trash2Icon, {}) })] }, item.id));
+                }) })), _jsx("div", { children: _jsxs(Button, { type: "button", variant: "outline", size: "sm", onClick: onAdd, disabled: atMax, children: [_jsx(PlusIcon, {}), addLabel] }) })] }));
+}

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

@@ -0,0 +1,27 @@
+import * as React from 'react';
+export declare function MultiReference<Id extends string | number>({ options, value, onValueChange, getLabel, onSearchChange, id, placeholder, emptyText, 'aria-label': ariaLabel, 'aria-invalid': ariaInvalid, className, }: {
+    /** The records the current search returned, in display order. */
+    options: readonly {
+        id: Id;
+        label: string;
+    }[];
+    /** The picked ids. */
+    value: Id[];
+    onValueChange: (value: Id[]) => void;
+    /**
+     * The name of any id: a picked one (from the app's lookup by ids) or an
+     * option. `undefined` while it's still loading.
+     */
+    getLabel: (id: Id) => string | undefined;
+    /** Called with the typed text; the app feeds it to its search query. */
+    onSearchChange: (search: string) => void;
+    /** Id for the text input, so a <FieldLabel htmlFor> labels it. */
+    id?: string;
+    placeholder?: string;
+    /** Shown in the dropdown when the search matches nothing. */
+    emptyText?: string;
+    /** For use without a visible label (e.g. a table toolbar filter). */
+    'aria-label'?: string;
+    'aria-invalid'?: boolean;
+    className?: string;
+}): React.JSX.Element;

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

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A multi-reference picker: links to several records of another entity,
+// shown as removable chips, with the rest found by typing. The one control
+// for every "multi reference" field (conventions/docs/entity-plan-template.md),
+// on a form (Widget Extra Categories) and as a table filter.
+//
+// MultiChoice's sibling, for values that are record ids rather than enum
+// strings. Two differences follow from that:
+// - A chip needs a *name* for an id the current search may not include
+//   (editing a saved record, a filter from a shared link). The app fetches
+//   names for exactly the picked ids (Widget: GET /categories?ids=...) and
+//   passes `getLabel`; this component never guesses one.
+// - Matching happens on the server: `onSearchChange` reports what was typed
+//   and `options` is whatever the app's search query returned, so nothing
+//   is filtered here (filter={null}).
+import * as React from 'react';
+import { Combobox, ComboboxChip, ComboboxChips, ComboboxChipsInput, ComboboxContent, ComboboxEmpty, ComboboxItem, ComboboxList, ComboboxValue, useComboboxAnchor, } from '../ui/combobox.js';
+/** Shown on a chip whose name hasn't loaded yet, instead of a bare id. */
+const PENDING_LABEL = '…';
+export function MultiReference({ options, value, onValueChange, getLabel, onSearchChange, id, placeholder, emptyText = 'No matches.', 'aria-label': ariaLabel, 'aria-invalid': ariaInvalid, className, }) {
+    const anchor = useComboboxAnchor();
+    const label = (option) => getLabel(option) ?? PENDING_LABEL;
+    return (_jsxs(Combobox, { multiple: true, autoHighlight: true, 
+        // Ids, not {id,label} objects: Base UI compares items to the value
+        // with Object.is, so the items must have the value's own shape.
+        items: options.map((option) => option.id), value: value, onValueChange: (next) => onValueChange(next), onInputValueChange: onSearchChange, itemToStringLabel: label, filter: null, children: [_jsx(ComboboxChips, { ref: anchor, className: className, children: _jsx(ComboboxValue, { children: (selected) => (_jsxs(React.Fragment, { children: [selected.map((option) => (_jsx(ComboboxChip, { children: label(option) }, option))), _jsx(ComboboxChipsInput, { id: id, "aria-label": ariaLabel, "aria-invalid": ariaInvalid, placeholder: selected.length === 0 ? placeholder : undefined })] })) }) }), _jsxs(ComboboxContent, { anchor: anchor, children: [_jsx(ComboboxEmpty, { children: emptyText }), _jsx(ComboboxList, { children: (option) => (_jsx(ComboboxItem, { value: option, children: label(option) }, option)) })] })] }));
+}

package/dist/components/ui/checkbox.d.ts

@@ -0,0 +1,3 @@
+import { Checkbox as CheckboxPrimitive } from "@base-ui/react/checkbox";
+declare function Checkbox({ className, ...props }: CheckboxPrimitive.Root.Props): import("react").JSX.Element;
+export { Checkbox };

package/dist/components/ui/checkbox.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Checkbox as CheckboxPrimitive } from "@base-ui/react/checkbox";
+import { cn } from "cn";
+import { CheckIcon } from "lucide-react";
+function Checkbox({ className, ...props }) {
+    return (_jsx(CheckboxPrimitive.Root, { "data-slot": "checkbox", className: cn("peer relative flex size-4 shrink-0 items-center justify-center rounded-[4px] border border-input transition-colors outline-none group-has-disabled/field:opacity-50 group-has-[:focus-visible]/field-label:ring-0 group-has-[:focus-visible]/field-label:not-data-checked:border-input after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 aria-invalid:aria-checked:border-primary dark:bg-input/30 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-checked:border-primary data-checked:bg-primary data-checked:text-primary-foreground group-has-[:focus-visible]/field-label:data-checked:border-primary dark:data-checked:bg-primary", className), ...props, children: _jsx(CheckboxPrimitive.Indicator, { "data-slot": "checkbox-indicator", className: "grid place-content-center text-current transition-none [&>svg]:size-3.5", children: _jsx(CheckIcon, {}) }) }));
+}
+export { Checkbox };

package/dist/index.d.ts

@@ -5,6 +5,8 @@ export { ErrorState } from './components/app/error-state.js';
 export { FoundationProviders } from './components/app/foundation-providers.js';
 export { MockModeBanner } from './components/app/mock-mode-banner.js';
 export { MultiChoice } from './components/app/multi-choice.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';
 export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
 export { ThemeProvider } from './components/theme-provider.js';

package/dist/index.js

@@ -10,6 +10,8 @@ export { ErrorState } from './components/app/error-state.js';
 export { FoundationProviders } from './components/app/foundation-providers.js';
 export { MockModeBanner } from './components/app/mock-mode-banner.js';
 export { MultiChoice } from './components/app/multi-choice.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';
 export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
 export { ThemeProvider } from './components/theme-provider.js';

package/package.json

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