@mohasinac/appkit 4.13.1 → 4.14.0

package/dist/features/seller/repository/offer.repository.d.ts

@@ -4,35 +4,92 @@
  * Data access layer for the `offers` Firestore collection.
  * Handles buyer make-an-offer, seller counter/accept/decline lifecycle.
  */
-import { BaseRepository } from "../../../providers/db-firebase";
+import { BaseRepository, parseSieveDateValue } from "../../../providers/db-firebase";
 import type { SieveModel, FirebaseSieveResult } from "../../../providers/db-firebase";
 import type { OfferDocument, OfferCreateInput, OfferUpdateInput } from "../schemas";
 declare class OfferRepository extends BaseRepository<OfferDocument> {
     constructor();
     /** Override mapDoc to auto-decrypt PII on every offer read */
     protected mapDoc<D = OfferDocument>(snap: import("../../../providers/db-firebase").DocumentSnapshot): D;
+    /**
+     * Every Timestamp field here carries `parseValue: parseSieveDateValue`.
+     *
+     * Without it a GTE/LTE on a Timestamp field silently matches ZERO documents:
+     * sievejs's default coercion leaves an ISO string as a string, and Firestore
+     * requires an inequality's value to match the stored type. That is Root Cause
+     * #47, and `createdAt` flipping from `canFilter: false` to `true` here is
+     * exactly the transition that introduces it.
+     *
+     * `checkoutDeadline` is added by hand: `audit-sieve-date-fields` recognises
+     * Timestamp fields by an `...At` / `...Date` / `...Time` suffix, which this
+     * name does not have, so the audit cannot flag it for you.
+     */
     static readonly SIEVE_FIELDS: {
-        readonly status: {
-            readonly canFilter: true;
-            readonly canSort: false;
+        id: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        status: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        productId: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        productTitle: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        buyerUid: {
+            canFilter: boolean;
+            canSort: boolean;
         };
-        readonly productId: {
-            readonly canFilter: true;
-            readonly canSort: false;
+        buyerName: {
+            canFilter: boolean;
+            canSort: boolean;
         };
-        readonly buyerUid: {
-            readonly canFilter: true;
-            readonly canSort: false;
+        storeId: {
+            canFilter: boolean;
+            canSort: boolean;
         };
-        readonly storeId: {
-            readonly canFilter: true;
-            readonly canSort: false;
+        storeName: {
+            canFilter: boolean;
+            canSort: boolean;
         };
-        readonly createdAt: {
-            readonly canFilter: false;
-            readonly canSort: true;
+        offerAmount: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        listedPrice: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        createdAt: {
+            canFilter: boolean;
+            canSort: boolean;
+            parseValue: typeof parseSieveDateValue;
+        };
+        expiresAt: {
+            canFilter: boolean;
+            canSort: boolean;
+            parseValue: typeof parseSieveDateValue;
+        };
+        checkoutDeadline: {
+            canFilter: boolean;
+            canSort: boolean;
+            parseValue: typeof parseSieveDateValue;
         };
     };
+    /**
+     * Paginated, Firestore-native offer list (admin use).
+     *
+     * Mirrors `BidRepository.list`. The seller- and buyer-scoped reads have their
+     * own dedicated methods (`findByStore` / `findByBuyer`) because they carry
+     * mandatory ownership filters; this one is deliberately unscoped and is only
+     * reachable behind `admin:offers:read`.
+     */
+    list(model: SieveModel): Promise<FirebaseSieveResult<OfferDocument>>;
     create(input: OfferCreateInput): Promise<OfferDocument>;
     findByBuyer(buyerUid: string, model?: SieveModel): Promise<FirebaseSieveResult<OfferDocument>>;
     findByStore(storeId: string, model?: SieveModel): Promise<FirebaseSieveResult<OfferDocument>>;

package/dist/features/seller/repository/offer.repository.js

@@ -4,7 +4,7 @@
  * Data access layer for the `offers` Firestore collection.
  * Handles buyer make-an-offer, seller counter/accept/decline lifecycle.
  */
-import { BaseRepository, prepareForFirestore, } from "../../../providers/db-firebase";
+import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase";
 import { OFFER_COLLECTION, OFFER_FIELDS, createOfferId } from "../schemas";
 import { encryptPiiFields, decryptPiiFields, OFFER_PII_FIELDS, } from "../../../security";
 class OfferRepository extends BaseRepository {
@@ -18,6 +18,20 @@ class OfferRepository extends BaseRepository {
             ...OFFER_PII_FIELDS,
         ]);
     }
+    /**
+     * Paginated, Firestore-native offer list (admin use).
+     *
+     * Mirrors `BidRepository.list`. The seller- and buyer-scoped reads have their
+     * own dedicated methods (`findByStore` / `findByBuyer`) because they carry
+     * mandatory ownership filters; this one is deliberately unscoped and is only
+     * reachable behind `admin:offers:read`.
+     */
+    async list(model) {
+        return this.sieveQuery(model, OfferRepository.SIEVE_FIELDS, {
+            defaultPageSize: 50,
+            maxPageSize: 200,
+        });
+    }
     // --- Create --------------------------------------------------------------
     async create(input) {
         const now = new Date();
@@ -235,12 +249,33 @@ class OfferRepository extends BaseRepository {
         await batch.commit();
     }
 }
+/**
+ * Every Timestamp field here carries `parseValue: parseSieveDateValue`.
+ *
+ * Without it a GTE/LTE on a Timestamp field silently matches ZERO documents:
+ * sievejs's default coercion leaves an ISO string as a string, and Firestore
+ * requires an inequality's value to match the stored type. That is Root Cause
+ * #47, and `createdAt` flipping from `canFilter: false` to `true` here is
+ * exactly the transition that introduces it.
+ *
+ * `checkoutDeadline` is added by hand: `audit-sieve-date-fields` recognises
+ * Timestamp fields by an `...At` / `...Date` / `...Time` suffix, which this
+ * name does not have, so the audit cannot flag it for you.
+ */
 OfferRepository.SIEVE_FIELDS = {
-    status: { canFilter: true, canSort: false },
+    id: { canFilter: true, canSort: false },
+    status: { canFilter: true, canSort: true },
     productId: { canFilter: true, canSort: false },
+    productTitle: { canFilter: true, canSort: true },
     buyerUid: { canFilter: true, canSort: false },
+    buyerName: { canFilter: true, canSort: true },
     storeId: { canFilter: true, canSort: false },
-    createdAt: { canFilter: false, canSort: true },
+    storeName: { canFilter: true, canSort: true },
+    offerAmount: { canFilter: true, canSort: true },
+    listedPrice: { canFilter: true, canSort: true },
+    createdAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
+    expiresAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
+    checkoutDeadline: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
 };
 export const offerRepository = new OfferRepository();
 export { OfferRepository };

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,28 @@ 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>>;

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

@@ -26,3 +26,24 @@ 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(),
+    });
+}

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/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>;