@mohasinac/appkit 4.21.0 → 4.23.0

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;

package/dist/ui/forms/FormShell.js

@@ -45,6 +45,9 @@ export function applyZodIssues(issues, setFieldError) {
  */
 export function useFormShellState(schema, nav) {
     const [errors, setErrors] = useState({});
+    const [submitAttemptCount, setSubmitAttemptCount] = useState(0);
+    const markSubmitAttempted = useCallback(() => setSubmitAttemptCount((n) => n + 1), []);
+    const submitAttempted = submitAttemptCount > 0;
     const setFieldError = useCallback((name, error) => {
         setErrors((prev) => {
             if (!error) {
@@ -59,6 +62,19 @@ export function useFormShellState(schema, nav) {
     }, []);
     const clearErrors = useCallback(() => setErrors({}), []);
     const validate = useCallback((values) => {
+        /*
+         * 🛑 validate() does NOT mark the submit attempt, and must not.
+         *
+         * ELEVEN views call `validate(draft)` from a MOUNT EFFECT to keep the
+         * summary and the submit-button state live as the user types — which
+         * is the behaviour worth having. Marking here would fire on first
+         * paint in exactly those views and defeat the gate entirely.
+         *
+         * The attempt is marked where an attempt actually happens: <Form>'s
+         * native submit handler, <SectionForm>'s submit button, and
+         * QuickFormDrawer's. A caller whose submit is an onClick on a
+         * type="button" calls markSubmitAttempted() itself.
+         */
         if (!schema)
             return values;
         const parsed = schema.safeParse(values);
@@ -90,12 +106,28 @@ export function useFormShellState(schema, nav) {
         isSubmitting: false,
         stepErrorCounts: [],
         fieldToStepIndex: navFieldMap,
-    }), [errors, setFieldError, navSections, navGoTo, navFieldMap]);
-    return { shellCtx, setFieldError, clearErrors, hasErrors: Object.keys(errors).length > 0, validate };
+        submitAttempted,
+        submitAttemptCount,
+        markSubmitAttempted,
+    }), [errors, setFieldError, navSections, navGoTo, navFieldMap, submitAttempted, submitAttemptCount, markSubmitAttempted]);
+    return {
+        shellCtx,
+        setFieldError,
+        clearErrors,
+        hasErrors: Object.keys(errors).length > 0,
+        validate,
+        submitAttempted,
+        submitAttemptCount,
+        markSubmitAttempted,
+    };
 }
-export function FormShellProvider({ children, onSaveDraft, isDirty = false, autoSaveDelayMs = 2000, values = {}, schema, fieldToStepIndex, onGoToStep, sections, }) {
+export function FormShellProvider({ children, onSaveDraft, isDirty = false, autoSaveDelayMs = 2000, values = {}, schema, fieldToStepIndex, onGoToStep, sections, submitAttempted: submitAttemptedProp = false, }) {
     const [errors, setErrors] = useState({});
     const [touched, setTouched] = useState({});
+    const [ownAttemptCount, setOwnAttemptCount] = useState(0);
+    const markSubmitAttempted = useCallback(() => setOwnAttemptCount((n) => n + 1), []);
+    const submitAttemptCount = ownAttemptCount + (submitAttemptedProp ? 1 : 0);
+    const submitAttempted = submitAttemptCount > 0;
     const autoSaveTimer = useRef(null);
     const valuesRef = useRef(values);
     valuesRef.current = values;
@@ -169,6 +201,9 @@ export function FormShellProvider({ children, onSaveDraft, isDirty = false, auto
         isSubmitting: false,
         stepErrorCounts: [],
         fieldToStepIndex,
-    }), [errors, touched, setFieldError, setFieldTouched, clearFieldError, isDirty, onGoToStep, fieldToStepIndex, sections]);
+        submitAttempted,
+        submitAttemptCount,
+        markSubmitAttempted,
+    }), [errors, touched, setFieldError, setFieldTouched, clearFieldError, isDirty, onGoToStep, fieldToStepIndex, sections, submitAttempted, submitAttemptCount, markSubmitAttempted]);
     return _jsx(FormShellContext.Provider, { value: ctx, children: children });
 }

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

@@ -12,3 +12,5 @@ export type { ColorPickerFieldProps } from "./ColorPickerField";
 export { ColorPickerField } from "./ColorPickerField";
 export type { FormErrorSummaryProps } from "./FormErrorSummary";
 export { FormErrorSummary } from "./FormErrorSummary";
+export type { FormErrorListProps } from "./FormErrorList";
+export { FormErrorList } from "./FormErrorList";

package/dist/ui/forms/index.js

@@ -5,3 +5,4 @@ export { FieldCheckbox } from "./FieldCheckbox";
 export { FieldTextarea } from "./FieldTextarea";
 export { ColorPickerField } from "./ColorPickerField";
 export { FormErrorSummary } from "./FormErrorSummary";
+export { FormErrorList } from "./FormErrorList";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "4.21.0",
+  "version": "4.23.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"