@mohasinac/appkit 4.14.0 → 4.16.0

package/dist/features/seller/schemas/offer-forms.d.ts

@@ -35,3 +35,24 @@ export declare function makeOfferFormSchema(opts: {
     buyerNote?: string | undefined;
 }>;
 export type MakeOfferFormValues = z.infer<ReturnType<typeof makeOfferFormSchema>>;
+/**
+ * Admin cancel-offer form.
+ *
+ * A bare confirm dialog was the wrong control here. Admin cancel is an
+ * escalation over the store's own authority, and it lands in three permanent
+ * places at once — the buyer's notification, the offer's own status history,
+ * and `adminAuditLog`. All three are useless without a reason, and the route
+ * used to accept an optional one and never read it.
+ *
+ * The 10-character floor mirrors the server schema exactly. Stating it in both
+ * places is deliberate: the client bound exists so the admin is told before
+ * submitting, not so the server can trust it.
+ */
+export declare const cancelOfferFormSchema: z.ZodObject<{
+    reason: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    reason: string;
+}, {
+    reason: string;
+}>;
+export type CancelOfferFormValues = z.infer<typeof cancelOfferFormSchema>;

package/dist/features/seller/schemas/offer-forms.js

@@ -11,6 +11,8 @@
  *
  * EXPORTS:
  *   counterOfferFormSchema, type CounterOfferFormValues
+ *   makeOfferFormSchema, type MakeOfferFormValues
+ *   cancelOfferFormSchema, type CancelOfferFormValues
  *
  * @tag domain:seller,offers
  * @tag layer:schema
@@ -47,3 +49,22 @@ export function makeOfferFormSchema(opts) {
         buyerNote: z.string().max(300, "Keep your note under 300 characters.").optional(),
     });
 }
+/**
+ * Admin cancel-offer form.
+ *
+ * A bare confirm dialog was the wrong control here. Admin cancel is an
+ * escalation over the store's own authority, and it lands in three permanent
+ * places at once — the buyer's notification, the offer's own status history,
+ * and `adminAuditLog`. All three are useless without a reason, and the route
+ * used to accept an optional one and never read it.
+ *
+ * The 10-character floor mirrors the server schema exactly. Stating it in both
+ * places is deliberate: the client bound exists so the admin is told before
+ * submitting, not so the server can trust it.
+ */
+export const cancelOfferFormSchema = z.object({
+    reason: z
+        .string()
+        .min(10, "Give a reason of at least 10 characters — the buyer sees this.")
+        .max(300, "Keep the reason under 300 characters."),
+});

package/dist/features/shell/build-sections.d.ts

@@ -0,0 +1,63 @@
+import { type ReactNode } from "react";
+import type { ZodTypeAny } from "zod";
+import type { SectionDef } from "./SectionForm";
+import { type FieldUiMeta } from "./field-ui-meta";
+/** One field, resolved: its name, its schema, and its final metadata. */
+export interface ResolvedField {
+    name: string;
+    schema: ZodTypeAny;
+    meta: FieldUiMeta;
+    required: boolean;
+}
+/** Per-field JSX override. Receives everything the derived control would get. */
+export type FieldRenderer<T extends object> = (props: {
+    field: ResolvedField;
+    values: T;
+    onChange: (partial: Partial<T>) => void;
+    errors: Record<string, string>;
+}) => ReactNode;
+export interface BuildSectionsOptions<T extends object> {
+    /** Per-field JSX overrides, keyed by field name. */
+    renderers?: Record<string, FieldRenderer<T>>;
+    /** Option lists for `kind: "select"` fields that aren't Zod enums. */
+    options?: Record<string, {
+        value: string;
+        label: string;
+    }[]>;
+    /** Section id → label, when no field declared `sectionLabel`. */
+    sectionLabels?: Record<string, string>;
+    /**
+     * Section ids in the order they should appear. Sections not listed follow,
+     * in first-declaration order. `sectionRequired` still sorts first regardless.
+     */
+    sectionOrder?: string[];
+}
+/**
+ * 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 declare function resolveFields(schema: ZodTypeAny): ResolvedField[];
+/** Group resolved fields by section, preserving declaration order within each. */
+export declare function groupFieldsBySection(fields: ResolvedField[]): Map<string, ResolvedField[]>;
+/**
+ * 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 declare function packRows(fields: ResolvedField[]): ResolvedField[][];
+/**
+ * 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 declare function buildSectionsFromSchema<T extends object>(schema: ZodTypeAny, opts?: BuildSectionsOptions<T>): SectionDef<T>[];

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;