@metaobjectsdev/codegen-ts-tanstack 0.21.3 → 0.21.4-rc.1

package/README.md

@@ -1,6 +1,16 @@
 # @metaobjectsdev/codegen-ts-tanstack
 
-TanStack codegen for MetaObjects. Provides `tanstackQuery()` (per-entity `<Entity>.hooks.ts` — 5 React Query hooks, plus a `use<Source><Relation>(sourceId, opts?)` collection hook per many-to-many relationship), `tanstackGrid()` (`<Entity>.columns.tsx` for `@tanstack/react-table`), and `tanstackGridHook()`.
+TanStack codegen for MetaObjects. Provides `tanstackQuery()` (per-entity `<Entity>.hooks.ts` — 5 React Query hooks, plus a `use<Source><Relation>(sourceId, opts?)` collection hook per many-to-many relationship), `tanstackGrid()` (`<Entity>.columns.tsx` for `@tanstack/react-table`), and `tanstackGridHook()` (`<Entity>.grid.ts` — the controlled grid state + query).
+
+### Grids are opt-in per entity
+
+`tanstackQuery()` emits hooks for **every** entity. `tanstackGrid()` and `tanstackGridHook()` emit **only for an entity that declares a `layout.dataGrid` child** — declaring one is how you say "this entity is displayed in a grid". If you wire the grid generators and get no `.columns.tsx`/`.grid.ts`, that is the reason, and `meta gen` says so in its warnings. Opt an entity in with:
+
+```jsonc
+{ "layout.dataGrid": { "name": "default", "@columns": ["name", "email"] } }
+```
+
+`@columns` is an ordered list; omit it to get every field. Each `layout.dataGrid` yields a `<entity><Grid>Columns` + `<entity><Grid>Grid` pair from `tanstackGrid()` and a `use<Entity><Grid>Grid()` from `tanstackGridHook()`.
 
 ### M:N collection hooks (FR-018)
 
@@ -18,13 +28,28 @@ In your `metaobjects.config.ts`:
 
 ```ts
 import { defineConfig } from "@metaobjectsdev/cli";
-import { tanstackQuery, tanstackGrid } from "@metaobjectsdev/codegen-ts-tanstack";
+import { tanstackQuery, tanstackGrid, tanstackGridHook } from "@metaobjectsdev/codegen-ts-tanstack";
 
 export default defineConfig({
-  generators: [tanstackQuery(), tanstackGrid()],
+  generators: [tanstackQuery(), tanstackGrid(), tanstackGridHook()],
 });
 ```
 
+Then render. `<EntityGrid>` is fully controlled — beyond the columns it needs
+`rowCount`, a `state` object and three `onChange` callbacks — so pair it with the
+generated grid hook, which returns exactly that prop shape:
+
+```tsx
+import { EntityGrid } from "@metaobjectsdev/tanstack";
+import { authorDefaultColumns, authorDefaultGrid } from "./generated/Author.columns";
+import { useAuthorDefaultGrid } from "./generated/Author.grid";
+
+export function AuthorList() {
+  const grid = useAuthorDefaultGrid();   // owns sorting/pagination/filters + the query
+  return <EntityGrid {...grid} columns={authorDefaultColumns} grid={authorDefaultGrid} />;
+}
+```
+
 `tanstackQuery`/`tanstackGrid`/`tanstackGridHook` each accept `{ target }` to route
 their output (hooks/columns/grids) to a named target such as the browser app — see
 `@metaobjectsdev/cli` README, "Multiple output targets". The generated files import

package/dist/data-grid-gate.d.ts

@@ -0,0 +1,32 @@
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import type { GenContext } from "@metaobjectsdev/codegen-ts";
+/** True when the entity declares (or inherits) at least one `layout.dataGrid`. */
+export declare function hasDataGridLayout(entity: MetaObject): boolean;
+/**
+ * Grid artifacts are opt-IN per entity: an entity produces one only when it declares
+ * a `layout.dataGrid` child. That is intended — but nothing used to say so. An
+ * adopter who wired `tanstackQuery() + tanstackGrid()` got `.hooks.ts` for every
+ * entity and `.columns.tsx` for none, and reasonably concluded codegen was broken
+ * (#287). The package description promising "hooks and column definitions"
+ * unconditionally made it worse.
+ *
+ * So the run itself now says it, following the repo's tell-at-`meta gen`-time
+ * precedent (#226 / #258) rather than a doc line that gets missed the same way this
+ * one was. Warning only: the exit code is untouched, and `--dry-run` reports it too,
+ * since generators run before the write phase branches.
+ *
+ * It fires ONLY when the generator emitted **nothing at all** — which is the reported
+ * condition ("no columns file for ANY entity") and makes the note self-extinguishing:
+ * declare one `layout.dataGrid` anywhere in the model and it goes quiet forever. A
+ * 50-entity model with 3 grids therefore stays silent, because that author plainly
+ * knows how grids work and a permanent 47-name nag is exactly the cry-wolf failure
+ * that got the old `timestampMode` warning deleted from `runner.ts` rather than left
+ * to fire forever.
+ *
+ * `passesOtherGates` is the generator's own filter MINUS the layout check, so the
+ * named set is exactly "objects the layout gate — and nothing else — held back".
+ * `object.value`s are excluded from it: a value object is a payload/DTO shape, never
+ * a grid candidate, so naming one would be advice worth ignoring.
+ */
+export declare function warnMissingDataGridLayout(ctx: GenContext, passesOtherGates: (entity: MetaObject) => boolean, artifact: string): void;
+//# sourceMappingURL=data-grid-gate.d.ts.map

package/dist/data-grid-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-grid-gate.d.ts","sourceRoot":"","sources":["../src/data-grid-gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE7D,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAG7D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,UAAU,EACf,gBAAgB,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,EACjD,QAAQ,EAAE,MAAM,GACf,IAAI,CAaN"}

package/dist/data-grid-gate.js

@@ -0,0 +1,45 @@
+import { LAYOUT_SUBTYPE_DATA_GRID, OBJECT_SUBTYPE_VALUE } from "@metaobjectsdev/metadata";
+/** True when the entity declares (or inherits) at least one `layout.dataGrid`. */
+export function hasDataGridLayout(entity) {
+    // layouts() is effective — own + inherited layouts (from extends:/super:).
+    return entity.layouts().some((l) => l.subType === LAYOUT_SUBTYPE_DATA_GRID);
+}
+/**
+ * Grid artifacts are opt-IN per entity: an entity produces one only when it declares
+ * a `layout.dataGrid` child. That is intended — but nothing used to say so. An
+ * adopter who wired `tanstackQuery() + tanstackGrid()` got `.hooks.ts` for every
+ * entity and `.columns.tsx` for none, and reasonably concluded codegen was broken
+ * (#287). The package description promising "hooks and column definitions"
+ * unconditionally made it worse.
+ *
+ * So the run itself now says it, following the repo's tell-at-`meta gen`-time
+ * precedent (#226 / #258) rather than a doc line that gets missed the same way this
+ * one was. Warning only: the exit code is untouched, and `--dry-run` reports it too,
+ * since generators run before the write phase branches.
+ *
+ * It fires ONLY when the generator emitted **nothing at all** — which is the reported
+ * condition ("no columns file for ANY entity") and makes the note self-extinguishing:
+ * declare one `layout.dataGrid` anywhere in the model and it goes quiet forever. A
+ * 50-entity model with 3 grids therefore stays silent, because that author plainly
+ * knows how grids work and a permanent 47-name nag is exactly the cry-wolf failure
+ * that got the old `timestampMode` warning deleted from `runner.ts` rather than left
+ * to fire forever.
+ *
+ * `passesOtherGates` is the generator's own filter MINUS the layout check, so the
+ * named set is exactly "objects the layout gate — and nothing else — held back".
+ * `object.value`s are excluded from it: a value object is a payload/DTO shape, never
+ * a grid candidate, so naming one would be advice worth ignoring.
+ */
+export function warnMissingDataGridLayout(ctx, passesOtherGates, artifact) {
+    const candidates = ctx.entities.filter((e) => e.subType !== OBJECT_SUBTYPE_VALUE && passesOtherGates(e));
+    if (candidates.length === 0)
+        return;
+    if (candidates.some(hasDataGridLayout))
+        return; // the model uses grids — say nothing
+    ctx.warn(`no ${artifact} emitted for ${candidates.map((e) => e.name).join(", ")} — grid ` +
+        `artifacts are opt-in per entity via a \`layout.dataGrid\` child, and no object in ` +
+        `this model declares one. Add e.g. ` +
+        `{"layout.dataGrid": {"name": "default", "@columns": ["id", "name"]}} to an entity ` +
+        `to emit its grid.`);
+}
+//# sourceMappingURL=data-grid-gate.js.map

package/dist/data-grid-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-grid-gate.js","sourceRoot":"","sources":["../src/data-grid-gate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAG1F,kFAAkF;AAClF,MAAM,UAAU,iBAAiB,CAAC,MAAkB;IAClD,2EAA2E;IAC3E,OAAO,MAAM,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,wBAAwB,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,yBAAyB,CACvC,GAAe,EACf,gBAAiD,EACjD,QAAgB;IAEhB,MAAM,UAAU,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,CACpC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,oBAAoB,IAAI,gBAAgB,CAAC,CAAC,CAAC,CACjE,CAAC;IACF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACpC,IAAI,UAAU,CAAC,IAAI,CAAC,iBAAiB,CAAC;QAAE,OAAO,CAAG,qCAAqC;IACvF,GAAG,CAAC,IAAI,CACN,MAAM,QAAQ,gBAAgB,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU;QAC9E,oFAAoF;QACpF,oCAAoC;QACpC,oFAAoF;QACpF,mBAAmB,CACtB,CAAC;AACJ,CAAC"}

package/dist/tanstack-grid-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tanstack-grid-hook.d.ts","sourceRoot":"","sources":["../src/tanstack-grid-hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D,OAAO,EAA6B,KAAK,gBAAgB,EAAkF,MAAM,4BAA4B,CAAC;AAG9K,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAOD;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EA8BxB,gBAAgB,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC"}
+{"version":3,"file":"tanstack-grid-hook.d.ts","sourceRoot":"","sources":["../src/tanstack-grid-hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAA6B,KAAK,gBAAgB,EAAwH,MAAM,4BAA4B,CAAC;AAIpN,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EA8CxB,gBAAgB,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC"}

package/dist/tanstack-grid-hook.js

@@ -1,10 +1,6 @@
-import { LAYOUT_SUBTYPE_DATA_GRID } from "@metaobjectsdev/metadata";
-import { perEntity, formatTs, entityOutputPath, emitsInstanceArtifacts, CODEGEN_ATTR_EMIT_TANSTACK } from "@metaobjectsdev/codegen-ts";
+import { perEntity, formatTs, entityOutputPath, emitsInstanceArtifacts, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK, CODEGEN_ATTR_EMIT_GRID } from "@metaobjectsdev/codegen-ts";
+import { hasDataGridLayout, warnMissingDataGridLayout } from "./data-grid-gate.js";
 import { renderGridHookFile } from "./templates/grid-hook-file.js";
-function hasDataGridLayout(entity) {
-    // layouts() is effective — own + inherited layouts (from extends:/super:).
-    return entity.layouts().some((l) => l.subType === LAYOUT_SUBTYPE_DATA_GRID);
-}
 /**
  * Per-entity generator that emits <Entity>.grid.ts — one
  * use<Entity><Grid>Grid() hook per layout[dataGrid] declared on the entity.
@@ -14,24 +10,40 @@ function hasDataGridLayout(entity) {
  */
 export const tanstackGridHook = function tanstackGridHook(opts) {
     const userFilter = opts?.filter ?? (() => true);
+    // Every gate EXCEPT the dataGrid-layout opt-in: the framework instance-artifact
+    // guard (skips abstract types), the metadata opt-out, and the user filter. Split
+    // out so the discoverability note can name exactly the entities the LAYOUT gate
+    // alone held back (#287).
+    //
+    // The TPH clause must MATCH tanstackGrid's exactly. A TPH subtype inherits its base's
+    // dataGrid layout via extends, so `hasDataGridLayout` is true for it — but tanstackGrid
+    // deliberately emits no per-subtype columns without an own `@emitGrid: true` (the base's
+    // polymorphic grid is the single source of truth). Without the same clause here, a TPH
+    // subtype got a `<Sub>.grid.ts` whose sibling `<Sub>.columns.tsx` is never emitted:
+    // a dangling `use<Sub>DefaultGrid()` with nothing to pair it with, and an outright
+    // TS2307 when the inherited layout carries an `@filter` preset (the hook then imports
+    // `<sub>DefaultFilter` from the missing columns module).
+    const passesOtherGates = (e) => emitsInstanceArtifacts(e)
+        // ADR-0039: resolving — a concrete entity may inherit its @emit* opt-out flag via extends.
+        && e.attr(CODEGEN_ATTR_EMIT_TANSTACK) !== false
+        && userFilter(e)
+        && (!isTphSubtype(e) || e.attr(CODEGEN_ATTR_EMIT_GRID) === true);
+    const emit = perEntity(async (entity, ctx) => {
+        if (!ctx.renderContext) {
+            throw new Error("tanstack-grid-hook: renderContext is required (provided by runGen)");
+        }
+        return {
+            path: entityOutputPath(ctx.renderContext.outputLayout, entity.package, `${entity.name}.grid.ts`),
+            content: await formatTs(renderGridHookFile(entity, ctx.renderContext)),
+        };
+    });
     const generator = {
         name: "tanstack-grid-hook",
-        // AND-composes the framework instance-artifact guard (skips abstract types),
-        // opt-out, user filter, and dataGrid layout presence.
-        filter: (e) => emitsInstanceArtifacts(e)
-            // ADR-0039: resolving — a concrete entity may inherit its @emit* opt-out flag via extends.
-            && e.attr(CODEGEN_ATTR_EMIT_TANSTACK) !== false
-            && userFilter(e)
-            && hasDataGridLayout(e),
-        generate: perEntity(async (entity, ctx) => {
-            if (!ctx.renderContext) {
-                throw new Error("tanstack-grid-hook: renderContext is required (provided by runGen)");
-            }
-            return {
-                path: entityOutputPath(ctx.renderContext.outputLayout, entity.package, `${entity.name}.grid.ts`),
-                content: await formatTs(renderGridHookFile(entity, ctx.renderContext)),
-            };
-        }),
+        filter: (e) => passesOtherGates(e) && hasDataGridLayout(e),
+        generate: async (ctx) => {
+            warnMissingDataGridLayout(ctx, passesOtherGates, "<Entity>.grid.ts");
+            return emit(ctx);
+        },
     };
     if (opts?.target) {
         generator.target = opts.target;

package/dist/tanstack-grid-hook.js.map

@@ -1 +1 @@
-{"version":3,"file":"tanstack-grid-hook.js","sourceRoot":"","sources":["../src/tanstack-grid-hook.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,SAAS,EAAyC,QAAQ,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAC9K,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAOnE,SAAS,iBAAiB,CAAC,MAAkB;IAC3C,2EAA2E;IAC3E,OAAO,MAAM,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,wBAAwB,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,SAAS,gBAAgB,CAAC,IAA2B;IACnF,MAAM,UAAU,GAAG,IAAI,EAAE,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,SAAS,GAAc;QAC3B,IAAI,EAAE,oBAAoB;QAC1B,6EAA6E;QAC7E,sDAAsD;QACtD,MAAM,EAAE,CAAC,CAAa,EAAE,EAAE,CACxB,sBAAsB,CAAC,CAAC,CAAC;YACzB,2FAA2F;eACxF,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,KAAK,KAAK;eAC5C,UAAU,CAAC,CAAC,CAAC;eACb,iBAAiB,CAAC,CAAC,CAAC;QACzB,QAAQ,EAAE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE;YACxC,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;gBACvB,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;YACxF,CAAC;YACD,OAAO;gBACL,IAAI,EAAE,gBAAgB,CACpB,GAAG,CAAC,aAAa,CAAC,YAAY,EAC9B,MAAM,CAAC,OAAO,EACd,GAAG,MAAM,CAAC,IAAI,UAAU,CACzB;gBACD,OAAO,EAAE,MAAM,QAAQ,CAAC,kBAAkB,CAAC,MAAM,EAAE,GAAG,CAAC,aAAa,CAAC,CAAC;aACvE,CAAC;QACJ,CAAC,CAAC;KACH,CAAC;IACF,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;QACjB,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IACjC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAkD,CAAC"}
+{"version":3,"file":"tanstack-grid-hook.js","sourceRoot":"","sources":["../src/tanstack-grid-hook.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAyC,QAAQ,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,YAAY,EAAE,0BAA0B,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpN,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAOnE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,SAAS,gBAAgB,CAAC,IAA2B;IACnF,MAAM,UAAU,GAAG,IAAI,EAAE,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAChD,gFAAgF;IAChF,iFAAiF;IACjF,gFAAgF;IAChF,0BAA0B;IAC1B,EAAE;IACF,sFAAsF;IACtF,wFAAwF;IACxF,yFAAyF;IACzF,uFAAuF;IACvF,oFAAoF;IACpF,mFAAmF;IACnF,sFAAsF;IACtF,yDAAyD;IACzD,MAAM,gBAAgB,GAAG,CAAC,CAAa,EAAW,EAAE,CAClD,sBAAsB,CAAC,CAAC,CAAC;QACzB,2FAA2F;WACxF,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,KAAK,KAAK;WAC5C,UAAU,CAAC,CAAC,CAAC;WACb,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,KAAK,IAAI,CAAC,CAAC;IACnE,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,EAAE,MAAkB,EAAE,GAAG,EAAE,EAAE;QACvD,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;QACxF,CAAC;QACD,OAAO;YACL,IAAI,EAAE,gBAAgB,CACpB,GAAG,CAAC,aAAa,CAAC,YAAY,EAC9B,MAAM,CAAC,OAAO,EACd,GAAG,MAAM,CAAC,IAAI,UAAU,CACzB;YACD,OAAO,EAAE,MAAM,QAAQ,CAAC,kBAAkB,CAAC,MAAM,EAAE,GAAG,CAAC,aAAa,CAAC,CAAC;SACvE,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,MAAM,SAAS,GAAc;QAC3B,IAAI,EAAE,oBAAoB;QAC1B,MAAM,EAAE,CAAC,CAAa,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC;QACtE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACtB,yBAAyB,CAAC,GAAG,EAAE,gBAAgB,EAAE,kBAAkB,CAAC,CAAC;YACrE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;KACF,CAAC;IACF,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;QACjB,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IACjC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAkD,CAAC"}

package/dist/tanstack-grid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tanstack-grid.d.ts","sourceRoot":"","sources":["../src/tanstack-grid.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D,OAAO,EAA6B,KAAK,gBAAgB,EAAwH,MAAM,4BAA4B,CAAC;AAGpN,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAOD;;;;GAIG;AACH,eAAO,MAAM,YAAY,EA+BpB,gBAAgB,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC"}
+{"version":3,"file":"tanstack-grid.d.ts","sourceRoot":"","sources":["../src/tanstack-grid.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAA6B,KAAK,gBAAgB,EAAwH,MAAM,4BAA4B,CAAC;AAIpN,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAqCpB,gBAAgB,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC"}

package/dist/tanstack-grid.js

@@ -1,10 +1,6 @@
-import { LAYOUT_SUBTYPE_DATA_GRID } from "@metaobjectsdev/metadata";
 import { perEntity, formatTs, entityOutputPath, emitsInstanceArtifacts, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK, CODEGEN_ATTR_EMIT_GRID } from "@metaobjectsdev/codegen-ts";
+import { hasDataGridLayout, warnMissingDataGridLayout } from "./data-grid-gate.js";
 import { renderColumnsFile } from "./templates/columns-file.js";
-function hasDataGridLayout(entity) {
-    // layouts() is effective — own + inherited layouts (from extends:/super:).
-    return entity.layouts().some((l) => l.subType === LAYOUT_SUBTYPE_DATA_GRID);
-}
 /**
  * Per-entity opt-out via `@emitTanstack: false`. Per-entity opt-IN: presence of
  * at least one `dataGrid` layout on the object. If both pass and the user-supplied
@@ -12,29 +8,35 @@ function hasDataGridLayout(entity) {
  */
 export const tanstackGrid = function tanstackGrid(opts) {
     const userFilter = opts?.filter ?? (() => true);
+    // Every gate EXCEPT the dataGrid-layout opt-in: the framework instance-artifact
+    // guard (skips abstract types), the metadata opt-out, and the user filter.
+    // FR-017 Tier 3: a TPH discriminator base emits ONE polymorphic grid. Its
+    // subtypes inherit the base's dataGrid layout via extends, but per-subtype grids
+    // are opt-IN only (own `@emitGrid: true`) — otherwise the polymorphic grid is the
+    // single source of truth.
+    // Split out so the discoverability note can name exactly the entities the LAYOUT
+    // gate alone held back (#287) — an opted-out or abstract type is not a surprise.
+    const passesOtherGates = (e) => emitsInstanceArtifacts(e)
+        // ADR-0039: resolving — a concrete entity may inherit its @emit* opt-out flag via extends.
+        && e.attr(CODEGEN_ATTR_EMIT_TANSTACK) !== false
+        && userFilter(e)
+        && (!isTphSubtype(e) || e.attr(CODEGEN_ATTR_EMIT_GRID) === true);
+    const emit = perEntity(async (entity, ctx) => {
+        if (!ctx.renderContext) {
+            throw new Error("tanstack-grid: renderContext is required (provided by runGen)");
+        }
+        return {
+            path: entityOutputPath(ctx.renderContext.outputLayout, entity.package, `${entity.name}.columns.tsx`),
+            content: await formatTs(renderColumnsFile(entity, ctx.renderContext)),
+        };
+    });
     const generator = {
         name: "tanstack-grid",
-        // Always set: AND-composes the framework instance-artifact guard (skips
-        // abstract types), opt-out, user filter, and dataGrid layout presence.
-        // FR-017 Tier 3: a TPH discriminator base emits ONE polymorphic grid. Its
-        // subtypes inherit the base's dataGrid layout via extends, but per-subtype
-        // grids are opt-IN only (own `@emitGrid: true`) — otherwise the polymorphic
-        // grid is the single source of truth.
-        filter: (e) => emitsInstanceArtifacts(e)
-            // ADR-0039: resolving — a concrete entity may inherit its @emit* opt-out flag via extends.
-            && e.attr(CODEGEN_ATTR_EMIT_TANSTACK) !== false
-            && userFilter(e)
-            && hasDataGridLayout(e)
-            && (!isTphSubtype(e) || e.attr(CODEGEN_ATTR_EMIT_GRID) === true),
-        generate: perEntity(async (entity, ctx) => {
-            if (!ctx.renderContext) {
-                throw new Error("tanstack-grid: renderContext is required (provided by runGen)");
-            }
-            return {
-                path: entityOutputPath(ctx.renderContext.outputLayout, entity.package, `${entity.name}.columns.tsx`),
-                content: await formatTs(renderColumnsFile(entity, ctx.renderContext)),
-            };
-        }),
+        filter: (e) => passesOtherGates(e) && hasDataGridLayout(e),
+        generate: async (ctx) => {
+            warnMissingDataGridLayout(ctx, passesOtherGates, "<Entity>.columns.tsx");
+            return emit(ctx);
+        },
     };
     if (opts?.target) {
         generator.target = opts.target;

package/dist/tanstack-grid.js.map

@@ -1 +1 @@
-{"version":3,"file":"tanstack-grid.js","sourceRoot":"","sources":["../src/tanstack-grid.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,SAAS,EAAyC,QAAQ,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,YAAY,EAAE,0BAA0B,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpN,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAOhE,SAAS,iBAAiB,CAAC,MAAkB;IAC3C,2EAA2E;IAC3E,OAAO,MAAM,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,wBAAwB,CAAC,CAAC;AAC9E,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,SAAS,YAAY,CAAC,IAAuB;IACvE,MAAM,UAAU,GAAG,IAAI,EAAE,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,SAAS,GAAc;QAC3B,IAAI,EAAE,eAAe;QACrB,wEAAwE;QACxE,uEAAuE;QACvE,0EAA0E;QAC1E,2EAA2E;QAC3E,4EAA4E;QAC5E,sCAAsC;QACtC,MAAM,EAAE,CAAC,CAAa,EAAE,EAAE,CACxB,sBAAsB,CAAC,CAAC,CAAC;YACzB,2FAA2F;eACxF,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,KAAK,KAAK;eAC5C,UAAU,CAAC,CAAC,CAAC;eACb,iBAAiB,CAAC,CAAC,CAAC;eACpB,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,KAAK,IAAI,CAAC;QAClE,QAAQ,EAAE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE;YACxC,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;gBACvB,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;YACnF,CAAC;YACD,OAAO;gBACL,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,aAAa,CAAC,YAAY,EAAE,MAAM,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,IAAI,cAAc,CAAC;gBACpG,OAAO,EAAE,MAAM,QAAQ,CAAC,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,aAAa,CAAC,CAAC;aACtE,CAAC;QACJ,CAAC,CAAC;KACH,CAAC;IACF,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;QACjB,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IACjC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAA8C,CAAC"}
+{"version":3,"file":"tanstack-grid.js","sourceRoot":"","sources":["../src/tanstack-grid.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAyC,QAAQ,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,YAAY,EAAE,0BAA0B,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpN,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAOhE;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,SAAS,YAAY,CAAC,IAAuB;IACvE,MAAM,UAAU,GAAG,IAAI,EAAE,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAChD,gFAAgF;IAChF,2EAA2E;IAC3E,0EAA0E;IAC1E,iFAAiF;IACjF,kFAAkF;IAClF,0BAA0B;IAC1B,iFAAiF;IACjF,iFAAiF;IACjF,MAAM,gBAAgB,GAAG,CAAC,CAAa,EAAW,EAAE,CAClD,sBAAsB,CAAC,CAAC,CAAC;QACzB,2FAA2F;WACxF,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,KAAK,KAAK;WAC5C,UAAU,CAAC,CAAC,CAAC;WACb,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,KAAK,IAAI,CAAC,CAAC;IACnE,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,EAAE,MAAkB,EAAE,GAAG,EAAE,EAAE;QACvD,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;QACnF,CAAC;QACD,OAAO;YACL,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,aAAa,CAAC,YAAY,EAAE,MAAM,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,IAAI,cAAc,CAAC;YACpG,OAAO,EAAE,MAAM,QAAQ,CAAC,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,aAAa,CAAC,CAAC;SACtE,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,MAAM,SAAS,GAAc;QAC3B,IAAI,EAAE,eAAe;QACrB,MAAM,EAAE,CAAC,CAAa,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC;QACtE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACtB,yBAAyB,CAAC,GAAG,EAAE,gBAAgB,EAAE,sBAAsB,CAAC,CAAC;YACzE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;KACF,CAAC;IACF,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;QACjB,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IACjC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAA8C,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@metaobjectsdev/codegen-ts-tanstack",
-  "version": "0.21.3",
-  "description": "TanStack codegen for metaobjects — emits hooks and column definitions for TanStack Query and Table.",
+  "version": "0.21.4-rc.1",
+  "description": "TanStack codegen for metaobjects — TanStack Query hooks for every entity, plus TanStack Table column definitions and grid-state hooks for entities declaring a layout.dataGrid.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -44,8 +44,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@metaobjectsdev/metadata": "0.21.3",
-    "@metaobjectsdev/codegen-ts": "0.21.3",
+    "@metaobjectsdev/metadata": "0.21.4-rc.1",
+    "@metaobjectsdev/codegen-ts": "0.21.4-rc.1",
     "ts-poet": "^6.10.0"
   },
   "peerDependencies": {

package/src/data-grid-gate.ts

@@ -0,0 +1,54 @@
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import { LAYOUT_SUBTYPE_DATA_GRID, OBJECT_SUBTYPE_VALUE } from "@metaobjectsdev/metadata";
+import type { GenContext } from "@metaobjectsdev/codegen-ts";
+
+/** True when the entity declares (or inherits) at least one `layout.dataGrid`. */
+export function hasDataGridLayout(entity: MetaObject): boolean {
+  // layouts() is effective — own + inherited layouts (from extends:/super:).
+  return entity.layouts().some((l) => l.subType === LAYOUT_SUBTYPE_DATA_GRID);
+}
+
+/**
+ * Grid artifacts are opt-IN per entity: an entity produces one only when it declares
+ * a `layout.dataGrid` child. That is intended — but nothing used to say so. An
+ * adopter who wired `tanstackQuery() + tanstackGrid()` got `.hooks.ts` for every
+ * entity and `.columns.tsx` for none, and reasonably concluded codegen was broken
+ * (#287). The package description promising "hooks and column definitions"
+ * unconditionally made it worse.
+ *
+ * So the run itself now says it, following the repo's tell-at-`meta gen`-time
+ * precedent (#226 / #258) rather than a doc line that gets missed the same way this
+ * one was. Warning only: the exit code is untouched, and `--dry-run` reports it too,
+ * since generators run before the write phase branches.
+ *
+ * It fires ONLY when the generator emitted **nothing at all** — which is the reported
+ * condition ("no columns file for ANY entity") and makes the note self-extinguishing:
+ * declare one `layout.dataGrid` anywhere in the model and it goes quiet forever. A
+ * 50-entity model with 3 grids therefore stays silent, because that author plainly
+ * knows how grids work and a permanent 47-name nag is exactly the cry-wolf failure
+ * that got the old `timestampMode` warning deleted from `runner.ts` rather than left
+ * to fire forever.
+ *
+ * `passesOtherGates` is the generator's own filter MINUS the layout check, so the
+ * named set is exactly "objects the layout gate — and nothing else — held back".
+ * `object.value`s are excluded from it: a value object is a payload/DTO shape, never
+ * a grid candidate, so naming one would be advice worth ignoring.
+ */
+export function warnMissingDataGridLayout(
+  ctx: GenContext,
+  passesOtherGates: (entity: MetaObject) => boolean,
+  artifact: string,
+): void {
+  const candidates = ctx.entities.filter(
+    (e) => e.subType !== OBJECT_SUBTYPE_VALUE && passesOtherGates(e),
+  );
+  if (candidates.length === 0) return;
+  if (candidates.some(hasDataGridLayout)) return;   // the model uses grids — say nothing
+  ctx.warn(
+    `no ${artifact} emitted for ${candidates.map((e) => e.name).join(", ")} — grid ` +
+      `artifacts are opt-in per entity via a \`layout.dataGrid\` child, and no object in ` +
+      `this model declares one. Add e.g. ` +
+      `{"layout.dataGrid": {"name": "default", "@columns": ["id", "name"]}} to an entity ` +
+      `to emit its grid.`,
+  );
+}

package/src/tanstack-grid-hook.ts

@@ -1,6 +1,6 @@
 import type { MetaObject } from "@metaobjectsdev/metadata";
-import { LAYOUT_SUBTYPE_DATA_GRID } from "@metaobjectsdev/metadata";
-import { perEntity, type Generator, type GeneratorFactory, formatTs, entityOutputPath, emitsInstanceArtifacts, CODEGEN_ATTR_EMIT_TANSTACK } from "@metaobjectsdev/codegen-ts";
+import { perEntity, type Generator, type GeneratorFactory, formatTs, entityOutputPath, emitsInstanceArtifacts, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK, CODEGEN_ATTR_EMIT_GRID } from "@metaobjectsdev/codegen-ts";
+import { hasDataGridLayout, warnMissingDataGridLayout } from "./data-grid-gate.js";
 import { renderGridHookFile } from "./templates/grid-hook-file.js";
 
 export interface TanstackGridHookOpts {
@@ -8,11 +8,6 @@ export interface TanstackGridHookOpts {
   target?: string;
 }
 
-function hasDataGridLayout(entity: MetaObject): boolean {
-  // layouts() is effective — own + inherited layouts (from extends:/super:).
-  return entity.layouts().some((l) => l.subType === LAYOUT_SUBTYPE_DATA_GRID);
-}
-
 /**
  * Per-entity generator that emits <Entity>.grid.ts — one
  * use<Entity><Grid>Grid() hook per layout[dataGrid] declared on the entity.
@@ -22,29 +17,45 @@ function hasDataGridLayout(entity: MetaObject): boolean {
  */
 export const tanstackGridHook = function tanstackGridHook(opts?: TanstackGridHookOpts): Generator {
   const userFilter = opts?.filter ?? (() => true);
+  // Every gate EXCEPT the dataGrid-layout opt-in: the framework instance-artifact
+  // guard (skips abstract types), the metadata opt-out, and the user filter. Split
+  // out so the discoverability note can name exactly the entities the LAYOUT gate
+  // alone held back (#287).
+  //
+  // The TPH clause must MATCH tanstackGrid's exactly. A TPH subtype inherits its base's
+  // dataGrid layout via extends, so `hasDataGridLayout` is true for it — but tanstackGrid
+  // deliberately emits no per-subtype columns without an own `@emitGrid: true` (the base's
+  // polymorphic grid is the single source of truth). Without the same clause here, a TPH
+  // subtype got a `<Sub>.grid.ts` whose sibling `<Sub>.columns.tsx` is never emitted:
+  // a dangling `use<Sub>DefaultGrid()` with nothing to pair it with, and an outright
+  // TS2307 when the inherited layout carries an `@filter` preset (the hook then imports
+  // `<sub>DefaultFilter` from the missing columns module).
+  const passesOtherGates = (e: MetaObject): boolean =>
+    emitsInstanceArtifacts(e)
+    // ADR-0039: resolving — a concrete entity may inherit its @emit* opt-out flag via extends.
+    && e.attr(CODEGEN_ATTR_EMIT_TANSTACK) !== false
+    && userFilter(e)
+    && (!isTphSubtype(e) || e.attr(CODEGEN_ATTR_EMIT_GRID) === true);
+  const emit = perEntity(async (entity: MetaObject, ctx) => {
+    if (!ctx.renderContext) {
+      throw new Error("tanstack-grid-hook: renderContext is required (provided by runGen)");
+    }
+    return {
+      path: entityOutputPath(
+        ctx.renderContext.outputLayout,
+        entity.package,
+        `${entity.name}.grid.ts`,
+      ),
+      content: await formatTs(renderGridHookFile(entity, ctx.renderContext)),
+    };
+  });
   const generator: Generator = {
     name: "tanstack-grid-hook",
-    // AND-composes the framework instance-artifact guard (skips abstract types),
-    // opt-out, user filter, and dataGrid layout presence.
-    filter: (e: MetaObject) =>
-      emitsInstanceArtifacts(e)
-      // ADR-0039: resolving — a concrete entity may inherit its @emit* opt-out flag via extends.
-      && e.attr(CODEGEN_ATTR_EMIT_TANSTACK) !== false
-      && userFilter(e)
-      && hasDataGridLayout(e),
-    generate: perEntity(async (entity, ctx) => {
-      if (!ctx.renderContext) {
-        throw new Error("tanstack-grid-hook: renderContext is required (provided by runGen)");
-      }
-      return {
-        path: entityOutputPath(
-          ctx.renderContext.outputLayout,
-          entity.package,
-          `${entity.name}.grid.ts`,
-        ),
-        content: await formatTs(renderGridHookFile(entity, ctx.renderContext)),
-      };
-    }),
+    filter: (e: MetaObject) => passesOtherGates(e) && hasDataGridLayout(e),
+    generate: async (ctx) => {
+      warnMissingDataGridLayout(ctx, passesOtherGates, "<Entity>.grid.ts");
+      return emit(ctx);
+    },
   };
   if (opts?.target) {
     generator.target = opts.target;

package/src/tanstack-grid.ts

@@ -1,6 +1,6 @@
 import type { MetaObject } from "@metaobjectsdev/metadata";
-import { LAYOUT_SUBTYPE_DATA_GRID } from "@metaobjectsdev/metadata";
 import { perEntity, type Generator, type GeneratorFactory, formatTs, entityOutputPath, emitsInstanceArtifacts, isTphSubtype, CODEGEN_ATTR_EMIT_TANSTACK, CODEGEN_ATTR_EMIT_GRID } from "@metaobjectsdev/codegen-ts";
+import { hasDataGridLayout, warnMissingDataGridLayout } from "./data-grid-gate.js";
 import { renderColumnsFile } from "./templates/columns-file.js";
 
 export interface TanstackGridOpts {
@@ -8,11 +8,6 @@ export interface TanstackGridOpts {
   target?: string;
 }
 
-function hasDataGridLayout(entity: MetaObject): boolean {
-  // layouts() is effective — own + inherited layouts (from extends:/super:).
-  return entity.layouts().some((l) => l.subType === LAYOUT_SUBTYPE_DATA_GRID);
-}
-
 /**
  * Per-entity opt-out via `@emitTanstack: false`. Per-entity opt-IN: presence of
  * at least one `dataGrid` layout on the object. If both pass and the user-supplied
@@ -20,30 +15,36 @@ function hasDataGridLayout(entity: MetaObject): boolean {
  */
 export const tanstackGrid = function tanstackGrid(opts?: TanstackGridOpts): Generator {
   const userFilter = opts?.filter ?? (() => true);
+  // Every gate EXCEPT the dataGrid-layout opt-in: the framework instance-artifact
+  // guard (skips abstract types), the metadata opt-out, and the user filter.
+  // FR-017 Tier 3: a TPH discriminator base emits ONE polymorphic grid. Its
+  // subtypes inherit the base's dataGrid layout via extends, but per-subtype grids
+  // are opt-IN only (own `@emitGrid: true`) — otherwise the polymorphic grid is the
+  // single source of truth.
+  // Split out so the discoverability note can name exactly the entities the LAYOUT
+  // gate alone held back (#287) — an opted-out or abstract type is not a surprise.
+  const passesOtherGates = (e: MetaObject): boolean =>
+    emitsInstanceArtifacts(e)
+    // ADR-0039: resolving — a concrete entity may inherit its @emit* opt-out flag via extends.
+    && e.attr(CODEGEN_ATTR_EMIT_TANSTACK) !== false
+    && userFilter(e)
+    && (!isTphSubtype(e) || e.attr(CODEGEN_ATTR_EMIT_GRID) === true);
+  const emit = perEntity(async (entity: MetaObject, ctx) => {
+    if (!ctx.renderContext) {
+      throw new Error("tanstack-grid: renderContext is required (provided by runGen)");
+    }
+    return {
+      path: entityOutputPath(ctx.renderContext.outputLayout, entity.package, `${entity.name}.columns.tsx`),
+      content: await formatTs(renderColumnsFile(entity, ctx.renderContext)),
+    };
+  });
   const generator: Generator = {
     name: "tanstack-grid",
-    // Always set: AND-composes the framework instance-artifact guard (skips
-    // abstract types), opt-out, user filter, and dataGrid layout presence.
-    // FR-017 Tier 3: a TPH discriminator base emits ONE polymorphic grid. Its
-    // subtypes inherit the base's dataGrid layout via extends, but per-subtype
-    // grids are opt-IN only (own `@emitGrid: true`) — otherwise the polymorphic
-    // grid is the single source of truth.
-    filter: (e: MetaObject) =>
-      emitsInstanceArtifacts(e)
-      // ADR-0039: resolving — a concrete entity may inherit its @emit* opt-out flag via extends.
-      && e.attr(CODEGEN_ATTR_EMIT_TANSTACK) !== false
-      && userFilter(e)
-      && hasDataGridLayout(e)
-      && (!isTphSubtype(e) || e.attr(CODEGEN_ATTR_EMIT_GRID) === true),
-    generate: perEntity(async (entity, ctx) => {
-      if (!ctx.renderContext) {
-        throw new Error("tanstack-grid: renderContext is required (provided by runGen)");
-      }
-      return {
-        path: entityOutputPath(ctx.renderContext.outputLayout, entity.package, `${entity.name}.columns.tsx`),
-        content: await formatTs(renderColumnsFile(entity, ctx.renderContext)),
-      };
-    }),
+    filter: (e: MetaObject) => passesOtherGates(e) && hasDataGridLayout(e),
+    generate: async (ctx) => {
+      warnMissingDataGridLayout(ctx, passesOtherGates, "<Entity>.columns.tsx");
+      return emit(ctx);
+    },
   };
   if (opts?.target) {
     generator.target = opts.target;