@shwfed/config 3.0.0 → 3.0.2

package/dist/runtime/components/table/columns/2026-07-12/com.shwfed.table.column.dynamic/schema.d.ts

@@ -0,0 +1,63 @@
+import { Schema } from 'effect';
+import type { Environment } from '../../../../../vendor/cel-js/lib/index.js';
+import type { ColumnExpand } from '../../../utils/resolve.js';
+export declare const type: "com.shwfed.table.column.dynamic";
+export declare const compatibilityDate: "2026-07-12";
+export declare const metadata: {
+    readonly name: "动态列";
+    readonly icon: "fluent:table-lightning-20-regular";
+    readonly description: import("../../../../../share/markdown.js").Markdown;
+};
+declare const DynColumnKind: Schema.Literal<["text", "number", "date"]>;
+export type DynColumnKindValue = Schema.Schema.Type<typeof DynColumnKind>;
+/**
+ * The narrow, module-owned DTO the `transform` must emit per column. Keeping
+ * this contract closed (vs. exposing the internal column union) means internal
+ * schema evolution never breaks app config, the transform stays terse, and dyn
+ * cols auto-upgrade to the current renderer. Each element is decoded against
+ * this at runtime (partial-drop, loud) — the strongest static guarantee is
+ * only that `transform` returns `list<dyn>`.
+ */
+export declare const DynColumnDescriptor: Schema.Struct<{
+    key: Schema.filter<typeof Schema.String>;
+    header: typeof Schema.String;
+    kind: Schema.Literal<["text", "number", "date"]>;
+    accessor: Schema.filter<typeof Schema.String>;
+    /** px column width; defaults to 150. */
+    width: Schema.optional<typeof Schema.Number>;
+    /** Client-side sort by accessed value. */
+    sortable: Schema.optional<typeof Schema.Boolean>;
+    /** Backend sort field; only needed for server-side sort. */
+    sortKey: Schema.optional<typeof Schema.String>;
+    /** Default-hidden; the user can re-show it. */
+    hidden: Schema.optional<typeof Schema.Boolean>;
+    /** Header hover text; wrapped into a Locale by `expand`. */
+    tooltip: Schema.optional<typeof Schema.String>;
+    /** Text / number alignment. */
+    align: Schema.optional<Schema.Literal<["left", "center", "right"]>>;
+}>;
+export type DynColumnDescriptorValue = Schema.Schema.Type<typeof DynColumnDescriptor>;
+export declare function schema(configure: (env: Environment) => void): Schema.Struct<{
+    request: Schema.Schema<string, string, never>;
+    transform: Schema.Schema<string, string, never>;
+    id: Schema.refine<string, typeof Schema.String>;
+    groupId: Schema.optional<typeof Schema.UUID>;
+    type: Schema.Literal<["com.shwfed.table.column.dynamic"]>;
+    compatibilityDate: Schema.Literal<["2026-07-12"]>;
+}>;
+export type Value = Schema.Schema.Type<ReturnType<typeof schema>>;
+export declare function defaults(): Partial<Value>;
+/**
+ * Runtime generator. Evaluates the block's `transform` against the fetched
+ * `json`, then decodes each element against `DynColumnDescriptor` — keeping the
+ * valid, dropping the invalid / duplicate / colliding (partial-drop, loud).
+ * Three failure layers (see the design doc):
+ *   1. transform throws / returns a non-list → the whole block yields 0 columns
+ *      (other columns render normally).
+ *   2. individual elements malformed / duplicate `key` / `key` colliding with a
+ *      static id → drop that element alone, first-wins on keys.
+ *   3. per-row accessor eval throws → handled downstream (`translateColumn`'s
+ *      `accessorFn` try/catches per row) — not here.
+ */
+export declare const expand: ColumnExpand;
+export {};

package/dist/runtime/components/table/columns/2026-07-12/com.shwfed.table.column.dynamic/schema.js

@@ -0,0 +1,157 @@
+import { Effect, Either, Schema } from "effect";
+import { Expression, HttpRequestResult } from "../../../../../share/expression.js";
+import { columnIdentityFields } from "../../../utils/shared.js";
+import { md } from "../../../../../share/markdown.js";
+export const type = "com.shwfed.table.column.dynamic";
+export const compatibilityDate = "2026-07-12";
+export const metadata = {
+  name: "\u52A8\u6001\u5217",
+  icon: "fluent:table-lightning-20-regular",
+  description: md`
+    运行时动态列：由服务端返回的**列定义列表**生成一组普通列，而非在设计时逐列编写。
+    适用于列集合随租户 / 渠道变化、无法预先固定的场景。本块自身不渲染单元格，只是一个
+    生成器 —— 它产出的每一列都是普通的文本 / 数值 / 日期列，可照常调整宽度、排序、隐藏。
+  `
+};
+const DynColumnKind = Schema.Literal("text", "number", "date");
+const DynColumnAlign = Schema.Literal("left", "center", "right");
+export const DynColumnDescriptor = Schema.Struct({
+  // Column `id` — stable, unique within the table; the identity customization /
+  // sort / selection key off. For the legacy app this is `parameter_name`.
+  key: Schema.String.pipe(Schema.minLength(1)),
+  // Column label; wrapped into a Locale by `expand`.
+  header: Schema.String,
+  // Selects the leaf renderer (closed vocabulary).
+  kind: DynColumnKind,
+  // Per-row value CEL (`row` / `index` in scope) — the only field carrying
+  // app-specific read logic. Treated as an opaque per-row expression.
+  accessor: Schema.String.pipe(Schema.minLength(1)),
+  /** px column width; defaults to 150. */
+  width: Schema.optional(Schema.Number),
+  /** Client-side sort by accessed value. */
+  sortable: Schema.optional(Schema.Boolean),
+  /** Backend sort field; only needed for server-side sort. */
+  sortKey: Schema.optional(Schema.String),
+  /** Default-hidden; the user can re-show it. */
+  hidden: Schema.optional(Schema.Boolean),
+  /** Header hover text; wrapped into a Locale by `expand`. */
+  tooltip: Schema.optional(Schema.String),
+  /** Text / number alignment. */
+  align: Schema.optional(DynColumnAlign)
+});
+const KIND_TO_COLUMN = {
+  text: { type: "com.shwfed.table.column.text", compatibilityDate: "2026-04-14" },
+  number: { type: "com.shwfed.table.column.number", compatibilityDate: "2026-04-14" },
+  date: { type: "com.shwfed.table.column.date", compatibilityDate: "2026-04-14" }
+};
+const DEFAULT_DATE_FORMAT = "yyyy-MM-dd";
+const DEFAULT_WIDTH = 150;
+export function schema(configure) {
+  const CelRequest = Expression({ configure, resultType: HttpRequestResult });
+  const CelTransform = Expression({
+    configure: (env) => {
+      configure(env);
+      const declared = new Set(env.getDefinitions().variables.map((v) => v.name));
+      if (!declared.has("json")) {
+        env.registerVariable("json", "optional<dyn>", {
+          label: "HTTP \u54CD\u5E94\u4F53",
+          description: "\u5217\u5B9A\u4E49\u63A5\u53E3\u7684\u54CD\u5E94\u4F53\uFF08\u5DF2\u89E3\u6790 JSON\uFF09\uFF1B\u672A\u83B7\u53D6\u5230\u65F6\u4E3A none\uFF0C\u901A\u8FC7 `json.orValue(...)` \u89E3\u5305"
+        });
+      }
+      if (!declared.has("query")) {
+        env.registerVariable("query", "dyn", {
+          label: "\u641C\u7D22\u6761\u4EF6",
+          description: "\u641C\u7D22\u6761\u4EF6\u5F53\u524D\u72B6\u6001\uFF1B\u672A\u914D\u7F6E\u641C\u7D22\u6761\u4EF6\u65F6\u4E3A\u7A7A\u5BF9\u8C61"
+        });
+      }
+    },
+    resultType: (t) => t.startsWith("list") || t === "dyn" || t.startsWith("optional")
+  });
+  return Schema.Struct({
+    type: Schema.Literal(type),
+    compatibilityDate: Schema.Literal(compatibilityDate),
+    ...columnIdentityFields(),
+    request: CelRequest.annotations({
+      title: "\u5217\u5B9A\u4E49\u8BF7\u6C42",
+      description: md`
+        获取列定义列表的 HTTP 请求表达式（与数据源 \`request\` 同为 \`HttpRequest\` 形状）。
+        该请求**独立于表格状态** —— 作用域内没有 \`query\` / \`pageIndex\` / \`pageSize\` /
+        \`sorts\`，列集合不会随搜索、翻页、排序而变化。
+      `
+    }),
+    transform: CelTransform.annotations({
+      title: "\u5217\u5B9A\u4E49\u6620\u5C04",
+      description: md`
+        将 \`json\`（列定义响应体，用 \`json.orValue([])\` 解包）映射为一组列描述（\`list\`）。
+        每个元素需符合固定字段（注意 CEL 映射字面量的键要加引号）：\`key\`（列唯一标识）、
+        \`header\`（标题）、\`kind\`（\`"text"\`/\`"number"\`/\`"date"\`）、\`accessor\`（读取该列每行取值的
+        CEL，\`row\` 在作用域内）；可选 \`width\` / \`sortable\` / \`sortKey\` / \`hidden\` / \`tooltip\` /
+        \`align\`。**所有与后端数据契约相关的知识都在这里**。
+      `
+    })
+  }).annotations({ title: "DynamicColumns", description: "\u8FD0\u884C\u65F6\u52A8\u6001\u5217\uFF08\u7531\u670D\u52A1\u7AEF\u5217\u5B9A\u4E49\u751F\u6210\uFF09" });
+}
+export function defaults() {
+  return { request: "", transform: "" };
+}
+function wrapLocale(text) {
+  return [{ locale: "zh", message: text }];
+}
+function toColumnValue(d, block) {
+  const pin = KIND_TO_COLUMN[d.kind];
+  const col = {
+    id: d.key,
+    type: pin.type,
+    compatibilityDate: pin.compatibilityDate,
+    title: wrapLocale(d.header),
+    accessor: d.accessor,
+    size: d.width ?? DEFAULT_WIDTH
+  };
+  if (block.groupId !== void 0) col.groupId = block.groupId;
+  if (d.sortable) col.enableSorting = true;
+  if (d.sortKey !== void 0 && d.sortKey.length > 0) col.sortKey = d.sortKey;
+  if (d.hidden) col.hidden = true;
+  if (d.tooltip !== void 0 && d.tooltip.length > 0) col.tooltip = wrapLocale(d.tooltip);
+  if (d.align !== void 0) col.align = d.align;
+  if (d.kind === "date") col.format = DEFAULT_DATE_FORMAT;
+  return col;
+}
+const decodeDescriptor = Schema.decodeUnknownEither(DynColumnDescriptor);
+export const expand = (value, { json, $cel, context, seen }) => {
+  const block = value;
+  if (!block.transform || block.transform.trim().length === 0) return [];
+  let listRaw;
+  try {
+    listRaw = Effect.runSync($cel(block.transform, { ...context, json }));
+  } catch (e) {
+    console.warn("[shwfed-table] dynamic columns transform failed", e);
+    return [];
+  }
+  if (!Array.isArray(listRaw)) {
+    console.warn("[shwfed-table] dynamic columns transform did not return a list", listRaw);
+    return [];
+  }
+  const out = [];
+  const claimed = new Set(seen);
+  let dropped = 0;
+  for (const element of listRaw) {
+    const decoded = decodeDescriptor(element);
+    if (Either.isLeft(decoded)) {
+      dropped++;
+      console.warn("[shwfed-table] dropped invalid dynamic column descriptor", element);
+      continue;
+    }
+    const descriptor = decoded.right;
+    if (claimed.has(descriptor.key)) {
+      dropped++;
+      console.warn("[shwfed-table] dropped duplicate/colliding dynamic column key", descriptor.key);
+      continue;
+    }
+    claimed.add(descriptor.key);
+    out.push(toColumnValue(descriptor, block));
+  }
+  if (dropped > 0) {
+    console.warn(`[shwfed-table] ${dropped} of ${listRaw.length} dynamic columns dropped`);
+  }
+  return out;
+};

package/dist/runtime/components/table/index.vue

@@ -110,6 +110,7 @@ const inheritedContext = injectCELContext();
 const viewportRef = ref(null);
 const containerRef = computed(() => viewportRef.value?.viewportElement ?? null);
 const appliedInitialStateKey = ref("");
+const descriptorJson = ref({});
 const frozenGrowColumns = ref(/* @__PURE__ */ new Set());
 function isEffectiveGrow(column) {
   return !!column.columnDef.meta?.grow && !frozenGrowColumns.value.has(column.id);
@@ -136,7 +137,7 @@ let resizeGestureSeen = false;
 function restoreFrozenGrowColumns() {
   const userSizing = customization.snapshot()?.columnSizing;
   if (!userSizing) return;
-  const grows = (config.value?.columns ?? []).filter((c) => c.grow === true && userSizing[c.id] !== void 0);
+  const grows = effectiveColumns.value.filter((c) => c.grow === true && userSizing[c.id] !== void 0);
   if (grows.length === 0) return;
   const next = new Set(frozenGrowColumns.value);
   grows.forEach((c) => next.add(c.id));
@@ -166,10 +167,44 @@ function mergeCelContext(local) {
 }
 function currentSorts() {
   const sortKeyById = new Map(
-    (config.value?.columns ?? []).map((c) => [c.id, c.sortKey]).filter((e) => typeof e[1] === "string" && e[1].length > 0)
+    // `effectiveColumns`, not `config.columns`: a dyn column's `sortKey` lives
+    // on the generated child, absent from the config's generator block.
+    effectiveColumns.value.map((c) => [c.id, c.sortKey]).filter((e) => typeof e[1] === "string" && e[1].length > 0)
   );
   return tableApi.getState().sorting.map((s) => ({ key: sortKeyById.get(s.id), mode: s.desc ? "desc" : "asc" })).filter((s) => s.key !== void 0);
 }
+const effectiveColumns = computed(() => {
+  const cols = config.value?.columns;
+  if (!cols) return [];
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const col of cols) {
+    const entry = findColumn(col.type, col.compatibilityDate);
+    if (!entry?.expand) {
+      out.push(col);
+      seen.add(col.id);
+      continue;
+    }
+    const children = entry.expand(col, {
+      // `Option.none()` (not bare `undefined`) before the fetch lands, so the
+      // transform's `json.orValue(...)` yields an empty list rather than
+      // throwing on every pre-fetch render.
+      json: descriptorJson.value[col.id] ?? Option.none(),
+      $cel,
+      // Inherited host vars + inert `query` (pinned empty so the column set is
+      // independent of live search); `expand` injects `json` on top.
+      context: { ...celBindings(inheritedContext), query: {} },
+      getLocaleText,
+      seen
+    });
+    for (const child of children) {
+      out.push(child);
+      seen.add(child.id);
+    }
+  }
+  return out;
+});
+const customizationConfig = computed(() => config.value ? { ...config.value, columns: effectiveColumns.value } : void 0);
 function translateColumn(column) {
   const entry = findColumn(column.type, column.compatibilityDate);
   if (!entry) {
@@ -208,7 +243,7 @@ const columns = computed(() => {
   const groupById = new Map(cfg.groups?.map((g) => [g.id, g]) ?? []);
   const out = [];
   let current = null;
-  for (const col of cfg.columns) {
+  for (const col of effectiveColumns.value) {
     const def = translateColumn(col);
     const group = col.groupId ? groupById.get(col.groupId) : void 0;
     if (!group) {
@@ -529,6 +564,7 @@ provideEventTarget(tableInstanceId, {
 });
 const queryRef = ref(null);
 onMounted(async () => {
+  void fetchDescriptors();
   await queryRef.value?.seeded;
   persistedQuery.restore();
   await fetchDataSource();
@@ -574,6 +610,44 @@ watchDebounced(
   },
   { debounce: 200 }
 );
+function dynColumnBlocks() {
+  return (config.value?.columns ?? []).filter((c) => {
+    const entry = findColumn(c.type, c.compatibilityDate);
+    return typeof entry?.expand === "function" && typeof c.request === "string" && c.request.length > 0;
+  });
+}
+async function fetchDescriptors() {
+  for (const block of dynColumnBlocks()) {
+    const expr = block.request;
+    const program = Effect.gen(function* () {
+      return yield* fetchJsonOption(yield* $cel(expr, celBindings(inheritedContext)));
+    });
+    try {
+      const jsonOpt = await Effect.runPromise(Effect.provide(program, Fetch.layer));
+      descriptorJson.value = { ...descriptorJson.value, [block.id]: jsonOpt };
+    } catch (e) {
+      console.warn("[shwfed-table] dynamic column descriptor fetch failed", e);
+    }
+  }
+}
+const descriptorRequestSignature = computed(() => {
+  const blocks = dynColumnBlocks();
+  if (blocks.length === 0) return null;
+  const parts = [];
+  for (const block of blocks) {
+    const expr = block.request;
+    try {
+      const req = asRequest(Effect.runSync($cel(expr, celScope(inheritedContext))));
+      parts.push(`${block.id}:${Option.isSome(req) ? JSON.stringify(req.value.describe()) : "none"}`);
+    } catch {
+      parts.push(`${block.id}:err`);
+    }
+  }
+  return parts.join("|");
+});
+watch(descriptorRequestSignature, (next, prev) => {
+  if (next !== null && next !== prev) void fetchDescriptors();
+});
 const sortedRowIndexMap = computed(() => {
   const map = /* @__PURE__ */ new Map();
   tableApi.getSortedRowModel().flatRows.forEach((row, i) => {
@@ -584,11 +658,11 @@ const sortedRowIndexMap = computed(() => {
 function getDisplayIndex(row) {
   return sortedRowIndexMap.value.get(row.id) ?? row.index;
 }
-watch([config, customization.revision], ([config2]) => {
+watch([config, customization.revision, descriptorJson], ([config2]) => {
   if (!config2) return;
   const initialState = config2.initialState;
   const hiddenSeed = {};
-  for (const col of config2.columns) {
+  for (const col of effectiveColumns.value) {
     if (col.hidden) hiddenSeed[col.id] = false;
   }
   const hasSeed = Object.keys(hiddenSeed).length > 0;
@@ -596,7 +670,7 @@ watch([config, customization.revision], ([config2]) => {
   const { state: merged, pageSize: pageSizeOverride } = mergeCustomization(
     effective,
     customization.snapshot(),
-    buildCustomizationContext(config2),
+    buildCustomizationContext(),
     { explicit: customization.wasCustomized() }
   );
   const nextKey = merged ? JSON.stringify({ merged, pageSize: pageSizeOverride ?? null }) : "";
@@ -611,11 +685,11 @@ watch([config, customization.revision], ([config2]) => {
   appliedInitialStateKey.value = nextKey;
   syncPaginationPageSize();
 }, { immediate: true });
-function buildCustomizationContext(config2) {
+function buildCustomizationContext() {
   return {
-    columnIds: new Set(config2.columns.map((c) => c.id)),
-    pageSizes: config2.pagination?.pageSizes ?? [],
-    paginationEnabled: config2.pagination !== void 0
+    columnIds: new Set(effectiveColumns.value.map((c) => c.id)),
+    pageSizes: config.value?.pagination?.pageSizes ?? [],
+    paginationEnabled: config.value?.pagination !== void 0
   };
 }
 function onCustomizationConfirm(payload) {
@@ -824,8 +898,8 @@ export { TableConfig, createTableConfig, getColumnTechnicalKey } from "./schema"
            far-right corner, outside the scroll container so it neither moves
            on horizontal scroll nor collides with right-pinned columns. -->
       <TableCustomization
-        v-if="config?.id"
-        :config="config"
+        v-if="customizationConfig?.id"
+        :config="customizationConfig"
         :table-api="tableApi"
         @confirm="onCustomizationConfirm"
         @reset="resetCustomization"

package/dist/runtime/components/table/schema.d.ts

@@ -158,40 +158,6 @@ export declare function TableConfig(configure: (env: Environment) => void): Sche
             readonly message: string;
         }[]] | undefined;
     }[];
-    readonly query?: {
-        readonly style?: string | undefined;
-        readonly id?: string | undefined;
-        readonly initial?: {
-            readonly data: string;
-            readonly request?: string | undefined;
-        } | undefined;
-        readonly displayName?: string | undefined;
-        readonly kind: "shwfed.component.form";
-        readonly fields: readonly any[];
-        readonly layouts: readonly {
-            readonly name: string;
-            readonly layout: {
-                readonly style?: string | undefined;
-                readonly columns: number;
-                readonly gap?: number | undefined;
-                readonly rows?: number | undefined;
-                readonly placements: {
-                    readonly [x: string]: {
-                        readonly area: readonly [readonly [number, number], readonly [number, number]];
-                        readonly v?: "stretch" | "center" | "end" | "start" | undefined;
-                        readonly h?: "stretch" | "center" | "end" | "start" | undefined;
-                    };
-                };
-            };
-            readonly media?: string | undefined;
-        }[];
-        readonly readonly?: string | undefined;
-    } | undefined;
-    readonly dataSource?: {
-        readonly data: string;
-        readonly total?: string | undefined;
-        readonly request?: string | undefined;
-    } | undefined;
     readonly actions?: {
         readonly size: "default" | "sm" | "xs";
         readonly style?: string | undefined;
@@ -259,6 +225,40 @@ export declare function TableConfig(configure: (env: Environment) => void): Sche
             readonly variant?: "default" | "link" | "destructive" | "primary" | "ghost" | undefined;
         }[];
     } | undefined;
+    readonly query?: {
+        readonly style?: string | undefined;
+        readonly id?: string | undefined;
+        readonly initial?: {
+            readonly data: string;
+            readonly request?: string | undefined;
+        } | undefined;
+        readonly displayName?: string | undefined;
+        readonly kind: "shwfed.component.form";
+        readonly fields: readonly any[];
+        readonly layouts: readonly {
+            readonly name: string;
+            readonly layout: {
+                readonly style?: string | undefined;
+                readonly columns: number;
+                readonly gap?: number | undefined;
+                readonly rows?: number | undefined;
+                readonly placements: {
+                    readonly [x: string]: {
+                        readonly area: readonly [readonly [number, number], readonly [number, number]];
+                        readonly v?: "stretch" | "center" | "end" | "start" | undefined;
+                        readonly h?: "stretch" | "center" | "end" | "start" | undefined;
+                    };
+                };
+            };
+            readonly media?: string | undefined;
+        }[];
+        readonly readonly?: string | undefined;
+    } | undefined;
+    readonly dataSource?: {
+        readonly data: string;
+        readonly total?: string | undefined;
+        readonly request?: string | undefined;
+    } | undefined;
     readonly bottomActions?: {
         readonly size: "default" | "sm" | "xs";
         readonly style?: string | undefined;
@@ -827,40 +827,6 @@ export declare function createTableConfig(body: Omit<Schema.Schema.Type<ReturnTy
             readonly message: string;
         }[]] | undefined;
     }[];
-    query?: {
-        readonly style?: string | undefined;
-        readonly id?: string | undefined;
-        readonly initial?: {
-            readonly data: string;
-            readonly request?: string | undefined;
-        } | undefined;
-        readonly displayName?: string | undefined;
-        readonly kind: "shwfed.component.form";
-        readonly fields: readonly any[];
-        readonly layouts: readonly {
-            readonly name: string;
-            readonly layout: {
-                readonly style?: string | undefined;
-                readonly columns: number;
-                readonly gap?: number | undefined;
-                readonly rows?: number | undefined;
-                readonly placements: {
-                    readonly [x: string]: {
-                        readonly area: readonly [readonly [number, number], readonly [number, number]];
-                        readonly v?: "stretch" | "center" | "end" | "start" | undefined;
-                        readonly h?: "stretch" | "center" | "end" | "start" | undefined;
-                    };
-                };
-            };
-            readonly media?: string | undefined;
-        }[];
-        readonly readonly?: string | undefined;
-    } | undefined;
-    dataSource?: {
-        readonly data: string;
-        readonly total?: string | undefined;
-        readonly request?: string | undefined;
-    } | undefined;
     actions?: {
         readonly size: "default" | "sm" | "xs";
         readonly style?: string | undefined;
@@ -928,6 +894,40 @@ export declare function createTableConfig(body: Omit<Schema.Schema.Type<ReturnTy
             readonly variant?: "default" | "link" | "destructive" | "primary" | "ghost" | undefined;
         }[];
     } | undefined;
+    query?: {
+        readonly style?: string | undefined;
+        readonly id?: string | undefined;
+        readonly initial?: {
+            readonly data: string;
+            readonly request?: string | undefined;
+        } | undefined;
+        readonly displayName?: string | undefined;
+        readonly kind: "shwfed.component.form";
+        readonly fields: readonly any[];
+        readonly layouts: readonly {
+            readonly name: string;
+            readonly layout: {
+                readonly style?: string | undefined;
+                readonly columns: number;
+                readonly gap?: number | undefined;
+                readonly rows?: number | undefined;
+                readonly placements: {
+                    readonly [x: string]: {
+                        readonly area: readonly [readonly [number, number], readonly [number, number]];
+                        readonly v?: "stretch" | "center" | "end" | "start" | undefined;
+                        readonly h?: "stretch" | "center" | "end" | "start" | undefined;
+                    };
+                };
+            };
+            readonly media?: string | undefined;
+        }[];
+        readonly readonly?: string | undefined;
+    } | undefined;
+    dataSource?: {
+        readonly data: string;
+        readonly total?: string | undefined;
+        readonly request?: string | undefined;
+    } | undefined;
     bottomActions?: {
         readonly size: "default" | "sm" | "xs";
         readonly style?: string | undefined;

package/dist/runtime/components/table/utils/resolve.d.ts

@@ -3,6 +3,7 @@ import type { Schema, Effect } from 'effect';
 import type { ColumnDef } from '@tanstack/vue-table';
 import type { Environment } from '../../../vendor/cel-js/lib/index.js';
 import type { LocaleValue } from '../../../share/locale.js';
+import type { ColumnValue } from '../schema.js';
 type CelEvaluator = <T>(expression: string, context?: Record<string, unknown>) => Effect.Effect<T, any>;
 type AnySchema = Schema.Schema<any, any, never>;
 type SchemaFactory = (configure: (env: Environment) => void) => AnySchema;
@@ -29,6 +30,40 @@ export type ColumnDefDeps = Readonly<{
     inheritedContext: Record<string, unknown>;
 }>;
 type ToColumnDef = (value: any, deps: ColumnDefDeps) => Partial<ColumnDef<unknown, unknown>>;
+/**
+ * Capabilities a runtime column *generator* (`expand`) needs from the host.
+ * A generator column (e.g. `com.shwfed.table.column.dynamic`) renders no cell
+ * of its own — it maps a fetched payload into a list of ordinary
+ * `ColumnValue`s the *existing* `translateColumn` renders unchanged. All
+ * app-specific payload knowledge lives in the block's own CEL `transform`; the
+ * module never names the app's data contract.
+ */
+export type ColumnExpandDeps = Readonly<{
+    /**
+     * The block's fetched `request` response (parsed JSON), passed exactly as
+     * `dataSource.data` receives `json` — an `Option` (`None` before the fetch
+     * resolves or when the request opted out). `expand` runs the block's
+     * `transform` against it.
+     */
+    json: unknown;
+    $cel: CelEvaluator;
+    /**
+     * Base CEL context the `transform` evaluates in (inherited host vars plus an
+     * inert `query`); `expand` injects `json` on top. Deliberately excludes
+     * table runtime state (`pageIndex` / `pageSize` / `sorts` / live `query`) so
+     * the generated column set never depends on page / search / sort.
+     */
+    context: Record<string, unknown>;
+    getLocaleText: (value: LocaleValue | undefined) => string | undefined;
+    /**
+     * Column ids already claimed by static columns / earlier-expanded blocks.
+     * `expand` MUST NOT emit a column whose id is in this set (first-wins), so
+     * a generated key never overwrites a static id and corrupts customization /
+     * sort / selection keying.
+     */
+    seen: ReadonlySet<string>;
+}>;
+export type ColumnExpand = (value: any, deps: ColumnExpandDeps) => ColumnValue[];
 /**
  * Capabilities a column-migration function may need from the host. Mirrors
  * the form host's `MigrationContext` so cross-host helpers can share a
@@ -91,6 +126,13 @@ export type ColumnEntry = Readonly<{
      * the column is created with only `{ id, type, compatibilityDate }`.
      */
     defaults?: ColumnDefaults;
+    /**
+     * Present iff this entry is a runtime column *generator* (see
+     * `ColumnSchemaModule.expand`). Such an entry carries no `toColumnDef` and no
+     * `runtime.vue`; the host expands it away before rendering rows, so
+     * `translateColumn` only ever sees the leaf columns it emits.
+     */
+    expand?: ColumnExpand;
 }>;
 export declare const COLUMNS: ReadonlyArray<ColumnEntry>;
 export declare function allColumnSchemas(configure: (env: Environment) => void): ReadonlyArray<AnySchema>;

package/dist/runtime/components/table/utils/resolve.js

@@ -19,10 +19,17 @@ const registry = defineRegistry({
   configModules,
   runtimeModules,
   validateModule: (mod, type, date) => {
-    if (typeof mod.toColumnDef !== "function") {
-      throw new TypeError(`[shwfed-table] column "${type}@${date}" is missing toColumnDef export`);
+    const hasToColumnDef = typeof mod.toColumnDef === "function";
+    const hasExpand = typeof mod.expand === "function";
+    if (hasToColumnDef === hasExpand) {
+      throw new TypeError(
+        `[shwfed-table] column "${type}@${date}" must export exactly one of toColumnDef or expand (got ${hasToColumnDef ? "both" : "neither"})`
+      );
     }
   },
+  // Generator (`expand`) entries have no cell renderer, so they need no
+  // sibling `runtime.vue`. Every other column keeps requiring one.
+  runtimeOptional: (mod) => typeof mod.expand === "function",
   // Deprecation rules mirror the form host:
   //   (a) date-versioned: another entry shares this entry's `type` with a
   //       strictly greater `compatibilityDate`;
@@ -77,7 +84,8 @@ export const COLUMNS = registry.ENTRIES.map((e) => ({
   ...e.supersededBy !== void 0 ? { supersededBy: e.supersededBy } : {},
   ...e.module.migrate !== void 0 ? { migrate: e.module.migrate } : {},
   ...e.module.migrateFrom !== void 0 ? { migrateFrom: e.module.migrateFrom } : {},
-  ...e.module.defaults !== void 0 ? { defaults: e.module.defaults } : {}
+  ...e.module.defaults !== void 0 ? { defaults: e.module.defaults } : {},
+  ...e.module.expand !== void 0 ? { expand: e.module.expand } : {}
 }));
 const migrationTargets = (() => {
   const map = /* @__PURE__ */ new Map();

package/dist/runtime/share/define-registry.d.ts

@@ -36,6 +36,17 @@ export type RegistryOptions<TModule extends RegistryModuleBase, TEntryExtras ext
      * to be a function.
      */
     validateModule?: (mod: TModule, type: string, date: string) => void;
+    /**
+     * Optional predicate deciding whether a given module may ship WITHOUT a
+     * sibling `runtime.vue`. Returns true → the runtime lookup is tolerant and
+     * the entry's `runtime` holds `undefined` (still typed `Component` for
+     * call-site ergonomics). Such an entry must therefore never be rendered —
+     * the host enforces that via `validateModule` (e.g. table's dyn-column
+     * generator has `expand` instead of `toColumnDef`/`runtime.vue` and is
+     * expanded away before any row renders). Defaults to "runtime always
+     * required", so every other host is unaffected.
+     */
+    runtimeOptional?: (mod: TModule) => boolean;
     /**
      * Optional factory producing host-specific extras for each draft. Receives
      * the full draft set first (so hosts can compute cross-entry data such as