@mohasinac/appkit 4.13.1 → 4.15.0

package/dist/features/seller/schemas/firestore.d.ts

@@ -3,6 +3,7 @@
  */
 import { type GenerateOfferIdInput } from "../../../utils/id-generators";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+import type { StatusChangeEntry } from "../../../_internal/shared/history/index";
 export type OfferStatus = "pending" | "accepted" | "declined" | "countered" | "expired" | "withdrawn" | "paid";
 /** Runtime-accessible offer status values — use instead of bare string literals. */
 export declare const OfferStatusValues: {
@@ -39,7 +40,52 @@ export interface OfferDocument extends BaseDocument {
     /** Set by `markPaid` once the buyer's order exists — makes "paid" auditable. */
     paidOrderId?: string;
     paidAt?: Date;
+    /**
+     * Append-only delta log — the canonical record of when things happened to
+     * this offer. Shares `StatusChangeEntry` with `OrderDocument`; an offer is
+     * an order with more phases in front of it.
+     *
+     * `respondedAt` is deliberately kept but NOT extended: it means four
+     * different events (seller-accept, seller-decline, seller-counter,
+     * buyer-withdraw) and survives only as the legacy fallback for offers
+     * written before this field existed.
+     */
+    statusHistory?: StatusChangeEntry[];
+    /** Entries dropped off the front — so the UI never implies "this is all of it". */
+    statusHistoryTruncated?: number;
+    /**
+     * The multi-round chain. A counter-offer is a NEW document, so without
+     * these three a three-round negotiation is three unrelated records —
+     * which is what it is today: `previousOfferId` currently exists only
+     * inside a `serverLogger.info` call and never reaches Firestore.
+     */
+    previousOfferId?: string;
+    supersededByOfferId?: string;
+    /**
+     * Denormalised root of the chain (the root stores its own id) so a list row
+     * renders "Round 2" with ZERO extra reads, and `findChain` is a single-field
+     * equality served by the automatic index — no composite index needed.
+     */
+    chainRootOfferId?: string;
+    /** 1-based. Absent means round 1. */
+    counterRound?: number;
+    /**
+     * Admin escalation. The store keeps sole authority to accept/counter/
+     * decline; an admin may only cancel, with a reason, and it is recorded
+     * here as well as in `adminAuditLog`.
+     */
+    cancelledByAdminUid?: string;
+    cancelReason?: string;
 }
+/**
+ * Fields whose changes are recorded in an offer's `statusHistory`.
+ *
+ * Excludes `buyerName`/`buyerEmail` (PII — `encryptPiiFields` never descends
+ * into arrays, so they would persist in plaintext inside the history),
+ * `buyerNote`/`sellerNote` (they ride in the entry's `note`), and
+ * `updatedAt`/`respondedAt` (noise that would burn the FIFO cap).
+ */
+export declare const OFFER_TRACKED_FIELDS: readonly ["status", "offerAmount", "counterAmount", "lockedPrice", "checkoutDeadline", "paidOrderId", "supersededByOfferId", "previousOfferId"];
 export declare const OFFER_COLLECTION: "offers";
 export declare const OFFER_INDEXED_FIELDS: readonly ["buyerUid", "storeId", "productId", "status", "createdAt", "expiresAt", "checkoutDeadline"];
 export declare const OFFER_FIELDS: {
@@ -67,9 +113,17 @@ export declare const OFFER_FIELDS: {
     readonly PAID_AT: "paidAt";
     readonly CREATED_AT: "createdAt";
     readonly UPDATED_AT: "updatedAt";
+    readonly STATUS_HISTORY: "statusHistory";
+    readonly STATUS_HISTORY_TRUNCATED: "statusHistoryTruncated";
+    readonly PREVIOUS_OFFER_ID: "previousOfferId";
+    readonly SUPERSEDED_BY_OFFER_ID: "supersededByOfferId";
+    readonly CHAIN_ROOT_OFFER_ID: "chainRootOfferId";
+    readonly COUNTER_ROUND: "counterRound";
+    readonly CANCELLED_BY_ADMIN_UID: "cancelledByAdminUid";
+    readonly CANCEL_REASON: "cancelReason";
 };
-export type OfferCreateInput = Pick<OfferDocument, "productId" | "productTitle" | "productSlug" | "productImageUrl" | "buyerUid" | "buyerName" | "buyerEmail" | "storeId" | "storeName" | "offerAmount" | "listedPrice" | "currency" | "buyerNote">;
-export type OfferUpdateInput = Partial<Pick<OfferDocument, "status" | "counterAmount" | "lockedPrice" | "sellerNote" | "acceptedAt" | "checkoutDeadline" | "respondedAt" | "paidOrderId" | "paidAt" | "updatedAt">>;
+export type OfferCreateInput = Pick<OfferDocument, "productId" | "productTitle" | "productSlug" | "productImageUrl" | "buyerUid" | "buyerName" | "buyerEmail" | "storeId" | "storeName" | "offerAmount" | "listedPrice" | "currency" | "buyerNote" | "previousOfferId" | "chainRootOfferId" | "counterRound">;
+export type OfferUpdateInput = Partial<Pick<OfferDocument, "status" | "counterAmount" | "lockedPrice" | "sellerNote" | "acceptedAt" | "checkoutDeadline" | "respondedAt" | "paidOrderId" | "paidAt" | "updatedAt" | "statusHistory" | "statusHistoryTruncated" | "supersededByOfferId" | "cancelledByAdminUid" | "cancelReason">>;
 export declare const offerQueryHelpers: {
     readonly byBuyer: (buyerUid: string) => readonly ["buyerUid", "==", string];
     readonly byStore: (storeId: string) => readonly ["storeId", "==", string];

package/dist/features/seller/schemas/firestore.js

@@ -12,6 +12,24 @@ export const OfferStatusValues = {
     WITHDRAWN: "withdrawn",
     PAID: "paid",
 };
+/**
+ * Fields whose changes are recorded in an offer's `statusHistory`.
+ *
+ * Excludes `buyerName`/`buyerEmail` (PII — `encryptPiiFields` never descends
+ * into arrays, so they would persist in plaintext inside the history),
+ * `buyerNote`/`sellerNote` (they ride in the entry's `note`), and
+ * `updatedAt`/`respondedAt` (noise that would burn the FIFO cap).
+ */
+export const OFFER_TRACKED_FIELDS = [
+    "status",
+    "offerAmount",
+    "counterAmount",
+    "lockedPrice",
+    "checkoutDeadline",
+    "paidOrderId",
+    "supersededByOfferId",
+    "previousOfferId",
+];
 export const OFFER_COLLECTION = "offers";
 export const OFFER_INDEXED_FIELDS = [
     "buyerUid",
@@ -47,6 +65,15 @@ export const OFFER_FIELDS = {
     PAID_AT: "paidAt",
     CREATED_AT: "createdAt",
     UPDATED_AT: "updatedAt",
+    // Negotiation history + chain (W2)
+    STATUS_HISTORY: "statusHistory",
+    STATUS_HISTORY_TRUNCATED: "statusHistoryTruncated",
+    PREVIOUS_OFFER_ID: "previousOfferId",
+    SUPERSEDED_BY_OFFER_ID: "supersededByOfferId",
+    CHAIN_ROOT_OFFER_ID: "chainRootOfferId",
+    COUNTER_ROUND: "counterRound",
+    CANCELLED_BY_ADMIN_UID: "cancelledByAdminUid",
+    CANCEL_REASON: "cancelReason",
 };
 export const offerQueryHelpers = {
     byBuyer: (buyerUid) => ["buyerUid", "==", buyerUid],

package/dist/features/seller/schemas/index.d.ts

@@ -89,8 +89,8 @@ export declare const sellerStoreSchema: z.ZodObject<{
     id: string;
     createdAt: string;
     updatedAt: string;
-    storeName: string;
     ownerId: string;
+    storeName: string;
     storeSlug: string;
     isPublic: boolean;
     location?: string | undefined;
@@ -121,8 +121,8 @@ export declare const sellerStoreSchema: z.ZodObject<{
     id: string;
     createdAt: string;
     updatedAt: string;
-    storeName: string;
     ownerId: string;
+    storeName: string;
     storeSlug: string;
     isPublic: boolean;
     location?: string | undefined;

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

@@ -10,3 +10,49 @@ export declare const counterOfferFormSchema: z.ZodObject<{
     sellerNote?: string | undefined;
 }>;
 export type CounterOfferFormValues = z.infer<typeof counterOfferFormSchema>;
+/**
+ * Buyer-side Make-an-Offer form.
+ *
+ * A factory rather than a constant because both bounds depend on the listing:
+ * the floor is `minOfferAmount(listedPrice, minOfferPercent)` and the ceiling is
+ * the listed price itself. Both are re-checked server-side in `makeOffer` — this
+ * exists so the buyer is told before submitting, using the SAME
+ * `minOfferAmount()` the server uses, rather than a second rounding rule that
+ * could disagree by a rupee.
+ */
+export declare function makeOfferFormSchema(opts: {
+    listedPrice: number;
+    minOffer: number;
+    formatAmount: (n: number) => string;
+}): z.ZodObject<{
+    offerAmount: z.ZodNumber;
+    buyerNote: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    offerAmount: number;
+    buyerNote?: string | undefined;
+}, {
+    offerAmount: number;
+    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
@@ -26,3 +28,43 @@ export const counterOfferFormSchema = z.object({
         .positive("Counter amount must be greater than zero."),
     sellerNote: z.string().max(500, "Keep your note under 500 characters.").optional(),
 });
+/**
+ * Buyer-side Make-an-Offer form.
+ *
+ * A factory rather than a constant because both bounds depend on the listing:
+ * the floor is `minOfferAmount(listedPrice, minOfferPercent)` and the ceiling is
+ * the listed price itself. Both are re-checked server-side in `makeOffer` — this
+ * exists so the buyer is told before submitting, using the SAME
+ * `minOfferAmount()` the server uses, rather than a second rounding rule that
+ * could disagree by a rupee.
+ */
+export function makeOfferFormSchema(opts) {
+    const { listedPrice, minOffer, formatAmount } = opts;
+    return z.object({
+        offerAmount: z.coerce
+            .number({ invalid_type_error: "Enter an offer amount." })
+            .positive("Offer amount must be greater than zero.")
+            .min(minOffer, `Minimum offer is ${formatAmount(minOffer)}.`)
+            .max(listedPrice - 0.01, `Offer must be below the listed price of ${formatAmount(listedPrice)} — use Add to Cart to buy at that price.`),
+        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/seller/server.d.ts

@@ -8,4 +8,3 @@ export { OfferRepository, offerRepository, } from "./repository/offer.repository
 export { GET as sellerProductsGET } from "./api/products/route";
 export { GET as sellerStoreGET } from "./api/store/route";
 export { GET as sellerCouponsGET } from "./api/coupons/route";
-export { GET as sellerOffersGET } from "./api/offers/route";

package/dist/features/seller/server.js

@@ -8,4 +8,3 @@ export { OfferRepository, offerRepository, } from "./repository/offer.repository
 export { GET as sellerProductsGET } from "./api/products/route";
 export { GET as sellerStoreGET } from "./api/store/route";
 export { GET as sellerCouponsGET } from "./api/coupons/route";
-export { GET as sellerOffersGET } from "./api/offers/route";

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

@@ -0,0 +1,99 @@
+import { type ReactNode } from "react";
+import type { JsonValue } from "@mohasinac/appkit/client";
+import type { ZodTypeAny } from "zod";
+import type { FormShellStep } from "../../ui/forms/FormShell";
+/**
+ * A collapsible form segment. Replaces `StepDef` — the differences are the
+ * point, not incidental:
+ *
+ *  - there is no `goNext` gate, so a section can never block access to a
+ *    later one. Everything is reachable at all times;
+ *  - `required` sections sort first and open on mount;
+ *  - one shared submit at the bottom, never per-section.
+ */
+export interface SectionDef<T extends object = Record<string, JsonValue>> {
+    /** Stable, URL-safe. Becomes the `?section=` value and the DOM anchor id. */
+    id: string;
+    label: string;
+    /** Longer heading for the open panel. Defaults to `label`. */
+    heading?: string;
+    /**
+     * Mandatory section: sorted first, open on mount, and its header renders
+     * without a collapse control so it can't be hidden.
+     */
+    required?: boolean;
+    /**
+     * This section's fields belong to quick mode. Consumed by
+     * `deriveQuickFields` in `entity-form.ts`, not by SectionForm itself.
+     */
+    quick?: boolean;
+    /**
+     * Keep the panel mounted while collapsed. Set on any section holding
+     * uncommitted state — media uploads, rich-text buffers. See
+     * `CollapsibleSection.keepMounted`.
+     */
+    keepMounted?: boolean;
+    render: (props: {
+        values: T;
+        onChange: (partial: Partial<T>) => void;
+        errors: Record<string, string>;
+    }) => ReactNode;
+    /**
+     * Schema field names this section owns — drives error→section attribution
+     * so `<FormErrorSummary>` can offer a jump link.
+     */
+    fields?: string[];
+    /** Per-section schema. Falls back to `schema`, then `FormSchemaContext`. */
+    schema?: ZodTypeAny;
+    /** Hide the section entirely (conditional per-type sections). */
+    when?: (values: T) => boolean;
+}
+export interface SectionFormProps<T extends object = Record<string, JsonValue>> {
+    sections: SectionDef<T>[];
+    values: T;
+    onChange: (partial: Partial<T>) => void;
+    onSubmit: () => void | Promise<void>;
+    submitLabel?: string;
+    isLoading?: boolean;
+    /** Whole-form schema for sections that don't declare their own. */
+    schema?: ZodTypeAny;
+    /** Controlled open set. Omit to let SectionForm own it. */
+    openIds?: string[];
+    onOpenChange?: (ids: string[]) => void;
+    /** `"single"` = accordion. Default `"multi"` — independent sections. */
+    expandMode?: "single" | "multi";
+    /** Suppress the built-in submit row (a FormShell footer owns it instead). */
+    hideActions?: boolean;
+    /**
+     * Fires whenever live validation recomputes. SectionForm deliberately does
+     * NOT mount its own `FormShellContext.Provider` — the owning view keeps the
+     * single provider and composes these in, exactly as StepForm did, so a
+     * second provider can never shadow the real one.
+     */
+    onValidationChange?: (fieldErrors: Record<string, string>, fieldToSectionIndex: Record<string, number>) => void;
+}
+/** Sections in render order: required first, original order preserved within each group. */
+export declare function orderSections<T extends object>(sections: SectionDef<T>[]): SectionDef<T>[];
+/** `fieldName -> index into the ORDERED section list`. */
+export declare function buildFieldToSectionIndex<T extends object>(ordered: SectionDef<T>[]): Record<string, number>;
+export interface UseSectionFormNavResult<T extends object> {
+    /** Sections in render order — required first. */
+    ordered: SectionDef<T>[];
+    openIds: string[];
+    setOpenIds: (ids: string[]) => void;
+    /** Expand section `index`, then scroll it into view. */
+    goToSection: (index: number) => void;
+    fieldToSectionIndex: Record<string, number>;
+    /** Descriptors for `useFormShellState`'s `nav.sections`. */
+    sectionMeta: FormShellStep[];
+}
+/**
+ * Navigation state for a `<SectionForm>`. Feed `sectionMeta`/`goToSection`/
+ * `fieldToSectionIndex` into `useFormShellState(schema, nav)` and `openIds`
+ * back into `<SectionForm>`.
+ */
+export declare function useSectionFormNav<T extends object = Record<string, JsonValue>>(sections: SectionDef<T>[], values?: T): UseSectionFormNavResult<T>;
+/** DOM id for a section panel — kept in one place so nav and render agree. */
+export declare function sectionAnchorId(id: string): string;
+export declare function SectionForm<T extends object = Record<string, JsonValue>>({ sections, values, onChange, onSubmit, submitLabel, isLoading, schema, openIds: controlledOpenIds, onOpenChange, expandMode, hideActions, onValidationChange, }: SectionFormProps<T>): import("react").JSX.Element;
+export default SectionForm;

package/dist/features/shell/SectionForm.js

@@ -0,0 +1,128 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { Button } from "../../ui/components/Button";
+import { CollapsibleSection } from "../../ui/components/CollapsibleSection";
+import { Badge } from "../../ui/components/Badge";
+import { Row, Span, Stack } from "../../ui";
+import { FormSchemaContext } from "./FormShell";
+/** Sections in render order: required first, original order preserved within each group. */
+export function orderSections(sections) {
+    return [...sections.filter((s) => s.required), ...sections.filter((s) => !s.required)];
+}
+/** `fieldName -> index into the ORDERED section list`. */
+export function buildFieldToSectionIndex(ordered) {
+    const map = {};
+    ordered.forEach((section, i) => {
+        section.fields?.forEach((field) => { map[field] = i; });
+    });
+    return map;
+}
+/**
+ * Navigation state for a `<SectionForm>`. Feed `sectionMeta`/`goToSection`/
+ * `fieldToSectionIndex` into `useFormShellState(schema, nav)` and `openIds`
+ * back into `<SectionForm>`.
+ */
+export function useSectionFormNav(sections, values) {
+    const ordered = useMemo(() => {
+        const visible = values
+            ? sections.filter((s) => (s.when ? s.when(values) : true))
+            : sections;
+        return orderSections(visible);
+    }, [sections, values]);
+    const [openIds, setOpenIds] = useState(() => orderSections(sections).filter((s) => s.required).map((s) => s.id));
+    const fieldToSectionIndex = useMemo(() => buildFieldToSectionIndex(ordered), [ordered]);
+    const sectionMeta = useMemo(() => ordered.map((s) => ({ id: s.id, label: s.label, requiredFields: s.fields })), [ordered]);
+    const goToSection = useCallback((index) => {
+        const target = ordered[index];
+        if (!target)
+            return;
+        setOpenIds((prev) => (prev.includes(target.id) ? prev : [...prev, target.id]));
+        // The panel must MOUNT before it can be scrolled to — expanding is a state
+        // update, so defer a frame. Without this the scroll lands on a zero-height
+        // collapsed header and the offending field stays off-screen.
+        requestAnimationFrame(() => {
+            const el = document.getElementById(sectionAnchorId(target.id));
+            el?.scrollIntoView({ behavior: "smooth", block: "start" });
+            el?.querySelector("[aria-invalid='true']")?.focus();
+        });
+    }, [ordered]);
+    return { ordered, openIds, setOpenIds, goToSection, fieldToSectionIndex, sectionMeta };
+}
+/** DOM id for a section panel — kept in one place so nav and render agree. */
+export function sectionAnchorId(id) {
+    return `section-${id}`;
+}
+export function SectionForm({ sections, values, onChange, onSubmit, submitLabel = "Save", isLoading = false, schema, openIds: controlledOpenIds, onOpenChange, expandMode = "multi", hideActions = false, onValidationChange, }) {
+    const inheritedSchema = useContext(FormSchemaContext);
+    const [fieldErrors, setFieldErrors] = useState({});
+    const [uncontrolledOpenIds, setUncontrolledOpenIds] = useState(() => orderSections(sections).filter((s) => s.required).map((s) => s.id));
+    const ordered = useMemo(() => orderSections(sections.filter((s) => (s.when ? s.when(values) : true))), [sections, values]);
+    const openIds = controlledOpenIds ?? uncontrolledOpenIds;
+    const setOpenIds = useCallback((ids) => {
+        if (!controlledOpenIds)
+            setUncontrolledOpenIds(ids);
+        onOpenChange?.(ids);
+    }, [controlledOpenIds, onOpenChange]);
+    const fieldToSectionIndex = useMemo(() => buildFieldToSectionIndex(ordered), [ordered]);
+    // Keep the latest callback without making runValidation depend on it — the
+    // caller usually passes an inline arrow, which would otherwise rebuild the
+    // validator on every render and re-fire the effect below in a loop.
+    const onValidationChangeRef = useRef(onValidationChange);
+    onValidationChangeRef.current = onValidationChange;
+    const runValidation = useCallback((nextValues) => {
+        const activeSchema = schema ?? inheritedSchema;
+        if (!activeSchema)
+            return;
+        // audit-unvalidated-safeparse-ok: bulk-replaces fieldErrors from the full
+        // parse result so a field that just became valid is cleared — which
+        // applyZodIssues' incremental setFieldError-per-issue cannot do.
+        const parsed = activeSchema.safeParse(nextValues);
+        if (parsed.success) {
+            setFieldErrors({});
+            onValidationChangeRef.current?.({}, fieldToSectionIndex);
+            return;
+        }
+        const next = {};
+        for (const issue of parsed.error.issues) {
+            if (!issue.path || issue.path.length === 0)
+                continue;
+            next[issue.path.map(String).join(".")] = issue.message;
+        }
+        setFieldErrors(next);
+        onValidationChangeRef.current?.(next, fieldToSectionIndex);
+    }, [schema, inheritedSchema, fieldToSectionIndex]);
+    useEffect(() => {
+        runValidation(values);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [schema, inheritedSchema, fieldToSectionIndex]);
+    const handleFieldChange = useCallback((partial) => {
+        onChange(partial);
+        runValidation({ ...values, ...partial });
+    }, [values, onChange, runValidation]);
+    const toggle = useCallback((id) => {
+        const isOpen = openIds.includes(id);
+        if (expandMode === "single") {
+            setOpenIds(isOpen ? [] : [id]);
+            return;
+        }
+        setOpenIds(isOpen ? openIds.filter((x) => x !== id) : [...openIds, id]);
+    }, [openIds, expandMode, setOpenIds]);
+    const errorCountFor = useCallback((section) => {
+        if (!section.fields?.length)
+            return 0;
+        return section.fields.filter((f) => Object.keys(fieldErrors).some((k) => k === f || k.startsWith(`${f}.`))).length;
+    }, [fieldErrors]);
+    return (_jsxs(Stack, { gap: "md", children: [ordered.map((section) => {
+                const isRequired = section.required === true;
+                // A required section is always open — it holds the fields without
+                // which the record cannot be saved, so hiding it is never useful.
+                const isCollapsed = isRequired ? false : !openIds.includes(section.id);
+                const errorCount = errorCountFor(section);
+                return (_jsx(CollapsibleSection, { id: sectionAnchorId(section.id), title: _jsxs(Row, { align: "center", gap: "xs", children: [_jsx(Span, { weight: "semibold", size: "sm", children: section.heading ?? section.label }), isRequired && _jsx(Span, { size: "xs", color: "muted", children: "Required" })] }), isCollapsed: isCollapsed, onToggle: () => { if (!isRequired)
+                        toggle(section.id); }, keepMounted: section.keepMounted, renderHeaderExtra: errorCount > 0
+                        ? () => (_jsxs(Badge, { variant: "danger", children: [errorCount, " ", errorCount === 1 ? "issue" : "issues"] }))
+                        : undefined, children: section.render({ values, onChange: handleFieldChange, errors: fieldErrors }) }, section.id));
+            }), !hideActions && (_jsx(Row, { justify: "end", paddingY: "y-sm", children: _jsx(Button, { variant: "primary", type: "submit", onClick: () => void onSubmit(), isLoading: isLoading, disabled: isLoading, children: submitLabel }) }))] }));
+}
+export default SectionForm;

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>[];