@mohasinac/appkit 4.13.1 → 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/entity-form.d.ts

@@ -0,0 +1,109 @@
+import type { JsonValue } from "@mohasinac/appkit/client";
+import type { ZodTypeAny } from "zod";
+import type { SectionDef } from "./SectionForm";
+import type { QuickFieldDef, QuickFieldType } from "./QuickFormDrawer";
+/**
+ * One definition per entity, two rendered modes.
+ *
+ * The point of this type is that quick mode is DERIVED from `sections`, never
+ * declared alongside them — two hand-maintained field lists for one entity is
+ * the drift this codebase already has too much of.
+ *
+ * ## Quick mode is self-submitting
+ *
+ * Saving from the quick drawer must produce a complete, valid, publishable
+ * record. It is not step one of the full form; "open full form" is an optional
+ * secondary path. That gives a mechanical rule for what belongs in it:
+ *
+ *     quickFields = schema.required − derive()'s outputs
+ *
+ * If the resulting `quickSchema` cannot satisfy the server's create schema,
+ * the definition is wrong — the missing field either joins the quick set or
+ * gets a `derive()` default. Nothing may be left "for the user to finish
+ * later": that is exactly how `/store/products/new` came to POST without a
+ * `listingType` at all.
+ */
+export interface EntityFormDefinition<T extends object = Record<string, JsonValue>> {
+    /** Stable key — also the `SCHEMAS.forms` registry key. */
+    entity: string;
+    /** Full-mode schema. Satisfies `audit-form-schema`. */
+    schema: ZodTypeAny;
+    /**
+     * Create-mode schema for the quick drawer. Defaults to `schema` when
+     * omitted, but should normally be `schema.pick(quickFields)`.
+     *
+     * CREATE ONLY. A quick schema is a strict subset by construction, so
+     * sending it to a PATCH would strip every field outside the quick set.
+     */
+    quickSchema?: ZodTypeAny;
+    /** THE single source of truth for this entity's fields. */
+    sections: SectionDef<T>[];
+    /**
+     * Auto-compute fields from earlier ones — slug and SEO from a title, totals
+     * from line items, counts from an array.
+     *
+     * Two rules, both enforced rather than documented:
+     *  - a `derive()` output may NEVER also be a quick field (asserted by
+     *    `assertNoDeriveCollision`) — that would ask the user for something the
+     *    definition already computes;
+     *  - it must fill only when the target is empty or its source actually
+     *    changed, never overwrite a value the user typed.
+     */
+    derive?: (partial: Partial<T>, prev: T, ctx: {
+        mode: "create" | "edit";
+    }) => Partial<T>;
+    /** Field names `derive` can produce. Used to subtract them from the quick set. */
+    derivedFields?: readonly string[];
+    /** Input types for quick-mode fields. Anything absent defaults to `"text"`. */
+    quickFieldTypes?: Readonly<Record<string, QuickFieldType>>;
+    /** Labels for quick-mode fields. Falls back to a humanised field name. */
+    quickFieldLabels?: Readonly<Record<string, string>>;
+    /** Field names that are required in quick mode (drives the `required` flag). */
+    requiredFields?: readonly string[];
+    routes: {
+        list: string;
+        new: string;
+        edit: (id: string) => string;
+        view?: (id: string) => string;
+    };
+    labels: {
+        singular: string;
+        plural: string;
+    };
+}
+/** `"storeName"` / `"store_name"` / `"store.name"` -> `"Store name"`. */
+export declare function humaniseFieldName(name: string): string;
+/**
+ * The quick-mode field set: every field owned by a `quick: true` section,
+ * minus anything `derive()` produces.
+ *
+ * Derived, never declared — so quick and full modes cannot drift apart.
+ */
+export declare function deriveQuickFieldNames<T extends object>(def: EntityFormDefinition<T>): string[];
+/** Quick-mode field descriptors — feed straight into QuickFormDrawer's `fields` prop. */
+export declare function deriveQuickFields<T extends object>(def: EntityFormDefinition<T>): QuickFieldDef[];
+/**
+ * Throws when a `derive()` output is also offered as a quick field.
+ *
+ * That combination means the form asks the user to type something the
+ * definition computes for them, and whichever runs last silently wins. Call
+ * this once per definition — it is cheap and catches the mistake at the point
+ * the definition is written rather than at the point data is lost.
+ */
+export declare function assertNoDeriveCollision<T extends object>(def: EntityFormDefinition<T>): void;
+/**
+ * Every field name the definition can reach — the union of all section fields
+ * plus everything `derive()` produces.
+ *
+ * This is what a schema must be a superset of. A document field missing from
+ * this set is unreachable in the UI; a schema field missing from it can never
+ * be populated. `audit-form-field-roundtrip` checks both directions.
+ */
+export declare function allDefinitionFields<T extends object>(def: EntityFormDefinition<T>): string[];
+/**
+ * Apply `derive()` to a pending change, without clobbering user input.
+ *
+ * Returns the partial to merge: the caller's own change plus whatever the
+ * definition computed from it.
+ */
+export declare function applyDerive<T extends object>(def: EntityFormDefinition<T>, partial: Partial<T>, prev: T, mode: "create" | "edit"): Partial<T>;

package/dist/features/shell/entity-form.js

@@ -0,0 +1,96 @@
+/** `"storeName"` / `"store_name"` / `"store.name"` -> `"Store name"`. */
+export function humaniseFieldName(name) {
+    const leaf = name.includes(".") ? name.slice(name.lastIndexOf(".") + 1) : name;
+    const spaced = leaf
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[_-]+/g, " ")
+        .trim();
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+/**
+ * The quick-mode field set: every field owned by a `quick: true` section,
+ * minus anything `derive()` produces.
+ *
+ * Derived, never declared — so quick and full modes cannot drift apart.
+ */
+export function deriveQuickFieldNames(def) {
+    const derived = new Set(def.derivedFields ?? []);
+    const seen = new Set();
+    const out = [];
+    for (const section of def.sections) {
+        if (!section.quick)
+            continue;
+        for (const field of section.fields ?? []) {
+            if (derived.has(field) || seen.has(field))
+                continue;
+            seen.add(field);
+            out.push(field);
+        }
+    }
+    return out;
+}
+/** Quick-mode field descriptors — feed straight into QuickFormDrawer's `fields` prop. */
+export function deriveQuickFields(def) {
+    const required = new Set(def.requiredFields ?? []);
+    return deriveQuickFieldNames(def).map((name) => ({
+        name,
+        label: def.quickFieldLabels?.[name] ?? humaniseFieldName(name),
+        type: def.quickFieldTypes?.[name] ?? "text",
+        required: required.has(name),
+    }));
+}
+/**
+ * Throws when a `derive()` output is also offered as a quick field.
+ *
+ * That combination means the form asks the user to type something the
+ * definition computes for them, and whichever runs last silently wins. Call
+ * this once per definition — it is cheap and catches the mistake at the point
+ * the definition is written rather than at the point data is lost.
+ */
+export function assertNoDeriveCollision(def) {
+    const derived = new Set(def.derivedFields ?? []);
+    if (derived.size === 0)
+        return;
+    const collisions = [];
+    for (const section of def.sections) {
+        if (!section.quick)
+            continue;
+        for (const field of section.fields ?? []) {
+            if (derived.has(field))
+                collisions.push(field);
+        }
+    }
+    if (collisions.length > 0) {
+        throw new Error(`EntityFormDefinition("${def.entity}"): ${collisions.join(", ")} ` +
+            `${collisions.length === 1 ? "is" : "are"} produced by derive() and also ` +
+            `marked as quick field(s). A derived field must not be asked of the user — ` +
+            `drop it from the quick section's \`fields\`, or stop deriving it.`);
+    }
+}
+/**
+ * Every field name the definition can reach — the union of all section fields
+ * plus everything `derive()` produces.
+ *
+ * This is what a schema must be a superset of. A document field missing from
+ * this set is unreachable in the UI; a schema field missing from it can never
+ * be populated. `audit-form-field-roundtrip` checks both directions.
+ */
+export function allDefinitionFields(def) {
+    const out = new Set(def.derivedFields ?? []);
+    for (const section of def.sections) {
+        for (const field of section.fields ?? [])
+            out.add(field);
+    }
+    return [...out];
+}
+/**
+ * Apply `derive()` to a pending change, without clobbering user input.
+ *
+ * Returns the partial to merge: the caller's own change plus whatever the
+ * definition computed from it.
+ */
+export function applyDerive(def, partial, prev, mode) {
+    if (!def.derive)
+        return partial;
+    return { ...partial, ...def.derive(partial, prev, { mode }) };
+}

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;