@mohasinac/appkit 4.30.18 → 4.31.0

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.
  *

package/dist/features/shell/field-ui-meta.js

@@ -300,15 +300,22 @@ export function inferFieldUiMeta(name, schema) {
         meta.derived = true;
         meta.tier = meta.tier ?? "t2-server";
     }
-    // >5 options is the standing PaginatedSelect threshold. Recorded as `help`
-    // rather than a separate flag so the renderer can decide without a second
-    // source of truth about what "many options" means.
-    const options = enumOptions(inner);
-    if (meta.kind === "select" && options != null && options.length > 5) {
-        meta.help = meta.help ?? "paginated";
-    }
     return meta;
 }
+/**
+ * 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 const PAGINATED_SELECT_THRESHOLD = 5;
 /**
  * The field's final metadata: inference first, explicit registration on top.
  *

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

@@ -0,0 +1,46 @@
+/**
+ * The canonical section ORDER vocabulary.
+ *
+ * ## Why this is a `group`, not a rename of `section`
+ *
+ * The plan called for collapsing the 58 free-form section ids in use across 30
+ * schemas onto a closed 12-value set. Measured before doing it, that merges
+ * sections in 7 files and 8 places — the scam report's `who` + `what` +
+ * `declare` become one blob, coupons' `limits` + `validity` collapse together,
+ * blog's `content` + `seo` merge, and payout methods lose the split between
+ * `method` and `bank`.
+ *
+ * The mistake was treating one identifier as two things. A section id is the
+ * RENDERED UNIT — fine-grained, form-specific, and the thing whose heading the
+ * user reads (`build-sections` falls back to `humaniseFieldName(sectionId)`, so
+ * 144 of the 228 annotations get their visible heading straight from the id).
+ * What the ordering rule actually needs is a PRIORITY BAND: required first,
+ * danger last, everything else in a predictable middle.
+ *
+ * So the id stays free-form and every section declares a `group` from this
+ * closed union. Order and default-open derive from the group; identity and
+ * heading stay with the id. Nothing merges, and the audit still has a closed
+ * set to check against.
+ *
+ * ## Ordering
+ *
+ * Array order IS render order. `required` is index 0 and is the section left
+ * open by default; `danger` is always last. That gives "1. Required → 2.
+ * Additional → … → least important last" mechanically, with no per-form
+ * `sectionOrder` to maintain.
+ */
+export declare const FORM_SECTION_GROUP: readonly ["required", "identity", "classification", "pricing", "inventory", "media", "logistics", "relationships", "schedule", "visibility", "advanced", "danger"];
+export type FormSectionGroup = (typeof FORM_SECTION_GROUP)[number];
+/** Position of a group in render order; unknown groups sort just before danger. */
+export declare function groupRank(group: FormSectionGroup | undefined): number;
+/**
+ * Default group for each section id currently in use, so 30 schemas do not each
+ * need a hand-written `group`. A section id absent here must declare its own —
+ * `audit-form-sectionised` fails otherwise, which is what stops a new id
+ * silently defaulting into the middle of the form.
+ *
+ * Derived from the 58 ids actually present, counted rather than guessed.
+ */
+export declare const SECTION_GROUP_DEFAULTS: Record<string, FormSectionGroup>;
+/** The group for a section id — its declared group, else the default, else advanced. */
+export declare function resolveSectionGroup(sectionId: string, declared?: FormSectionGroup): FormSectionGroup;