@tristan2828/ui-foundation 3.5.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`, `MultiReference`, `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

@@ -95,7 +95,15 @@ is a filled-in example while the Widgets demo is still here).
    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):
+   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

@@ -54,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/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

@@ -6,6 +6,7 @@ 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

@@ -11,6 +11,7 @@ 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.5.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": {