@mohasinac/appkit 4.14.0 → 4.15.0

package/dist/features/shell/build-sections.js

@@ -0,0 +1,207 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+/*
+ * WHY: A `SectionDef[]` written by hand is a second source of truth that has to
+ *      stay aligned with the schema that validates it. Nothing enforces the
+ *      alignment, so a field added to the schema renders nowhere, and a field
+ *      removed from the schema keeps rendering into a key that is stripped on
+ *      save. `audit-form-field-roundtrip` exists to catch exactly that — this
+ *      file removes the opportunity instead.
+ * WHAT: `buildSectionsFromSchema` — walk a schema's shape, group by
+ *       `FieldUiMeta.section`, pack consecutive fields into `<FormGroup>` rows
+ *       by their `row` span, and pick each control from its `kind`.
+ *
+ * Sections become DERIVED, exactly as quick mode already is. Adding a field to
+ * the schema puts it in the right section, in the right row, in the right mode,
+ * with one edit rather than three.
+ *
+ * ## The escape hatch is per field, not per form
+ *
+ * `renderers` overrides a single field's JSX while everything around it stays
+ * derived. That matters: a form with one bespoke control should not have to
+ * hand-write its other twelve fields, which is what an all-or-nothing escape
+ * hatch would force and is how hand-written section arrays got normalised in
+ * the first place.
+ *
+ * EXPORTS:
+ *   buildSectionsFromSchema, groupFieldsBySection, packRows,
+ *   type FieldRenderer, type BuildSectionsOptions
+ *
+ * @tag domain:forms
+ * @tag layer:shared
+ * @tag pattern:slot-shell
+ * @tag access:client
+ * @tag consumers:SectionForm callsites
+ * @tag sideEffects:none
+ */
+import { Fragment } from "react";
+import { FormGroup } from "../../ui/components/Form";
+import { FieldInput } from "../../ui/forms/FieldInput";
+import { FieldSelect } from "../../ui/forms/FieldSelect";
+import { FieldTextarea } from "../../ui/forms/FieldTextarea";
+import { FieldCheckbox } from "../../ui/forms/FieldCheckbox";
+import { humaniseFieldName } from "./entity-form";
+import { ROW_COLUMNS, inferFieldUiMeta, objectShape, schemaEnumOptions, schemaIsOptional, ui, } from "./field-ui-meta";
+/**
+ * Enum members as `<FieldSelect>` options.
+ *
+ * Both the zod-version handling and the optional/required test live in
+ * `field-ui-meta.ts` — this file must not grow a second copy, which is how the
+ * two majors' differing `_def` shapes would come to be handled inconsistently.
+ */
+function selectOptions(schema) {
+    const options = schemaEnumOptions(schema);
+    return options ? options.map((o) => ({ value: o, label: humaniseFieldName(o) })) : null;
+}
+/**
+ * Resolve every field in a schema's shape.
+ *
+ * Fields with no registration are still returned, carrying inferred metadata
+ * and a `section` of `""`. Dropping them silently would hide the exact defect
+ * `audit-field-ui-meta` is meant to report — an unregistered field, or one
+ * whose `.register()` was not the last call in the chain and was therefore
+ * discarded by a subsequent `.optional()`.
+ */
+export function resolveFields(schema) {
+    const shape = objectShape(schema);
+    if (!shape)
+        return [];
+    return Object.entries(shape).map(([name, fieldSchema]) => {
+        const explicit = ui.get(fieldSchema);
+        const meta = {
+            section: "",
+            ...inferFieldUiMeta(name, fieldSchema),
+            ...(explicit ?? {}),
+        };
+        return { name, schema: fieldSchema, meta, required: !schemaIsOptional(fieldSchema) };
+    });
+}
+/** Group resolved fields by section, preserving declaration order within each. */
+export function groupFieldsBySection(fields) {
+    const bySection = new Map();
+    for (const field of fields) {
+        if (field.meta.derived)
+            continue; // server-owned — never an input
+        const key = field.meta.section || "advanced";
+        const bucket = bySection.get(key);
+        if (bucket)
+            bucket.push(field);
+        else
+            bySection.set(key, [field]);
+    }
+    for (const bucket of bySection.values()) {
+        bucket.sort((a, b) => (a.meta.order ?? Number.MAX_SAFE_INTEGER) - (b.meta.order ?? Number.MAX_SAFE_INTEGER));
+    }
+    return bySection;
+}
+/**
+ * Pack consecutive fields into rows by their span.
+ *
+ * A `full` field always breaks the current row — that is what stops a media
+ * upload or a textarea being squeezed alongside a short input. Mixed spans
+ * start a new row too, rather than being crammed together: two `pair` fields
+ * make a clean 2-up, a `pair` next to a `quarter` makes neither.
+ */
+export function packRows(fields) {
+    const rows = [];
+    let current = [];
+    let currentSpan = null;
+    const flush = () => {
+        if (current.length > 0)
+            rows.push(current);
+        current = [];
+        currentSpan = null;
+    };
+    for (const field of fields) {
+        const span = field.meta.row ?? "pair";
+        if (span === "full") {
+            flush();
+            rows.push([field]);
+            continue;
+        }
+        if (currentSpan !== null && (span !== currentSpan || current.length >= ROW_COLUMNS[span])) {
+            flush();
+        }
+        current.push(field);
+        currentSpan = span;
+    }
+    flush();
+    return rows;
+}
+/**
+ * Build the `SectionDef[]` a `<SectionForm>` renders.
+ *
+ * Section order: `sectionRequired` first (there is normally exactly one — the
+ * fields without which the record cannot be saved), then `sectionOrder`, then
+ * first-declaration order.
+ */
+export function buildSectionsFromSchema(schema, opts = {}) {
+    const fields = resolveFields(schema);
+    const bySection = groupFieldsBySection(fields);
+    const declarationOrder = [...bySection.keys()];
+    const explicitOrder = opts.sectionOrder ?? [];
+    const rank = (id) => {
+        const bucket = bySection.get(id) ?? [];
+        if (bucket.some((f) => f.meta.sectionRequired))
+            return -1;
+        const i = explicitOrder.indexOf(id);
+        return i === -1 ? explicitOrder.length + declarationOrder.indexOf(id) : i;
+    };
+    return declarationOrder
+        .slice()
+        .sort((a, b) => rank(a) - rank(b))
+        .map((sectionId) => {
+        const sectionFields = bySection.get(sectionId) ?? [];
+        const label = sectionFields.find((f) => f.meta.sectionLabel)?.meta.sectionLabel ??
+            opts.sectionLabels?.[sectionId] ??
+            humaniseFieldName(sectionId);
+        return {
+            id: sectionId,
+            label,
+            required: sectionFields.some((f) => f.meta.sectionRequired),
+            quick: sectionFields.some((f) => f.meta.quick),
+            // Any section holding uncommitted state must stay mounted while
+            // collapsed — `<Collapse>` unmounts children, which would discard an
+            // in-flight media upload. Inference sets this for every media field.
+            keepMounted: sectionFields.some((f) => f.meta.sectionKeepMounted),
+            fields: sectionFields.map((f) => f.name),
+            render: ({ values, onChange, errors }) => (_jsx(_Fragment, { children: packRows(sectionFields).map((row, i) => (_jsx(FormGroup, { columns: ROW_COLUMNS[row[0].meta.row ?? "pair"], children: row.map((field) => renderField(field, { values, onChange, errors }, opts)) }, `${sectionId}-row-${i}`))) })),
+        };
+    });
+}
+function renderField(field, ctx, opts) {
+    const override = opts.renderers?.[field.name];
+    // A keyed Fragment, not a wrapper element: an override may legitimately
+    // return a block-level control (a media uploader, a repeatable list editor),
+    // and wrapping that in a <span> would put block content inside an inline box.
+    if (override)
+        return _jsx(Fragment, { children: override({ field, ...ctx }) }, field.name);
+    const { name, meta, required } = field;
+    const label = meta.label ?? humaniseFieldName(name);
+    const value = ctx.values[name];
+    const set = (v) => ctx.onChange({ [name]: v });
+    switch (meta.kind) {
+        case "toggle":
+            return (_jsx(FieldCheckbox, { name: name, label: label, hint: meta.help, checked: Boolean(value), onChange: set }, name));
+        case "textarea":
+            return (_jsx(FieldTextarea, { name: name, label: label, hint: meta.help, required: required, value: typeof value === "string" ? value : "", onChange: set }, name));
+        case "select": {
+            const options = opts.options?.[name] ?? selectOptions(field.schema) ?? [];
+            return (_jsx(FieldSelect, { name: name, label: label, hint: meta.help === "paginated" ? undefined : meta.help, required: required, value: typeof value === "string" ? value : "", options: options, onChange: set }, name));
+        }
+        case "number":
+            return (_jsx(FieldInput, { name: name, type: "number", label: label, hint: meta.help, required: required, value: value == null ? "" : String(value), onChange: (v) => set(v === "" ? undefined : Number(v)) }, name));
+        case "date":
+            return (_jsx(FieldInput, { name: name, type: "date", label: label, hint: meta.help, required: required, value: typeof value === "string" ? value.slice(0, 10) : "", onChange: set }, name));
+        // `media` and `list` have no derived control on purpose. A MediaUploadField
+        // needs an upload context, a staging path and a finalize call that only the
+        // owning feature can supply, and a list editor needs to know what an item
+        // looks like. Deriving a placeholder for either would render a control that
+        // silently fails to save — worse than requiring an explicit renderer.
+        case "media":
+        case "list":
+            return (_jsx(FieldInput, { name: name, label: label, hint: meta.help ?? `Provide a renderer for "${name}" — this field needs a custom control.`, required: required, disabled: true, value: "" }, name));
+        default:
+            return (_jsx(FieldInput, { name: name, label: label, hint: meta.help, required: required, value: typeof value === "string" ? value : value == null ? "" : String(value), onChange: set }, name));
+    }
+}

package/dist/features/shell/field-ui-meta.d.ts

@@ -0,0 +1,115 @@
+import type { ZodTypeAny } from "zod";
+/** How much of a row a field claims on desktop. Everything is 1-up on mobile. */
+export type FieldRow = "full" | "pair" | "third" | "quarter";
+/** Which input primitive renders the field, and its default row span. */
+export type FieldKind = "text" | "number" | "date" | "select" | "toggle" | "textarea" | "media" | "list";
+/**
+ * Which tier owns a value that is not typed by the user.
+ * T1 client `derive()` · T2 server-on-write · T3 mirror · T4 background job.
+ * The tier decides the correctness rule — see the calculated-field dictionary.
+ */
+export type CalculatedTier = "t1-derive" | "t2-server" | "t3-mirror" | "t4-aggregate";
+export interface FieldUiMeta {
+    /**
+     * Section id this field belongs to — the grouping key, and the ONE key that
+     * cannot be inferred. Whether `gstin` belongs under "Tax" or "Business
+     * details" is a product decision, and a wrong section renders perfectly
+     * fine in the wrong place with nothing failing. Deliberately NOT inferred
+     * from a name prefix (`billing_city` → "billing"): that would work for a
+     * handful of schemas and quietly mis-group the rest.
+     */
+    section: string;
+    /** Human label for the section. The first field to declare it wins. */
+    sectionLabel?: string;
+    /** Marks its section required-first, open on mount, non-collapsible. */
+    sectionRequired?: boolean;
+    /**
+     * Section keeps its panel mounted while collapsed. Mandatory for any
+     * section holding uncommitted state — `<Collapse>` unmounts its children,
+     * which discards an in-flight media upload.
+     */
+    sectionKeepMounted?: boolean;
+    /** Row span. Drives the `<FormGroup columns>` packing. */
+    row?: FieldRow;
+    /** Control kind. Picks the primitive and the default row span. */
+    kind?: FieldKind;
+    /** Sort order within the section. Unset sorts after ordered fields. */
+    order?: number;
+    /** Belongs in the self-submitting quick drawer. */
+    quick?: boolean;
+    /** Produced by `derive()` or the server — never rendered as a bare input. */
+    derived?: boolean;
+    /** Which calculated-field tier owns it, when it is not user-entered. */
+    tier?: CalculatedTier;
+    label?: string;
+    help?: string;
+}
+export declare const ui: {
+    /** Attach metadata to a schema instance. Returns the SAME instance. */
+    add<S extends ZodTypeAny>(schema: S, meta: FieldUiMeta): S;
+    get(schema: ZodTypeAny): FieldUiMeta | undefined;
+    has(schema: ZodTypeAny): boolean;
+};
+/**
+ * Annotate a field. **Must be the outermost call in the chain** — see the
+ * ordering trap in the header.
+ *
+ *     name:  annotate(z.string().min(1),   { section: "basics", quick: true }),
+ *     photo: annotate(z.string().optional(), { section: "media" }),
+ *
+ * Wrapping the call rather than chaining off it (`.register()`-style) is
+ * deliberate: it puts the schema visually INSIDE the annotation, so appending
+ * `.optional()` afterwards looks as wrong as it is.
+ */
+export declare function annotate<S extends ZodTypeAny>(schema: S, meta: FieldUiMeta): S;
+/** `row` → the `<FormGroup columns>` value it packs into. */
+export declare const ROW_COLUMNS: Record<FieldRow, 1 | 2 | 3 | 4>;
+/**
+ * Strip `.optional()` / `.nullable()` / `.default()` / `.catch()` to reach the
+ * type that actually decides the control. Returns the innermost schema and its
+ * normalised type discriminator.
+ *
+ * Reads `_def` because zod exposes no public accessor for this, on either
+ * major. Depth-bounded rather than trusting the shape: `_def` is internal, and
+ * this must degrade to "text" rather than loop if a future zod reshapes it.
+ */
+export declare function unwrapSchema(schema: ZodTypeAny): {
+    schema: ZodTypeAny;
+    type: string;
+};
+/** Public: the option list for a select-shaped field, or null. */
+export declare function schemaEnumOptions(schema: ZodTypeAny): string[] | null;
+/** Public: whether a field's type is optional-wrapped (i.e. not required). */
+export declare function schemaIsOptional(schema: ZodTypeAny): boolean;
+/**
+ * The `.shape` of an object schema, seeing through effects wrappers.
+ *
+ * `.superRefine()` / `.refine()` / `.transform()` return a wrapper that does
+ * NOT expose `.shape` — verified: `z.object({...}).superRefine(fn)` has
+ * `_def.typeName === "ZodEffects"`, `.shape === undefined`, and the real object
+ * on `_def.schema`. Reading `.shape` directly therefore returns nothing for any
+ * schema with a cross-field rule, which is most of the interesting ones (the
+ * payout form's UPI-vs-bank branch is exactly this shape).
+ *
+ * Failing to unwrap would not error — it would silently derive a form with
+ * ZERO sections, which is the quiet-wrong-answer failure mode this whole wave
+ * exists to eliminate.
+ */
+export declare function objectShape(schema: ZodTypeAny): Record<string, ZodTypeAny> | null;
+/**
+ * Everything about a field's layout that can be derived from its name and its
+ * Zod type. `section` is never inferred, so the return type is a Partial —
+ * `resolveFieldUiMeta` is what merges it with the explicit registration.
+ *
+ * This is what makes annotation cheap: a 13-field form is 13 short
+ * `.register(ui, { section: "…" })` calls, not 13 full metadata objects.
+ */
+export declare function inferFieldUiMeta(name: string, schema: ZodTypeAny): Partial<FieldUiMeta>;
+/**
+ * The field's final metadata: inference first, explicit registration on top.
+ *
+ * Returns `null` when the field has no registration at all — the caller
+ * decides whether that is a hard error (a registered form schema, where
+ * `section` is mandatory) or a fallback (an ad-hoc schema being previewed).
+ */
+export declare function resolveFieldUiMeta(name: string, schema: ZodTypeAny): FieldUiMeta | null;

package/dist/features/shell/field-ui-meta.js

@@ -0,0 +1,324 @@
+/*
+ * WHY: Which section a field belongs to, and whether it shares a row with its
+ *      neighbour, were conventions written in a table in a plan document. A
+ *      convention drifts; 70 bare `grid-cols-2` in the tree — each one two
+ *      columns wide at 320px — are what that drift looks like. Zod 4 lets the
+ *      rule live on the field it describes, so the schema becomes the single
+ *      source of validation, section membership AND layout.
+ * WHAT: `FieldUiMeta`, the typed `ui` registry, and `inferFieldUiMeta` — the
+ *       heuristic that means only `section` has to be stated per field.
+ *
+ * ## 🛑 There are TWO zods in this repo, and that decided the design
+ *
+ * Measured 2026-08-24: the app depends on **zod 4.4.3**, but `appkit`'s own
+ * `package.json` declares `zod: ^3.24.0` and a v3 copy is nested at
+ * `node_modules/@mohasinac/appkit/node_modules/zod` (3.25.76). Verified with
+ * `createRequire`: appkit's shipped `dist` resolves `"zod"` to that nested v3,
+ * while consumer code resolves to root v4. Two instances, one bundle — the
+ * Root Cause #19 shape, on a package the dedupe script does not cover.
+ *
+ * So `z.registry<FieldUiMeta>()` is **not usable here**: it is a zod-4 API and
+ * appkit compiles against v3. Aligning the two is a dependency major across
+ * the 76 appkit files that import zod — its own wave, not a drive-by inside a
+ * spine wave.
+ *
+ * This registry is therefore a plain `WeakMap` keyed by schema instance, which
+ * is what `z.registry()` is internally. It behaves identically, works on both
+ * majors, and is strictly MORE robust to the split: object identity does not
+ * care which zod class produced the object. `annotate()` is typed, so a typo
+ * (`rows:` for `row:`) is a compile error — the property `.meta()` never had.
+ *
+ * Everything that introspects a schema below reads BOTH shapes for the same
+ * reason: zod 3 says `_def.typeName === "ZodOptional"`, zod 4 says
+ * `_def.type === "optional"`, and this file sees both at runtime.
+ *
+ * ## 🛑 The ordering trap — metadata MUST be the last call in the chain
+ *
+ * Verified at runtime:
+ *
+ *     annotate(z.string(), {...}).optional()   // ✗ meta LOST → lookup undefined
+ *     annotate(z.string().optional(), {...})   // ✓ survives
+ *
+ * Every wrapper (`.optional()`, `.nullable()`, `.default()`, `.catch()`)
+ * returns a NEW schema instance, and the registry is keyed by instance. Most
+ * fields are optional, so getting this backwards silently drops layout for the
+ * majority of them. `audit-field-ui-meta` enforces the ordering.
+ *
+ * EXPORTS:
+ *   FieldUiMeta, FieldRow, FieldKind, CalculatedTier, ui, annotate,
+ *   inferFieldUiMeta, resolveFieldUiMeta, unwrapSchema, ROW_COLUMNS
+ *
+ * @tag domain:forms
+ * @tag layer:shared
+ * @tag pattern:registry
+ * @tag access:isomorphic
+ * @tag consumers:buildSectionsFromSchema,audit-field-ui-meta
+ * @tag sideEffects:none
+ */
+/**
+ * The registry. A module-level singleton, because the whole point is that
+ * every form schema in the app annotates into the same place and can be
+ * queried as one ("every media field", "every quick field", "every field with
+ * no section").
+ *
+ * `WeakMap` so annotating a schema never keeps it alive.
+ */
+const REGISTRY = new WeakMap();
+export const ui = {
+    /** Attach metadata to a schema instance. Returns the SAME instance. */
+    add(schema, meta) {
+        REGISTRY.set(schema, meta);
+        return schema;
+    },
+    get(schema) {
+        return REGISTRY.get(schema);
+    },
+    has(schema) {
+        return REGISTRY.has(schema);
+    },
+};
+/**
+ * Annotate a field. **Must be the outermost call in the chain** — see the
+ * ordering trap in the header.
+ *
+ *     name:  annotate(z.string().min(1),   { section: "basics", quick: true }),
+ *     photo: annotate(z.string().optional(), { section: "media" }),
+ *
+ * Wrapping the call rather than chaining off it (`.register()`-style) is
+ * deliberate: it puts the schema visually INSIDE the annotation, so appending
+ * `.optional()` afterwards looks as wrong as it is.
+ */
+export function annotate(schema, meta) {
+    return ui.add(schema, meta);
+}
+/** `row` → the `<FormGroup columns>` value it packs into. */
+export const ROW_COLUMNS = {
+    full: 1,
+    pair: 2,
+    third: 3,
+    quarter: 4,
+};
+// ---------------------------------------------------------------------------
+// Inference
+// ---------------------------------------------------------------------------
+/**
+ * Normalise a zod type discriminator across majors.
+ * zod 3: `_def.typeName === "ZodOptional"` · zod 4: `_def.type === "optional"`.
+ */
+function typeOf(schema) {
+    const def = schema._def;
+    if (def?.type)
+        return def.type; // v4, already lowercase
+    const name = def?.typeName; // v3, "ZodOptional"
+    return name ? name.replace(/^Zod/, "").toLowerCase() : "";
+}
+/** Wrappers that produce a new instance around an inner type. */
+const WRAPPERS = new Set(["optional", "nullable", "default", "catch", "readonly", "nonoptional"]);
+/**
+ * Strip `.optional()` / `.nullable()` / `.default()` / `.catch()` to reach the
+ * type that actually decides the control. Returns the innermost schema and its
+ * normalised type discriminator.
+ *
+ * Reads `_def` because zod exposes no public accessor for this, on either
+ * major. Depth-bounded rather than trusting the shape: `_def` is internal, and
+ * this must degrade to "text" rather than loop if a future zod reshapes it.
+ */
+export function unwrapSchema(schema) {
+    let current = schema;
+    for (let depth = 0; depth < 10; depth++) {
+        const def = current._def;
+        const type = typeOf(current);
+        if (!WRAPPERS.has(type) || !def?.innerType)
+            return { schema: current, type };
+        current = def.innerType;
+    }
+    return { schema: current, type: "" };
+}
+/**
+ * The `max()` bound on a string schema, when it declares one — the signal that
+ * separates a text input from a textarea.
+ *
+ * The two majors store checks completely differently:
+ *   v3: `_def.checks = [{ kind: "max", value: 300 }]`
+ *   v4: `_def.checks = [{ _zod: { def: { check: "max_length", maximum: 300 } } }]`
+ */
+function stringMaxLength(schema) {
+    const checks = schema._def?.checks;
+    if (!Array.isArray(checks))
+        return undefined;
+    for (const check of checks) {
+        const v4 = check?._zod?.def;
+        if (v4?.check === "max_length" && typeof v4.maximum === "number")
+            return v4.maximum;
+        const v3 = check;
+        if (v3?.kind === "max" && typeof v3.value === "number")
+            return v3.value;
+    }
+    return undefined;
+}
+/**
+ * Enum members. v4 exposes `.options`; v3 keeps them on `_def.values`, and for
+ * a native enum on `_def.values` as an object.
+ */
+function enumOptions(schema) {
+    const direct = schema.options;
+    if (Array.isArray(direct))
+        return direct.filter((o) => typeof o === "string");
+    const values = schema._def?.values;
+    if (Array.isArray(values))
+        return values.filter((o) => typeof o === "string");
+    if (values && typeof values === "object") {
+        return Object.values(values).filter((o) => typeof o === "string");
+    }
+    return undefined;
+}
+/** Public: the option list for a select-shaped field, or null. */
+export function schemaEnumOptions(schema) {
+    const { schema: inner } = unwrapSchema(schema);
+    return enumOptions(inner) ?? null;
+}
+/** Public: whether a field's type is optional-wrapped (i.e. not required). */
+export function schemaIsOptional(schema) {
+    const type = typeOf(schema);
+    return type === "optional" || type === "default" || type === "nullish";
+}
+/**
+ * The `.shape` of an object schema, seeing through effects wrappers.
+ *
+ * `.superRefine()` / `.refine()` / `.transform()` return a wrapper that does
+ * NOT expose `.shape` — verified: `z.object({...}).superRefine(fn)` has
+ * `_def.typeName === "ZodEffects"`, `.shape === undefined`, and the real object
+ * on `_def.schema`. Reading `.shape` directly therefore returns nothing for any
+ * schema with a cross-field rule, which is most of the interesting ones (the
+ * payout form's UPI-vs-bank branch is exactly this shape).
+ *
+ * Failing to unwrap would not error — it would silently derive a form with
+ * ZERO sections, which is the quiet-wrong-answer failure mode this whole wave
+ * exists to eliminate.
+ */
+export function objectShape(schema) {
+    let current = schema;
+    for (let depth = 0; depth < 10; depth++) {
+        const direct = current.shape;
+        if (direct)
+            return direct;
+        const def = current._def;
+        const next = def?.schema ?? def?.innerType ?? def?.in;
+        if (!next)
+            return null;
+        current = next;
+    }
+    return null;
+}
+/**
+ * Name patterns override the Zod type, because a name carries intent a type
+ * cannot. `images` is `ZodArray` but it is a media field, not a list editor;
+ * `description` is `ZodString` but it is a textarea.
+ *
+ * Ordered — the first match wins, so the media test runs before the long-text
+ * one (`coverImage` must not become a textarea).
+ */
+const NAME_RULES = [
+    {
+        // Media claims a full row ALWAYS, and forces its section to keepMounted:
+        // a MediaUploadField stacks a source-tab strip, a drop target, a progress
+        // bar and a preview, and collapsing it mid-upload discards the transfer.
+        test: /(^|[a-z])(image|images|photo|video|media|avatar|banner|logo|cover|thumbnail)([A-Z]|s?$)/i,
+        meta: { kind: "media", row: "full", sectionKeepMounted: true },
+    },
+    {
+        test: /^(description|body|content|notes?|bio|message|excerpt|answer|returnPolicy)$/i,
+        meta: { kind: "textarea", row: "full" },
+    },
+    {
+        // Long single inputs: truncating a URL or an address into half a row makes
+        // it unreadable, so they take the whole row even though they are short types.
+        test: /^(url|slug|email|title|name|displayName|headline|address|addressLine1|addressLine2|line1|line2)$/i,
+        meta: { row: "full" },
+    },
+    {
+        test: /^(firstName|lastName|city|state|postcode|pincode|postalCode|ifsc|gstin|pan|hsn|price|rate|percent|quantity|phone)$/i,
+        meta: { row: "pair" },
+    },
+];
+/**
+ * Fields nothing should ever render as an input — ids, audit stamps and
+ * counters. Marked `derived` so `audit-form-field-roundtrip` reads them as
+ * server-owned rather than as unreachable schema fields.
+ */
+const SERVER_OWNED = /^(id|createdAt|updatedAt|createdBy|updatedBy|ownerId|authorId|userId|views|viewCount|productCount|usageCount|helpfulCount|replyCount|reportCount)$/;
+/** Zod type → its default control and row span. */
+function fromZodType(type, inner) {
+    switch (type) {
+        case "boolean":
+            // Several per wrapping row — a switch plus label is short, and stacking
+            // them one-per-row makes a settings section endless.
+            return { kind: "toggle", row: "quarter" };
+        case "enum":
+        case "nativeEnum":
+        case "literal":
+        case "union":
+            return { kind: "select", row: "pair" };
+        case "date":
+            return { kind: "date", row: "pair" };
+        case "number":
+        case "bigint":
+            return { kind: "number", row: "pair" };
+        case "array":
+            return { kind: "list", row: "full" };
+        case "object":
+        case "record":
+            return { kind: "list", row: "full" };
+        case "string": {
+            const max = stringMaxLength(inner);
+            return max != null && max > 200
+                ? { kind: "textarea", row: "full" }
+                : { kind: "text", row: "pair" };
+        }
+        default:
+            return { kind: "text", row: "pair" };
+    }
+}
+/**
+ * Everything about a field's layout that can be derived from its name and its
+ * Zod type. `section` is never inferred, so the return type is a Partial —
+ * `resolveFieldUiMeta` is what merges it with the explicit registration.
+ *
+ * This is what makes annotation cheap: a 13-field form is 13 short
+ * `.register(ui, { section: "…" })` calls, not 13 full metadata objects.
+ */
+export function inferFieldUiMeta(name, schema) {
+    const { schema: inner, type } = unwrapSchema(schema);
+    const meta = { ...fromZodType(type, inner) };
+    for (const rule of NAME_RULES) {
+        if (rule.test.test(name)) {
+            Object.assign(meta, rule.meta);
+            break;
+        }
+    }
+    if (SERVER_OWNED.test(name)) {
+        meta.derived = true;
+        meta.tier = meta.tier ?? "t2-server";
+    }
+    // >5 options is the standing PaginatedSelect threshold. Recorded as `help`
+    // rather than a separate flag so the renderer can decide without a second
+    // source of truth about what "many options" means.
+    const options = enumOptions(inner);
+    if (meta.kind === "select" && options != null && options.length > 5) {
+        meta.help = meta.help ?? "paginated";
+    }
+    return meta;
+}
+/**
+ * The field's final metadata: inference first, explicit registration on top.
+ *
+ * Returns `null` when the field has no registration at all — the caller
+ * decides whether that is a hard error (a registered form schema, where
+ * `section` is mandatory) or a fallback (an ad-hoc schema being previewed).
+ */
+export function resolveFieldUiMeta(name, schema) {
+    const explicit = ui.get(schema);
+    if (!explicit)
+        return null;
+    return { ...inferFieldUiMeta(name, schema), ...explicit };
+}

package/dist/features/shell/index.d.ts

@@ -10,5 +10,9 @@ export type { SectionDef, SectionFormProps, UseSectionFormNavResult, } from "./S
 export { SectionForm, useSectionFormNav, orderSections, buildFieldToSectionIndex, sectionAnchorId, } from "./SectionForm";
 export type { EntityFormDefinition } from "./entity-form";
 export { deriveQuickFields, deriveQuickFieldNames, allDefinitionFields, applyDerive, assertNoDeriveCollision, humaniseFieldName, } from "./entity-form";
+export type { FieldUiMeta, FieldRow, FieldKind, CalculatedTier, } from "./field-ui-meta";
+export { ui, annotate, ROW_COLUMNS, inferFieldUiMeta, resolveFieldUiMeta, unwrapSchema, schemaEnumOptions, schemaIsOptional, objectShape, } from "./field-ui-meta";
+export type { ResolvedField, FieldRenderer, BuildSectionsOptions, } from "./build-sections";
+export { buildSectionsFromSchema, resolveFields, groupFieldsBySection, packRows, } from "./build-sections";
 export type { TitleDescriptionGroupProps, ImageFieldGroupProps, SeoFieldGroupProps, StatusFieldGroupProps, StatusFieldGroupOption, } from "./field-groups";
 export { TitleDescriptionGroup, ImageFieldGroup, SeoFieldGroup, StatusFieldGroup, } from "./field-groups";

package/dist/features/shell/index.js

@@ -4,4 +4,6 @@ export { QuickFormDrawer } from "./QuickFormDrawer";
 export { StepForm, StepFormActions, StepIndicator } from "./StepForm";
 export { SectionForm, useSectionFormNav, orderSections, buildFieldToSectionIndex, sectionAnchorId, } from "./SectionForm";
 export { deriveQuickFields, deriveQuickFieldNames, allDefinitionFields, applyDerive, assertNoDeriveCollision, humaniseFieldName, } from "./entity-form";
+export { ui, annotate, ROW_COLUMNS, inferFieldUiMeta, resolveFieldUiMeta, unwrapSchema, schemaEnumOptions, schemaIsOptional, objectShape, } from "./field-ui-meta";
+export { buildSectionsFromSchema, resolveFields, groupFieldsBySection, packRows, } from "./build-sections";
 export { TitleDescriptionGroup, ImageFieldGroup, SeoFieldGroup, StatusFieldGroup, } from "./field-groups";