@shwfed/config 2.11.6 → 2.12.1

package/dist/runtime/components/form/fields/2026-06-14/com.shwfed.form.field.combobox.single/schema.d.ts

@@ -20,13 +20,19 @@ export declare const metadata: {
 };
 export declare function itemSchema(configure: (env: Environment) => void): Schema.Struct<{
     id: Schema.refine<string, typeof Schema.String>;
-    label: Schema.TupleType<readonly [Schema.Struct<{
-        locale: Schema.Literal<["zh"]>;
-        message: Schema.SchemaClass<string, string, never>;
-    }>], [Schema.Struct<{
-        locale: Schema.Literal<["ja", "en", "ko"]>;
-        message: Schema.SchemaClass<string, string, never>;
-    }>]>;
+    label: Schema.suspend<readonly [{
+        readonly locale: "zh";
+        readonly message: string;
+    }, ...{
+        readonly locale: "en" | "ja" | "ko";
+        readonly message: string;
+    }[]], string | readonly [{
+        readonly locale: "zh";
+        readonly message: string;
+    }, ...{
+        readonly locale: "en" | "ja" | "ko";
+        readonly message: string;
+    }[]], never>;
     value: Schema.Union<[Schema.Struct<{
         kind: Schema.Literal<["text"]>;
         value: typeof Schema.String;
@@ -40,13 +46,19 @@ export declare function itemSchema(configure: (env: Environment) => void): Schem
     }, ...{
         readonly locale: "en" | "ja" | "ko";
         readonly message: string;
-    }[]], Schema.TupleType<readonly [Schema.Struct<{
-        locale: Schema.Literal<["zh"]>;
-        message: Schema.SchemaClass<string, string, never>;
-    }>], [Schema.Struct<{
-        locale: Schema.Literal<["ja", "en", "ko"]>;
-        message: Schema.SchemaClass<string, string, never>;
-    }>]>>>;
+    }[]], Schema.suspend<readonly [{
+        readonly locale: "zh";
+        readonly message: string;
+    }, ...{
+        readonly locale: "en" | "ja" | "ko";
+        readonly message: string;
+    }[]], string | readonly [{
+        readonly locale: "zh";
+        readonly message: string;
+    }, ...{
+        readonly locale: "en" | "ja" | "ko";
+        readonly message: string;
+    }[]], never>>>;
     keywords: Schema.optional<Schema.Array$<typeof Schema.String>>;
 }>;
 export declare function remoteOptionsSchema(configure: (env: Environment) => void): Schema.Struct<{
@@ -63,13 +75,19 @@ export declare function optionsSchema(configure: (env: Environment) => void): Sc
     kind: Schema.Literal<["static"]>;
     items: Schema.optionalWith<Schema.Array$<Schema.Struct<{
         id: Schema.refine<string, typeof Schema.String>;
-        label: Schema.TupleType<readonly [Schema.Struct<{
-            locale: Schema.Literal<["zh"]>;
-            message: Schema.SchemaClass<string, string, never>;
-        }>], [Schema.Struct<{
-            locale: Schema.Literal<["ja", "en", "ko"]>;
-            message: Schema.SchemaClass<string, string, never>;
-        }>]>;
+        label: Schema.suspend<readonly [{
+            readonly locale: "zh";
+            readonly message: string;
+        }, ...{
+            readonly locale: "en" | "ja" | "ko";
+            readonly message: string;
+        }[]], string | readonly [{
+            readonly locale: "zh";
+            readonly message: string;
+        }, ...{
+            readonly locale: "en" | "ja" | "ko";
+            readonly message: string;
+        }[]], never>;
         value: Schema.Union<[Schema.Struct<{
             kind: Schema.Literal<["text"]>;
             value: typeof Schema.String;
@@ -83,13 +101,19 @@ export declare function optionsSchema(configure: (env: Environment) => void): Sc
         }, ...{
             readonly locale: "en" | "ja" | "ko";
             readonly message: string;
-        }[]], Schema.TupleType<readonly [Schema.Struct<{
-            locale: Schema.Literal<["zh"]>;
-            message: Schema.SchemaClass<string, string, never>;
-        }>], [Schema.Struct<{
-            locale: Schema.Literal<["ja", "en", "ko"]>;
-            message: Schema.SchemaClass<string, string, never>;
-        }>]>>>;
+        }[]], Schema.suspend<readonly [{
+            readonly locale: "zh";
+            readonly message: string;
+        }, ...{
+            readonly locale: "en" | "ja" | "ko";
+            readonly message: string;
+        }[]], string | readonly [{
+            readonly locale: "zh";
+            readonly message: string;
+        }, ...{
+            readonly locale: "en" | "ja" | "ko";
+            readonly message: string;
+        }[]], never>>>;
         keywords: Schema.optional<Schema.Array$<typeof Schema.String>>;
     }>>, {
         default: () => readonly [];
@@ -105,27 +129,45 @@ export declare function optionsSchema(configure: (env: Environment) => void): Sc
     optionKeywords: Schema.optional<Schema.Schema<string, string, never>>;
 }>]>;
 export declare function schema(configure: (env: Environment) => void): Schema.Struct<{
-    label: Schema.optional<Schema.TupleType<readonly [Schema.Struct<{
-        locale: Schema.Literal<["zh"]>;
-        message: Schema.SchemaClass<string, string, never>;
-    }>], [Schema.Struct<{
-        locale: Schema.Literal<["ja", "en", "ko"]>;
-        message: Schema.SchemaClass<string, string, never>;
-    }>]>>;
-    placeholder: Schema.optional<Schema.TupleType<readonly [Schema.Struct<{
-        locale: Schema.Literal<["zh"]>;
-        message: Schema.SchemaClass<string, string, never>;
-    }>], [Schema.Struct<{
-        locale: Schema.Literal<["ja", "en", "ko"]>;
-        message: Schema.SchemaClass<string, string, never>;
-    }>]>>;
-    tooltip: Schema.optional<Schema.TupleType<readonly [Schema.Struct<{
-        locale: Schema.Literal<["zh"]>;
-        message: Schema.SchemaClass<string, string, never>;
-    }>], [Schema.Struct<{
-        locale: Schema.Literal<["ja", "en", "ko"]>;
-        message: Schema.SchemaClass<string, string, never>;
-    }>]>>;
+    label: Schema.optional<Schema.suspend<readonly [{
+        readonly locale: "zh";
+        readonly message: string;
+    }, ...{
+        readonly locale: "en" | "ja" | "ko";
+        readonly message: string;
+    }[]], string | readonly [{
+        readonly locale: "zh";
+        readonly message: string;
+    }, ...{
+        readonly locale: "en" | "ja" | "ko";
+        readonly message: string;
+    }[]], never>>;
+    placeholder: Schema.optional<Schema.suspend<readonly [{
+        readonly locale: "zh";
+        readonly message: string;
+    }, ...{
+        readonly locale: "en" | "ja" | "ko";
+        readonly message: string;
+    }[]], string | readonly [{
+        readonly locale: "zh";
+        readonly message: string;
+    }, ...{
+        readonly locale: "en" | "ja" | "ko";
+        readonly message: string;
+    }[]], never>>;
+    tooltip: Schema.optional<Schema.suspend<readonly [{
+        readonly locale: "zh";
+        readonly message: string;
+    }, ...{
+        readonly locale: "en" | "ja" | "ko";
+        readonly message: string;
+    }[]], string | readonly [{
+        readonly locale: "zh";
+        readonly message: string;
+    }, ...{
+        readonly locale: "en" | "ja" | "ko";
+        readonly message: string;
+    }[]], never>>;
     orientation: Schema.optional<Schema.Literal<["vertical", "floating"]>>;
     binding: Schema.optional<Schema.refine<string, typeof Schema.String>>;
     disabled: Schema.optional<Schema.Schema<string, string, never>>;
@@ -138,13 +180,19 @@ export declare function schema(configure: (env: Environment) => void): Schema.St
         kind: Schema.Literal<["static"]>;
         items: Schema.optionalWith<Schema.Array$<Schema.Struct<{
             id: Schema.refine<string, typeof Schema.String>;
-            label: Schema.TupleType<readonly [Schema.Struct<{
-                locale: Schema.Literal<["zh"]>;
-                message: Schema.SchemaClass<string, string, never>;
-            }>], [Schema.Struct<{
-                locale: Schema.Literal<["ja", "en", "ko"]>;
-                message: Schema.SchemaClass<string, string, never>;
-            }>]>;
+            label: Schema.suspend<readonly [{
+                readonly locale: "zh";
+                readonly message: string;
+            }, ...{
+                readonly locale: "en" | "ja" | "ko";
+                readonly message: string;
+            }[]], string | readonly [{
+                readonly locale: "zh";
+                readonly message: string;
+            }, ...{
+                readonly locale: "en" | "ja" | "ko";
+                readonly message: string;
+            }[]], never>;
             value: Schema.Union<[Schema.Struct<{
                 kind: Schema.Literal<["text"]>;
                 value: typeof Schema.String;
@@ -158,13 +206,19 @@ export declare function schema(configure: (env: Environment) => void): Schema.St
             }, ...{
                 readonly locale: "en" | "ja" | "ko";
                 readonly message: string;
-            }[]], Schema.TupleType<readonly [Schema.Struct<{
-                locale: Schema.Literal<["zh"]>;
-                message: Schema.SchemaClass<string, string, never>;
-            }>], [Schema.Struct<{
-                locale: Schema.Literal<["ja", "en", "ko"]>;
-                message: Schema.SchemaClass<string, string, never>;
-            }>]>>>;
+            }[]], Schema.suspend<readonly [{
+                readonly locale: "zh";
+                readonly message: string;
+            }, ...{
+                readonly locale: "en" | "ja" | "ko";
+                readonly message: string;
+            }[]], string | readonly [{
+                readonly locale: "zh";
+                readonly message: string;
+            }, ...{
+                readonly locale: "en" | "ja" | "ko";
+                readonly message: string;
+            }[]], never>>>;
             keywords: Schema.optional<Schema.Array$<typeof Schema.String>>;
         }>>, {
             default: () => readonly [];
@@ -197,13 +251,19 @@ export declare function schema(configure: (env: Environment) => void): Schema.St
         }, ...{
             readonly locale: "en" | "ja" | "ko";
             readonly message: string;
-        }[]], Schema.TupleType<readonly [Schema.Struct<{
-            locale: Schema.Literal<["zh"]>;
-            message: Schema.SchemaClass<string, string, never>;
-        }>], [Schema.Struct<{
-            locale: Schema.Literal<["ja", "en", "ko"]>;
-            message: Schema.SchemaClass<string, string, never>;
-        }>]>>;
+        }[]], Schema.suspend<readonly [{
+            readonly locale: "zh";
+            readonly message: string;
+        }, ...{
+            readonly locale: "en" | "ja" | "ko";
+            readonly message: string;
+        }[]], string | readonly [{
+            readonly locale: "zh";
+            readonly message: string;
+        }, ...{
+            readonly locale: "en" | "ja" | "ko";
+            readonly message: string;
+        }[]], never>>;
     }>>>;
     type: Schema.Literal<["com.shwfed.form.field.combobox.single"]>;
     compatibilityDate: Schema.Literal<["2026-06-14"]>;

package/dist/runtime/components/form/fields/2026-06-20/com.shwfed.form.field.tabs/schema.d.ts

@@ -19,13 +19,19 @@ export declare const metadata: {
     readonly inlineConfig: false;
 };
 export declare const TabMeta: Schema.Struct<{
-    label: Schema.TupleType<readonly [Schema.Struct<{
-        locale: Schema.Literal<["zh"]>;
-        message: Schema.SchemaClass<string, string, never>;
-    }>], [Schema.Struct<{
-        locale: Schema.Literal<["ja", "en", "ko"]>;
-        message: Schema.SchemaClass<string, string, never>;
-    }>]>;
+    label: Schema.suspend<readonly [{
+        readonly locale: "zh";
+        readonly message: string;
+    }, ...{
+        readonly locale: "en" | "ja" | "ko";
+        readonly message: string;
+    }[]], string | readonly [{
+        readonly locale: "zh";
+        readonly message: string;
+    }, ...{
+        readonly locale: "en" | "ja" | "ko";
+        readonly message: string;
+    }[]], never>;
 }>;
 /**
  * A tabbed grouping. Pure view — children of each tab stay flat in the form
@@ -65,13 +71,19 @@ export declare function schema(configure: (env: Environment) => void): Schema.St
             fields: ReadonlyArray<import("../../../schema.js").FieldValue>;
             layouts: ReadonlyArray<import("../../../schema.js").LayoutSetValue>;
         }>, never>;
-        label: Schema.TupleType<readonly [Schema.Struct<{
-            locale: Schema.Literal<["zh"]>;
-            message: Schema.SchemaClass<string, string, never>;
-        }>], [Schema.Struct<{
-            locale: Schema.Literal<["ja", "en", "ko"]>;
-            message: Schema.SchemaClass<string, string, never>;
-        }>]>;
+        label: Schema.suspend<readonly [{
+            readonly locale: "zh";
+            readonly message: string;
+        }, ...{
+            readonly locale: "en" | "ja" | "ko";
+            readonly message: string;
+        }[]], string | readonly [{
+            readonly locale: "zh";
+            readonly message: string;
+        }, ...{
+            readonly locale: "en" | "ja" | "ko";
+            readonly message: string;
+        }[]], never>;
         id: Schema.refine<string, typeof Schema.String>;
     }>>>>;
 }>;

package/dist/runtime/components/form/utils/ai-field-tools.d.ts

@@ -0,0 +1,11 @@
+import type { Environment } from '../../../vendor/cel-js/lib/index.js';
+import type { AgenticTool } from '../../../utils/ai/index.js';
+type AnyRecord = Record<string, any>;
+export interface QueryFieldToolDeps {
+    readonly read: () => AnyRecord | undefined;
+    readonly write: (next: AnyRecord) => void;
+    readonly configure: (env: Environment) => void;
+    readonly genUuid: () => string;
+}
+export declare function createQueryFieldTools(deps: QueryFieldToolDeps): AgenticTool[];
+export {};

package/dist/runtime/components/form/utils/ai-field-tools.js

@@ -0,0 +1,282 @@
+import { JSONSchema, ParseResult, Schema } from "effect";
+import { coerceFromString } from "../../../share/coerce-from-string.js";
+import { Area } from "../../../share/layout.js";
+import { defaultFormConfig } from "../schema.js";
+import { registerFormVariablesIfAbsent } from "./form-vars.js";
+import { activeFields } from "./resolve.js";
+const HARNESS_KEYS = ["id", "compatibilityDate"];
+const PlaceInput = Schema.Struct({
+  id: Schema.String.pipe(Schema.minLength(1)),
+  area: Area
+});
+function formScope(configure) {
+  return (env) => {
+    registerFormVariablesIfAbsent(env);
+    configure(env);
+  };
+}
+function publicFieldSchema(entry, configure) {
+  return entry.schema(formScope(configure)).pipe(Schema.omit(...HARNESS_KEYS));
+}
+function decode(schema, input) {
+  const result = Schema.decodeUnknownEither(schema)(coerceFromString(input, schema));
+  if (result._tag === "Right") return { ok: true, value: result.right };
+  const issues = ParseResult.ArrayFormatter.formatErrorSync(result.left);
+  const report = issues.map((i) => `- ${i.path.map(String).join(".") || "(root)"}: ${i.message}`).join("\n");
+  return { ok: false, report };
+}
+function overlaps(a, b) {
+  return a[0][0] < b[1][0] && a[1][0] > b[0][0] && a[0][1] < b[1][1] && a[1][1] > b[0][1];
+}
+function growColumns(layout) {
+  let maxCol = typeof layout.columns === "number" ? layout.columns : 1;
+  const placements = layout.placements ?? {};
+  for (const p of Object.values(placements)) {
+    const x2 = p.area[1][0];
+    if (x2 - 1 > maxCol) maxCol = x2 - 1;
+  }
+  layout.columns = Math.max(1, maxCol);
+}
+function ensureFormConfig(deps) {
+  return deps.read() ?? defaultFormConfig();
+}
+export function createQueryFieldTools(deps) {
+  return [
+    // ---- 信息获取 ----
+    {
+      name: "list_available_query_field_types",
+      description: "List the form field types you can insert into the table's search-condition form. Returns each type's name. Use this first to discover what fields exist; for a field's full field contract and defaults, follow up with `describe_specific_query_field_type`. Deprecated types are hidden.",
+      inputJsonSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false
+      },
+      execute: () => activeFields().map((f) => {
+        const entry = { type: f.type, name: f.metadata.name };
+        const description = f.metadata.description;
+        if (description !== void 0) entry.description = description;
+        return entry;
+      })
+    },
+    {
+      name: "describe_specific_query_field_type",
+      description: "Return, for one search-condition field type: the JSON Schema (without `id`/`compatibilityDate` \u2014 managed by the harness), the default values, and the default placement size `w`/`h` (each `{ initial, min, max }`; `w` is in grid columns, `h` in rows). Call this before `insert_query_field` / `place_query_field` to learn the field contract and how big to place it \u2014 use `w.initial` / `h.initial` as the placed area's width / height. Deprecated types are not accepted.",
+      inputJsonSchema: {
+        type: "object",
+        properties: {
+          type: { type: "string", description: "A `type` value from `list_available_query_field_types`." }
+        },
+        required: ["type"],
+        additionalProperties: false
+      },
+      execute: (input) => {
+        const { type } = input ?? {};
+        if (typeof type !== "string" || type.length === 0) {
+          return "describe failed: `type` must be a non-empty string.";
+        }
+        const entry = activeFields().find((f) => f.type === type);
+        if (!entry) {
+          return `describe failed: query field type "${type}" is not available. Call list_available_query_field_types to see what is.`;
+        }
+        const publicSchema = publicFieldSchema(entry, deps.configure);
+        let jsonSchema;
+        try {
+          jsonSchema = JSONSchema.make(publicSchema);
+        } catch {
+          jsonSchema = "(schema unavailable)";
+        }
+        return {
+          schema: jsonSchema,
+          defaults: entry.defaults?.() ?? null,
+          // Default placement size from the field's registry metadata. The
+          // system prompt requires the model to use `w.initial` / `h.initial`
+          // as the placed area's width / height; `min`/`max` bound what it may
+          // adjust to. (`place_query_field` itself only guards overlap — the
+          // "use the initial size" rule lives in the prompt, not the tool.)
+          w: entry.metadata.w,
+          h: entry.metadata.h
+        };
+      }
+    },
+    {
+      name: "list_query_fields",
+      description: "Return the search-condition form's current fields (each with its `id`) joined with its placement: `placement` is the field's grid area `[[x1,y1],[x2,y2]]`, or `null` when the field exists but has NOT been placed yet (unplaced fields are not rendered). `grid` reports the layout's current column count. Use this to discover ids, see what still needs placing, and find a free area before calling `place_query_field`.",
+      inputJsonSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false
+      },
+      execute: () => {
+        const fc = deps.read();
+        if (!fc) return { fields: [], grid: null };
+        const fields = Array.isArray(fc.fields) ? fc.fields : [];
+        const layout = Array.isArray(fc.layouts) ? fc.layouts[0]?.layout : void 0;
+        const placements = layout?.placements ?? {};
+        return {
+          fields: fields.map((f) => ({
+            ...f,
+            placement: placements[f.id]?.area ?? null
+          })),
+          grid: layout ? { columns: layout.columns ?? null } : null
+        };
+      }
+    },
+    // ---- 配置 ----
+    {
+      name: "insert_query_field",
+      description: "Insert one new field into the table's search-condition form. Provide `type` (from `list_available_query_field_types`) plus the field's fields as described by `describe_specific_query_field_type`. Do NOT include `id` or `compatibilityDate` \u2014 the harness assigns them. The field is created UNPLACED: it exists but is not rendered until you place it with `place_query_field`. On validation failure the tool returns the issues; fix them and call again.",
+      inputJsonSchema: {
+        type: "object",
+        properties: {
+          type: { type: "string", description: "The field type to insert." }
+        },
+        required: ["type"],
+        additionalProperties: true
+      },
+      execute: (input) => {
+        const raw = input ?? {};
+        const { type, ...rest } = raw;
+        if (typeof type !== "string" || type.length === 0) {
+          return "insert failed: `type` must be a non-empty string.";
+        }
+        for (const k of HARNESS_KEYS) {
+          if (k in rest) {
+            return `insert failed: do not pass \`${k}\` \u2014 the harness assigns it.`;
+          }
+        }
+        const entry = activeFields().find((f) => f.type === type);
+        if (!entry) {
+          return `insert failed: query field type "${type}" is not available. Call list_available_query_field_types to see what is.`;
+        }
+        const publicSchema = publicFieldSchema(entry, deps.configure);
+        const verdict = decode(publicSchema, raw);
+        if (!verdict.ok) {
+          return `insert failed for type "${type}". Fix these and call insert_query_field again:
+${verdict.report}`;
+        }
+        const fc = ensureFormConfig(deps);
+        const fields = Array.isArray(fc.fields) ? fc.fields : [];
+        const newField = {
+          id: deps.genUuid(),
+          compatibilityDate: entry.compatibilityDate,
+          ...verdict.value
+        };
+        fc.fields = [...fields, newField];
+        deps.write(fc);
+        return { id: newField.id, type };
+      }
+    },
+    {
+      name: "delete_query_fields",
+      description: "Delete one or more search-condition fields by id. Call `list_query_fields` first to obtain ids. Fields are matched by id only. On any unknown id the call is rejected without writing; fix and call again. Deleting a field also removes it from the layout (its placement is stripped).",
+      inputJsonSchema: {
+        type: "object",
+        properties: {
+          ids: {
+            type: "array",
+            items: { type: "string", minLength: 1 },
+            minItems: 1,
+            description: "Field ids to delete. Get them from `list_query_fields` first."
+          }
+        },
+        required: ["ids"],
+        additionalProperties: false
+      },
+      execute: (input) => {
+        const raw = input ?? {};
+        const ids = raw.ids;
+        if (!Array.isArray(ids) || ids.length === 0) {
+          return "delete failed: `ids` must be a non-empty array of field ids.";
+        }
+        for (const id of ids) {
+          if (typeof id !== "string" || id.length === 0) {
+            return "delete failed: every `ids` entry must be a non-empty string.";
+          }
+        }
+        const seen = /* @__PURE__ */ new Set();
+        for (const id of ids) {
+          if (seen.has(id)) {
+            return `delete failed: duplicate id "${id}" in input \u2014 dedupe and call again.`;
+          }
+          seen.add(id);
+        }
+        const fc = deps.read();
+        const fields = fc && Array.isArray(fc.fields) ? fc.fields : [];
+        const existing = new Set(fields.map((f) => f.id));
+        for (const id of ids) {
+          if (!existing.has(id)) {
+            return `delete failed: query field id "${id}" is not present. Call list_query_fields to see current ids.`;
+          }
+        }
+        const cfg = fc;
+        const deleted = new Set(ids);
+        cfg.fields = fields.filter((f) => !deleted.has(f.id));
+        if (Array.isArray(cfg.layouts)) {
+          cfg.layouts = cfg.layouts.map((ls) => {
+            const placements = ls?.layout?.placements;
+            if (!placements) return ls;
+            const next = Object.fromEntries(
+              Object.entries(placements).filter(([pid]) => !deleted.has(pid))
+            );
+            return { ...ls, layout: { ...ls.layout, placements: next } };
+          });
+        }
+        deps.write(cfg);
+        return { deleted: ids, count: ids.length };
+      }
+    },
+    {
+      name: "place_query_field",
+      description: "Place a field into the search-condition layout at grid coordinates you choose. `area` is `[[x1,y1],[x2,y2]]` using 1-based grid lines (top-left inclusive, bottom-right exclusive); e.g. a field occupying columns 1\u20132 on row 1 is `[[1,1],[3,2]]`. The field must already exist (call `insert_query_field` first). The harness rejects an `area` that overlaps another field \u2014 pick a free spot (use `list_query_fields` to see current placements) and call again. Placing an already-placed field MOVES it. The layout column count grows to fit your placements; how many columns the search bar uses is up to you and the guidance you were given.",
+      inputJsonSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "The field id to place (from `list_query_fields`)." },
+          area: {
+            type: "array",
+            description: "Grid area `[[x1,y1],[x2,y2]]`, 1-based grid lines, bottom-right exclusive.",
+            items: { type: "array", items: { type: "integer", minimum: 1 }, minItems: 2, maxItems: 2 },
+            minItems: 2,
+            maxItems: 2
+          }
+        },
+        required: ["id", "area"],
+        additionalProperties: false
+      },
+      execute: (input) => {
+        const verdict = decode(PlaceInput, input ?? {});
+        if (!verdict.ok) {
+          return `place failed. Fix these and call place_query_field again:
+${verdict.report}`;
+        }
+        const { id, area } = verdict.value;
+        const fc = deps.read();
+        if (!fc) {
+          return "place failed: there is no query form yet. Call insert_query_field first.";
+        }
+        const fields = Array.isArray(fc.fields) ? fc.fields : [];
+        if (!fields.some((f) => f.id === id)) {
+          return `place failed: query field id "${id}" is not present. Call list_query_fields to see ids.`;
+        }
+        const layouts = Array.isArray(fc.layouts) ? fc.layouts : [];
+        const ls = layouts[0];
+        if (!ls || !ls.layout) {
+          return "place failed: the query form has no layout to place into.";
+        }
+        const placements = { ...ls.layout.placements ?? {} };
+        for (const [pid, p] of Object.entries(placements)) {
+          if (pid === id) continue;
+          if (overlaps(area, p.area)) {
+            return `place failed: area overlaps field "${pid}" at ${JSON.stringify(p.area)}. Pick a free area (see list_query_fields) and call again.`;
+          }
+        }
+        placements[id] = { area };
+        const nextLayout = { ...ls.layout, placements };
+        growColumns(nextLayout);
+        fc.layouts = [{ ...ls, layout: nextLayout }, ...layouts.slice(1)];
+        deps.write(fc);
+        return { id, area, columns: nextLayout.columns };
+      }
+    }
+  ];
+}

package/dist/runtime/components/form/utils/common.d.ts

@@ -16,13 +16,19 @@ export declare function validationRuleStruct(configure: (env: Environment) => vo
     }, ...{
         readonly locale: "en" | "ja" | "ko";
         readonly message: string;
-    }[]], Schema.TupleType<readonly [Schema.Struct<{
-        locale: Schema.Literal<["zh"]>;
-        message: Schema.SchemaClass<string, string, never>;
-    }>], [Schema.Struct<{
-        locale: Schema.Literal<["ja", "en", "ko"]>;
-        message: Schema.SchemaClass<string, string, never>;
-    }>]>>;
+    }[]], Schema.suspend<readonly [{
+        readonly locale: "zh";
+        readonly message: string;
+    }, ...{
+        readonly locale: "en" | "ja" | "ko";
+        readonly message: string;
+    }[]], string | readonly [{
+        readonly locale: "zh";
+        readonly message: string;
+    }, ...{
+        readonly locale: "en" | "ja" | "ko";
+        readonly message: string;
+    }[]], never>>;
 }>;
 export declare function commonFieldFields(configure: (env: Environment) => void): {
     id: Schema.refine<string, typeof Schema.String>;
@@ -38,13 +44,19 @@ export declare function commonFieldFields(configure: (env: Environment) => void)
         }, ...{
             readonly locale: "en" | "ja" | "ko";
             readonly message: string;
-        }[]], Schema.TupleType<readonly [Schema.Struct<{
-            locale: Schema.Literal<["zh"]>;
-            message: Schema.SchemaClass<string, string, never>;
-        }>], [Schema.Struct<{
-            locale: Schema.Literal<["ja", "en", "ko"]>;
-            message: Schema.SchemaClass<string, string, never>;
-        }>]>>;
+        }[]], Schema.suspend<readonly [{
+            readonly locale: "zh";
+            readonly message: string;
+        }, ...{
+            readonly locale: "en" | "ja" | "ko";
+            readonly message: string;
+        }[]], string | readonly [{
+            readonly locale: "zh";
+            readonly message: string;
+        }, ...{
+            readonly locale: "en" | "ja" | "ko";
+            readonly message: string;
+        }[]], never>>;
     }>>>;
 };
 export declare const FIELD_ORIENTATIONS: readonly ["vertical", "floating"];