@mohasinac/appkit 4.21.0 → 4.22.0

package/dist/features/shell/QuickFormDrawer.js

@@ -25,6 +25,15 @@ export function QuickFormDrawer({ isOpen, onClose, title, fields, defaultValues,
     const drawerRef = useRef(null);
     const [values, setValues] = useState(() => initValues(fields, defaultValues));
     const [errors, setErrors] = useState({});
+    /*
+     * The drawer's `errors` state is already submit-gated (only `validate()`
+     * writes it), but the summary below reads `liveErrors`, which is a pure
+     * function of the current values and therefore non-empty from first paint.
+     * Without this flag the drawer opens listing every field it is about to
+     * ask for. Reset on close, so reopening starts clean.
+     */
+    const [submitAttemptCount, setSubmitAttemptCount] = useState(0);
+    const submitAttempted = submitAttemptCount > 0;
     const [submitting, setSubmitting] = useState(false);
     // Re-initialise when defaultValues change (e.g. edit mode)
     useEffect(() => {
@@ -101,6 +110,7 @@ export function QuickFormDrawer({ isOpen, onClose, title, fields, defaultValues,
     })();
     const handleSubmit = useCallback(async (e) => {
         e?.preventDefault();
+        setSubmitAttemptCount((n) => n + 1);
         if (!validate())
             return;
         setSubmitting(true);
@@ -118,6 +128,7 @@ export function QuickFormDrawer({ isOpen, onClose, title, fields, defaultValues,
     const handleClose = useCallback(() => {
         setValues(initValues(fields, defaultValues));
         setErrors({});
+        setSubmitAttemptCount(0);
         onClose();
     }, [fields, defaultValues, onClose]);
     // Keyboard: Esc → close; Tab → trap focus
@@ -175,7 +186,10 @@ export function QuickFormDrawer({ isOpen, onClose, title, fields, defaultValues,
         isDirty: false,
         isSubmitting: submitting,
         stepErrorCounts: [],
-    }), [liveErrors, submitting]);
+        submitAttempted,
+        submitAttemptCount,
+        markSubmitAttempted: () => setSubmitAttemptCount((n) => n + 1),
+    }), [liveErrors, submitting, submitAttempted, submitAttemptCount]);
     if (!isOpen)
         return null;
     const busy = submitting || isLoading;

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

@@ -1,7 +1,7 @@
 import { type ReactNode } from "react";
 import type { JsonValue } from "@mohasinac/appkit/client";
 import type { ZodTypeAny } from "zod";
-import type { FormShellStep } from "../../ui/forms/FormShell";
+import { type FormShellStep } from "../../ui/forms/FormShell";
 /**
  * A collapsible form segment. Replaces `StepDef` — the differences are the
  * point, not incidental:
@@ -64,6 +64,20 @@ export interface SectionFormProps<T extends object = Record<string, JsonValue>>
     expandMode?: "single" | "multi";
     /** Suppress the built-in submit row (a FormShell footer owns it instead). */
     hideActions?: boolean;
+    /**
+     * Secondary action for the pinned mobile bar. Omit on a settings page with
+     * nowhere to go back to — the bar then shows Save alone.
+     */
+    onCancel?: () => void;
+    cancelLabel?: string;
+    /**
+     * Publish Save/Cancel and the error sheet into the mobile bottom-chrome
+     * tier. On by default: a SectionForm is a page-level form, which is exactly
+     * the case the pinned bar exists for. The hook suppresses itself inside a
+     * Modal or SideDrawer regardless, so this is only for the rarer case of a
+     * page that wants to own the bar itself.
+     */
+    bottomBar?: boolean;
     /**
      * Fires whenever live validation recomputes. SectionForm deliberately does
      * NOT mount its own `FormShellContext.Provider` — the owning view keeps the
@@ -95,5 +109,5 @@ export interface UseSectionFormNavResult<T extends object> {
 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 declare function SectionForm<T extends object = Record<string, JsonValue>>({ sections, values, onChange, onSubmit, submitLabel, isLoading, schema, openIds: controlledOpenIds, onOpenChange, expandMode, hideActions, onValidationChange, onCancel, cancelLabel, bottomBar, }: SectionFormProps<T>): import("react").JSX.Element;
 export default SectionForm;

package/dist/features/shell/SectionForm.js

@@ -5,6 +5,8 @@ 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 { FormShellContext } from "../../ui/forms/FormShell";
+import { useFormBottomActions } from "../layout/hooks/useFormBottomActions";
 import { FormSchemaContext } from "./FormShell";
 /** Sections in render order: required first, original order preserved within each group. */
 export function orderSections(sections) {
@@ -53,8 +55,15 @@ export function useSectionFormNav(sections, values) {
 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, }) {
+export function SectionForm({ sections, values, onChange, onSubmit, submitLabel = "Save", isLoading = false, schema, openIds: controlledOpenIds, onOpenChange, expandMode = "multi", hideActions = false, onValidationChange, onCancel, cancelLabel, bottomBar = true, }) {
     const inheritedSchema = useContext(FormSchemaContext);
+    /*
+     * SectionForm deliberately does not OWN a FormShellContext (the owning view
+     * keeps the provider — see the prop docs above), but it does own the submit
+     * button, so it is the one place that knows an attempt happened. Null when
+     * a caller renders it outside a provider, which is legitimate.
+     */
+    const shellCtx = useContext(FormShellContext);
     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]);
@@ -100,6 +109,23 @@ export function SectionForm({ sections, values, onChange, onSubmit, submitLabel
         onChange(partial);
         runValidation({ ...values, ...partial });
     }, [values, onChange, runValidation]);
+    /*
+     * The one submit path, shared by the inline button below and the pinned
+     * mobile bar — so an attempt is recorded and the error sheet revealed
+     * identically whichever the user presses.
+     */
+    const handleSubmit = useCallback(() => {
+        shellCtx?.markSubmitAttempted();
+        void onSubmit();
+    }, [shellCtx, onSubmit]);
+    useFormBottomActions({
+        onSubmit: handleSubmit,
+        onCancel,
+        submitLabel,
+        cancelLabel,
+        isLoading,
+        enabled: bottomBar && !hideActions,
+    });
     const toggle = useCallback((id) => {
         const isOpen = openIds.includes(id);
         if (expandMode === "single") {
@@ -123,6 +149,6 @@ export function SectionForm({ sections, values, onChange, onSubmit, submitLabel
                         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 }) }))] }));
+            }), !hideActions && (_jsx(Row, { justify: "end", paddingY: "y-sm", children: _jsx(Button, { variant: "primary", type: "submit", onClick: handleSubmit, isLoading: isLoading, disabled: isLoading, children: submitLabel }) }))] }));
 }
 export default SectionForm;

package/dist/features/shipments/components/AdminShipmentEditorView.js

@@ -77,7 +77,9 @@ export function AdminShipmentEditorView({ shipmentId, onSaved }) {
             onSaved?.(saved.id);
         },
     });
-    return (_jsx(Form, { schema: createShipmentSchema, spacing: "md", children: ({ setFieldError }) => (_jsxs(_Fragment, { children: [_jsxs(Grid, { cols: 2, gap: "md", children: [_jsx(FieldInput, { name: "shipmentNumber", label: "Shipment Number", required: true, value: shipmentNumber, onChange: setShipmentNumber, placeholder: "SH-2026-0001" }), _jsx(FieldInput, { name: "supplierName", label: "Supplier Name", required: true, value: supplierName, onChange: setSupplierName }), _jsx(FieldInput, { name: "originCountry", label: "Origin Country", value: originCountry, onChange: setOriginCountry }), _jsx(FieldSelect, { name: "status", label: "Status", required: true, value: status, onChange: setStatus, options: STATUS_OPTIONS }), _jsx(FieldInput, { name: "trackingNumber", label: "Tracking Number", value: trackingNumber, onChange: setTrackingNumber }), _jsx(FieldInput, { name: "carrier", label: "Carrier", value: carrier, onChange: setCarrier }), _jsx(FieldInput, { name: "etaDate", label: "ETA Date", type: "date", value: etaDate, onChange: setEtaDate }), _jsx(FieldInput, { name: "laborHoursSpent", label: "Labor Hours Spent", type: "number", min: "0", value: laborHoursSpent, onChange: setLaborHoursSpent }), _jsx(FieldInput, { name: "customsTotal", label: "Customs Total (\u20B9)", type: "number", min: "0", value: customsTotalRupees, onChange: setCustomsTotalRupees, hint: "Split across lots by declared value" }), _jsx(FieldInput, { name: "shippingTotal", label: "Shipping Total (\u20B9)", type: "number", min: "0", value: shippingTotalRupees, onChange: setShippingTotalRupees, hint: "Split across lots by weight" })] }), _jsx(FieldTextarea, { name: "notes", label: "Notes", value: notes, onChange: setNotes, rows: 3 }), _jsx(FormErrorSummary, {}), _jsx(Button, { type: "button", isLoading: saveMutation.isPending, onClick: () => {
+    return (_jsx(Form, { schema: createShipmentSchema, spacing: "md", children: ({ setFieldError, markSubmitAttempted }) => (_jsxs(_Fragment, { children: [_jsxs(Grid, { cols: 2, gap: "md", children: [_jsx(FieldInput, { name: "shipmentNumber", label: "Shipment Number", required: true, value: shipmentNumber, onChange: setShipmentNumber, placeholder: "SH-2026-0001" }), _jsx(FieldInput, { name: "supplierName", label: "Supplier Name", required: true, value: supplierName, onChange: setSupplierName }), _jsx(FieldInput, { name: "originCountry", label: "Origin Country", value: originCountry, onChange: setOriginCountry }), _jsx(FieldSelect, { name: "status", label: "Status", required: true, value: status, onChange: setStatus, options: STATUS_OPTIONS }), _jsx(FieldInput, { name: "trackingNumber", label: "Tracking Number", value: trackingNumber, onChange: setTrackingNumber }), _jsx(FieldInput, { name: "carrier", label: "Carrier", value: carrier, onChange: setCarrier }), _jsx(FieldInput, { name: "etaDate", label: "ETA Date", type: "date", value: etaDate, onChange: setEtaDate }), _jsx(FieldInput, { name: "laborHoursSpent", label: "Labor Hours Spent", type: "number", min: "0", value: laborHoursSpent, onChange: setLaborHoursSpent }), _jsx(FieldInput, { name: "customsTotal", label: "Customs Total (\u20B9)", type: "number", min: "0", value: customsTotalRupees, onChange: setCustomsTotalRupees, hint: "Split across lots by declared value" }), _jsx(FieldInput, { name: "shippingTotal", label: "Shipping Total (\u20B9)", type: "number", min: "0", value: shippingTotalRupees, onChange: setShippingTotalRupees, hint: "Split across lots by weight" })] }), _jsx(FieldTextarea, { name: "notes", label: "Notes", value: notes, onChange: setNotes, rows: 3 }), _jsx(FormErrorSummary, {}), _jsx(Button, { type: "button", isLoading: saveMutation.isPending, onClick: () => {
+                        // type="button" — no native submit, so unhide the summary here.
+                        markSubmitAttempted();
                         const parsed = createShipmentSchema.safeParse({
                             shipmentNumber,
                             supplierName,

package/dist/features/tester/seed-data/tester-checklist-seed-data.js

@@ -1156,6 +1156,42 @@ const rawTesterChecklistItems = [
                     description: "The fix had to cover the update path as well as create — a create-only fix would mean the listing saved correctly and then lost its per-type block the first time anyone edited anything else (Root Cause #39).",
                     href: "/store/classified",
                 },
+                {
+                    key: "form-errors-wait-for-first-submit",
+                    label: "Opening the address form shows NO errors until you press Save",
+                    description: "Live bug fixed 2026-08-26: every schema-driven form greeted the user with a list of its own requirements as errors before they had typed anything. Two causes compounded — <FormErrorSummary> was deliberately un-gated, and ~20 views run validate(draft) in a mount effect, so an untouched empty draft failed every .min(1) on first paint. Open /user/addresses/new: the summary block must be absent. Press Save with the form empty: NOW it lists the missing fields.",
+                    href: "/user/addresses/new",
+                },
+                {
+                    key: "form-errors-stay-live-after-first-submit",
+                    label: "After a failed Save, the error list SHRINKS as you fill fields in",
+                    description: "The fix gates the DISPLAY, not the computation — the live validation underneath is what makes the list useful. Press Save on an empty address form, then fill Full name. The summary must drop that entry immediately, without a second Save. If the list is frozen, the on-mount validate() was removed instead of gated, which is the wrong fix.",
+                    href: "/user/addresses/new",
+                },
+                {
+                    key: "form-mobile-bar-pinned",
+                    label: "On a phone, Save and Cancel are pinned above the tab bar on the address form",
+                    description: "Added 2026-08-26 (W21). Narrow the window below 1024px, or use a real phone. Save/Cancel should sit in the same fixed bar the cart uses for 'Proceed to checkout' — above the bottom tab bar, not scrolled off the end of a long form. On desktop the bar is hidden and the inline Save/Cancel row at the bottom of the form is the control.",
+                    href: "/user/addresses/new",
+                },
+                {
+                    key: "form-mobile-error-sheet",
+                    label: "On a phone, a failed Save opens a 'Fix N issues' sheet you can tap through",
+                    description: "Below 1024px, press Save on an empty address form. A 'Fix 6 issues' row must appear above the buttons with the list already open. Collapse it, press Save again — it must RE-open (the count is a counter, not a boolean, precisely so a second attempt is a new event). Tapping an entry on a sectioned form jumps to that field.",
+                    href: "/user/addresses/new",
+                },
+                {
+                    key: "form-bar-restores-listing-bulk-bar",
+                    label: "Closing a form drawer over a listing brings the listing's bulk bar back",
+                    description: "Regression test for the singleton clobber: there is ONE bottom bar per route and DataListingView claims it on ~70 admin screens. Select a few rows on an admin listing so the bulk bar appears, open a row's editor drawer, then close it — the bulk bar must still be there with the selection intact. Before the claim stack landed, the drawer overwrote it and blanked it on close.",
+                    href: "/admin/products",
+                },
+                {
+                    key: "form-bar-absent-inside-a-modal",
+                    label: "A form inside a modal or drawer does NOT get a second bar at the bottom of the screen",
+                    description: "An overlay owns its own footer, and a viewport-fixed bar would render behind the backdrop, below the dialog it belongs to. Open any drawer-based editor on a phone-width window and confirm the only Save/Cancel controls are the ones inside the drawer.",
+                    href: "/admin/coupons",
+                },
                 {
                     key: "address-routes-normalised",
                     label: "Adding and editing an address works, and the OLD urls still resolve",

package/dist/index.d.ts

@@ -2120,6 +2120,9 @@ export { SidebarLayout } from "./features/layout/index";
 export { TitleBar } from "./features/layout/index";
 export { TitleBarLayout } from "./features/layout/index";
 export { useBottomActions } from "./features/layout/index";
+export { useFormBottomActions } from "./features/layout/index";
+export { FormErrorList } from "./ui/forms";
+export { OverlayContext, useIsInsideOverlay } from "./ui/components/overlay-context";
 export { useBottomActionsContext } from "./features/layout/index";
 export { useDashboardNav } from "./features/layout/index";
 export type { AppLayoutShellProps } from "./features/layout/index";

package/dist/index.js

@@ -3934,6 +3934,10 @@ export { TitleBarLayout } from "./features/layout/index";
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
 // useBottomActions - React hook for use bottom actions.
 export { useBottomActions } from "./features/layout/index";
+// useFormBottomActions - pins a form's Save/Cancel row + error sheet to the mobile bottom-chrome tier.
+export { useFormBottomActions } from "./features/layout/index";
+export { FormErrorList } from "./ui/forms";
+export { OverlayContext, useIsInsideOverlay } from "./ui/components/overlay-context";
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
 // useBottomActionsContext - React hook for use bottom actions context.
 export { useBottomActionsContext } from "./features/layout/index";

package/dist/ui/components/Form.d.ts

@@ -28,13 +28,34 @@ export interface FormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement
      * provider would shadow the parent's for everything rendered as `children`.
      */
     shellCtx?: FormShellContextValue;
+    /**
+     * Publish Save/Cancel and the mobile error sheet into the bottom-chrome
+     * tier — the same bar the cart uses.
+     *
+     * Opt-IN, unlike `<SectionForm>` where it is on by default. `<Form>` is the
+     * generic wrapper and is used inside `<Modal>` and `<SideDrawer>` footers,
+     * inside listing toolbars, and several times over on one page
+     * (`AdminSiteSettingsView` mounts twenty). Publishing route-level chrome
+     * from all of those by default would be wrong far more often than right.
+     * The hook additionally suppresses itself inside an overlay, so passing
+     * this in a modal is a no-op rather than a bug.
+     */
+    bottomBar?: FormBottomBarConfig;
     /** Cross-axis alignment of flex/grid children. Replaces raw `items-*` className. */
     align?: "start" | "center" | "end" | "stretch";
     /** Gap between children — use instead of raw `gap-*` className. */
     gap?: GapToken;
 }
 export type GapToken = "none" | "xs" | "sm" | "md" | "lg" | "xl";
-export declare function Form({ children, spacing, schema, shellCtx: shellCtxProp, align, gap, surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, className, ...props }: FormProps): React.JSX.Element;
+export interface FormBottomBarConfig {
+    onSubmit: () => void | Promise<void>;
+    onCancel?: () => void;
+    submitLabel?: string;
+    cancelLabel?: string;
+    isLoading?: boolean;
+    disabled?: boolean;
+}
+export declare function Form({ children, spacing, schema, shellCtx: shellCtxProp, bottomBar, align, gap, surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, className, ...props }: FormProps): React.JSX.Element;
 export interface FormGroupProps {
     children: React.ReactNode;
     columns?: 1 | 2 | 3 | 4;

package/dist/ui/components/Form.js

@@ -1,8 +1,10 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
+import React from "react";
 import { Row } from "./Layout";
 import { buildSurfaceClasses } from "./surface-tokens";
 import { FormShellContext, useFormShellState, } from "../forms/FormShell";
+import { useFormBottomActions } from "../../features/layout/hooks/useFormBottomActions";
 const FORM_SPACING_MAP = {
     none: "",
     xs: "space-y-1",
@@ -43,9 +45,35 @@ const FORM_ALIGN_MAP = {
     end: "items-end",
     stretch: "items-stretch",
 };
-export function Form({ children, spacing, schema, shellCtx: shellCtxProp, align, gap, surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, className = "", ...props }) {
+export function Form({ children, spacing, schema, shellCtx: shellCtxProp, bottomBar, align, gap, surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, className = "", ...props }) {
     const helpers = useFormShellState(schema);
     const effectiveCtx = shellCtxProp ?? helpers.shellCtx;
+    /*
+     * Marking the attempt on the NATIVE submit event covers both shapes this
+     * component is used in: the caller that calls `validate()` (which marks
+     * anyway) and the caller that hand-rolls its checks in the submit button's
+     * `onClick`. React fires `onClick` before `onSubmit`, so by the time the
+     * re-render happens the errors are already in the context.
+     *
+     * `effectiveCtx` may come from a parent's `useFormShellState`, so mark on
+     * whichever context is actually mounted — not on `helpers`, which is a
+     * second, ignored state instance in that case.
+     */
+    const { onSubmit: onSubmitProp } = props;
+    const handleSubmit = React.useCallback((e) => {
+        effectiveCtx.markSubmitAttempted();
+        onSubmitProp?.(e);
+    }, [effectiveCtx, onSubmitProp]);
+    useFormBottomActions({
+        onSubmit: bottomBar?.onSubmit ?? (() => { }),
+        onCancel: bottomBar?.onCancel,
+        submitLabel: bottomBar?.submitLabel,
+        cancelLabel: bottomBar?.cancelLabel,
+        isLoading: bottomBar?.isLoading,
+        disabled: bottomBar?.disabled,
+        enabled: bottomBar != null,
+        ctx: effectiveCtx,
+    });
     const content = typeof children === "function"
         ? children({ ...helpers, shellCtx: effectiveCtx })
         : children;
@@ -56,7 +84,7 @@ export function Form({ children, spacing, schema, shellCtx: shellCtxProp, align,
                 gap ? GAP_MAP[gap] : "",
                 buildSurfaceClasses({ surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow }),
                 className,
-            ].filter(Boolean).join(" "), ...props, children: content }) }));
+            ].filter(Boolean).join(" "), ...props, onSubmit: handleSubmit, children: content }) }));
 }
 export function FormGroup({ children, columns = 1, gap = "md", className = "", }) {
     const gridClasses = {

package/dist/ui/components/Modal.js

@@ -7,6 +7,7 @@ import { Heading } from "./Typography";
 import { Button } from "./Button";
 import { SPRING_GENTLE } from "../../tokens/motion";
 import { useHandMode } from "../../_internal/client/hand-mode";
+import { OverlayContext } from "./overlay-context";
 const SIZE_CLASSES = {
     sm: "appkit-modal__panel--sm",
     md: "appkit-modal__panel--md",
@@ -69,9 +70,9 @@ export function Modal({ isOpen, open, onClose, title, children, size = "md", sho
     if (typeof document === "undefined") {
         return null;
     }
-    return createPortal(_jsx(AnimatePresence, { children: visible && (_jsxs(motion.div, { className: "appkit-modal", role: "dialog", "aria-modal": "true", "aria-labelledby": title ? titleId : undefined, onKeyDown: handleKeyDown, initial: reduced ? false : { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 }, transition: { duration: 0.15 }, "data-section": "modal-div-561", children: [_jsx("div", { className: "appkit-modal__backdrop", "aria-hidden": "true", onClick: onClose }), _jsxs(motion.div, { ref: panelRef, tabIndex: -1, className: ["appkit-modal__panel", SIZE_CLASSES[size], className]
-                        .filter(Boolean)
-                        .join(" "), initial: reduced ? false : { opacity: 0, scale: 0.95, y: 8 }, animate: { opacity: 1, scale: 1, y: 0 }, exit: { opacity: 0, scale: 0.95, y: 8 }, transition: SPRING_GENTLE, "data-section": "modal-div-562", children: [(title || showCloseButton) && (_jsxs("div", { className: hand === "left" ? "appkit-modal__header flex-row-reverse" : "appkit-modal__header", "data-section": "modal-div-563", children: [title ? (_jsx(Heading, { level: 2, id: titleId, className: "appkit-modal__title", children: title })) : (_jsx("span", {})), showCloseButton ? (_jsx(Button, { variant: "ghost", size: "sm", type: "button", onClick: onClose, className: "appkit-modal__close", "aria-label": "Close", children: _jsx("span", { className: "appkit-modal__close-icon", "aria-hidden": "true", children: "\u00D7" }) })) : null] })), _jsx("div", { className: "appkit-modal__body", "data-section": "modal-div-564", children: children }), actions ? _jsx(ModalFooter, { children: actions }) : null] })] })) }), document.body);
+    return createPortal(_jsx(OverlayContext.Provider, { value: true, children: _jsx(AnimatePresence, { children: visible && (_jsxs(motion.div, { className: "appkit-modal", role: "dialog", "aria-modal": "true", "aria-labelledby": title ? titleId : undefined, onKeyDown: handleKeyDown, initial: reduced ? false : { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 }, transition: { duration: 0.15 }, "data-section": "modal-div-561", children: [_jsx("div", { className: "appkit-modal__backdrop", "aria-hidden": "true", onClick: onClose }), _jsxs(motion.div, { ref: panelRef, tabIndex: -1, className: ["appkit-modal__panel", SIZE_CLASSES[size], className]
+                            .filter(Boolean)
+                            .join(" "), initial: reduced ? false : { opacity: 0, scale: 0.95, y: 8 }, animate: { opacity: 1, scale: 1, y: 0 }, exit: { opacity: 0, scale: 0.95, y: 8 }, transition: SPRING_GENTLE, "data-section": "modal-div-562", children: [(title || showCloseButton) && (_jsxs("div", { className: hand === "left" ? "appkit-modal__header flex-row-reverse" : "appkit-modal__header", "data-section": "modal-div-563", children: [title ? (_jsx(Heading, { level: 2, id: titleId, className: "appkit-modal__title", children: title })) : (_jsx("span", {})), showCloseButton ? (_jsx(Button, { variant: "ghost", size: "sm", type: "button", onClick: onClose, className: "appkit-modal__close", "aria-label": "Close", children: _jsx("span", { className: "appkit-modal__close-icon", "aria-hidden": "true", children: "\u00D7" }) })) : null] })), _jsx("div", { className: "appkit-modal__body", "data-section": "modal-div-564", children: children }), actions ? _jsx(ModalFooter, { children: actions }) : null] })] })) }) }), document.body);
 }
 export function ModalFooter({ children, className = "", }) {
     return (_jsx("div", { className: [

package/dist/ui/components/SideDrawer.js

@@ -10,6 +10,7 @@ import { useSwipe } from "../../react";
 import { Text } from "./Typography";
 import { SPRING_SNAPPY } from "../../tokens/motion";
 import { useHandMode } from "../../_internal/client/hand-mode";
+import { OverlayContext } from "./overlay-context";
 const UI_SIDE_DRAWER = {
     backdrop: "appkit-side-drawer__backdrop",
     root: "appkit-side-drawer",
@@ -152,8 +153,8 @@ export function SideDrawer({ isOpen, onClose, title, children, footer, mode = "v
     const reduced = useReducedMotion();
     const positionClass = resolvedSide === "left" ? UI_SIDE_DRAWER.left : UI_SIDE_DRAWER.right;
     const slideX = resolvedSide === "left" ? "-100%" : "100%";
-    return (_jsx(AnimatePresence, { children: isOpen && (_jsxs(_Fragment, { children: [_jsx(motion.div, { className: UI_SIDE_DRAWER.backdrop, onClick: attemptClose, "aria-hidden": "true", initial: reduced ? false : { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 }, transition: { duration: 0.2 } }), _jsxs(motion.div, { ref: drawerRef, className: [UI_SIDE_DRAWER.root, positionClass].join(" "), role: "dialog", "aria-modal": "true", "aria-labelledby": "drawer-title", initial: reduced ? false : { x: slideX }, animate: { x: 0 }, exit: { x: slideX }, transition: SPRING_SNAPPY, "data-section": "sidedrawer-div-598", children: [_jsxs(Row, { justify: "between", gap: "none", className: [
-                                UI_SIDE_DRAWER.header,
-                                UI_SIDE_DRAWER.headerMode[mode],
-                            ].join(" "), children: [_jsxs(Row, { gap: "3", className: "min-w-0", reverse: hand === "left", children: [_jsx(Button, { variant: "ghost", onClick: attemptClose, className: UI_SIDE_DRAWER.closeBtn, "aria-label": tActions("close"), children: _jsx("svg", { className: UI_SIDE_DRAWER.closeIcon, fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M6 18L18 6M6 6l12 12" }) }) }), _jsx(Heading, { level: 3, id: "drawer-title", className: "truncate", children: title })] }), mode === "delete" && (_jsx(Span, { className: UI_SIDE_DRAWER.deleteBadge, children: tActions("delete") }))] }), _jsx("div", { className: UI_SIDE_DRAWER.content, "data-section": "sidedrawer-div-599", children: children }), footer && _jsx("div", { className: UI_SIDE_DRAWER.footer, "data-section": "sidedrawer-div-600", children: footer })] }), showUnsavedWarning && (_jsxs(_Fragment, { children: [_jsx("div", { className: UI_SIDE_DRAWER.warnBackdrop, onClick: cancelClose }), _jsxs("div", { className: UI_SIDE_DRAWER.warnDialog, "data-section": "sidedrawer-div-601", children: [_jsxs("div", { className: UI_SIDE_DRAWER.warnHeader, "data-section": "sidedrawer-div-602", children: [_jsx("div", { className: UI_SIDE_DRAWER.warnIcon, "data-section": "sidedrawer-div-603", children: _jsx("svg", { fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" }) }) }), _jsxs("div", { "data-section": "sidedrawer-div-604", children: [_jsx(Heading, { level: 4, className: "mb-1", children: tConfirm("unsavedChangesTitle") }), _jsx(Text, { className: UI_SIDE_DRAWER.warnText, children: tConfirm("unsavedChangesDescription") })] })] }), _jsxs("div", { className: UI_SIDE_DRAWER.warnActions, "data-section": "sidedrawer-div-605", children: [_jsx(Button, { variant: "outline", onClick: cancelClose, size: "sm", children: tActions("keepEditing") }), _jsx(Button, { variant: "danger", onClick: confirmClose, size: "sm", children: tActions("discardChanges") })] })] })] }))] })) }));
+    return (_jsx(OverlayContext.Provider, { value: true, children: _jsx(AnimatePresence, { children: isOpen && (_jsxs(_Fragment, { children: [_jsx(motion.div, { className: UI_SIDE_DRAWER.backdrop, onClick: attemptClose, "aria-hidden": "true", initial: reduced ? false : { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 }, transition: { duration: 0.2 } }), _jsxs(motion.div, { ref: drawerRef, className: [UI_SIDE_DRAWER.root, positionClass].join(" "), role: "dialog", "aria-modal": "true", "aria-labelledby": "drawer-title", initial: reduced ? false : { x: slideX }, animate: { x: 0 }, exit: { x: slideX }, transition: SPRING_SNAPPY, "data-section": "sidedrawer-div-598", children: [_jsxs(Row, { justify: "between", gap: "none", className: [
+                                    UI_SIDE_DRAWER.header,
+                                    UI_SIDE_DRAWER.headerMode[mode],
+                                ].join(" "), children: [_jsxs(Row, { gap: "3", className: "min-w-0", reverse: hand === "left", children: [_jsx(Button, { variant: "ghost", onClick: attemptClose, className: UI_SIDE_DRAWER.closeBtn, "aria-label": tActions("close"), children: _jsx("svg", { className: UI_SIDE_DRAWER.closeIcon, fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M6 18L18 6M6 6l12 12" }) }) }), _jsx(Heading, { level: 3, id: "drawer-title", className: "truncate", children: title })] }), mode === "delete" && (_jsx(Span, { className: UI_SIDE_DRAWER.deleteBadge, children: tActions("delete") }))] }), _jsx("div", { className: UI_SIDE_DRAWER.content, "data-section": "sidedrawer-div-599", children: children }), footer && _jsx("div", { className: UI_SIDE_DRAWER.footer, "data-section": "sidedrawer-div-600", children: footer })] }), showUnsavedWarning && (_jsxs(_Fragment, { children: [_jsx("div", { className: UI_SIDE_DRAWER.warnBackdrop, onClick: cancelClose }), _jsxs("div", { className: UI_SIDE_DRAWER.warnDialog, "data-section": "sidedrawer-div-601", children: [_jsxs("div", { className: UI_SIDE_DRAWER.warnHeader, "data-section": "sidedrawer-div-602", children: [_jsx("div", { className: UI_SIDE_DRAWER.warnIcon, "data-section": "sidedrawer-div-603", children: _jsx("svg", { fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" }) }) }), _jsxs("div", { "data-section": "sidedrawer-div-604", children: [_jsx(Heading, { level: 4, className: "mb-1", children: tConfirm("unsavedChangesTitle") }), _jsx(Text, { className: UI_SIDE_DRAWER.warnText, children: tConfirm("unsavedChangesDescription") })] })] }), _jsxs("div", { className: UI_SIDE_DRAWER.warnActions, "data-section": "sidedrawer-div-605", children: [_jsx(Button, { variant: "outline", onClick: cancelClose, size: "sm", children: tActions("keepEditing") }), _jsx(Button, { variant: "danger", onClick: confirmClose, size: "sm", children: tActions("discardChanges") })] })] })] }))] })) }) }));
 }

package/dist/ui/components/overlay-context.d.ts

@@ -0,0 +1,21 @@
+/**
+ * "Am I rendering inside a Modal or a SideDrawer?"
+ *
+ * WHY: route-level chrome must not attach itself to content that is floating
+ * above the route. The concrete case is `useFormBottomActions` — a form on a
+ * page publishes its Save/Cancel row and its error sheet into the fixed
+ * `BottomChrome` tier, which is correct there and wrong inside an overlay:
+ * the overlay already owns a footer, and a bar pinned to the viewport bottom
+ * would sit *behind* the backdrop, below the very dialog it belongs to.
+ *
+ * Detection has to come from the overlay itself. There is no way to infer it
+ * from the DOM at render time (both portal elsewhere), and asking every form
+ * to declare where it is being rendered is the kind of convention that is one
+ * forgetful call site away from a bar appearing under a backdrop.
+ *
+ * Mounted by `Modal` and `SideDrawer`. Default `false`, so a component outside
+ * any overlay — the overwhelmingly common case — needs no provider at all.
+ */
+export declare const OverlayContext: import("react").Context<boolean>;
+/** True when the calling component is rendered inside a Modal or SideDrawer. */
+export declare function useIsInsideOverlay(): boolean;

package/dist/ui/components/overlay-context.js

@@ -0,0 +1,25 @@
+"use client";
+import { createContext, useContext } from "react";
+/**
+ * "Am I rendering inside a Modal or a SideDrawer?"
+ *
+ * WHY: route-level chrome must not attach itself to content that is floating
+ * above the route. The concrete case is `useFormBottomActions` — a form on a
+ * page publishes its Save/Cancel row and its error sheet into the fixed
+ * `BottomChrome` tier, which is correct there and wrong inside an overlay:
+ * the overlay already owns a footer, and a bar pinned to the viewport bottom
+ * would sit *behind* the backdrop, below the very dialog it belongs to.
+ *
+ * Detection has to come from the overlay itself. There is no way to infer it
+ * from the DOM at render time (both portal elsewhere), and asking every form
+ * to declare where it is being rendered is the kind of convention that is one
+ * forgetful call site away from a bar appearing under a backdrop.
+ *
+ * Mounted by `Modal` and `SideDrawer`. Default `false`, so a component outside
+ * any overlay — the overwhelmingly common case — needs no provider at all.
+ */
+export const OverlayContext = createContext(false);
+/** True when the calling component is rendered inside a Modal or SideDrawer. */
+export function useIsInsideOverlay() {
+    return useContext(OverlayContext);
+}

package/dist/ui/forms/FormErrorList.d.ts

@@ -0,0 +1,29 @@
+import { type FormShellContextValue } from "./FormShell";
+export interface FormErrorListProps {
+    /**
+     * Read errors from this context value instead of the ambient one. The
+     * mobile bottom sheet needs it: `useFormBottomActions` builds the panel as
+     * a detached ReactNode that is rendered by `BottomActions`, high up in the
+     * layout tree and therefore OUTSIDE the form's own provider.
+     */
+    ctx?: FormShellContextValue;
+    className?: string;
+}
+/**
+ * The `<ul>` of current validation errors, with a jump link per entry when
+ * the form declares sections.
+ *
+ * WHY it is its own file: two surfaces render this exact list — the inline
+ * `<FormErrorSummary>` beside the submit button on desktop, and the mobile
+ * "Fix N issues" sheet in the bottom-chrome tier. Writing it twice would mean
+ * a jump-link fix, an empty-state fix or a wording fix landing in one and not
+ * the other, which is the bug-fix multiplier the Duplication Framework calls
+ * out. There are exactly two consumers and they are the same list, so this is
+ * a consolidation, not speculative abstraction.
+ *
+ * Renders nothing when there are no errors. It does NOT gate on
+ * `submitAttempted` — that is the *summary's* decision, not the list's, and
+ * the sheet needs to keep rendering while open.
+ */
+export declare function FormErrorList({ ctx: ctxProp, className }: FormErrorListProps): import("react").JSX.Element | null;
+export default FormErrorList;

package/dist/ui/forms/FormErrorList.js

@@ -0,0 +1,36 @@
+"use client";
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useContext } from "react";
+import { FormShellContext } from "./FormShell";
+import { Span } from "../components/Typography";
+/**
+ * The `<ul>` of current validation errors, with a jump link per entry when
+ * the form declares sections.
+ *
+ * WHY it is its own file: two surfaces render this exact list — the inline
+ * `<FormErrorSummary>` beside the submit button on desktop, and the mobile
+ * "Fix N issues" sheet in the bottom-chrome tier. Writing it twice would mean
+ * a jump-link fix, an empty-state fix or a wording fix landing in one and not
+ * the other, which is the bug-fix multiplier the Duplication Framework calls
+ * out. There are exactly two consumers and they are the same list, so this is
+ * a consolidation, not speculative abstraction.
+ *
+ * Renders nothing when there are no errors. It does NOT gate on
+ * `submitAttempted` — that is the *summary's* decision, not the list's, and
+ * the sheet needs to keep rendering while open.
+ */
+export function FormErrorList({ ctx: ctxProp, className }) {
+    const ambient = useContext(FormShellContext);
+    const ctx = ctxProp ?? ambient;
+    if (!ctx)
+        return null;
+    const entries = Object.entries(ctx.errors);
+    if (entries.length === 0)
+        return null;
+    return (_jsx("ul", { className: ["appkit-formshell__error-summary__list", className].filter(Boolean).join(" "), children: entries.map(([key, message]) => {
+            const stepIndex = ctx.fieldToStepIndex?.[key];
+            const stepLabel = stepIndex != null ? ctx.steps[stepIndex]?.label : undefined;
+            return (_jsx("li", { children: stepLabel ? (_jsxs("button", { type: "button", className: "appkit-formshell__error-summary__step-link", onClick: () => ctx.goToStep(stepIndex), children: [_jsxs(Span, { weight: "semibold", children: [stepLabel, ":"] }), " ", message] })) : (_jsx(Span, { children: message })) }, key));
+        }) }));
+}
+export default FormErrorList;

package/dist/ui/forms/FormErrorSummary.d.ts

@@ -13,6 +13,14 @@ export interface FormErrorSummaryProps {
  * error immediately as fields change — not gated by `touched`, unlike the
  * inline per-field errors.
  *
+ * 🛑 It IS gated on `ctx.submitAttempted`, and must stay that way. The
+ * summary speaks about fields the user has not reached yet, so before a
+ * submit it reads as a list of accusations rather than of mistakes — and
+ * ~20 views run `validate(draft)` in a mount effect, so an untouched empty
+ * draft fails every `.min(1)` on first paint. Gate the DISPLAY only: the
+ * live validation underneath is what keeps this list shrinking as the user
+ * fixes things after a failed submit, which is the whole point of it.
+ *
  * For multi-step forms whose step engine populates
  * `FormShellContextValue.fieldToStepIndex`, each entry names its owning step
  * and is clickable to jump there. Falls back to a flat list when no step

package/dist/ui/forms/FormErrorSummary.js

@@ -2,7 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useContext } from "react";
 import { FormShellContext } from "./FormShell";
-import { Span } from "../components/Typography";
+import { FormErrorList } from "./FormErrorList";
 /**
  * Shared, live validation-error summary — supplements (does not replace) the
  * per-field inline errors `FieldInput`/`FieldSelect`/`FormField` already
@@ -11,6 +11,14 @@ import { Span } from "../components/Typography";
  * error immediately as fields change — not gated by `touched`, unlike the
  * inline per-field errors.
  *
+ * 🛑 It IS gated on `ctx.submitAttempted`, and must stay that way. The
+ * summary speaks about fields the user has not reached yet, so before a
+ * submit it reads as a list of accusations rather than of mistakes — and
+ * ~20 views run `validate(draft)` in a mount effect, so an untouched empty
+ * draft fails every `.min(1)` on first paint. Gate the DISPLAY only: the
+ * live validation underneath is what keeps this list shrinking as the user
+ * fixes things after a failed submit, which is the whole point of it.
+ *
  * For multi-step forms whose step engine populates
  * `FormShellContextValue.fieldToStepIndex`, each entry names its owning step
  * and is clickable to jump there. Falls back to a flat list when no step
@@ -23,15 +31,14 @@ export function FormErrorSummary({ hideWhenEmpty = true, className, title = "Ple
     const ctx = useContext(FormShellContext);
     if (!ctx)
         return null;
+    // Nothing to say until they've tried. See the header.
+    if (!ctx.submitAttempted)
+        return null;
     const entries = Object.entries(ctx.errors);
+    // `hideWhenEmpty` is the only reason an empty list would render at all —
+    // as an empty titled block confirming there is nothing to fix.
     if (entries.length === 0 && hideWhenEmpty)
         return null;
-    if (entries.length === 0)
-        return null;
-    return (_jsxs("div", { role: "alert", "aria-live": "polite", className: ["appkit-formshell__error-summary", className].filter(Boolean).join(" "), children: [_jsx("div", { className: "appkit-formshell__error-summary__title", children: title }), _jsx("ul", { className: "appkit-formshell__error-summary__list", children: entries.map(([key, message]) => {
-                    const stepIndex = ctx.fieldToStepIndex?.[key];
-                    const stepLabel = stepIndex != null ? ctx.steps[stepIndex]?.label : undefined;
-                    return (_jsx("li", { children: stepLabel ? (_jsxs("button", { type: "button", className: "appkit-formshell__error-summary__step-link", onClick: () => ctx.goToStep(stepIndex), children: [_jsxs(Span, { weight: "semibold", children: [stepLabel, ":"] }), " ", message] })) : (_jsx(Span, { children: message })) }, key));
-                }) })] }));
+    return (_jsxs("div", { role: "alert", "aria-live": "polite", className: ["appkit-formshell__error-summary", className].filter(Boolean).join(" "), children: [_jsx("div", { className: "appkit-formshell__error-summary__title", children: title }), _jsx(FormErrorList, {})] }));
 }
 export default FormErrorSummary;

package/dist/ui/forms/FormShell.d.ts

@@ -56,6 +56,19 @@ export interface FormShellContextValue {
      * treats undefined as "no step context" and renders a flat list.
      */
     fieldToStepIndex?: Record<string, number>;
+    submitAttempted: boolean;
+    /**
+     * How many times. `submitAttempted` is `submitAttemptCount > 0` — DERIVED
+     * at the one place each producer builds this object, never stored twice.
+     *
+     * The count exists because a boolean cannot express "this is a NEW
+     * attempt". The mobile error sheet force-opens on a bumped counter, so
+     * pressing Save a second time re-opens a sheet the user had collapsed,
+     * while an ordinary re-render does not.
+     */
+    submitAttemptCount: number;
+    /** Call from a submit handler, before validating. */
+    markSubmitAttempted: () => void;
 }
 export declare const FormShellContext: React.Context<FormShellContextValue | null>;
 export declare function useFormShell(): FormShellContextValue;
@@ -70,6 +83,16 @@ export interface UseFormShellStateResult {
      * parsed value on success or null on failure.
      */
     validate: <T = unknown>(values: unknown) => T | null;
+    /** True once the user has actually tried to submit. Gates <FormErrorSummary>. */
+    submitAttempted: boolean;
+    /** See FormShellContextValue.submitAttemptCount. */
+    submitAttemptCount: number;
+    /**
+     * Record a submit attempt. `<Form>` / `<SectionForm>` / `<QuickFormDrawer>`
+     * call this for you; call it directly only when your submit control is a
+     * `type="button"` with an `onClick`, so no native submit event fires.
+     */
+    markSubmitAttempted: () => void;
 }
 /**
  * `applyZodIssues` — pipe every issue from a Zod safeParse failure into the
@@ -135,5 +158,6 @@ export interface FormShellProviderProps {
      * used to be hardcoded `[]`. Supply alongside `fieldToStepIndex`.
      */
     sections?: FormShellStep[];
+    submitAttempted?: boolean;
 }
-export declare function FormShellProvider({ children, onSaveDraft, isDirty, autoSaveDelayMs, values, schema, fieldToStepIndex, onGoToStep, sections, }: FormShellProviderProps): React.JSX.Element;
+export declare function FormShellProvider({ children, onSaveDraft, isDirty, autoSaveDelayMs, values, schema, fieldToStepIndex, onGoToStep, sections, submitAttempted: submitAttemptedProp, }: FormShellProviderProps): React.JSX.Element;