akanjs 3.0.0-alpha.35 → 3.0.0-alpha.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.35",
+  "version": "3.0.0-alpha.37",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/store/action.ts

@@ -316,6 +316,11 @@ export const makeFormSetter = (refName: string, fetch: FetchProxy<any>) => {
                 : (value as object);
           (state[names.modelForm] as { [key: string]: any })[namesOfField.field] = setValue;
         });
+
+        const postSet = (this as unknown as { [key: string]: ((value: unknown) => unknown) | undefined })[
+          namesOfField.postSetField
+        ];
+        if (postSet) void postSet.call(this, value);
       },
       ...(field.isArray
         ? {

package/store/agentic/formFields.ts

@@ -174,6 +174,18 @@ export class FormFields {
     return field.arrDepth > 0 || (field.modelRef as unknown) === Map || !!FormFields.#scalarModel(field);
   }
 
+  /**
+   * The embedded model an array field's rows are, or null for every other field.
+   *
+   * This is the one shape where writing the whole array is a hazard rather than an inconvenience: the agent has to
+   * echo every row it is *not* changing, `checked` validates types and not values, so one mistyped row it was never
+   * asked to touch is written silently. A relation array is excluded — its rows travel as ids, which are the payload
+   * and are refused by name when wrong — and so is an array of primitives, for the same reason.
+   */
+  static rowModelOf(field: ConstantField) {
+    return field.arrDepth > 0 ? FormFields.#scalarModel(field) : null;
+  }
+
   static #scalarModel(field: ConstantField) {
     const modelRef = field.modelRef as unknown as Cls;
     if (field.enum || PrimitiveRegistry.has(modelRef)) return null;

package/store/agentic/index.ts

@@ -4,5 +4,6 @@ export * from "./readableValue";
 export * from "./StToolBuilder";
 export * from "./useFieldTool";
 export * from "./useFormTools";
+export * from "./useRelationFieldTool";
 export * from "./useStExpose";
 export * from "./useStState";

package/store/agentic/useFieldTool.ts

@@ -1,9 +1,93 @@
 "use client";
+import { capitalize } from "akanjs/common";
+import type { JsonSchema, ToolEntry } from "../../vendor/use-agentic";
 import { useScopePath, useSurface } from "../../vendor/use-agentic";
 import { actionTagOf } from "../actionTag";
+import { formSetterNames } from "../formSetterNames";
 
 import { useEffect, useRef } from "../hooks";
-import { FormFields } from "./formFields";
+import { StoreRegistry } from "../storeRegistry";
+import { type FormFieldRef, FormFields } from "./formFields";
+
+/**
+ * A control's `transform` is what it does to every value a person types, so an agent's write goes through it too —
+ * otherwise a `Field.Phone` stores `010-1234-5678` for the person and the raw digits for the agent. It normalizes
+ * one scalar, so an array-valued control (`TextList`, `Tags`, `DoubleNumber`) applies it per element. A cleared
+ * nullable field stays null: a normalizer written for a value would turn it into one.
+ */
+const normalized = (value: unknown, transform: unknown): unknown => {
+  if (typeof transform !== "function" || value === null) return value;
+  const apply = transform as (input: unknown) => unknown;
+  return Array.isArray(value) ? value.map((item) => apply(item)) : apply(value);
+};
+
+const dispatcherOf = (action: string) =>
+  StoreRegistry.instance.do[action] as ((...args: unknown[]) => unknown) | undefined;
+
+const rowsOf = (ref: FormFieldRef): unknown[] => {
+  const form = StoreRegistry.instance.get()[`${ref.refName}Form`] as { [key: string]: unknown } | undefined;
+  const rows = form?.[ref.key];
+  return Array.isArray(rows) ? rows : [];
+};
+
+/**
+ * Append and remove-by-index for an array of embedded rows, beside the whole-array setter.
+ *
+ * Not new authority: the setter this control already published can produce any array these two can, so they are
+ * strictly weaker — which is what makes deriving them from the same field sound. What they add is that neither can
+ * touch a row it was not given, so the agent stops having to retype the rows it is leaving alone.
+ *
+ * Both take a list and act atomically. Removing indices one call at a time would shift the ones not yet removed, so
+ * `sub` filters the whole set at once, the way the generated action already does.
+ *
+ * `add` appends and publishes no insert position: the `+` a person presses always appends, and the framework cannot
+ * see the `limit` an app may pass from its own `onAdd`. `addOrSub` is never published — it matches by `indexOf`, so
+ * on rows it compares by reference and every toggle would append.
+ */
+const rowEntries = (ref: FormFieldRef, arraySchema: JsonSchema): ToolEntry[] => {
+  if (!FormFields.rowModelOf(ref.field)) return [];
+  const names = formSetterNames(capitalize(ref.refName), ref.key);
+  if (!dispatcherOf(names.addFieldOnModel) || !dispatcherOf(names.subFieldOnModel)) return [];
+  return [
+    {
+      name: names.addFieldOnModel,
+      description: `Append rows to ${ref.key} on the ${ref.refName} form. Leaves every existing row untouched.`,
+      parameters: {
+        type: "object",
+        properties: { values: arraySchema },
+        required: ["values"],
+        additionalProperties: false,
+      },
+      effect: "state",
+      run: (args) => {
+        const checked = FormFields.checked(names.addFieldOnModel, "values", ref.field, args.values);
+        return dispatcherOf(names.addFieldOnModel)?.(checked);
+      },
+    },
+    {
+      name: names.subFieldOnModel,
+      description: `Remove rows of ${ref.key} from the ${ref.refName} form by their positions, counting from 0.`,
+      parameters: {
+        type: "object",
+        properties: { idxs: { type: "array", items: { type: "integer" } } },
+        required: ["idxs"],
+        additionalProperties: false,
+      },
+      effect: "state",
+      guard: (args) => {
+        const idxs = args.idxs;
+        if (!Array.isArray(idxs) || !idxs.length) return `"idxs" of ${names.subFieldOnModel} takes at least one index.`;
+        const length = rowsOf(ref).length;
+        const outside = idxs.filter(
+          (idx) => typeof idx !== "number" || !Number.isInteger(idx) || idx < 0 || idx >= length,
+        );
+        if (!outside.length) return true;
+        return `${ref.key} has ${length} ${length === 1 ? "row" : "rows"}, so ${outside.join(", ")} is out of range.`;
+      },
+      run: (args) => dispatcherOf(names.subFieldOnModel)?.(args.idxs),
+    },
+  ];
+};
 
 /**
  * Publishes the setter a form control is already holding, for exactly as long as the control is on screen.
@@ -14,27 +98,34 @@ import { FormFields } from "./formFields";
  * consequences. Publishing from the form's subscription instead would offer every field of the model, including
  * the ones this template draws no control for.
  */
-export const useFieldTool = (onChange: unknown) => {
+export const useFieldTool = (onChange: unknown, transform?: unknown) => {
   const surface = useSurface();
   const scope = useScopePath();
   const action = actionTagOf(onChange)?.action ?? null;
-  const live = useRef(onChange);
-  live.current = onChange;
+  const live = useRef({ onChange, transform });
+  live.current = { onChange, transform };
   const scopeKey = scope.join(".");
   useEffect(() => {
     if (!action) return;
     const ref = FormFields.ref(action);
     const schema = ref && FormFields.schema(ref.field);
     if (!ref || !schema) return;
-    return surface.registerTool(scope, {
-      name: action,
-      description: `Set ${ref.key} on the ${ref.refName} form.`,
-      parameters: { type: "object", properties: { value: schema }, required: ["value"], additionalProperties: false },
-      effect: "state",
-      run: (args) =>
-        (live.current as (value: unknown) => unknown)(
-          FormFields.checked(action, "value", ref.field, args.value === undefined ? null : args.value),
-        ),
-    });
+    const entries: ToolEntry[] = [
+      {
+        name: action,
+        description: `Set ${ref.key} on the ${ref.refName} form.`,
+        parameters: { type: "object", properties: { value: schema }, required: ["value"], additionalProperties: false },
+        effect: "state",
+        run: (args) => {
+          const checked = FormFields.checked(action, "value", ref.field, args.value === undefined ? null : args.value);
+          return (live.current.onChange as (value: unknown) => unknown)(normalized(checked, live.current.transform));
+        },
+      },
+      ...rowEntries(ref, schema),
+    ];
+    const registered = entries.map((entry) => surface.registerTool(scope, entry));
+    return () => {
+      for (const unregister of registered) unregister();
+    };
   }, [surface, scopeKey, action]);
 };

package/store/agentic/useRelationFieldTool.ts

@@ -0,0 +1,114 @@
+"use client";
+import { type Cls, type DataList, PrimitiveRegistry } from "akanjs/base";
+import { capitalize } from "akanjs/common";
+import { type ConstantField, ConstantRegistry } from "akanjs/constant";
+import type { JsonSchema } from "../../vendor/use-agentic";
+import { useScopePath, useSurface } from "../../vendor/use-agentic";
+import { actionTagOf } from "../actionTag";
+
+import { useEffect, useRef } from "../hooks";
+import { FormFields } from "./formFields";
+
+export interface RelationFieldSource<T extends { id: string }> {
+  /** Read live from the store rather than closed over: `load` below changes the list mid-call. */
+  read: () => DataList<T>;
+  /** Loads the options an agent never opened the dropdown to fetch. */
+  load: () => Promise<unknown> | unknown;
+  /** How one option reads to a person, so the agent can match what it sees on screen. */
+  label: (model: T) => string;
+  disabled?: boolean;
+}
+
+/** The database model a relation field points at, or null for anything else — a primitive, an enum, a scalar. */
+const relationOf = (field: ConstantField): string | null => {
+  const modelRef = field.modelRef as unknown as Cls;
+  if (field.fieldType !== "property" || field.enum || !modelRef || PrimitiveRegistry.has(modelRef)) return null;
+  const refName = ConstantRegistry.getRefName(modelRef, { allowEmpty: true });
+  return refName && ConstantRegistry.database.has(refName) ? refName : null;
+};
+
+/**
+ * The two tools a relation picker owes an agent: list the documents it can pick, then pick by id.
+ *
+ * `FormFields` publishes no schema for a relation, and it is right not to — the form holds the whole related
+ * document, so an id would need a lookup the store does not do. The picker is where that lookup lives: it holds
+ * the slice list, the loader, and the label each option renders with. So the field reaches an agent from the one
+ * component that can resolve it, which is the rule every other control follows — the control is the declaration.
+ *
+ * Listing is its own tool because loading is its own step for a person too: the options arrive when the dropdown
+ * opens, and an agent never opens it. Folding the load into the setter would leave an agent guessing ids in order
+ * to learn them from the refusal.
+ */
+export const useRelationFieldTool = <T extends { id: string }>(
+  onChange: unknown,
+  { read, load, label, disabled }: RelationFieldSource<T>,
+) => {
+  const surface = useSurface();
+  const scope = useScopePath();
+  const action = actionTagOf(onChange)?.action ?? null;
+  const live = useRef({ onChange, read, load, label });
+  live.current = { onChange, read, load, label };
+  const scopeKey = scope.join(".");
+  useEffect(() => {
+    if (!action || disabled) return;
+    const ref = FormFields.ref(action);
+    const target = ref && relationOf(ref.field);
+
+    if (!ref || !target || FormFields.schema(ref.field)) return;
+    const many = ref.field.arrDepth > 0;
+    const nullable = !!ref.field.nullable && !many;
+    const listName = `load${capitalize(ref.key)}OptionsOn${capitalize(ref.refName)}`;
+    const argName = many ? `${ref.key}Ids` : `${ref.key}Id`;
+    const id: JsonSchema = { type: "string" };
+    const options = () => live.current.read().map((model) => ({ id: model.id, label: live.current.label(model) }));
+    const idsIn = (args: Record<string, unknown>): unknown => {
+      const value = args[argName];
+      if (nullable && (value === null || value === undefined)) return [];
+      return many ? value : [value];
+    };
+    const offList = surface.registerTool(scope, {
+      name: listName,
+      description: `List the ${target}s the ${ref.refName} form can pick for ${ref.key}, loading them first. Pass an id from it to ${action}.`,
+      effect: "query",
+      run: async () => {
+        await live.current.load();
+        return options();
+      },
+    });
+    const offSet = surface.registerTool(scope, {
+      name: action,
+      description: `Set ${ref.key} on the ${ref.refName} form to ${many ? `${target}s` : `one ${target}`}, by id. Call ${listName} first for the ids.`,
+      parameters: {
+        type: "object",
+        properties: { [argName]: many ? { type: "array", items: id } : id },
+        ...(nullable ? {} : { required: [argName] }),
+        additionalProperties: false,
+      },
+      effect: "state",
+      guard: (args) => {
+        const ids = idsIn(args);
+        if (!Array.isArray(ids)) return `"${argName}" of ${action} must be an array of ids.`;
+        const list = live.current.read();
+        const missing = ids.filter((value) => typeof value !== "string" || !list.get(value));
+        if (!missing.length) return true;
+        if (!list.length) return `No ${target} is loaded yet. Call ${listName} first for the ids.`;
+        return `The ${ref.refName} form offers no ${target} ${missing.join(", ")}. It offers: ${list
+          .map((model) => `${model.id} (${live.current.label(model)})`)
+          .join(", ")}.`;
+      },
+      run: (args) => {
+        const list = live.current.read();
+        const setter = live.current.onChange as (value: unknown) => unknown;
+        const picked = (idsIn(args) as string[]).flatMap((value) => {
+          const model = list.get(value);
+          return model ? [model] : [];
+        });
+        return setter(many ? picked : (picked[0] ?? null));
+      },
+    });
+    return () => {
+      offList();
+      offSet();
+    };
+  }, [surface, scopeKey, action, disabled]);
+};

package/store/formSetterNames.ts

@@ -17,5 +17,14 @@ export const formSetterNames = (className: string, key: string) => {
     subFieldOnModel: `sub${classKeyName}On${className}`,
     addOrSubFieldOnModel: `addOrSub${classKeyName}On${className}`,
     uploadFieldOnModel: `upload${classKeyName}On${className}`,
+    /**
+     * The optional hook a store declares to run after this field is written.
+     *
+     * It carries no model suffix and a leading `_`, so it can never collide with a generated action name — which is
+     * the whole point: every generated action lives in a mapped type, and a mapped type produces *properties*, so a
+     * subclass method of the same name is a TS2425 error and there is no legal way to override one. A hook under a
+     * name the base type does not declare is the only shape TypeScript permits.
+     */
+    postSetField: `_postSet${classKeyName}`,
   };
 };

package/store/storeRegistry.ts

@@ -1,6 +1,7 @@
 import {
   ACTION_META,
   ACTION_OWNER_META,
+  FIELD_META,
   type MergeAllKeyOfObjects,
   type MergeAllKeyOfTypes,
   type MergeAllTypes,
@@ -9,7 +10,9 @@ import {
   STATE_META,
 } from "akanjs/base";
 import { applyMixins } from "akanjs/common";
+import { ConstantRegistry } from "akanjs/constant";
 import { attachAgentic } from "./agentic";
+import { formSetterNames } from "./formSetterNames";
 import type { RootStoreCls } from "./rootStore";
 import type { StoreCls } from "./store";
 import { StoreInstance } from "./storeInstance";
@@ -57,8 +60,28 @@ export class StoreRegistry {
     store[ACTION_META] = actions;
     store[ACTION_OWNER_META] = owners;
     StoreRegistry.#state.store.set(store.refName, store);
+    StoreRegistry.#warnUnknownPostSetHooks(store);
     return store;
   }
+
+  /**
+   * A `_postSet<Field>` hook cannot be typed — the generated setters live in a mapped type, so every name the base
+   * declares is a property a subclass method may not redeclare (TS2425), and the hook only compiles because the base
+   * declares nothing under it. A misspelled field would therefore never fire and never complain, so say so here.
+   */
+  static #warnUnknownPostSetHooks(store: StoreCls) {
+    const hooks = Object.keys(Object.getOwnPropertyDescriptors(store.prototype)).filter((key) =>
+      key.startsWith("_postSet"),
+    );
+    if (!hooks.length) return;
+    const model = ConstantRegistry.getDatabase(store.refName, { allowEmpty: true });
+    if (!model) return;
+    const known = new Set(
+      Object.keys(model.full[FIELD_META] as object).map((key) => formSetterNames("", key).postSetField),
+    );
+    for (const hook of hooks.filter((key) => !known.has(key)))
+      console.warn(`[${store.refName}Store] ${hook} matches no field of ${store.refName}, so it will never run.`);
+  }
   static get(refName: string) {
     return StoreRegistry.#state.store.get(refName);
   }

package/types/store/agentic/formFields.d.ts

@@ -41,4 +41,13 @@ export declare class FormFields {
     static checked(action: string, path: string, field: ConstantField, value: unknown, depth?: number): unknown;
     /** A field no annotated control can ever name: its rows are written through `writeOn<Model>(path, value)`. */
     static isComposite(field: ConstantField): boolean;
+    /**
+     * The embedded model an array field's rows are, or null for every other field.
+     *
+     * This is the one shape where writing the whole array is a hazard rather than an inconvenience: the agent has to
+     * echo every row it is *not* changing, `checked` validates types and not values, so one mistyped row it was never
+     * asked to touch is written silently. A relation array is excluded — its rows travel as ids, which are the payload
+     * and are refused by name when wrong — and so is an array of primitives, for the same reason.
+     */
+    static rowModelOf(field: ConstantField): (new (...args: never[]) => unknown) | null;
 }

package/types/store/agentic/index.d.ts

@@ -4,5 +4,6 @@ export * from "./readableValue.d.ts";
 export * from "./StToolBuilder.d.ts";
 export * from "./useFieldTool.d.ts";
 export * from "./useFormTools.d.ts";
+export * from "./useRelationFieldTool.d.ts";
 export * from "./useStExpose.d.ts";
 export * from "./useStState.d.ts";

package/types/store/agentic/useFieldTool.d.ts

@@ -7,4 +7,4 @@
  * consequences. Publishing from the form's subscription instead would offer every field of the model, including
  * the ones this template draws no control for.
  */
-export declare const useFieldTool: (onChange: unknown) => void;
+export declare const useFieldTool: (onChange: unknown, transform?: unknown) => void;

package/types/store/agentic/useRelationFieldTool.d.ts

@@ -0,0 +1,27 @@
+import { type DataList } from "akanjs/base";
+export interface RelationFieldSource<T extends {
+    id: string;
+}> {
+    /** Read live from the store rather than closed over: `load` below changes the list mid-call. */
+    read: () => DataList<T>;
+    /** Loads the options an agent never opened the dropdown to fetch. */
+    load: () => Promise<unknown> | unknown;
+    /** How one option reads to a person, so the agent can match what it sees on screen. */
+    label: (model: T) => string;
+    disabled?: boolean;
+}
+/**
+ * The two tools a relation picker owes an agent: list the documents it can pick, then pick by id.
+ *
+ * `FormFields` publishes no schema for a relation, and it is right not to — the form holds the whole related
+ * document, so an id would need a lookup the store does not do. The picker is where that lookup lives: it holds
+ * the slice list, the loader, and the label each option renders with. So the field reaches an agent from the one
+ * component that can resolve it, which is the rule every other control follows — the control is the declaration.
+ *
+ * Listing is its own tool because loading is its own step for a person too: the options arrive when the dropdown
+ * opens, and an agent never opens it. Folding the load into the setter would leave an agent guessing ids in order
+ * to learn them from the refusal.
+ */
+export declare const useRelationFieldTool: <T extends {
+    id: string;
+}>(onChange: unknown, { read, load, label, disabled }: RelationFieldSource<T>) => void;

package/types/store/formSetterNames.d.ts

@@ -13,4 +13,13 @@ export declare const formSetterNames: (className: string, key: string) => {
     subFieldOnModel: string;
     addOrSubFieldOnModel: string;
     uploadFieldOnModel: string;
+    /**
+     * The optional hook a store declares to run after this field is written.
+     *
+     * It carries no model suffix and a leading `_`, so it can never collide with a generated action name — which is
+     * the whole point: every generated action lives in a mapped type, and a mapped type produces *properties*, so a
+     * subclass method of the same name is a TS2425 error and there is no legal way to override one. A hook under a
+     * name the base type does not declare is the only shape TypeScript permits.
+     */
+    postSetField: string;
 };

package/ui/Field.tsx

@@ -3,7 +3,7 @@ import { type DataList, type Dayjs, dayjs, type EnumInstance, isEnum } from "aka
 import { cn, usePage } from "akanjs/client";
 import { capitalize, formatPhone, isPhoneNumber, lowerlize } from "akanjs/common";
 import type { SliceMeta } from "akanjs/fetch";
-import { st, useFieldTool } from "akanjs/store";
+import { st, useFieldTool, useRelationFieldTool } from "akanjs/store";
 import { memo, type ReactNode, useState } from "react";
 import { AiOutlinePlus } from "react-icons/ai";
 import { BiHelpCircle, BiTrash, BiX } from "react-icons/bi";
@@ -104,8 +104,9 @@ const List = <Item,>({
 }: ListProps<Item>) => {
   const { l } = usePage();
   const recipe = useUiRecipe("button") ?? buttonRecipe;
+  useFieldTool(onChange);
   return (
-    <div className={cn("flex w-full flex-col", className)}>
+    <div {...agentAttrs(onChange)} className={cn("flex w-full flex-col", className)}>
       {label ? <Label className={labelClassName} nullable={nullable} label={label} desc={desc} /> : null}
       <div className="mb-2 flex w-full flex-col gap-2 rounded-box border border-border p-2">
         {value.map((item, idx) => (
@@ -181,7 +182,7 @@ const Text = ({
   inputClassName,
   inputStyleType = "bordered",
 }: TextProps) => {
-  useFieldTool(onChange);
+  useFieldTool(onChange, transform);
   const { l } = usePage();
   return (
     <div className={cn("flex flex-col", className)}>
@@ -247,7 +248,7 @@ const Price = ({
   inputClassName,
   inputStyleType = "bordered",
 }: PriceProps) => {
-  useFieldTool(onChange);
+  useFieldTool(onChange, transform);
   const { l } = usePage();
   return (
     <div className={cn("flex flex-col", className)}>
@@ -315,7 +316,7 @@ const TextArea = ({
   cache,
   inputClassName,
 }: TextAreaProps) => {
-  useFieldTool(onChange);
+  useFieldTool(onChange, transform);
   const { l } = usePage();
   return (
     <div className={cn("flex flex-col", className)}>
@@ -544,7 +545,7 @@ const TextList = ({
   validate,
   inputClassName,
 }: TextListProps) => {
-  useFieldTool(onChange);
+  useFieldTool(onChange, transform);
   const { l } = usePage();
   const recipe = useUiRecipe("button") ?? buttonRecipe;
   return (
@@ -651,7 +652,7 @@ const Tags = ({
   validate,
   inputClassName,
 }: TagsProps) => {
-  useFieldTool(onChange);
+  useFieldTool(onChange, transform);
   const { l } = usePage();
   const badge = useUiRecipe("badge") ?? badgeRecipe;
   const [inputVisible, setInputVisible] = useState(false);
@@ -814,9 +815,7 @@ const DateRange = <Nullable extends boolean>({
             value={from}
             max={max}
             min={min}
-            onChange={(value: Dayjs) => {
-              onChangeFrom(value);
-            }}
+            onChange={onChangeFrom}
           />
         </div>
         <div className="relative flex w-full flex-col items-start gap-2 text-center md:flex-row md:items-center">
@@ -828,9 +827,7 @@ const DateRange = <Nullable extends boolean>({
             value={to}
             max={max}
             min={min}
-            onChange={(value: Dayjs) => {
-              onChangeTo(value);
-            }}
+            onChange={onChangeTo}
           />
         </div>
       </div>
@@ -881,7 +878,7 @@ const Number = ({
   formatter,
   parser,
 }: NumberProps) => {
-  useFieldTool(onChange);
+  useFieldTool(onChange, transform);
   const { l } = usePage();
   return (
     <div className={cn("flex flex-col", className)}>
@@ -953,7 +950,7 @@ const DoubleNumber = ({
   validate,
   onPressEnter,
 }: DoubleNumberProps) => {
-  useFieldTool(onChange);
+  useFieldTool(onChange, transform);
   const { l } = usePage();
   return (
     <div {...agentAttrs(onChange)} className={cn("flex flex-col", className)}>
@@ -1041,7 +1038,7 @@ const Email = ({
   inputClassName,
   inputStyleType,
 }: EmailProps) => {
-  useFieldTool(onChange);
+  useFieldTool(onChange, transform);
   const { l } = usePage();
   return (
     <div className={cn("flex flex-col", className)}>
@@ -1106,7 +1103,7 @@ const Phone = ({
   onPressEnter,
   inputClassName,
 }: PhoneProps) => {
-  useFieldTool(onChange);
+  useFieldTool(onChange, transform);
   const { l } = usePage();
 
   return (
@@ -1178,7 +1175,7 @@ const Password = ({
   inputClassName,
   showConfirm,
 }: PasswordProps) => {
-  useFieldTool(onChange);
+  useFieldTool(onChange, transform);
   const { l } = usePage();
   return (
     <div className={cn("flex flex-col", className)}>
@@ -1242,6 +1239,12 @@ interface ParentProps<T extends string, State, Input, Full, Light> {
   renderOption: (model: Light) => ReactNode;
   renderSelected?: (value: Light) => ReactNode;
 }
+/** The one line an option renders as, so an agent can match an id against what it reads on screen. */
+const optionLabel = <Light extends { id: string }>(model: Light, render: (model: Light) => ReactNode) => {
+  const rendered = render(model);
+  return typeof rendered === "string" ? rendered : model.id;
+};
+
 const Parent = <T extends string, State, Input, Full extends { id: string }, Light extends { id: string }>({
   label,
   desc,
@@ -1263,6 +1266,7 @@ const Parent = <T extends string, State, Input, Full extends { id: string }, Lig
   const [modelName, ModelName] = [lowerlize(refName), capitalize(refName)];
   const storeUse = st.use as { [key: string]: () => unknown };
   const storeDo = st.do as unknown as { [key: string]: (...args: any[]) => Promise<void> };
+  const storeGet = st.get as unknown as <V>() => { [key: string]: V };
 
   const names = {
     model: modelName,
@@ -1279,9 +1283,15 @@ const Parent = <T extends string, State, Input, Full extends { id: string }, Lig
 
   const modelList = storeUse[namesOfSlice.modelList]() as DataList<Light>;
   const modelListLoading = storeUse[namesOfSlice.modelListLoading]() as string | boolean;
+  useRelationFieldTool(onChange, {
+    read: () => storeGet<DataList<Light>>()[namesOfSlice.modelList],
+    load: () => storeDo[namesOfSlice.refreshModel]({ invalidate: true, queryArgs: initArgs }),
+    label: (model) => optionLabel(model, renderOption),
+    disabled,
+  });
 
   return (
-    <div className={cn("flex flex-col", className)}>
+    <div {...agentAttrs(onChange)} className={cn("flex flex-col", className)}>
       {label ? <Label className={labelClassName} nullable={nullable} label={label} desc={desc} /> : null}
       <Select<string | null, false, true>
         label={label}
@@ -1373,9 +1383,11 @@ const ParentId = <T extends string, State, Input, Full extends { id: string }, L
   };
   const modelList = storeUse[namesOfSlice.modelList]() as DataList<Light>;
   const modelListLoading = storeUse[namesOfSlice.modelListLoading]() as string | boolean;
+  
+  useFieldTool(onChange);
 
   return (
-    <div className={cn("flex flex-col", className)}>
+    <div {...agentAttrs(onChange)} className={cn("flex flex-col", className)}>
       {label ? <Label className={labelClassName} nullable={nullable} label={label} desc={desc} /> : null}
       <Select<string | null, false, true>
         searchable
@@ -1464,9 +1476,15 @@ const Children = <T extends string, State, Input, Full extends { id: string }, L
   };
   const modelList = storeUse[namesOfSlice.modelList]() as DataList<Light>;
   const modelListLoading = storeUse[namesOfSlice.modelListLoading]() as string | boolean;
+  useRelationFieldTool(onChange, {
+    read: () => storeGet<DataList<Light>>()[namesOfSlice.modelList],
+    load: () => storeDo[namesOfSlice.refreshModel]({ invalidate: true, queryArgs: initArgs }),
+    label: (model) => optionLabel(model, renderOption),
+    disabled,
+  });
 
   return (
-    <div className={cn("flex flex-col", className)}>
+    <div {...agentAttrs(onChange)} className={cn("flex flex-col", className)}>
       {label ? <Label className={labelClassName} nullable={nullable} label={label} desc={desc} /> : null}
       <Select
         searchable
@@ -1554,9 +1572,11 @@ const ChildrenId = <T extends string, State, Input, Full extends { id: string },
   };
   const modelList = storeUse[namesOfSlice.modelList]() as DataList<Light>;
   const modelListLoading = storeUse[namesOfSlice.modelListLoading]() as string | boolean;
+  
+  useFieldTool(onChange);
 
   return (
-    <div className={cn("flex flex-col", className)}>
+    <div {...agentAttrs(onChange)} className={cn("flex flex-col", className)}>
       {label ? <Label className={labelClassName} nullable={nullable} label={label} desc={desc} /> : null}
       <Select
         searchable