@metaobjectsdev/sdk 0.21.3 → 0.21.4

package/agent-context/skills/metaobjects-authoring/SKILL.md

@@ -719,8 +719,56 @@ Multi-source: multiple `source.rdb` children, each with a `@role`, exactly one
 ```
 
 **An entity's PRIMARY source must be writable** (`table`) — read-only kinds are
-legal only in non-primary roles (e.g. table `primary` + view `replica` for
-read-through). A derived read model over a view/proc is an **`object.projection`**
+legal only in non-primary roles.
+
+### Derived/computed columns: reach for an ENTITY READ-VIEW first
+
+**Do not default to `object.projection` for a list screen, grid, or "one extra
+column" read.** The usual need — an entity's own rows plus a joined display name or a
+per-row count, filterable and sortable like any other column — is an **entity
+read-view**, not a projection:
+
+```jsonc
+{ "object.entity": { "name": "Order", "children": [
+  { "source.rdb": { "@kind": "table", "@table": "orders" } },              // writes
+  { "source.rdb": { "@kind": "view", "@view": "v_order", "@role": "replica" } },  // reads
+  // …the entity's own fields stay as they are — you re-state NOTHING…
+  { "field.string": { "name": "customerName", "@filterable": true, "children": [
+    { "origin.passthrough": { "@from": "Customer.name" } } ]}},
+  { "field.int": { "name": "itemCount", "@filterable": true, "children": [
+    { "origin.aggregate": { "@agg": "count", "@of": "OrderItem.id", "@via": "Order.items" } } ]}}
+]}}
+```
+
+That is the whole change. Writes route to the table (derived fields are excluded from
+the write codecs); reads route to the view; `meta migrate` emits the `CREATE VIEW` from
+the **same assembly logic** a projection view uses — one emitter, two hosts (FR-024 §7,
+#213/#214). Filtering and sorting on `customerName` / `itemCount` work like any other
+column because the filter tier runs against the view.
+
+**Reach for a projection only when one of these is true** (from
+`docs/features/source-kinds.md`, which carries the full decision table):
+
+| Entity read-view | Projection |
+|---|---|
+| extras sit over the entity's **own** table | an independent **exposure contract** |
+| same trust domain — a new entity field showing up in the view is correct | a subset, **renamed** columns, versioned, or external consumers |
+| the base is still INSERTable and is the record of truth | keyless, multi-base, proc-backed, all-derived, or borrowed identity |
+
+Two things genuinely force a projection: **renamed base columns** (a field carries one
+`@column` per paradigm) and **row-filtered views** (soft-delete / `WHERE status='active'`
+— an entity read-view exposes the whole entity; only a projection carries a row-scope
+`@filter`, #207).
+
+Choosing a projection when a read-view would do costs a second URL, a second type, a
+second identity declaration, and re-stating every passthrough column — for no gain.
+
+> Historical note for anyone porting older advice: before 0.17.0 (2026-07-18) an entity
+> hosting a derived field silently produced no view and read the wrong table, so a
+> projection genuinely WAS the only way to get a grid with a derived column. That is
+> fixed; guidance written before then is stale.
+
+A derived read model that IS an independent exposure is an **`object.projection`**
 (FR-024): its fields `extends` entity fields (`extends: "Author.id"` — dotted
 child traversal, package only on the root segment) and/or carry `origin.*`
 children (`passthrough` / `aggregate` / `collection` / `computed` / `first`)

package/agent-context/skills/metaobjects-runtime-ui/SKILL.md

@@ -125,6 +125,24 @@ fetcher-provider at the tree root; every generated hook reads it from context. T
 generated grid and form components, filter-qs serializer, and cell renderers all
 sit on top of this one seam.
 
+## Grids are opt-in per entity
+
+Read/CRUD hooks are generated for **every** entity. Grids are the exception:
+wherever your stack generates them (the TanStack client today), an entity produces
+grid artifacts only when it declares a `layout.dataGrid` child. So wiring the grid
+generator and seeing no grid files is expected metadata, not a broken build — the
+run says so in its `meta gen` warnings. Opt an entity in with:
+
+```jsonc
+{ "layout.dataGrid": { "name": "default", "@columns": ["name", "email"] } }
+```
+
+Generated grid components are fully **controlled** — they need row-count and
+sort/pagination/filter state on top of the column definitions — so pair the columns
+generator with the grid-**hook** generator, which generates that state plumbing
+instead of leaving you to hand-write it. Your client's reference fragment has the
+generator names and a rendered example.
+
 ---
 
 For this project's runtime + web-client specifics, read every `references/*.md` file in this skill's directory (one per server language and client framework in this project's stack).

package/agent-context/skills/metaobjects-runtime-ui/references/tanstack.md

@@ -4,14 +4,15 @@
 hooks + a TanStack Table grid component. Like the React client it is **universal**:
 it consumes any backend (TS / Java / Kotlin / C# / Python) that speaks the
 cross-port REST contract. It pairs with `codegen-ts-tanstack`, which emits
-`<Entity>.hooks.ts` and `<Entity>.columns.tsx` that import from this package.
+`<Entity>.hooks.ts`, `<Entity>.columns.tsx` and `<Entity>.grid.ts` that import from
+this package.
 
 ## Contents
 - Install
 - Key exports
 - The `EntityFetcher` contract
-- Generated hooks (`tanstackQuery()`)
-- Generated grid (`tanstackGrid()`)
+- Generated hooks (`tanstackQuery()`) — every entity
+- Generated grid (`tanstackGrid()` + `tanstackGridHook()`) — **opt-in per entity**
 - Cell renderer overrides
 
 ## Install
@@ -84,23 +85,68 @@ projections):
 Query hooks return `UseQueryResult`; mutation hooks return `UseMutationResult` and
 invalidate the entity's query keys so lists re-fetch after writes.
 
-## Generated grid (`tanstackGrid()`)
+## Generated grid (`tanstackGrid()`) — **opt-in per entity**
+
+Grid artifacts are the one generator pair that is **not** emitted for every entity.
+`tanstackGrid()` emits `<Entity>.columns.tsx` **only for an entity that declares a
+`layout.dataGrid` child**; an entity without one gets its `.hooks.ts` and no
+columns file at all. That is intended — a grid is a presentation decision about a
+particular entity, so declaring one is how you say "this entity is displayed in a
+grid"; emitting columns for every entity in the model would be noise. A run that
+skips grids for this reason says so in its `meta gen` warnings.
+
+So the minimum to get a grid is a `layout.dataGrid` on the entity:
+
+```jsonc
+{ "object.entity": { "name": "Author", "children": [
+  // ...fields...
+  { "layout.dataGrid": {
+      "name": "default",
+      "@columns": ["name", "email", "createdAt"],   // ordered; omit for every field
+      "@pageSize": 25,
+      "@defaultSortField": "createdAt",
+      "@defaultSortOrder": "desc"
+  }}
+]}}
+```
+
+One `layout.dataGrid` → one pair of generated consts, named
+`<entity><Grid>Columns` (the `ColumnDef<T>[]`, each carrying `meta.view` for the
+renderer registry) and `<entity><Grid>Grid` (the `GridConfig`). The grid's `name`
+is capitalized into both, so `"name": "default"` on `Author` yields
+`authorDefaultColumns` + `authorDefaultGrid`. Declare several named grids on one
+entity and you get several pairs.
 
-Emits `<Entity>.columns.tsx` from the entity's `layout.dataGrid` child — TanStack
-`ColumnDef<T>[]`, each carrying `meta.view` for the renderer registry. Render with
-`<EntityGrid>`:
+### Rendering: pair it with `tanstackGridHook()`
+
+`<EntityGrid>` is **fully controlled** — beyond `columns`/`grid`/`data` it also
+requires `rowCount`, a `state` object, and three `onChange` callbacks. Wiring that
+by hand (sorting + pagination + column filters + the `withCount=1` query and its
+`buildFilterQs` serialization) is a page of boilerplate that the metadata already
+describes, so **`tanstackGridHook()` generates it**: add it to the config and each
+grid gets a `use<Entity><Grid>Grid()` returning exactly the prop shape
+`<EntityGrid>` wants.
+
+```ts
+// metaobjects.config.ts
+generators: [entityFile(), tanstackQuery(), tanstackGrid(), tanstackGridHook()],
+```
 
 ```tsx
-import { useAuthors } from "./generated/Author.hooks";
-import { authorColumns } from "./generated/Author.columns";
 import { EntityGrid } from "@metaobjectsdev/tanstack";
+import { authorDefaultColumns, authorDefaultGrid } from "./generated/Author.columns";
+import { useAuthorDefaultGrid } from "./generated/Author.grid";
 
-const { data } = useAuthors({ sort: "name:asc", limit: 25, offset: 0, withCount: 1 });
-<EntityGrid columns={authorColumns} data={data?.rows ?? []} rowCount={data?.total ?? 0} />
+export function AuthorList() {
+  const grid = useAuthorDefaultGrid();   // owns sorting/pagination/filters + the query
+  return <EntityGrid {...grid} columns={authorDefaultColumns} grid={authorDefaultGrid} />;
+}
 ```
 
-`tanstackGridHook()` (optional) wraps the sorting/pagination/filter state plumbing
-into a `useAuthorGrid()` so the consumer renders `<EntityGrid {...useAuthorGrid()} />`.
+`tanstackGridHook()` is optional only in the sense that you may own that state
+yourself; if you do, supply `data`, `rowCount`, `state`, `onSortingChange`,
+`onPaginationChange` and `onColumnFiltersChange` by hand — the hook exists so you
+don't have to.
 
 ## Cell renderer overrides
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/sdk",
-  "version": "0.21.3",
+  "version": "0.21.4",
   "description": "Workspace helpers and agent-docs utilities for MetaObjects projects.",
   "type": "module",
   "main": "./dist/index.js",
@@ -56,7 +56,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@metaobjectsdev/metadata": "0.21.3",
+    "@metaobjectsdev/metadata": "0.21.4",
     "zod": "^3.23.0"
   },
   "devDependencies": {