@tristan2828/ui-foundation 3.7.0 → 3.9.0

package/conventions/AGENTS.md

@@ -132,7 +132,9 @@ net.
 Follow `docs/foundation/add-an-entity.md` (in Claude Code, `/new-entity
 <Name>` is a shortcut to it). It builds from the entity's plan,
 `docs/entities/<entity>.md`; if there's no plan, work one out with the
-developer first. Never guess the fields.
+developer first. Never guess the fields. The files it copies are the
+Widgets demo's until the app removes it; after that, the `### Reference
+files` section below names the app's own.
 
 ## Upgrading the Foundation
 ```bash

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

@@ -12,6 +12,30 @@ Do not skip steps or reorder them. Replace `<Entity>` with the PascalCase
 entity name (e.g. `Invoice`) and `<entity>` with its kebab-case form
 (`invoice`) throughout.
 
+## The reference files
+
+The steps name the template's Widgets demo as the code to copy:
+`src/routes/widgets/`, `src/api/gateway/widgets.ts` and
+`widget-categories.ts`, their mocks and tests. An app deletes the demo
+once its own entity works, and from then on those names point at nothing.
+So the app's `AGENTS.md`, below the foundation block, has a
+**`### Reference files`** section: for each pattern (a table, a form, a
+reference field, a multi choice and the rest), the app's own file to copy.
+
+- **That section exists:** it wins. Wherever a step below names a demo
+  file, copy the file the section names for that pattern instead. A
+  pattern it doesn't list, and the demo is gone: stop and ask which file
+  to copy. Never rebuild a pattern from this file's prose alone.
+- **It doesn't, and the demo is still here:** copy the demo, as written.
+- **When the app removes the demo:** write the section first, naming the
+  file that now holds each pattern the demo showed. The template's own
+  `AGENTS.md` has the section, filled in for the demo, as the shape.
+
+The demo's referenced entity is `WidgetCategory` (`/widget-categories`,
+the `widget_categories` table), named for its widget so it never collides
+with an app's own entity. An app whose entity is a Category builds it
+alongside the demo with no rename.
+
 ## Before anything: the entity plan
 
 **Never guess what an entity is.** Every field, type, option list and rule
@@ -64,14 +88,14 @@ is a filled-in example while the Widgets demo is still here).
    a raw sentinel instead of a "not set" label, passes `verify` unnoticed.
    One row costs nothing and step 8 asserts it. Extend `tests/mocks/conformance.test.ts` so the
    new handlers are validated against `openapi.yaml`, the same way
-   `widgets`/`categories` already are.
+   `widgets`/`widget-categories` already are.
 5. **Add a gateway module in `src/api/gateway/<entity>.ts`** until step 3's
    tests pass, built on `safeFetch`/`toAppError` from
    `@tristan2828/ui-foundation/gateway` (see `src/api/gateway/widgets.ts`).
    Wire → `Page<T>` / `AppError` translation only; no hand-written types
    (everything comes from `schema.d.ts`).
-6. **Copy the widgets reference files, one for one, not just the two
-   screens** — shaped by the plan: table columns and sortable columns from
+6. **Copy the reference files, one for one, not just the two screens**
+   (the Widgets demo's, or the ones the app's `### Reference files` names) — shaped by the plan: table columns and sortable columns from
    its "List" column, toolbar filters from its "Filter" column, form fields
    and labels from its field table, and field types by pattern (a
    `reference` field copies Category's searchable combobox, a
@@ -85,12 +109,14 @@ 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 — and a `multi reference` copies Extra Categories:
+   repeated parameter; each option shows its label, never its wire value
+   (`quick_win` reads "Quick win"): one `Record<value, label>`
+   (`WIDGET_TAG_LABELS`) feeds `MultiChoice`'s `getLabel` and the badges — 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
+   (`GET /widget-categories?ids=1&ids=3`, `getWidgetCategoriesByIds`,
+   `useWidgetCategoriesByIdsQuery`). 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
@@ -120,7 +146,15 @@ is a filled-in example while the Widgets demo is still here).
    table flickers when, say, reference names arrive after the rows. Data
    that arrives later reaches the cells through context, as
    `category-names.tsx` does for category names.
-   - `src/routes/widgets/use-widgets.ts`, `use-categories.ts` →
+
+   **A `yes/no` marked `toggle`** copies In Stock's cell
+   (`in-stock-toggle.tsx`, cell pattern 15): a `Switch` in its own
+   component that PATCHes the one field through an optimistic mutation
+   (`useToggleWidgetInStockMutation`: every cached list page updates at
+   once and is restored if the save fails, with a toast naming the row),
+   then refetches the lists. Its specs cover a flip that saves, the
+   keyboard, and a failed save putting the switch back.
+   - `src/routes/widgets/use-widgets.ts`, `use-widget-categories.ts` →
      `src/routes/<entity>/use-<entity>.ts` (TanStack Query hooks over the
      new gateway module)
    - `src/routes/widgets/widget-schema.ts` →

package/conventions/docs/cell-patterns.md

@@ -330,3 +330,23 @@ A person: an assignee or an owner.
 - **Cost:** a column of faces draws the eye more than any other cell. Use
   it when *who* matters most in the row, not as decoration.
 
+## 15. Yes/no you flip in the row
+
+A yes/no the user changes more often than they open the form ("available
+now", "happened"). Widget's In Stock column is the reference
+(`src/routes/widgets/in-stock-toggle.tsx`).
+
+- **A `Switch`, never a checkbox.** It acts at once; a checkbox in a row
+  reads as "select this row".
+- **It saves on its own:** a PATCH of that one field, not the form. Show
+  the new value at once (optimistic) and put it back, with a toast naming
+  the row, if the save fails (`useToggleWidgetInStockMutation`).
+- **Keep the word beside it** (pattern 12), `aria-hidden` since the switch
+  announces its own state. Give the switch a row-specific name
+  (`In stock: ${row.original.name}`).
+- Its own component in its own file, rendered from the column's `cell`,
+  so the hook lives in a component and the columns stay stable
+  ([`add-an-entity.md`](add-an-entity.md) "Keep column definitions
+  stable").
+- **Cost:** one click changes data, with no confirmation. Only for values
+  that are cheap to flip back; never for anything destructive.

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

@@ -28,7 +28,8 @@ One or two sentences: what one record is, and who uses the screens.
     say its default and the filter's three labels, e.g. Any stock /
     In stock / Out of stock), `single choice` (list the options, in display
     order; see the note below if it is *optional*), `multi choice` (list
-    the options; any number can be picked —
+    the options, with a label for any whose wire value isn't fit to show,
+    e.g. `quick_win` (Quick win); 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), `multi reference`
     (to any number of records of another entity — name it; chips with a
@@ -36,7 +37,7 @@ One or two sentences: what one record is, and who uses the screens.
     the other entity's list endpoint must also accept `ids`),
     `computed` (read-only: the server works it out from other data on
     every read and never stores it — give its rule, and if it's a choice,
-    its values in sort order; a read-only column, a filter and a sort the
+    its values in sort order with a label for each; a read-only column, a filter and a sort the
     server evaluates, never on the form). A count of related records is a
     `computed` integer.
   - *Close variants* (built by a small, stated change to the nearest
@@ -55,7 +56,8 @@ One or two sentences: what one record is, and who uses the screens.
   a screen — a Base UI `Select` can't take `""` as an item value, so the
   pattern needs a sentinel and gets the display wrong without one.
 - **List**: `column` if it shows in the table, and `sortable` if you can
-  sort by it; blank if it's form-only.
+  sort by it; blank if it's form-only. A `yes/no` can also say `toggle`:
+  flipped straight from its row, saved on its own (cell pattern 15).
 - **Filter**: `search` (the text search box), `yes` (a filter control), or
   blank.
 

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

@@ -1,9 +1,14 @@
 import * as React from 'react';
-export declare function MultiChoice<T extends string>({ options, value, onValueChange, id, placeholder, 'aria-label': ariaLabel, 'aria-invalid': ariaInvalid, className, }: {
+export declare function MultiChoice<T extends string>({ options, value, onValueChange, getLabel, id, placeholder, 'aria-label': ariaLabel, 'aria-invalid': ariaInvalid, className, }: {
     /** Every allowed option, in display order. */
     options: readonly T[];
     value: T[];
     onValueChange: (value: T[]) => void;
+    /**
+     * The text shown for an option: on its chip, in the dropdown, and what
+     * typing matches against. Defaults to the value itself.
+     */
+    getLabel?: (value: T) => string;
     /** Id for the text input, so a <FieldLabel htmlFor> labels it. */
     id?: string;
     placeholder?: string;

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

@@ -5,9 +5,13 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // filter — so entities reuse it rather than re-assembling the combobox
 // primitive each time. Built on shadcn's Combobox `multiple` mode, following
 // its own ComboboxMultiple example.
+//
+// Values are the wire's enum strings; `getLabel` names them when those
+// aren't fit to show (`quick_win` → "Quick win"). Chips, options and the
+// typed-text match all use the label, and the value is what's emitted.
 import * as React from 'react';
 import { Combobox, ComboboxChip, ComboboxChips, ComboboxChipsInput, ComboboxContent, ComboboxEmpty, ComboboxItem, ComboboxList, ComboboxValue, useComboboxAnchor, } from '../ui/combobox.js';
-export function MultiChoice({ options, value, onValueChange, id, placeholder, 'aria-label': ariaLabel, 'aria-invalid': ariaInvalid, className, }) {
+export function MultiChoice({ options, value, onValueChange, getLabel = String, id, placeholder, 'aria-label': ariaLabel, 'aria-invalid': ariaInvalid, className, }) {
     const anchor = useComboboxAnchor();
-    return (_jsxs(Combobox, { multiple: true, autoHighlight: true, items: options, value: value, onValueChange: (next) => onValueChange(next), children: [_jsx(ComboboxChips, { ref: anchor, className: className, children: _jsx(ComboboxValue, { children: (selected) => (_jsxs(React.Fragment, { children: [selected.map((option) => (_jsx(ComboboxChip, { children: 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: "No options found." }), _jsx(ComboboxList, { children: (option) => (_jsx(ComboboxItem, { value: option, children: option }, option)) })] })] }));
+    return (_jsxs(Combobox, { multiple: true, autoHighlight: true, items: options, value: value, onValueChange: (next) => onValueChange(next), itemToStringLabel: getLabel, children: [_jsx(ComboboxChips, { ref: anchor, className: className, children: _jsx(ComboboxValue, { children: (selected) => (_jsxs(React.Fragment, { children: [selected.map((option) => (_jsx(ComboboxChip, { children: getLabel(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: "No options found." }), _jsx(ComboboxList, { children: (option) => (_jsx(ComboboxItem, { value: option, children: getLabel(option) }, option)) })] })] }));
 }

package/package.json

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