@tristan2828/ui-foundation 3.6.0 → 3.7.0

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

@@ -103,7 +103,23 @@ 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.
    - `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

@@ -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; 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).

package/package.json

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