@mohasinac/appkit 4.30.19 → 4.31.1

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

@@ -31,21 +31,37 @@ export const counterOfferFormSchema = z.object({
 /**
  * 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.
+ * A factory rather than a constant because both bounds depend on the listing.
+ * It takes the already-resolved `OfferBounds` rather than recomputing them:
+ * `resolveOfferBounds()` is what `makeOffer` enforces, so anything this schema
+ * accepts, the server accepts. Deriving a second floor here is exactly how the
+ * forms came to advertise a 50% minimum the server rejected at 70 (see the
+ * offers config header).
+ *
+ * Three shapes, all from the same bounds object:
+ *
+ * - **Buy request** (`isBuyRequest`) — no cart on this type and no haggling
+ *   opted in, so `min === max` and the only legal amount is the asking price.
+ * - **Offer, no cart** — floor to asking price *inclusive*: with no Add to Cart
+ *   button, refusing a full-price offer would leave the buyer nowhere to go.
+ * - **Offer, cartable** — the original rule, ceiling exclusive of the price.
  */
 export function makeOfferFormSchema(opts) {
-    const { listedPrice, minOffer, formatAmount } = opts;
+    const { listedPrice, bounds, formatAmount } = opts;
+    const amount = z.coerce
+        .number({ invalid_type_error: "Enter an offer amount." })
+        .positive("Offer amount must be greater than zero.");
+    const bounded = bounds.isBuyRequest
+        ? amount
+            .min(bounds.min, `This seller is not taking lower offers — the price is ${formatAmount(bounds.min)}.`)
+            .max(bounds.max, `This seller is not taking lower offers — the price is ${formatAmount(bounds.max)}.`)
+        : amount
+            .min(bounds.min, `Minimum offer is ${formatAmount(bounds.min)}.`)
+            .max(bounds.max, bounds.max >= listedPrice
+            ? `Your offer cannot exceed the asking price of ${formatAmount(listedPrice)}.`
+            : `Offer must be below the listed price of ${formatAmount(listedPrice)} — use Add to Cart to buy at that price.`);
     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.`),
+        offerAmount: bounded,
         buyerNote: z.string().max(300, "Keep your note under 300 characters.").optional(),
     });
 }

package/dist/features/shell/FormShell.js

@@ -6,7 +6,7 @@ import { Button } from "../../ui/components/Button";
 import { IconButton } from "../../ui/components/IconButton";
 import { classNames } from "../../ui/style.helper";
 import { FORM_ACTION_META, FORM_ACTION_ID } from "../products/constants/action-defs";
-import { Div, Row, Span, Stack, Text } from "../../ui";
+import { ActionRow, Div, Row, Span, Stack, Text } from "../../ui";
 /**
  * Carries the `schema` prop passed to `<FormShell>` down to any nested
  * `<SectionForm>` that doesn't declare its own `schema`/`SectionDef.schema` —
@@ -125,5 +125,5 @@ export function FormShell({ isOpen, onClose, title, breadcrumb, schema, isDirty
     return (_jsxs(FormSchemaContext.Provider, { value: schema, children: [_jsx(Div, { surface: "overlay-sm", className: "fixed inset-0 backdrop-blur-[2px]", style: { zIndex: "calc(var(--appkit-z-modal) - 1)" }, "aria-hidden": "true", onClick: attemptClose }), _jsxs(Div, { layout: "flex", ref: panelRef, role: "dialog", "aria-modal": "true", "aria-label": title, className: "fixed top-0 bottom-0 left-0 right-0 lg:left-[10%] lg:right-[10%] [flex-direction:column] bg-[var(--appkit-color-surface)]", shadow: "2xl", style: { zIndex: "var(--appkit-z-modal)" }, children: [_jsxs(Row, { gap: "sm", paddingX: "x-5", className: "flex-shrink-0 sticky top-0 z-10 border-b border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)]", padding: "y-sm", children: [previewMode ? (_jsxs(Button, { variant: "ghost", type: "button", onClick: () => setPreviewMode(false), "aria-label": "Back to edit", gap: "xs", rounded: "lg", textSize: "sm", textColor: "muted", className: "flex-shrink-0", children: [_jsx(ArrowLeft, { className: "w-4 h-4" }), _jsx(Span, { className: "hidden sm:inline", children: "Back to Edit" })] })) : (_jsx(IconButton, { type: "button", onClick: attemptClose, "aria-label": "Close", variant: "ghost", rounded: "lg", className: "text-[var(--appkit-color-text-muted)] flex-shrink-0", children: _jsx(X, { className: "w-5 h-5" }) })), _jsxs(Div, { className: "flex-1 min-w-0", children: [breadcrumb && (_jsx(Text, { className: "text-[var(--appkit-color-text-muted)] truncate mb-0.5", size: "xs", children: breadcrumb })), _jsx(Text, { className: "text-[var(--appkit-color-text)] truncate", size: "sm", weight: "semibold", children: previewMode ? `Preview — ${title}` : title })] }), _jsx(Row, { gap: "xs", className: "flex-shrink-0", children: previewMode ? null : (_jsxs(_Fragment, { children: [previewSlot && (_jsxs(Button, { variant: "outline", type: "button", onClick: () => setPreviewMode(true), gap: "xs", rounded: "lg", paddingX: "sm", textSize: "sm", textColor: "muted", children: [_jsx(Eye, { className: "w-4 h-4" }), _jsx(Span, { className: "hidden sm:inline", children: "Preview" })] })), onSaveDraft && (_jsx(Button, { variant: "outline", size: "sm", onClick: handleSaveDraft, disabled: isLoading || savingDraft || publishing, isLoading: savingDraft, children: saveLabel })), onPublish && (_jsx(Button, { variant: "primary", size: "sm", onClick: handlePublish, disabled: isLoading || savingDraft || publishing, isLoading: publishing, children: publishLabel }))] })) })] }), _jsxs(Div, { layout: "flex", className: `flex-1 ${__O.hidden}`, children: [sections && sections.length > 0 && !previewMode && (_jsx("nav", { "aria-label": "Form sections", className: "hidden lg:flex flex-col flex-shrink-0 w-48 border-r border-[var(--appkit-color-border)] py-[var(--appkit-space-4)] px-[var(--appkit-space-3)] gap-[var(--appkit-space-1)] overflow-y-auto", children: sections.map((sec) => (_jsx(Button, { variant: "ghost", type: "button", onClick: () => scrollToSection(sec.id), rounded: "lg", paddingX: "sm", paddingY: "xs", textSize: "sm", textColor: "muted", justify: "start", className: "text-left", children: sec.label }, sec.id))) })), sections && sections.length > 0 && !previewMode && (_jsx(Row, { gap: "px", className: `lg:hidden fixed top-[var(--form-shell-topbar-h,57px)] left-0 right-0 z-10 ${__O.xAuto} px-[1.25rem] bg-[var(--appkit-color-surface)] border-b border-[var(--appkit-color-border)]`, padding: "y-xs", children: sections.map((sec) => (_jsx(Button, { variant: "outline", type: "button", onClick: () => scrollToSection(sec.id), rounded: "full", paddingX: "sm", paddingY: "xs", textSize: "xs", textColor: "muted", className: "flex-shrink-0 hover:border-primary hover:text-primary whitespace-nowrap", children: sec.label }, sec.id))) })), _jsx(Div, { ref: bodyRef, className: classNames("flex-1 overflow-y-auto", sections && sections.length > 0 && !previewMode ? "pt-[var(--appkit-space-0)] lg:pt-[var(--appkit-space-0)]" : ""), children: previewMode && previewSlot ? (_jsxs(_Fragment, { children: [_jsxs(Row, { textSize: "sm", gap: "xs", className: "sticky top-0 z-10 bg-[var(--appkit-color-warning-surface)] border-b border-[var(--appkit-color-warning)] text-[var(--appkit-color-warning-text,var(--appkit-color-warning))]", paddingY: "y-xs", paddingX: "x-md", children: [_jsx(Eye, { className: "w-4 h-4 flex-shrink-0" }), _jsx(Span, { children: "Preview \u2014 not visible to buyers until published" })] }), _jsx(Div, { padding: "y-md", children: previewSlot() })] })) : splitPreview && previewSlot ? (
                                 // S-STORE-3-D — desktop 60/40 split: form left, preview right.
                                 // Below `lg`, falls back to single-column form (preview-as-modal via existing toggle).
-                                _jsxs(Div, { className: "lg:grid lg:grid-cols-[3fr_2fr] lg:gap-[1.5rem] lg:px-[1.5rem] lg:py-[1.5rem] lg:max-w-[1400px] lg:mx-auto", children: [_jsx(Div, { className: "max-w-3xl mx-auto px-[1.25rem] sm:px-[1.5rem] lg:max-w-none lg:px-[0] lg:py-[0]", padding: "y-lg", children: children }), _jsxs(Div, { className: `hidden lg:block sticky lg:top-4 lg:self-start lg:max-h-[calc(100vh-6rem)] ${__O.yAuto} border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface-raised)] ${__P.p4}`, rounded: "lg", children: [_jsxs(Row, { textWeight: "semibold", textSize: "xs", gap: "xs", className: "mb-3 uppercase tracking-wide text-[var(--appkit-color-text-muted)]", children: [_jsx(Eye, { className: "w-3.5 h-3.5" }), _jsx(Span, { children: "Live preview" })] }), previewSlot()] })] })) : (_jsx(Div, { className: "max-w-3xl mx-auto px-[1.25rem] sm:px-[1.5rem]", padding: "y-lg", children: children })) })] }), !previewMode && renderBottomBar ? (renderBottomBar()) : !previewMode && (onSaveDraft || onPublish) ? (_jsxs(Stack, { gap: "none", className: "flex-shrink-0 sticky bottom-0 z-10 border-t border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)]", children: [footerTopSlot && (_jsx(Div, { paddingX: "x-5", padding: "t-sm", children: footerTopSlot })), _jsxs(Row, { justify: "between", paddingX: "x-5", padding: "y-sm", style: { paddingBottom: "calc(var(--appkit-space-3) + var(--keyboard-inset-height, 0px))" }, children: [_jsx(Button, { variant: "ghost", size: "sm", onClick: attemptClose, disabled: isLoading, children: FORM_ACTION_META[FORM_ACTION_ID.DISCARD].label }), _jsxs(Row, { gap: "xs", children: [onSaveDraft && (_jsx(Button, { variant: "outline", size: "sm", onClick: handleSaveDraft, disabled: isLoading || savingDraft || publishing, isLoading: savingDraft, children: saveLabel })), onPublish && (_jsxs(Button, { variant: "primary", size: "sm", onClick: handlePublish, disabled: isLoading || savingDraft || publishing, isLoading: publishing, children: [publishLabel, " \u2192"] }))] })] })] })) : null] }), showUnsaved && (_jsxs(_Fragment, { children: [_jsx(Div, { surface: "overlay-lg", className: "fixed inset-0", style: { zIndex: "var(--appkit-z-confirm)" }, onClick: () => setShowUnsaved(false) }), _jsxs(Div, { className: "fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 w-[90vw] max-w-sm bg-[var(--appkit-color-surface)]", shadow: "2xl", rounded: "xl", padding: "lg", style: { zIndex: "var(--appkit-z-confirm)" }, children: [_jsxs(Row, { gap: "sm", align: "start", className: "mb-4", children: [_jsx(Span, { layout: "flex-center", className: "flex-shrink-0 w-10 h-10 bg-[var(--appkit-color-warning-surface)]", rounded: "full", children: _jsx(AlertTriangle, { className: "w-5 h-5 text-[var(--appkit-color-warning)]" }) }), _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { className: "text-[var(--appkit-color-text)]", weight: "semibold", children: "Unsaved changes" }), _jsx(Text, { className: "text-[var(--appkit-color-text-muted)]", size: "sm", children: "You have unsaved changes. Leave without saving?" })] })] }), _jsxs(Row, { gap: "xs", justify: "end", children: [_jsx(Button, { variant: "outline", size: "sm", onClick: () => setShowUnsaved(false), children: "Stay" }), _jsx(Button, { variant: "danger", size: "sm", onClick: () => { setShowUnsaved(false); onClose(); }, children: "Leave" })] })] })] }))] }));
+                                _jsxs(Div, { className: "lg:grid lg:grid-cols-[3fr_2fr] lg:gap-[1.5rem] lg:px-[1.5rem] lg:py-[1.5rem] lg:max-w-[1400px] lg:mx-auto", children: [_jsx(Div, { className: "max-w-3xl mx-auto px-[1.25rem] sm:px-[1.5rem] lg:max-w-none lg:px-[0] lg:py-[0]", padding: "y-lg", children: children }), _jsxs(Div, { className: `hidden lg:block sticky lg:top-4 lg:self-start lg:max-h-[calc(100vh-6rem)] ${__O.yAuto} border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface-raised)] ${__P.p4}`, rounded: "lg", children: [_jsxs(Row, { textWeight: "semibold", textSize: "xs", gap: "xs", className: "mb-3 uppercase tracking-wide text-[var(--appkit-color-text-muted)]", children: [_jsx(Eye, { className: "w-3.5 h-3.5" }), _jsx(Span, { children: "Live preview" })] }), previewSlot()] })] })) : (_jsx(Div, { className: "max-w-3xl mx-auto px-[1.25rem] sm:px-[1.5rem]", padding: "y-lg", children: children })) })] }), !previewMode && renderBottomBar ? (renderBottomBar()) : !previewMode && (onSaveDraft || onPublish) ? (_jsxs(Stack, { gap: "none", className: "flex-shrink-0 sticky bottom-0 z-10 border-t border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)]", children: [footerTopSlot && (_jsx(Div, { paddingX: "x-5", padding: "t-sm", children: footerTopSlot })), _jsxs(ActionRow, { align: "end", paddingX: "x-5", padding: "y-sm", style: { paddingBottom: "calc(var(--appkit-space-3) + var(--keyboard-inset-height, 0px))" }, anchor: _jsx(Button, { variant: "ghost", size: "sm", onClick: attemptClose, disabled: isLoading, children: FORM_ACTION_META[FORM_ACTION_ID.DISCARD].label }), children: [onSaveDraft && (_jsx(Button, { variant: "outline", size: "sm", onClick: handleSaveDraft, disabled: isLoading || savingDraft || publishing, isLoading: savingDraft, children: saveLabel })), onPublish && (_jsxs(Button, { variant: "primary", size: "sm", onClick: handlePublish, disabled: isLoading || savingDraft || publishing, isLoading: publishing, children: [publishLabel, " \u2192"] }))] })] })) : null] }), showUnsaved && (_jsxs(_Fragment, { children: [_jsx(Div, { surface: "overlay-lg", className: "fixed inset-0", style: { zIndex: "var(--appkit-z-confirm)" }, onClick: () => setShowUnsaved(false) }), _jsxs(Div, { className: "fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 w-[90vw] max-w-sm bg-[var(--appkit-color-surface)]", shadow: "2xl", rounded: "xl", padding: "lg", style: { zIndex: "var(--appkit-z-confirm)" }, children: [_jsxs(Row, { gap: "sm", align: "start", className: "mb-4", children: [_jsx(Span, { layout: "flex-center", className: "flex-shrink-0 w-10 h-10 bg-[var(--appkit-color-warning-surface)]", rounded: "full", children: _jsx(AlertTriangle, { className: "w-5 h-5 text-[var(--appkit-color-warning)]" }) }), _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { className: "text-[var(--appkit-color-text)]", weight: "semibold", children: "Unsaved changes" }), _jsx(Text, { className: "text-[var(--appkit-color-text-muted)]", size: "sm", children: "You have unsaved changes. Leave without saving?" })] })] }), _jsxs(Row, { gap: "xs", justify: "end", children: [_jsx(Button, { variant: "outline", size: "sm", onClick: () => setShowUnsaved(false), children: "Stay" }), _jsx(Button, { variant: "danger", size: "sm", onClick: () => { setShowUnsaved(false); onClose(); }, children: "Leave" })] })] })] }))] }));
 }

package/dist/features/shell/QuickFormDrawer.js

@@ -6,7 +6,7 @@ import { Button } from "../../ui/components/Button";
 import { IconButton } from "../../ui/components/IconButton";
 import { FormField } from "../../ui/components/FormField";
 import { Toggle } from "../../ui/components/Toggle";
-import { Div, Form, Row, Stack, Text } from "../../ui";
+import { ActionRow, Div, Form, Row, Stack, Text } from "../../ui";
 import { FormShellContext, FormErrorSummary } from "../../ui/forms";
 import { useHandMode } from "../../_internal/client/hand-mode";
 function initValues(fields, defaults = {}) {
@@ -203,5 +203,5 @@ export function QuickFormDrawer({ isOpen, onClose, title, fields, defaultValues,
                                                     : field.type === "select"
                                                         ? "select"
                                                         : "text", value: String(value ?? ""), onChange: (v) => set(field.name, field.type === "number" ? Number(v) : v), options: field.options, placeholder: field.placeholder, disabled: busy, error: errors[field.name] }), field.helperText && !errors[field.name] && (_jsx(Text, { className: "mt-1 text-[var(--appkit-color-text-muted)]", size: "xs", children: field.helperText }))] }, field.name));
-                                }), renderExtra?.(values, set)] }), _jsxs(Div, { className: "flex-shrink-0 border-t border-[var(--appkit-color-border)] bg-[var(--appkit-color-bg)]", children: [_jsx(Div, { paddingX: "x-md", padding: "t-sm", children: _jsx(FormErrorSummary, {}) }), _jsxs(Row, { padding: "md", align: "center", justify: "between", gap: "sm", children: [_jsx(Button, { variant: "outline", size: "sm", onClick: handleClose, disabled: busy, children: cancelLabel }), _jsxs(Button, { variant: "primary", size: "sm", onClick: () => void handleSubmit(), disabled: busy, isLoading: busy, children: [submitLabel, " \u2192"] })] })] })] })] }) }));
+                                }), renderExtra?.(values, set)] }), _jsxs(Div, { className: "flex-shrink-0 border-t border-[var(--appkit-color-border)] bg-[var(--appkit-color-bg)]", children: [_jsx(Div, { paddingX: "x-md", padding: "t-sm", children: _jsx(FormErrorSummary, {}) }), _jsxs(ActionRow, { padding: "md", children: [_jsx(Button, { variant: "outline", size: "sm", onClick: handleClose, disabled: busy, children: cancelLabel }), _jsxs(Button, { variant: "primary", size: "sm", onClick: () => void handleSubmit(), disabled: busy, isLoading: busy, children: [submitLabel, " \u2192"] })] })] })] })] }) }));
 }

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

@@ -110,6 +110,14 @@ export interface SectionFormProps<T extends object = Record<string, JsonValue>>
 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 UseSectionFormNavOptions {
+    /**
+     * `"{portal}:{surface}"` — persists this form's open set to the user's
+     * profile. Omit for in-memory-only, which is the default and what every
+     * pre-existing call site gets.
+     */
+    scope?: string;
+}
 export interface UseSectionFormNavResult<T extends object> {
     /** Sections in render order — required first. */
     ordered: SectionDef<T>[];
@@ -126,8 +134,18 @@ export interface UseSectionFormNavResult<T extends object> {
  * `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>;
+export declare function useSectionFormNav<T extends object = Record<string, JsonValue>>(sections: SectionDef<T>[], values?: T, opts?: UseSectionFormNavOptions): UseSectionFormNavResult<T>;
 /** DOM id for a section panel — kept in one place so nav and render agree. */
 export declare function sectionAnchorId(id: string): string;
+/**
+ * Scroll a section into view and focus the first invalid control inside it.
+ *
+ * Deliberately module-level and shared by `goToSection` and `SectionForm`'s own
+ * submit handler: the deferred frame is the load-bearing part and is easy to
+ * drop when copying. The panel must MOUNT before it can be scrolled to —
+ * expanding is a state update, so without the deferral the scroll lands on a
+ * zero-height collapsed header and the offending field stays off-screen.
+ */
+export declare function scrollToSection(id: string): void;
 export declare function SectionForm<T extends object = Record<string, JsonValue>>({ sections, values, onChange, onSubmit, submitLabel, isLoading, schema, openIds: controlledOpenIds, onOpenChange, expandMode, hideActions, destructiveAction, onValidationChange, onCancel, cancelLabel, bottomBar, }: SectionFormProps<T>): import("react").JSX.Element;
 export default SectionForm;

package/dist/features/shell/SectionForm.js

@@ -7,6 +7,7 @@ import { Badge } from "../../ui/components/Badge";
 import { Div, Row, Span, Stack } from "../../ui";
 import { FormShellContext } from "../../ui/forms/FormShell";
 import { useFormBottomActions } from "../layout/hooks/useFormBottomActions";
+import { useSectionState } from "../account/hooks/useCollapsedSections";
 import { FormSchemaContext } from "./FormShell";
 /** Sections in render order: required first, original order preserved within each group. */
 export function orderSections(sections) {
@@ -25,36 +26,62 @@ export function buildFieldToSectionIndex(ordered) {
  * `fieldToSectionIndex` into `useFormShellState(schema, nav)` and `openIds`
  * back into `<SectionForm>`.
  */
-export function useSectionFormNav(sections, values) {
+export function useSectionFormNav(sections, values, opts) {
     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 sectionIds = useMemo(() => ordered.map((s) => s.id), [ordered]);
+    const defaultOpen = useMemo(() => ordered.filter((s) => s.required).map((s) => s.id), [ordered]);
+    /*
+     * The open set is `useSectionState`, not a local `useState` — which is what
+     * makes "expand section 3, reload, find it still expanded" true. `scope: ""`
+     * (the default) is EPHEMERAL: identical in-memory behaviour to the previous
+     * `useState`, so the seven existing call sites are unchanged until each names
+     * a durable scope. Without that opt-out every unnamed form would share one
+     * `sectionState[""]` entry and fight over it.
+     */
+    const { openIds, setOpenIds, open } = useSectionState({
+        scope: opts?.scope ?? "",
+        sectionIds,
+        defaultOpen,
+        mode: "multi",
+    });
     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]);
+        open(target.id);
+        scrollToSection(target.id);
+    }, [ordered, open]);
     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}`;
 }
+/**
+ * Scroll a section into view and focus the first invalid control inside it.
+ *
+ * Deliberately module-level and shared by `goToSection` and `SectionForm`'s own
+ * submit handler: the deferred frame is the load-bearing part and is easy to
+ * drop when copying. The panel must MOUNT before it can be scrolled to —
+ * expanding is a state update, so without the deferral the scroll lands on a
+ * zero-height collapsed header and the offending field stays off-screen.
+ */
+export function scrollToSection(id) {
+    if (typeof document === "undefined")
+        return;
+    requestAnimationFrame(() => {
+        const el = document.getElementById(sectionAnchorId(id));
+        el?.scrollIntoView({ behavior: "smooth", block: "start" });
+        el?.querySelector("[aria-invalid='true']")?.focus();
+    });
+}
 export function SectionForm({ sections, values, onChange, onSubmit, submitLabel = "Save", isLoading = false, schema, openIds: controlledOpenIds, onOpenChange, expandMode = "multi", hideActions = false, destructiveAction, onValidationChange, onCancel, cancelLabel, bottomBar = true, }) {
     const inheritedSchema = useContext(FormSchemaContext);
     /*
@@ -66,6 +93,18 @@ export function SectionForm({ sections, values, onChange, onSubmit, submitLabel
     const shellCtx = useContext(FormShellContext);
     const [fieldErrors, setFieldErrors] = useState({});
     const [uncontrolledOpenIds, setUncontrolledOpenIds] = useState(() => orderSections(sections).filter((s) => s.required).map((s) => s.id));
+    /*
+     * Sections held open because they hold a validation error, kept SEPARATE
+     * from `openIds`.
+     *
+     * Under `expandMode: "single"` the open set is an accordion — opening any
+     * other section replaces it — so a section revealed by a failed submit would
+     * be collapsed again by the user's very next click, hiding the error they
+     * were sent to fix. This set is unioned into the rendered state and is pruned
+     * per-section as each one's errors clear (below), so it can never wedge a
+     * section open once it is valid.
+     */
+    const [forceOpenIds, setForceOpenIds] = useState([]);
     const ordered = useMemo(() => orderSections(sections.filter((s) => (s.when ? s.when(values) : true))), [sections, values]);
     const openIds = controlledOpenIds ?? uncontrolledOpenIds;
     const setOpenIds = useCallback((ids) => {
@@ -79,6 +118,15 @@ export function SectionForm({ sections, values, onChange, onSubmit, submitLabel
     // validator on every render and re-fire the effect below in a loop.
     const onValidationChangeRef = useRef(onValidationChange);
     onValidationChangeRef.current = onValidationChange;
+    /** Section ids holding at least one error, in render order. */
+    const erroringSectionIds = useCallback((errs) => {
+        const keys = Object.keys(errs);
+        if (keys.length === 0)
+            return [];
+        return ordered
+            .filter((s) => s.fields?.some((f) => keys.some((k) => k === f || k.startsWith(`${f}.`))))
+            .map((s) => s.id);
+    }, [ordered]);
     const runValidation = useCallback((nextValues) => {
         const activeSchema = schema ?? inheritedSchema;
         if (!activeSchema)
@@ -89,6 +137,7 @@ export function SectionForm({ sections, values, onChange, onSubmit, submitLabel
         const parsed = activeSchema.safeParse(nextValues);
         if (parsed.success) {
             setFieldErrors({});
+            setForceOpenIds([]);
             onValidationChangeRef.current?.({}, fieldToSectionIndex);
             return;
         }
@@ -99,8 +148,16 @@ export function SectionForm({ sections, values, onChange, onSubmit, submitLabel
             next[issue.path.map(String).join(".")] = issue.message;
         }
         setFieldErrors(next);
+        // Release a force-opened section as soon as ITS OWN errors clear, rather
+        // than waiting for the whole form to become valid — otherwise fixing
+        // section 1 leaves it pinned open while the user works through section 5.
+        const stillBad = new Set(erroringSectionIds(next));
+        setForceOpenIds((prev) => {
+            const kept = prev.filter((id) => stillBad.has(id));
+            return kept.length === prev.length ? prev : kept;
+        });
         onValidationChangeRef.current?.(next, fieldToSectionIndex);
-    }, [schema, inheritedSchema, fieldToSectionIndex]);
+    }, [schema, inheritedSchema, fieldToSectionIndex, erroringSectionIds]);
     useEffect(() => {
         runValidation(values);
         // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -116,8 +173,27 @@ export function SectionForm({ sections, values, onChange, onSubmit, submitLabel
      */
     const handleSubmit = useCallback(() => {
         shellCtx?.markSubmitAttempted();
+        /*
+         * Reveal the FIRST offending section — only the first. Expanding all five
+         * at once loses the user's place, and the per-section error badge already
+         * points at the rest.
+         *
+         * This is additive: `onSubmit` still fires exactly as before, so a caller
+         * that does its own parse or lets the server decide is unaffected. Blocking
+         * here would change behaviour for all thirteen call sites, and `fieldErrors`
+         * is only ever populated when a schema is present — a schema-less form
+         * finds nothing to expand and falls straight through.
+         */
+        const [firstBadId] = erroringSectionIds(fieldErrors);
+        if (firstBadId) {
+            setForceOpenIds((prev) => (prev.includes(firstBadId) ? prev : [...prev, firstBadId]));
+            if (!openIds.includes(firstBadId)) {
+                setOpenIds(expandMode === "single" ? [firstBadId] : [...openIds, firstBadId]);
+            }
+            scrollToSection(firstBadId);
+        }
         void onSubmit();
-    }, [shellCtx, onSubmit]);
+    }, [shellCtx, onSubmit, erroringSectionIds, fieldErrors, openIds, setOpenIds, expandMode]);
     useFormBottomActions({
         onSubmit: handleSubmit,
         onCancel,
@@ -128,13 +204,22 @@ export function SectionForm({ sections, values, onChange, onSubmit, submitLabel
         enabled: bottomBar && !hideActions,
     });
     const toggle = useCallback((id) => {
-        const isOpen = openIds.includes(id);
+        /*
+         * A DIRECT click on the header always wins. `forceOpenIds` exists to
+         * survive an INDIRECT collapse — the accordion closing this section because
+         * a sibling was opened — not to make the header unresponsive. Leaving the
+         * id in the set here would mean clicking a section holding an error does
+         * visibly nothing, which reads as a broken control and is worse than the
+         * hidden error it was protecting against.
+         */
+        setForceOpenIds((prev) => (prev.includes(id) ? prev.filter((x) => x !== id) : prev));
+        const isOpen = openIds.includes(id) || forceOpenIds.includes(id);
         if (expandMode === "single") {
             setOpenIds(isOpen ? [] : [id]);
             return;
         }
         setOpenIds(isOpen ? openIds.filter((x) => x !== id) : [...openIds, id]);
-    }, [openIds, expandMode, setOpenIds]);
+    }, [openIds, forceOpenIds, expandMode, setOpenIds]);
     const errorCountFor = useCallback((section) => {
         if (!section.fields?.length)
             return 0;
@@ -144,7 +229,9 @@ export function SectionForm({ sections, values, onChange, onSubmit, submitLabel
                 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 isCollapsed = isRequired
+                    ? false
+                    : !(openIds.includes(section.id) || forceOpenIds.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

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

@@ -53,6 +53,29 @@ export declare function groupFieldsBySection(fields: ResolvedField[]): Map<strin
  * make a clean 2-up, a `pair` next to a `quarter` makes neither.
  */
 export declare function packRows(fields: ResolvedField[]): ResolvedField[][];
+/**
+ * The draft, minus every field whose `when` predicate says it is not on screen.
+ *
+ * ## Why this exists, and why it is not optional
+ *
+ * A `when` predicate hides a CONTROL; it does not clear the value behind it.
+ * So a form that renders conditionally and submits `{...draft}` sends whatever
+ * the user typed before they switched the option away — the control is gone
+ * from the screen and its value is still in the payload.
+ *
+ * That is not hypothetical. Four of the twenty dead controls found in the W3c
+ * sweep were exactly this: a cap typed on a percentage coupon persisted after
+ * switching to free-shipping; a lottery slot price written under uniform
+ * pricing; an AdSense slot shipped with a manually-authored ad. Each looked
+ * right on screen and saved something else.
+ *
+ * Build the payload from THIS, not from the draft, and hidden-implies-not-sent
+ * holds by construction rather than by remembering.
+ *
+ * Fields with no `when` are always kept, so a schema with no conditionals gets
+ * its draft back unchanged and the call is free.
+ */
+export declare function visibleValues<T extends object>(schema: ZodTypeAny, values: T): Partial<T>;
 /**
  * Build the `SectionDef[]` a `<SectionForm>` renders.
  *

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

@@ -1,5 +1,5 @@
 "use client";
-import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } 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
@@ -34,14 +34,18 @@ import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
  * @tag consumers:SectionForm callsites
  * @tag sideEffects:none
  */
+import { groupRank, resolveSectionGroup } from "./form-sections";
 import { Fragment } from "react";
 import { FormGroup } from "../../ui/components/Form";
+import { PaginatedSelect } from "../../ui/components/PaginatedSelect";
+import { Stack } from "../../ui/components/Layout";
+import { Text } from "../../ui/components/Typography";
 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";
+import { ROW_COLUMNS, inferFieldUiMeta, objectShape, schemaEnumOptions, schemaIsOptional, ui, PAGINATED_SELECT_THRESHOLD, } from "./field-ui-meta";
 /**
  * Enum members as `<FieldSelect>` options.
  *
@@ -80,8 +84,21 @@ export function resolveFields(schema) {
 export function groupFieldsBySection(fields) {
     const bySection = new Map();
     for (const field of fields) {
-        if (field.meta.derived)
-            continue; // server-owned — never an input
+        // A derived field is never a bare input, but "never an input" and "never
+        // shown" are different questions and the tier answers them differently:
+        //
+        //   t2-server / t3-mirror / t4-aggregate — the client cannot know the value
+        //     at edit time (an id, a timestamp, a rollup). Omitted entirely; a blank
+        //     read-only box for a value that does not exist yet is noise.
+        //   t1-derive — the client CAN compute it, live, from a field on this same
+        //     form (slug from title). Kept, and rendered read-only by renderField,
+        //     so the user can see what will be saved and cannot desync it from its
+        //     source by typing.
+        //
+        // Absent `tier` keeps the original behaviour of dropping the field: that is
+        // what every existing `derived: true` annotation was written against.
+        if (field.meta.derived && field.meta.tier !== "t1-derive")
+            continue;
         const key = field.meta.section || "advanced";
         const bucket = bySection.get(key);
         if (bucket)
@@ -128,6 +145,42 @@ export function packRows(fields) {
     flush();
     return rows;
 }
+/**
+ * The draft, minus every field whose `when` predicate says it is not on screen.
+ *
+ * ## Why this exists, and why it is not optional
+ *
+ * A `when` predicate hides a CONTROL; it does not clear the value behind it.
+ * So a form that renders conditionally and submits `{...draft}` sends whatever
+ * the user typed before they switched the option away — the control is gone
+ * from the screen and its value is still in the payload.
+ *
+ * That is not hypothetical. Four of the twenty dead controls found in the W3c
+ * sweep were exactly this: a cap typed on a percentage coupon persisted after
+ * switching to free-shipping; a lottery slot price written under uniform
+ * pricing; an AdSense slot shipped with a manually-authored ad. Each looked
+ * right on screen and saved something else.
+ *
+ * Build the payload from THIS, not from the draft, and hidden-implies-not-sent
+ * holds by construction rather than by remembering.
+ *
+ * Fields with no `when` are always kept, so a schema with no conditionals gets
+ * its draft back unchanged and the call is free.
+ */
+export function visibleValues(schema, values) {
+    const fields = resolveFields(schema);
+    if (!fields.some((f) => f.meta.when))
+        return values;
+    const out = {};
+    for (const field of fields) {
+        if (field.meta.when && !field.meta.when(values))
+            continue;
+        const key = field.name;
+        if (key in values)
+            out[key] = values[key];
+    }
+    return out;
+}
 /**
  * Build the `SectionDef[]` a `<SectionForm>` renders.
  *
@@ -140,12 +193,27 @@ export function buildSectionsFromSchema(schema, opts = {}) {
     const bySection = groupFieldsBySection(fields);
     const declarationOrder = [...bySection.keys()];
     const explicitOrder = opts.sectionOrder ?? [];
+    /**
+     * Order is: required first, then an explicit `sectionOrder` if the caller
+     * gave one, then the section's GROUP band, then declaration order.
+     *
+     * The group band is what makes "required → additional → … → least important
+     * last" hold without every form maintaining its own `sectionOrder`. It cannot
+     * come from the section id, because ids are free-form and form-specific —
+     * see the note on `FieldUiMeta.group`. An explicit `sectionOrder` still wins,
+     * so a form with a genuine bespoke sequence keeps it.
+     */
     const rank = (id) => {
         const bucket = bySection.get(id) ?? [];
         if (bucket.some((f) => f.meta.sectionRequired))
-            return -1;
+            return -1000;
         const i = explicitOrder.indexOf(id);
-        return i === -1 ? explicitOrder.length + declarationOrder.indexOf(id) : i;
+        if (i !== -1)
+            return i;
+        const group = resolveSectionGroup(id, bucket.find((f) => f.meta.group)?.meta.group);
+        // Band first, declaration order inside the band. The multiplier just has to
+        // exceed any plausible section count in one form.
+        return explicitOrder.length + groupRank(group) * 1000 + declarationOrder.indexOf(id);
     };
     return declarationOrder
         .slice()
@@ -189,6 +257,21 @@ function renderField(field, ctx, opts) {
     const label = meta.label ?? humaniseFieldName(name);
     const value = ctx.values[name];
     const set = (v) => ctx.onChange({ [name]: v });
+    /*
+     * A t1-derive field — a slug computed from a title — is a live PREVIEW of
+     * what will be saved, not an input.
+     *
+     * Read-only rather than merely discouraged, because the two are only equal
+     * while the user behaves: an editable slug beside its source lets them be
+     * desynced, and slug immutability after creation is this codebase's
+     * established convention (categories, brands, bundles — Root Cause #39).
+     * `required` is deliberately NOT passed on: the user cannot fill it, so
+     * marking it required would put a permanent asterisk on a field they are not
+     * allowed to touch, and the error summary would name it.
+     */
+    if (meta.derived) {
+        return (_jsx(FieldInput, { name: name, label: label, hint: meta.help ?? "Generated automatically — not editable.", readOnly: true, value: typeof value === "string" ? value : value == null ? "" : String(value), onChange: () => { } }, name));
+    }
     switch (meta.kind) {
         case "toggle":
             return (_jsx(FieldCheckbox, { name: name, label: label, hint: meta.help, checked: Boolean(value), onChange: set }, name));
@@ -196,7 +279,18 @@ function renderField(field, ctx, opts) {
             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));
+            /*
+             * More than five options and a native dropdown is unscannable — the
+             * standing rule in CLAUDE.md § UI Primitive Rules. Decided here, by
+             * counting, so it holds for a caller-supplied `opts.options` list too:
+             * inference can only see a Zod enum, and the long lists (categories,
+             * brands, stores) all arrive through `opts.options`, which is exactly the
+             * case that most needs searching.
+             */
+            if (options.length > PAGINATED_SELECT_THRESHOLD) {
+                return (_jsxs(Stack, { gap: "xs", children: [_jsxs(Text, { size: "sm", weight: "medium", color: "muted", children: [label, required ? " *" : ""] }), _jsx(PaginatedSelect, { value: typeof value === "string" ? value : null, onChange: (v) => set(v ?? ""), options: options, ariaLabel: label, placeholder: `Select ${label.toLowerCase()}…` }), meta.help && _jsx(Text, { size: "xs", color: "muted", children: meta.help }), ctx.errors[name] && (_jsx(Text, { size: "xs", color: "error", role: "alert", children: ctx.errors[name] }))] }, name));
+            }
+            return (_jsx(FieldSelect, { name: name, label: label, hint: 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));
@@ -211,6 +305,10 @@ function renderField(field, ctx, opts) {
         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));
+            return (_jsx(FieldInput, { name: name, 
+                // Defaults to "text". Without the passthrough a password field
+                // renders in PLAINTEXT, and an email field gets the wrong mobile
+                // keyboard and no autofill — see FieldUiMeta.inputType.
+                type: meta.inputType ?? "text", 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

@@ -1,3 +1,4 @@
+import type { FormSectionGroup } from "./form-sections";
 import type { ZodTypeAny } from "zod";
 import type { FormValues } from "../../schemas/types";
 /** How much of a row a field claims on desktop. Everything is 1-up on mobile. */
@@ -20,6 +21,22 @@ export interface FieldUiMeta {
      * handful of schemas and quietly mis-group the rest.
      */
     section: string;
+    /**
+     * Priority band this section belongs to — drives ORDER and default-open,
+     * never identity.
+     *
+     * Deliberately separate from `section`, which stays free-form. Collapsing the
+     * 58 section ids in use onto a closed 12-value set was measured first and
+     * would have MERGED sections in 7 files: the scam report's `who` + `what` +
+     * `declare` into one blob, coupons' `limits` + `validity`, blog's `content` +
+     * `seo`. The id is the rendered unit and supplies the visible heading (144 of
+     * 228 annotations have no `sectionLabel`, so `humaniseFieldName(id)` IS their
+     * heading); the group is only "how early does this appear".
+     *
+     * Omit it and `SECTION_GROUP_DEFAULTS` resolves one from the id. A brand-new
+     * id with no default must declare its own.
+     */
+    group?: FormSectionGroup;
     /** Human label for the section. The first field to declare it wins. */
     sectionLabel?: string;
     /** Marks its section required-first, open on mount, non-collapsible. */
@@ -64,6 +81,19 @@ export interface FieldUiMeta {
     tier?: CalculatedTier;
     label?: string;
     help?: string;
+    /**
+     * The native `<input type>` for a `kind: "text"` field.
+     *
+     * `FieldKind` deliberately stays a small set of CONTROL kinds — it picks
+     * which primitive renders, and `email`/`password`/`tel`/`url` all render the
+     * same `<FieldInput>`. What they change is the browser's keyboard, autofill
+     * and masking, which is a property of the field rather than of the control.
+     *
+     * 🛑 Without this the generator emits a bare `<FieldInput>` with no `type`,
+     * so a password field renders **in plaintext**. Any schema with a password,
+     * an email or a phone number must set it.
+     */
+    inputType?: "text" | "email" | "password" | "tel" | "url" | "search";
 }
 export declare const ui: {
     /** Attach metadata to a schema instance. Returns the SAME instance. */
@@ -126,6 +156,20 @@ export declare function objectShape(schema: ZodTypeAny): Record<string, ZodTypeA
  * `.register(ui, { section: "…" })` calls, not 13 full metadata objects.
  */
 export declare function inferFieldUiMeta(name: string, schema: ZodTypeAny): Partial<FieldUiMeta>;
+/**
+ * Above this many options a select becomes a searchable `<PaginatedSelect>`.
+ * The standing UI rule (CLAUDE.md § UI Primitive Rules): more than five options
+ * and a plain dropdown is unscannable.
+ *
+ * 🛑 This is the WHOLE mechanism — there is deliberately no `paginated` flag on
+ * `FieldUiMeta`. It used to be smuggled through `help` as the literal string
+ * `"paginated"`, which broke in both directions: the assignment was
+ * `meta.help ?? "paginated"`, so a select that had real help text never became
+ * paginated; and the renderer had to blank `help` to avoid printing the
+ * sentinel, so one that DID become paginated could never show help. Counting
+ * the options at render time needs neither.
+ */
+export declare const PAGINATED_SELECT_THRESHOLD = 5;
 /**
  * The field's final metadata: inference first, explicit registration on top.
  *