@mohasinac/appkit 4.13.1 → 4.15.0

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

@@ -1,19 +1,37 @@
 import React, { type ReactNode } from "react";
 import type { FormValues } from "../../schemas/types";
 /**
- * A step descriptor. The step-wizard *rendering* this once drove
- * (`<FormShell steps={…}>`) was deleted 2026-08-09 as dead code — the real
- * wizard chrome is `features/shell/FormShell.tsx` + `StepForm.tsx`. This type
- * survives because `FormShellContextValue.steps` still carries the shape for
- * any context consumer that reads it (FormShellProvider/useFormShellState
- * both populate it as `[]` since neither is step-aware).
+ * A navigable form segment — a wizard step historically, a `<SectionForm>`
+ * section today. `FormShellContextValue.steps` carries these purely so
+ * `<FormErrorSummary>` can name the segment that owns an error and offer a
+ * jump link.
+ *
+ * `content` is optional because the common producer (`useSectionFormNav`)
+ * builds descriptors from section metadata alone — it has an id and a label
+ * to render in the summary, and no node to hand over. Requiring a node here
+ * is what previously forced both context producers to give up and populate
+ * `steps: []`, which silently disabled the jump link everywhere.
  */
 export interface FormShellStep {
     id: string;
     label: string;
     /** Field names required in this step — drives publish gate + error badge */
     requiredFields?: string[];
-    content: React.ReactNode;
+    content?: React.ReactNode;
+}
+/**
+ * Navigation wiring for a form split into steps or collapsible sections.
+ *
+ * Supplying this is what makes `<FormErrorSummary>`'s "jump to section" link
+ * work: it needs `sections` to name the owning segment and `onGoToSection` to
+ * actually move there. Omit it for single-segment forms — the summary then
+ * renders a flat list, which is correct for them.
+ */
+export interface FormShellNav {
+    sections?: FormShellStep[];
+    onGoToSection?: (index: number) => void;
+    /** Maps a (dotted) error key to the index of the section that owns it. */
+    fieldToSectionIndex?: Record<string, number>;
 }
 export interface FormShellContextValue {
     errors: Record<string, string>;
@@ -73,12 +91,17 @@ export declare function applyZodIssues(issues: ReadonlyArray<{
     message: string;
 }>, setFieldError: (name: string, error: string | null) => void): void;
 /**
- * `useFormShellState(schema?)` — caller-owned form state with optional Zod
- * validation. When a schema is supplied, `validate(values)` runs it and pipes
- * issues into the FormShellContext error map. `audit-form-schema` requires
- * every callsite to pass a schema.
+ * `useFormShellState(schema?, nav?)` — caller-owned form state with optional
+ * Zod validation. When a schema is supplied, `validate(values)` runs it and
+ * pipes issues into the FormShellContext error map. `audit-form-schema`
+ * requires every callsite to pass a schema.
+ *
+ * Pass `nav` when the form is split into sections (see `useSectionFormNav`)
+ * so `<FormErrorSummary>` can name the owning section and jump to it. Omit it
+ * for single-segment forms; the summary renders a flat list, which is right
+ * for them.
  */
-export declare function useFormShellState<TSchema extends import("zod").ZodTypeAny = import("zod").ZodTypeAny>(schema?: TSchema): UseFormShellStateResult;
+export declare function useFormShellState<TSchema extends import("zod").ZodTypeAny = import("zod").ZodTypeAny>(schema?: TSchema, nav?: FormShellNav): UseFormShellStateResult;
 export interface FormShellProviderProps {
     children: ReactNode;
     /** Called on debounced auto-save when isDirty changes */
@@ -105,5 +128,12 @@ export interface FormShellProviderProps {
     fieldToStepIndex?: Record<string, number>;
     /** Wired into `FormShellContextValue.goToStep` when the caller has real step navigation to drive (e.g. a step-wizard's `setCurrentStep`). */
     onGoToStep?: (n: number) => void;
+    /**
+     * The navigable segments this form is split into, in order. Without these
+     * `<FormErrorSummary>` can call `goToStep(i)` but has no label to render for
+     * segment `i`, so it silently falls back to a flat list — which is why this
+     * used to be hardcoded `[]`. Supply alongside `fieldToStepIndex`.
+     */
+    sections?: FormShellStep[];
 }
-export declare function FormShellProvider({ children, onSaveDraft, isDirty, autoSaveDelayMs, values, schema, fieldToStepIndex, onGoToStep, }: FormShellProviderProps): React.JSX.Element;
+export declare function FormShellProvider({ children, onSaveDraft, isDirty, autoSaveDelayMs, values, schema, fieldToStepIndex, onGoToStep, sections, }: FormShellProviderProps): React.JSX.Element;

package/dist/ui/forms/FormShell.js

@@ -33,12 +33,17 @@ export function applyZodIssues(issues, setFieldError) {
     }
 }
 /**
- * `useFormShellState(schema?)` — caller-owned form state with optional Zod
- * validation. When a schema is supplied, `validate(values)` runs it and pipes
- * issues into the FormShellContext error map. `audit-form-schema` requires
- * every callsite to pass a schema.
+ * `useFormShellState(schema?, nav?)` — caller-owned form state with optional
+ * Zod validation. When a schema is supplied, `validate(values)` runs it and
+ * pipes issues into the FormShellContext error map. `audit-form-schema`
+ * requires every callsite to pass a schema.
+ *
+ * Pass `nav` when the form is split into sections (see `useSectionFormNav`)
+ * so `<FormErrorSummary>` can name the owning section and jump to it. Omit it
+ * for single-segment forms; the summary renders a flat list, which is right
+ * for them.
  */
-export function useFormShellState(schema) {
+export function useFormShellState(schema, nav) {
     const [errors, setErrors] = useState({});
     const setFieldError = useCallback((name, error) => {
         setErrors((prev) => {
@@ -64,25 +69,31 @@ export function useFormShellState(schema) {
         applyZodIssues(parsed.error.issues, setFieldError);
         return null;
     }, [schema, setFieldError]);
+    const navSections = nav?.sections;
+    const navGoTo = nav?.onGoToSection;
+    const navFieldMap = nav?.fieldToSectionIndex;
     const shellCtx = useMemo(() => ({
         errors,
         touched: Object.fromEntries(Object.keys(errors).map((k) => [k, true])),
         setFieldError,
         setFieldTouched: () => { },
         clearFieldError: (name) => setFieldError(name, null),
-        steps: [],
+        // Real sections when the caller supplied nav — this is what makes
+        // <FormErrorSummary>'s jump link resolve a label instead of `undefined`.
+        steps: navSections ?? [],
         currentStep: 0,
-        goToStep: () => { },
+        goToStep: navGoTo ?? (() => { }),
         nextStep: () => { },
         prevStep: () => { },
         isPublishReady: Object.keys(errors).length === 0,
         isDirty: false,
         isSubmitting: false,
         stepErrorCounts: [],
-    }), [errors, setFieldError]);
+        fieldToStepIndex: navFieldMap,
+    }), [errors, setFieldError, navSections, navGoTo, navFieldMap]);
     return { shellCtx, setFieldError, clearErrors, hasErrors: Object.keys(errors).length > 0, validate };
 }
-export function FormShellProvider({ children, onSaveDraft, isDirty = false, autoSaveDelayMs = 2000, values = {}, schema, fieldToStepIndex, onGoToStep, }) {
+export function FormShellProvider({ children, onSaveDraft, isDirty = false, autoSaveDelayMs = 2000, values = {}, schema, fieldToStepIndex, onGoToStep, sections, }) {
     const [errors, setErrors] = useState({});
     const [touched, setTouched] = useState({});
     const autoSaveTimer = useRef(null);
@@ -148,7 +159,7 @@ export function FormShellProvider({ children, onSaveDraft, isDirty = false, auto
         setFieldError,
         setFieldTouched,
         clearFieldError,
-        steps: [],
+        steps: sections ?? [],
         currentStep: 0,
         goToStep: onGoToStep ?? (() => { }),
         nextStep: () => { },
@@ -158,6 +169,6 @@ export function FormShellProvider({ children, onSaveDraft, isDirty = false, auto
         isSubmitting: false,
         stepErrorCounts: [],
         fieldToStepIndex,
-    }), [errors, touched, setFieldError, setFieldTouched, clearFieldError, isDirty, onGoToStep, fieldToStepIndex]);
+    }), [errors, touched, setFieldError, setFieldTouched, clearFieldError, isDirty, onGoToStep, fieldToStepIndex, sections]);
     return _jsx(FormShellContext.Provider, { value: ctx, children: children });
 }

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

@@ -1,4 +1,4 @@
-export type { FormShellProviderProps, FormShellStep, FormShellContextValue, UseFormShellStateResult, } from "./FormShell";
+export type { FormShellProviderProps, FormShellStep, FormShellNav, FormShellContextValue, UseFormShellStateResult, } from "./FormShell";
 export { FormShellProvider, FormShellContext, useFormShell, useFormShellState, applyZodIssues } from "./FormShell";
 export type { FieldInputProps } from "./FieldInput";
 export { FieldInput } from "./FieldInput";

package/dist/ui/index.d.ts

@@ -1,6 +1,6 @@
 import "./components/index.style.css";
 import "./forms/FormShell.style.css";
-export type { FormShellStep, FormShellContextValue, } from "./forms";
+export type { FormShellStep, FormShellNav, FormShellContextValue, } from "./forms";
 export { FormShellProvider, useFormShell } from "./forms";
 export type { FieldInputProps } from "./forms";
 export { FieldInput } from "./forms";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "4.13.1",
+  "version": "4.15.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -128,6 +128,7 @@
     "scripts/init-config.mjs",
     "scripts/labels-extract.mjs",
     "scripts/seed-cli.mjs",
+    "scripts/node-esm-loader.mjs",
     "scripts/seed-cli-loader.mjs",
     "scripts/dedupe-peer-deps.mjs",
     "scripts/copy-assets.mjs",

package/scripts/node-esm-loader.mjs

@@ -0,0 +1,65 @@
+/**
+ * ESM resolver hook — makes `import("@mohasinac/appkit")` work from ANY
+ * standalone Node script.
+ *
+ * appkit is `"type": "module"` built by plain `tsc`, and tsc does not rewrite
+ * import specifiers — so all ~2,190 emitted `.js` files carry bare relative
+ * imports with no `.js` extension. Bundlers (Next/Turbopack, tsup, vite)
+ * resolve those happily; Node's ESM resolver refuses them outright. This hook
+ * retries with `.js` and then `/index.js` on ERR_MODULE_NOT_FOUND, and stubs
+ * the two other things that make a raw Node import of appkit explode.
+ *
+ * Registered by:
+ *   - `appkit/scripts/seed-cli.mjs`      (the appkit-seed CLI)
+ *   - `scripts/qa/roundtrip-diff.mjs`    (the schema field-loss gate)
+ *
+ * **Renamed from `seed-cli-loader.mjs`** — it was never seed-specific, and
+ * that name was why a later session diagnosed the same ESM failure from
+ * scratch and concluded the fix was to rewrite every specifier at build time.
+ * It is not: it is this file, registered in three lines. `seed-cli-loader.mjs`
+ * remains as a re-export so any pinned path keeps working.
+ */
+
+// Stub out non-JS asset imports (CSS, etc.) — appkit's dist contains
+// `import "./foo.css"` side-effect statements that Node ESM can't load.
+const STUB_EXTENSIONS = [".css", ".scss", ".sass", ".png", ".jpg", ".jpeg", ".svg", ".webp", ".gif"];
+
+// server-only / client-only are Next.js-specific sentinel packages — their
+// entire module body unconditionally throws, because their whole purpose is
+// a Next.js-compiler-time + Next.js-runtime guard against importing a
+// server-only (or client-only) module from the wrong side of the boundary.
+// A raw Node script (this CLI) is neither a Next.js Server Component nor a
+// Client Component, so the guard is meaningless here — the main
+// @mohasinac/appkit barrel transitively reaches a module (e.g.
+// features/contact/email.tsx) that imports "server-only" at the top level,
+// which crashes the whole CLI on load. Stub both to a no-op module. Found
+// 2026-08-17 debugging the CLI seed tool being unable to import appkit at all.
+const SENTINEL_SPECIFIERS = new Set(["server-only", "client-only"]);
+
+export async function load(url, context, nextLoad) {
+  if (STUB_EXTENSIONS.some((ext) => url.endsWith(ext))) {
+    return { format: "module", shortCircuit: true, source: "export default undefined;" };
+  }
+  return nextLoad(url, context);
+}
+
+export async function resolve(specifier, context, nextResolve) {
+  if (SENTINEL_SPECIFIERS.has(specifier)) {
+    return { url: `data:text/javascript,export default undefined;`, shortCircuit: true };
+  }
+  try {
+    return await nextResolve(specifier, context);
+  } catch (err) {
+    if (err?.code !== "ERR_MODULE_NOT_FOUND" && err?.code !== "ERR_UNSUPPORTED_DIR_IMPORT") throw err;
+    if (specifier.endsWith(".js") || specifier.endsWith(".mjs") || specifier.endsWith(".cjs")) throw err;
+    // Try with .js suffix (most common case)
+    try {
+      return await nextResolve(`${specifier}.js`, context);
+    } catch {}
+    // Try as a directory index
+    try {
+      return await nextResolve(`${specifier}/index.js`, context);
+    } catch {}
+    throw err;
+  }
+}

package/scripts/seed-cli-loader.mjs

@@ -1,52 +1,9 @@
 /**
- * ESM resolver hook for seed-cli.mjs.
+ * Back-compat shim. The real implementation is `node-esm-loader.mjs`.
  *
- * appkit's dist emits bare relative imports without `.js` extensions
- * (TS build is bundler-target, not Node). Node ESM is strict and refuses
- * them. This hook tries appending `.js` and `/index.js` when a resolution
- * fails with ERR_MODULE_NOT_FOUND.
+ * The hook was never seed-specific — it makes a bare `import("@mohasinac/appkit")`
+ * resolve from any standalone Node script — so it was renamed. This file stays
+ * so a pinned path (a published tarball, a script outside this repo) keeps
+ * working. Register `node-esm-loader.mjs` directly in anything new.
  */
-
-// Stub out non-JS asset imports (CSS, etc.) — appkit's dist contains
-// `import "./foo.css"` side-effect statements that Node ESM can't load.
-const STUB_EXTENSIONS = [".css", ".scss", ".sass", ".png", ".jpg", ".jpeg", ".svg", ".webp", ".gif"];
-
-// server-only / client-only are Next.js-specific sentinel packages — their
-// entire module body unconditionally throws, because their whole purpose is
-// a Next.js-compiler-time + Next.js-runtime guard against importing a
-// server-only (or client-only) module from the wrong side of the boundary.
-// A raw Node script (this CLI) is neither a Next.js Server Component nor a
-// Client Component, so the guard is meaningless here — the main
-// @mohasinac/appkit barrel transitively reaches a module (e.g.
-// features/contact/email.tsx) that imports "server-only" at the top level,
-// which crashes the whole CLI on load. Stub both to a no-op module. Found
-// 2026-08-17 debugging the CLI seed tool being unable to import appkit at all.
-const SENTINEL_SPECIFIERS = new Set(["server-only", "client-only"]);
-
-export async function load(url, context, nextLoad) {
-  if (STUB_EXTENSIONS.some((ext) => url.endsWith(ext))) {
-    return { format: "module", shortCircuit: true, source: "export default undefined;" };
-  }
-  return nextLoad(url, context);
-}
-
-export async function resolve(specifier, context, nextResolve) {
-  if (SENTINEL_SPECIFIERS.has(specifier)) {
-    return { url: `data:text/javascript,export default undefined;`, shortCircuit: true };
-  }
-  try {
-    return await nextResolve(specifier, context);
-  } catch (err) {
-    if (err?.code !== "ERR_MODULE_NOT_FOUND" && err?.code !== "ERR_UNSUPPORTED_DIR_IMPORT") throw err;
-    if (specifier.endsWith(".js") || specifier.endsWith(".mjs") || specifier.endsWith(".cjs")) throw err;
-    // Try with .js suffix (most common case)
-    try {
-      return await nextResolve(`${specifier}.js`, context);
-    } catch {}
-    // Try as a directory index
-    try {
-      return await nextResolve(`${specifier}/index.js`, context);
-    } catch {}
-    throw err;
-  }
-}
+export { load, resolve } from "./node-esm-loader.mjs";

package/scripts/seed-cli.mjs

@@ -34,7 +34,7 @@ import readline from "node:readline";
 // Register an ESM resolver hook that retries with `.js` / `/index.js` when
 // appkit's bundler-target dist emits extension-less relative imports.
 const __dirname = dirname(fileURLToPath(import.meta.url));
-register("./seed-cli-loader.mjs", pathToFileURL(__dirname + "/"));
+register("./node-esm-loader.mjs", pathToFileURL(__dirname + "/"));
 
 // ---------------------------------------------------------------------------
 // CLI parsing — entry point detects bin name so the same script powers