@metaobjectsdev/codegen-ts-tanstack 0.5.0-rc.1

package/src/tanstack-grid.ts

@@ -0,0 +1,44 @@
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import { LAYOUT_SUBTYPE_DATA_GRID } from "@metaobjectsdev/metadata";
+import { perEntity, type Generator, type GeneratorFactory, formatTs, entityOutputPath } from "@metaobjectsdev/codegen-ts";
+import { renderColumnsFile } from "./templates/columns-file.js";
+
+export interface TanstackGridOpts {
+  filter?: (entity: MetaObject) => boolean;
+  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
+ * filter passes, the generator emits.
+ */
+export const tanstackGrid = function tanstackGrid(opts?: TanstackGridOpts): Generator {
+  const userFilter = opts?.filter ?? (() => true);
+  const generator: Generator = {
+    name: "tanstack-grid",
+    // Always set: AND-composes opt-out, user filter, and dataGrid layout presence.
+    filter: (e: MetaObject) =>
+      e.ownAttr("emitTanstack") !== false
+      && userFilter(e)
+      && hasDataGridLayout(e),
+    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)),
+      };
+    }),
+  };
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<TanstackGridOpts | void>;

package/src/tanstack-query.ts

@@ -0,0 +1,39 @@
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import { perEntity, type Generator, type GeneratorFactory, formatTs, entityOutputPath } from "@metaobjectsdev/codegen-ts";
+import { renderHooksFile } from "./templates/hooks-file.js";
+
+export interface TanstackQueryOpts {
+  filter?: (entity: MetaObject) => boolean;
+  target?: string;
+}
+
+/**
+ * Per-entity generator that emits <Entity>.hooks.ts — a query-key factory
+ * plus 2 query hooks and 3 mutation hooks backed by useEntityFetcher().
+ *
+ * Per-entity opt-out via `@emitTanstack: false` is honored. If the user
+ * supplies their own filter, both must pass (AND).
+ */
+export const tanstackQuery = function tanstackQuery(opts?: TanstackQueryOpts): Generator {
+  const userFilter = opts?.filter ?? (() => true);
+  const generator: Generator = {
+    name: "tanstack-query",
+    // AND-composes metadata opt-out with optional user filter.
+    filter: (e: MetaObject) => e.ownAttr("emitTanstack") !== false && userFilter(e),
+    generate: perEntity(async (entity, ctx) => {
+      if (!ctx.renderContext) {
+        throw new Error(
+          "tanstack-query: renderContext is required (provided by runGen)",
+        );
+      }
+      return {
+        path: entityOutputPath(ctx.renderContext.outputLayout, entity.package, `${entity.name}.hooks.ts`),
+        content: await formatTs(renderHooksFile(entity, ctx.renderContext)),
+      };
+    }),
+  };
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<TanstackQueryOpts | void>;

package/src/templates/columns-file.ts

@@ -0,0 +1,192 @@
+import { code, imp, joinCode, type Code } from "ts-poet";
+import type { MetaObject, MetaField } from "@metaobjectsdev/metadata";
+import {
+  LAYOUT_SUBTYPE_DATA_GRID,
+  LAYOUT_DATA_GRID_ATTR_PAGE_SIZE,
+  LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_FIELD,
+  LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_ORDER,
+  LAYOUT_DATA_GRID_ATTR_FILTERABLE,
+  LAYOUT_DATA_GRID_ATTR_FILTER,
+  LAYOUT_DATA_GRID_ATTR_COLUMNS,
+} from "@metaobjectsdev/metadata";
+import type { RenderContext } from "@metaobjectsdev/codegen-ts";
+import { GENERATED_HEADER, entityModuleSpecifier } from "@metaobjectsdev/codegen-ts";
+
+interface ColumnSpec {
+  id:        string;
+  header:    string;     // humanized label
+  viewKind:  string;     // field's view subtype, falls back to "text"
+  sortable?: boolean;
+  width?:    number;
+  renderer?: string;
+}
+
+interface GridSpec {
+  name:               string;
+  pageSize:           number;
+  defaultSortField?:  string;
+  defaultSortOrder?:  "asc" | "desc";
+  filterable:         boolean;
+  filter?:            Record<string, unknown>;   // desugared, load-time-validated @filter object
+  columns:            ColumnSpec[];
+}
+
+function humanize(s: string): string {
+  return s
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/^./, (c) => c.toUpperCase());
+}
+
+function fieldViewKind(field: MetaField): string {
+  const view = field.ownViews()[0];
+  return view?.subType ?? "text";
+}
+
+function fieldLabel(field: MetaField): string {
+  const view = field.ownViews()[0];
+  const label = view?.ownAttr("label");
+  if (typeof label === "string") return label;
+  return humanize(field.name);
+}
+
+/**
+ * Extract grid specs from an entity's dataGrid layouts, resolving column
+ * metadata against the entity's field list.
+ *
+ * Column set: read from @columns stringArray attr on the layout. If absent,
+ * fall back to all fields on the entity (pre-E-T2 behaviour, kept for
+ * backwards compat with metadata not yet migrated by E-T4).
+ */
+function extractGrids(entity: MetaObject): GridSpec[] {
+  // fields() and layouts() are both effective (own + inherited via extends:/super:).
+  const fieldsByName = new Map(
+    entity.fields().map((f) => [f.name, f] as const),
+  );
+
+  const grids: GridSpec[] = [];
+  for (const layout of entity.layouts()) {
+    if (layout.subType !== LAYOUT_SUBTYPE_DATA_GRID) continue;
+
+    // @columns is a stringArray attr on the layout (set by E-T4 migration).
+    // Fall back to all entity fields if not present.
+    const columnsAttr = layout.ownAttr(LAYOUT_DATA_GRID_ATTR_COLUMNS);
+    const columnNames: string[] = Array.isArray(columnsAttr)
+      ? (columnsAttr as unknown[]).filter((x): x is string => typeof x === "string")
+      : [...fieldsByName.keys()];
+
+    const columns: ColumnSpec[] = columnNames.flatMap((name) => {
+      const field = fieldsByName.get(name);
+      if (!field) return [];     // columns ref that doesn't exist on entity; defensive skip
+      const spec: ColumnSpec = {
+        id:       name,
+        header:   fieldLabel(field),
+        viewKind: fieldViewKind(field),
+      };
+      return [spec];
+    });
+
+    const sortField = layout.ownAttr(LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_FIELD);
+    const sortOrder = layout.ownAttr(LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_ORDER);
+
+    const filterAttr = layout.ownAttr(LAYOUT_DATA_GRID_ATTR_FILTER);
+    const grid: GridSpec = {
+      name:       layout.name || "default",
+      pageSize:   (layout.ownAttr(LAYOUT_DATA_GRID_ATTR_PAGE_SIZE) as number | undefined) ?? 25,
+      filterable: layout.ownAttr(LAYOUT_DATA_GRID_ATTR_FILTERABLE) === true,
+      columns,
+    };
+    if (typeof sortField === "string") grid.defaultSortField = sortField;
+    if (sortOrder === "asc" || sortOrder === "desc") grid.defaultSortOrder = sortOrder;
+    if (typeof filterAttr === "object" && filterAttr !== null && !Array.isArray(filterAttr)) {
+      grid.filter = filterAttr as Record<string, unknown>;
+    }
+    grids.push(grid);
+  }
+  return grids;
+}
+
+function renderColumnDef(col: ColumnSpec): string {
+  const parts: string[] = [];
+  parts.push(`    id: ${JSON.stringify(col.id)}`);
+  parts.push(`    accessorKey: ${JSON.stringify(col.id)}`);
+  parts.push(`    header: ${JSON.stringify(col.header)}`);
+  const meta: string[] = [`view: ${JSON.stringify(col.viewKind)}`];
+  if (col.sortable !== undefined) meta.push(`sortable: ${col.sortable}`);
+  if (col.width    !== undefined) meta.push(`width: ${col.width}`);
+  if (col.renderer !== undefined) meta.push(`renderer: ${JSON.stringify(col.renderer)}`);
+  parts.push(`    meta: { ${meta.join(", ")} }`);
+  return `  {\n${parts.join(",\n")}\n  }`;
+}
+
+export function renderColumnsFile(entity: MetaObject, ctx: RenderContext): string {
+  const entityName = entity.name;
+  const lcEntity   = entityName.charAt(0).toLowerCase() + entityName.slice(1);
+  const grids      = extractGrids(entity);
+
+  const ColumnDefSym = imp("t:ColumnDef@@tanstack/react-table");
+
+  // Track whether any grid emits a filter const so we know to import <Entity>Filter.
+  let hasFilterConst = false;
+
+  const sections = grids.map((grid) => {
+    const gridConstName    = `${lcEntity}${capitalize(grid.name)}Grid`;
+    const columnsConstName = `${lcEntity}${capitalize(grid.name)}Columns`;
+
+    const sortBlock = grid.defaultSortField && grid.defaultSortOrder
+      ? `  defaultSort: { field: ${JSON.stringify(grid.defaultSortField)}, order: ${JSON.stringify(grid.defaultSortOrder)} as const },\n`
+      : "";
+    const gridConst = code`
+export const ${gridConstName} = {
+  name:        ${JSON.stringify(grid.name)},
+  pageSize:    ${grid.pageSize},
+${sortBlock}  filterable:  ${grid.filterable},
+};
+`;
+    const colsLines = grid.columns.map(renderColumnDef).join(",\n");
+    const colsConst = code`
+export const ${columnsConstName}: ${ColumnDefSym}<${entityName}Row>[] = [
+${colsLines},
+];
+`;
+
+    // Emit per-grid filter const when @filter is set. The value is already a
+    // desugared, load-time-validated object — emit it verbatim.
+    let filterConstCode: Code | null = null;
+    if (grid.filter !== undefined) {
+      const filterConstName = `${lcEntity}${capitalize(grid.name)}Filter`;
+      hasFilterConst = true;
+      filterConstCode = code`
+export const ${filterConstName}: ${entityName}Filter = ${JSON.stringify(grid.filter, null, 2)};
+`;
+    }
+
+    return filterConstCode
+      ? code`${gridConst}\n${colsConst}\n${filterConstCode}`
+      : code`${gridConst}\n${colsConst}`;
+  });
+
+  const header =
+    `// ${GENERATED_HEADER}-tanstack — DO NOT EDIT.\n` +
+    `// Source metadata: ${entityName} (${entity.fqn()})\n`;
+
+  // Import the entity's own file. Same target → relative "./Entity"; cross
+  // target → importBase-qualified package path.
+  const entityModule = entityModuleSpecifier(
+    ctx.selfTarget,
+    ctx.entityModuleTarget,
+    entity.package,
+    entityName,
+    ctx.extStyle,
+  );
+  // Import <Entity>Row always; import <Entity>Filter only when a filter const is emitted.
+  const entityImportCode = hasFilterConst
+    ? code`import type { ${entityName} as ${entityName}Row, ${entityName}Filter } from ${JSON.stringify(entityModule)};`
+    : code`import type { ${entityName} as ${entityName}Row } from ${JSON.stringify(entityModule)};`;
+
+  const body: Code = joinCode(sections, { on: "\n" });
+  return header + entityImportCode.toString() + "\n" + body.toString();
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}

package/src/templates/grid-hook-file.ts

@@ -0,0 +1,155 @@
+// Generated grid-hook template — emits one use<Entity><Grid>Grid() per
+// layout[dataGrid] declared on the entity. The hook owns
+// {sorting, pagination, columnFilters, search} state and runs the query
+// against the entity's CRUD list route with withCount=1 (opt-in envelope).
+//
+// The hook returns the controlled-<EntityGrid> prop shape, so a consumer
+// page is just:
+//   const grid = useSubscriberDefaultGrid();
+//   <EntityGrid {...grid} columns={subscriberDefaultColumns} grid={subscriberDefaultGrid} />
+
+import { code, imp, joinCode, type Code } from "ts-poet";
+import type { MetaObject, MetaLayout } from "@metaobjectsdev/metadata";
+import { LAYOUT_SUBTYPE_DATA_GRID } from "@metaobjectsdev/metadata";
+import type { RenderContext } from "@metaobjectsdev/codegen-ts";
+import { GENERATED_HEADER, entityModuleSpecifier, siblingSpecifier } from "@metaobjectsdev/codegen-ts";
+
+interface GridSpec {
+  name: string;           // e.g. "default", "activeOnly"
+  pageSize: number;
+  hasFilterPreset: boolean;
+  defaultSortField?: string | undefined;
+  defaultSortOrder?: "asc" | "desc" | undefined;
+}
+
+function extractGrids(entity: MetaObject): GridSpec[] {
+  const out: GridSpec[] = [];
+  for (const l of entity.layouts() as MetaLayout[]) {
+    if (l.subType !== LAYOUT_SUBTYPE_DATA_GRID) continue;
+    out.push({
+      name: l.name || "default",
+      pageSize: l.pageSize ?? 25,
+      hasFilterPreset: l.filter !== undefined,
+      defaultSortField: l.defaultSortField,
+      defaultSortOrder: l.defaultSortOrder as "asc" | "desc" | undefined,
+    });
+  }
+  return out;
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+export function renderGridHookFile(entity: MetaObject, ctx: RenderContext): string {
+  const entityName = entity.name;
+  const lcEntity   = entityName.charAt(0).toLowerCase() + entityName.slice(1);
+  const grids      = extractGrids(entity);
+
+  if (grids.length === 0) return "";
+
+  // Import the entity's own file. Same target → relative "./Entity"; cross
+  // target → importBase-qualified package path.
+  const entityModule = entityModuleSpecifier(
+    ctx.selfTarget,
+    ctx.entityModuleTarget,
+    entity.package,
+    entityName,
+    ctx.extStyle,
+  );
+
+  // ts-poet symbols (imp()) — typed and deduped on emit.
+  const useStateSym = imp("useState@react");
+  const useMemoSym  = imp("useMemo@react");
+  const useQuerySym = imp("useQuery@@tanstack/react-query");
+  const SortingStateSym       = imp("t:SortingState@@tanstack/react-table");
+  const PaginationStateSym    = imp("t:PaginationState@@tanstack/react-table");
+  const ColumnFiltersStateSym = imp("t:ColumnFiltersState@@tanstack/react-table");
+  const useEntityFetcherSym = imp("useEntityFetcher@@metaobjectsdev/tanstack");
+  const buildFilterQsSym    = imp("buildFilterQs@@metaobjectsdev/runtime-web");
+
+  const entityImports: Code = code`
+import { ${entityName} } from ${JSON.stringify(entityModule)};
+import type { ${entityName} as ${entityName}Row } from ${JSON.stringify(entityModule)};
+`;
+
+  // Collect names of all filter preset consts needed.
+  const filterPresetImports: string[] = grids
+    .filter((g) => g.hasFilterPreset)
+    .map((g) => `${lcEntity}${capitalize(g.name)}Filter`);
+
+  // Columns file is a same-target sibling of the grid-hook (both emitted to
+  // selfTarget) — always relative, package-layout aware.
+  const columnsModule = siblingSpecifier(ctx.selfTarget, entity.package, `${entityName}.columns`, ctx.extStyle);
+  const filterPresetImportCode: Code =
+    filterPresetImports.length > 0
+      ? code`import { ${filterPresetImports.join(", ")} } from ${JSON.stringify(columnsModule)};\n`
+      : code``;
+
+  const sections: Code[] = grids.map((grid) => {
+    const cap      = capitalize(grid.name);
+    const hookName = `use${entityName}${cap}Grid`;
+    const presetConst = grid.hasFilterPreset ? `${lcEntity}${cap}Filter` : null;
+
+    const initialSorting = grid.defaultSortField
+      ? `[{ id: ${JSON.stringify(grid.defaultSortField)}, desc: ${JSON.stringify(grid.defaultSortOrder === "desc")} }]`
+      : `[]`;
+    const initialPagination = `{ pageIndex: 0, pageSize: ${grid.pageSize} }`;
+
+    return code`
+export function ${hookName}() {
+  const [sorting,       setSorting]       = ${useStateSym}<${SortingStateSym}>(${initialSorting});
+  const [pagination,    setPagination]    = ${useStateSym}<${PaginationStateSym}>(${initialPagination});
+  const [columnFilters, setColumnFilters] = ${useStateSym}<${ColumnFiltersStateSym}>([]);
+  const [search,        setSearch]        = ${useStateSym}<string>("");
+
+  const fetcher = ${useEntityFetcherSym}();
+
+  const qs = ${useMemoSym}(() => {
+    const filterObj: Record<string, unknown> = ${presetConst ? `{ ...${presetConst} }` : `{}`};
+    for (const f of columnFilters) {
+      filterObj[f.id] = f.value as unknown;
+    }
+    const sort = sorting.length > 0
+      ? \`\${sorting[0].id}:\${sorting[0].desc ? "desc" : "asc"}\`
+      : undefined;
+    return ${buildFilterQsSym}({
+      ...filterObj,
+      ...(sort !== undefined ? { sort } : {}),
+      limit:  pagination.pageSize,
+      offset: pagination.pageIndex * pagination.pageSize,
+      ...(search !== "" ? { search } : {}),
+      withCount: 1,
+    });
+  }, [sorting, pagination, columnFilters, search]);
+
+  const query = ${useQuerySym}<{ rows: ${entityName}Row[]; total: number }>({
+    queryKey: [${JSON.stringify(lcEntity)}, "grid", ${JSON.stringify(grid.name)}, qs],
+    queryFn: () => fetcher<{ rows: ${entityName}Row[]; total: number }>(
+      \`\${${entityName}.$apiPrefix}\${${entityName}.$path}?\${qs}\`,
+    ),
+  });
+
+  return {
+    data: query.data?.rows ?? [],
+    rowCount: query.data?.total ?? 0,
+    state: { sorting, pagination, columnFilters },
+    onSortingChange:       setSorting,
+    onPaginationChange:    setPagination,
+    onColumnFiltersChange: setColumnFilters,
+    search,
+    onSearchChange: setSearch,
+    isLoading: query.isLoading,
+    error:     query.error,
+  };
+}
+`;
+  });
+
+  const header =
+    `// ${GENERATED_HEADER}-tanstack — DO NOT EDIT.\n` +
+    `// Source metadata: ${entityName} (${entity.fqn()})\n`;
+
+  const body = joinCode(sections, { on: "\n" });
+  return header + entityImports.toString() + filterPresetImportCode.toString() + body.toString();
+}

package/src/templates/hooks-file.ts

@@ -0,0 +1,235 @@
+import { code, imp, joinCode, type Code } from "ts-poet";
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import type { RenderContext } from "@metaobjectsdev/codegen-ts";
+import { GENERATED_HEADER, isProjection, pluralize, entityModuleSpecifier } from "@metaobjectsdev/codegen-ts";
+
+/**
+ * Render <Entity>.hooks.ts — query-key factory + 2 query hooks + (for non-projections) 3 mutation hooks.
+ *
+ * Projections (view-backed, read-only) emit only:
+ *   - <camel>Keys query-key factory
+ *   - use<Entity>(id)       — useQuery on GET :id
+ *   - use<Entities>(filter) — useQuery on list
+ *
+ * Full (writable) entities additionally emit:
+ *   - useCreate<Entity>
+ *   - useUpdate<Entity>
+ *   - useDelete<Entity>
+ *
+ * All hooks call useEntityFetcher() (from @metaobjectsdev/tanstack) for
+ * the underlying HTTP. Mutations aggressively invalidate <entity>Keys.all().
+ */
+export function renderHooksFile(entity: MetaObject, ctx: RenderContext): string {
+  // Import the entity's own file. Same target → relative "./Entity"; cross
+  // target → importBase-qualified package path.
+  const entityModule = entityModuleSpecifier(
+    ctx.selfTarget,
+    ctx.entityModuleTarget,
+    entity.package,
+    entity.name,
+    ctx.extStyle,
+  );
+  if (isProjection(entity)) {
+    return renderReadOnlyHooksFile(entity, entityModule);
+  }
+  return renderFullHooksFile(entity, entityModule);
+}
+
+// ---------------------------------------------------------------------------
+// Read-only path (projections)
+// ---------------------------------------------------------------------------
+
+function renderReadOnlyHooksFile(entity: MetaObject, entityModule: string): string {
+  const entityName = entity.name;
+  const entityNamePlural = pluralize(entityName);
+  const lcEntity = entityName.charAt(0).toLowerCase() + entityName.slice(1);
+  const keysVar = `${lcEntity}Keys`;
+
+  const useQuerySym = imp("useQuery@@tanstack/react-query");
+  const useQueryOptionsSym = imp("t:UseQueryOptions@@tanstack/react-query");
+  const useQueryResultSym = imp("t:UseQueryResult@@tanstack/react-query");
+  const useEntityFetcherSym = imp("useEntityFetcher@@metaobjectsdev/tanstack");
+  const buildFilterQsSym = imp("buildFilterQs@@metaobjectsdev/runtime-web");
+
+  const entityImports: Code = code`
+import {
+  ${entityName},
+  type ${entityName} as ${entityName}Row,
+  type ${entityName}Filter,
+} from ${JSON.stringify(entityModule)};
+`;
+
+  const queryKeys: Code = code`
+export const ${keysVar} = {
+  all:     () => [${JSON.stringify(lcEntity)}] as const,
+  lists:   () => [...${keysVar}.all(), "list"] as const,
+  list:    (filter?: ${entityName}Filter) => [...${keysVar}.lists(), filter ?? {}] as const,
+  details: () => [...${keysVar}.all(), "detail"] as const,
+  detail:  (id: number) => [...${keysVar}.details(), id] as const,
+};
+`;
+
+  const queries: Code = code`
+export function use${entityName}(
+  id: number,
+  opts?: Omit<${useQueryOptionsSym}<${entityName}Row>, "queryKey" | "queryFn">,
+): ${useQueryResultSym}<${entityName}Row> {
+  const fetcher = ${useEntityFetcherSym}();
+  return ${useQuerySym}<${entityName}Row>({
+    queryKey: ${keysVar}.detail(id),
+    queryFn: () => fetcher<${entityName}Row>(\`\${${entityName}.$apiPrefix}\${${entityName}.$path}/\${id}\`),
+    ...opts,
+  });
+}
+
+export function use${entityNamePlural}(
+  filter?: ${entityName}Filter,
+  opts?: Omit<${useQueryOptionsSym}<${entityName}Row[]>, "queryKey" | "queryFn">,
+): ${useQueryResultSym}<${entityName}Row[]> {
+  const fetcher = ${useEntityFetcherSym}();
+  const qs = filter ? "?" + ${buildFilterQsSym}(filter as Record<string, unknown>) : "";
+  return ${useQuerySym}<${entityName}Row[]>({
+    queryKey: ${keysVar}.list(filter),
+    queryFn: () => fetcher<${entityName}Row[]>(\`\${${entityName}.$apiPrefix}\${${entityName}.$path}\${qs}\`),
+    ...opts,
+  });
+}
+`;
+
+  const body: Code = joinCode([queryKeys, queries], { on: "\n" });
+
+  const header =
+    `// ${GENERATED_HEADER}-tanstack — DO NOT EDIT.\n` +
+    `// Source metadata: ${entityName} (${entity.fqn()})\n`;
+  return header + entityImports.toString() + body.toString();
+}
+
+// ---------------------------------------------------------------------------
+// Full path (writable entities — table-backed or write-through)
+// ---------------------------------------------------------------------------
+
+function renderFullHooksFile(entity: MetaObject, entityModule: string): string {
+  const entityName = entity.name;
+  const entityNamePlural = pluralize(entityName);
+  const lcEntity = entityName.charAt(0).toLowerCase() + entityName.slice(1);
+  const keysVar = `${lcEntity}Keys`;
+
+  const useMutationSym = imp("useMutation@@tanstack/react-query");
+  const useQuerySym = imp("useQuery@@tanstack/react-query");
+  const useQueryClientSym = imp("useQueryClient@@tanstack/react-query");
+  const useQueryOptionsSym = imp("t:UseQueryOptions@@tanstack/react-query");
+  const useMutationOptionsSym = imp("t:UseMutationOptions@@tanstack/react-query");
+  const useQueryResultSym = imp("t:UseQueryResult@@tanstack/react-query");
+  const useMutationResultSym = imp("t:UseMutationResult@@tanstack/react-query");
+  const useEntityFetcherSym = imp("useEntityFetcher@@metaobjectsdev/tanstack");
+  const buildFilterQsSym = imp("buildFilterQs@@metaobjectsdev/runtime-web");
+
+  const entityImports: Code = code`
+import {
+  ${entityName},
+  type ${entityName} as ${entityName}Row,
+  type ${entityName}Insert,
+  type ${entityName}Update,
+  type ${entityName}Filter,
+} from ${JSON.stringify(entityModule)};
+`;
+
+  const queryKeys: Code = code`
+export const ${keysVar} = {
+  all:     () => [${JSON.stringify(lcEntity)}] as const,
+  lists:   () => [...${keysVar}.all(), "list"] as const,
+  list:    (filter?: ${entityName}Filter) => [...${keysVar}.lists(), filter ?? {}] as const,
+  details: () => [...${keysVar}.all(), "detail"] as const,
+  detail:  (id: number) => [...${keysVar}.details(), id] as const,
+};
+`;
+
+  const queries: Code = code`
+export function use${entityName}(
+  id: number,
+  opts?: Omit<${useQueryOptionsSym}<${entityName}Row>, "queryKey" | "queryFn">,
+): ${useQueryResultSym}<${entityName}Row> {
+  const fetcher = ${useEntityFetcherSym}();
+  return ${useQuerySym}<${entityName}Row>({
+    queryKey: ${keysVar}.detail(id),
+    queryFn: () => fetcher<${entityName}Row>(\`\${${entityName}.$apiPrefix}\${${entityName}.$path}/\${id}\`),
+    ...opts,
+  });
+}
+
+export function use${entityNamePlural}(
+  filter?: ${entityName}Filter,
+  opts?: Omit<${useQueryOptionsSym}<${entityName}Row[]>, "queryKey" | "queryFn">,
+): ${useQueryResultSym}<${entityName}Row[]> {
+  const fetcher = ${useEntityFetcherSym}();
+  const qs = filter ? "?" + ${buildFilterQsSym}(filter as Record<string, unknown>) : "";
+  return ${useQuerySym}<${entityName}Row[]>({
+    queryKey: ${keysVar}.list(filter),
+    queryFn: () => fetcher<${entityName}Row[]>(\`\${${entityName}.$apiPrefix}\${${entityName}.$path}\${qs}\`),
+    ...opts,
+  });
+}
+`;
+
+  const mutations: Code = code`
+export function useCreate${entityName}(
+  opts?: Omit<${useMutationOptionsSym}<${entityName}Row, Error, ${entityName}Insert>, "mutationFn">,
+): ${useMutationResultSym}<${entityName}Row, Error, ${entityName}Insert> {
+  const fetcher = ${useEntityFetcherSym}();
+  const qc = ${useQueryClientSym}();
+  return ${useMutationSym}<${entityName}Row, Error, ${entityName}Insert>({
+    mutationFn: (input) => fetcher<${entityName}Row>(\`\${${entityName}.$apiPrefix}\${${entityName}.$path}\`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input),
+    }),
+    ...opts,
+    onSuccess: (...args) => {
+      qc.invalidateQueries({ queryKey: ${keysVar}.all() });
+      opts?.onSuccess?.(...args);
+    },
+  });
+}
+
+export function useUpdate${entityName}(
+  opts?: Omit<${useMutationOptionsSym}<${entityName}Row, Error, { id: number; input: ${entityName}Update }>, "mutationFn">,
+): ${useMutationResultSym}<${entityName}Row, Error, { id: number; input: ${entityName}Update }> {
+  const fetcher = ${useEntityFetcherSym}();
+  const qc = ${useQueryClientSym}();
+  return ${useMutationSym}({
+    mutationFn: ({ id, input }) => fetcher<${entityName}Row>(\`\${${entityName}.$apiPrefix}\${${entityName}.$path}/\${id}\`, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input),
+    }),
+    ...opts,
+    onSuccess: (...args) => {
+      qc.invalidateQueries({ queryKey: ${keysVar}.all() });
+      opts?.onSuccess?.(...args);
+    },
+  });
+}
+
+export function useDelete${entityName}(
+  opts?: Omit<${useMutationOptionsSym}<void, Error, number>, "mutationFn">,
+): ${useMutationResultSym}<void, Error, number> {
+  const fetcher = ${useEntityFetcherSym}();
+  const qc = ${useQueryClientSym}();
+  return ${useMutationSym}({
+    mutationFn: (id) => fetcher<void>(\`\${${entityName}.$apiPrefix}\${${entityName}.$path}/\${id}\`, { method: "DELETE" }),
+    ...opts,
+    onSuccess: (...args) => {
+      qc.invalidateQueries({ queryKey: ${keysVar}.all() });
+      opts?.onSuccess?.(...args);
+    },
+  });
+}
+`;
+
+  const body: Code = joinCode([queryKeys, queries, mutations], { on: "\n" });
+
+  const header =
+    `// ${GENERATED_HEADER}-tanstack — DO NOT EDIT.\n` +
+    `// Source metadata: ${entityName} (${entity.fqn()})\n`;
+  return header + entityImports.toString() + body.toString();
+}