@tristan2828/ui-foundation 3.6.0 → 3.8.0

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

@@ -103,7 +103,31 @@ is a filled-in example while the Widgets demo is still here).
    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):
+   in the table, never the items — and a `computed` field copies
+   Progress (`checklistState`): `readOnly` in `openapi.yaml` and absent
+   from `<Entity>Create`/`<Entity>Update`, one SQL expression in the
+   router that the filter and sort use (correlated `EXISTS`, or a scalar
+   subquery for a count, so they hold across pages), a Python mirror on
+   the model for the value each row reads back with, a test that the two
+   agree for every value, the mocks recomputing it on every write and
+   ignoring any client-sent value, a read-only column and a filter, and
+   nothing on the form):
+
+   **Keep column definitions stable.** Build them once
+   (`useMemo(() => build<Entity>Columns(), [])`) from nothing that loads
+   later. TanStack's `flexRender` treats each column's `cell` as a
+   component, so rebuilt columns remount every cell: focus is lost and the
+   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.
+
+   **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-categories.ts` →
      `src/routes/<entity>/use-<entity>.ts` (TanStack Query hooks over the
      new gateway module)

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

@@ -33,7 +33,12 @@ One or two sentences: what one record is, and who uses the screens.
     (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`).
+    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 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
     pattern): `integer` (from decimal), `url` (from email — a format
     check), `date` (from date-time — no time part).
@@ -50,7 +55,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/package.json

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