@tristan2828/ui-foundation 3.7.0 → 3.8.0

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

@@ -120,6 +120,14 @@ 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.
+
+   **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

@@ -36,7 +36,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 +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.7.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": {