@mohasinac/appkit 4.71.0 → 4.71.2

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

@@ -1,7 +1,9 @@
 import { type ReactNode } from "react";
 import type { ZodTypeAny } from "zod";
 import type { SectionDef } from "./SectionForm";
-import { type FieldUiMeta } from "./field-ui-meta";
+import { type CustomFieldDef, type FieldUiMeta, type FormStep } from "./field-ui-meta";
+/** The scalar shape a `CustomFieldDef` value can hold — never nested, never `unknown`. */
+export type CustomFieldValue = string | number | boolean;
 /** One field, resolved: its name, its schema, and its final metadata. */
 export interface ResolvedField {
     name: string;
@@ -31,6 +33,78 @@ export interface BuildSectionsOptions<T extends object> {
      * in first-declaration order. `sectionRequired` still sorts first regardless.
      */
     sectionOrder?: string[];
+    /**
+     * Admin-authored per-field visibility override (Phase 3B widget system,
+     * `_internal/server/features/forms/field-visibility.ts` +
+     * `features/shell/useFieldVisibility.ts`), keyed by field name. `false`
+     * hides the field; absent or `true` leaves it to `when` alone. Optional
+     * and additive — every existing caller that doesn't pass this renders
+     * byte-identically to before.
+     *
+     * 🛑 Combines with `FieldUiMeta.when` by AND, `when` evaluated first,
+     * NEVER the reverse: an admin override may only hide a field `when`
+     * would otherwise show, never resurrect one `when` has ruled out. Forcing
+     * a `when`-gated field back on is a genuinely harder problem — see this
+     * field's own usage site in `render` below for why — and is deliberately
+     * not supported here.
+     */
+    fieldVisibility?: Record<string, boolean>;
+    /**
+     * Shows every field regardless of `fieldVisibility` (an admin re-enabling
+     * a field has to be able to SEE it first) plus a small toggle beside
+     * each one — "inline on the page itself, same pattern as page regions"
+     * (owner's own instruction on where this control lives). Pass the
+     * viewer's own `EditModeProvider` state; `build-sections.tsx` does not
+     * read it itself, so this stays usable in a context with no edit-mode
+     * concept at all. Ignored when `fieldVisibility` is not supplied.
+     */
+    editMode?: boolean;
+    /** Required when `editMode` is `true` — flips one field's stored visibility. */
+    onToggleFieldVisibility?: (fieldName: string, nextVisible: boolean) => void;
+    /**
+     * Admin-chosen render order (3B item 1b, `useFieldVisibility().fieldOrder`).
+     * Fields named here render first, in this order; fields not named keep
+     * their schema-declared relative order, appended after. Optional and
+     * additive — omit it and every field sorts exactly as before.
+     */
+    fieldOrder?: string[];
+    /**
+     * Edit-mode-only reorder — renders move-up/move-down buttons beside each
+     * field's eye-toggle (RS13-adjacent decision, 2026-11-04: an up/down
+     * BUTTON pair, never drag-and-drop — matching this codebase's one other
+     * real reorder UI, `NavPermissionsManager.tsx`'s ▲/▼ pattern, and the
+     * project-wide "no drag-and-drop, discrete controls only" constraint that
+     * already governs the card-element span picker). This function resolves
+     * the ADJACENT field name itself (scoped to the current section's own
+     * visible order, matching how `fieldOrder` already only reorders WITHIN
+     * a field's schema-derived section, never across one) — the caller's job
+     * is only "persist a swap of these two names", via
+     * `swapFieldOrder(fieldOrder, allFieldNames, fieldName, neighborName)`
+     * (`field-ui-meta.ts`). Ignored when `editMode` is not `true`.
+     */
+    onMoveField?: (fieldName: string, neighborFieldName: string) => void;
+    /**
+     * Admin-defined fields with no presence in the schema (3B item 1b). They
+     * render as their OWN section, after every schema-derived section, via a
+     * small fixed `type → control` map — never through `renderers`, which is
+     * keyed by a real schema field name these are not. Empty/omitted renders
+     * nothing extra, so an unconfigured surface is byte-identical to before
+     * this option existed.
+     */
+    customFields?: CustomFieldDef[];
+    /** Current values for `customFields`, keyed by `CustomFieldDef.key`. */
+    customFieldValues?: Record<string, CustomFieldValue>;
+    /** Required when `customFields` is non-empty. */
+    onCustomFieldChange?: (key: string, value: CustomFieldValue | undefined) => void;
+    /**
+     * Edit-mode-only — defines a new field with no schema presence. Rendered
+     * as a small "Add field" row at the end of the custom-fields section,
+     * same "inline on the page itself" placement as the field-visibility
+     * eye-icons. Ignored when `editMode` is not `true`.
+     */
+    onAddCustomField?: (field: CustomFieldDef) => void;
+    /** Edit-mode-only — removes a custom field definition AND its stored value. */
+    onRemoveCustomField?: (key: string) => void;
 }
 /**
  * Resolve every field in a schema's shape.
@@ -65,7 +139,7 @@ export declare function packRows(fields: ResolvedField[]): ResolvedField[][];
  *
  * 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
+ * switching to free-shipping; a giveaway slot price written under uniform
  * pricing; an AdSense slot shipped with a manually-authored ad. Each looked
  * right on screen and saved something else.
  *
@@ -84,3 +158,22 @@ export declare function visibleValues<T extends object>(schema: ZodTypeAny, valu
  * first-declaration order.
  */
 export declare function buildSectionsFromSchema<T extends object>(schema: ZodTypeAny, opts?: BuildSectionsOptions<T>): SectionDef<T>[];
+/**
+ * Partition an already-built `SectionDef[]` into wizard pages, one per
+ * `FormStep`. A section is assigned to the step owning its FIRST-declared
+ * field (`SectionDef.fields`, in source-declaration order) — never split
+ * across two steps, since `<SectionForm>` renders a section as one unit.
+ *
+ * Sections with no field named in ANY step are appended as a final,
+ * untitled page rather than silently dropped — a step config that forgot
+ * the custom-fields section (added after `steps` was authored) must not
+ * make that section vanish.
+ *
+ * `steps.length === 0` returns `[{ title: "", sections }]` — one page
+ * holding everything, so a caller can unconditionally map over the result
+ * without a separate "no steps" branch.
+ */
+export declare function groupSectionsByStep<T extends object>(sections: SectionDef<T>[], steps: FormStep[]): {
+    title: string;
+    sections: SectionDef<T>[];
+}[];

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

@@ -35,10 +35,13 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
  * @tag sideEffects:none
  */
 import { groupRank, resolveSectionGroup } from "./form-sections.js";
-import { Fragment } from "react";
+import { Fragment, useState } from "react";
+import { Div } from "../../ui/components/Div.js";
 import { FormGroup } from "../../ui/components/Form.js";
+import { Icon } from "../../ui/components/Icon.js";
+import { IconButton } from "../../ui/components/IconButton.js";
 import { PaginatedSelect } from "../../ui/components/PaginatedSelect.js";
-import { Stack } from "../../ui/components/Layout.js";
+import { Row, Stack } from "../../ui/components/Layout.js";
 import { Text } from "../../ui/components/Typography.js";
 import { FieldInput } from "../../ui/forms/FieldInput.js";
 import { FieldSelect } from "../../ui/forms/FieldSelect.js";
@@ -46,6 +49,7 @@ import { FieldTextarea } from "../../ui/forms/FieldTextarea.js";
 import { FieldCheckbox } from "../../ui/forms/FieldCheckbox.js";
 import { humaniseFieldName } from "./entity-form.js";
 import { ROW_COLUMNS, inferFieldUiMeta, objectShape, schemaEnumOptions, schemaIsOptional, ui, PAGINATED_SELECT_THRESHOLD, } from "./field-ui-meta.js";
+const CUSTOM_FIELDS_SECTION_ID = "__customFields";
 /**
  * Enum members as `<FieldSelect>` options.
  *
@@ -157,7 +161,7 @@ export function packRows(fields) {
  *
  * 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
+ * switching to free-shipping; a giveaway slot price written under uniform
  * pricing; an AdSense slot shipped with a manually-authored ad. Each looked
  * right on screen and saved something else.
  *
@@ -190,6 +194,19 @@ export function visibleValues(schema, values) {
  */
 export function buildSectionsFromSchema(schema, opts = {}) {
     const fields = resolveFields(schema);
+    // Admin `fieldOrder` (3B item 1b) overrides `meta.order` only for the
+    // fields it names, each getting its index as its new order — low enough
+    // to sort before every unset field (whose order stays `undefined`, i.e.
+    // MAX_SAFE_INTEGER). Fields it does NOT name are untouched, so they keep
+    // their existing relative order and simply render after the named ones.
+    if (opts.fieldOrder && opts.fieldOrder.length > 0) {
+        const position = new Map(opts.fieldOrder.map((name, i) => [name, i]));
+        for (const field of fields) {
+            const i = position.get(field.name);
+            if (i !== undefined)
+                field.meta = { ...field.meta, order: i };
+        }
+    }
     const bySection = groupFieldsBySection(fields);
     const declarationOrder = [...bySection.keys()];
     const explicitOrder = opts.sectionOrder ?? [];
@@ -215,7 +232,7 @@ export function buildSectionsFromSchema(schema, opts = {}) {
         // exceed any plausible section count in one form.
         return explicitOrder.length + groupRank(group) * 1000 + declarationOrder.indexOf(id);
     };
-    return declarationOrder
+    const sections = declarationOrder
         .slice()
         .sort((a, b) => rank(a) - rank(b))
         .map((sectionId) => {
@@ -239,12 +256,166 @@ export function buildSectionsFromSchema(schema, opts = {}) {
                  * the CURRENT values, so a field appears the moment its condition
                  * becomes true. Rows are packed after filtering so a hidden field
                  * does not leave a gap in a two-up row.
+                 *
+                 * `when` evaluates FIRST, `fieldVisibility` only narrows further —
+                 * see `BuildSectionsOptions.fieldVisibility`'s own doc comment for
+                 * why the order is not interchangeable.
                  */
-                const visible = sectionFields.filter((f) => !f.meta.when || f.meta.when(values));
-                return (_jsx(_Fragment, { children: packRows(visible).map((row, i) => (_jsx(FormGroup, { columns: ROW_COLUMNS[row[0].meta.row ?? "pair"], children: row.map((field) => renderField(field, { values, onChange, errors }, opts)) }, `${sectionId}-row-${i}`))) }));
+                const whenVisible = sectionFields.filter((f) => !f.meta.when || f.meta.when(values));
+                const visible = opts.editMode
+                    ? whenVisible
+                    : whenVisible.filter((f) => opts.fieldVisibility?.[f.name] !== false);
+                return (_jsx(_Fragment, { children: packRows(visible).map((row, i) => (_jsx(FormGroup, { columns: ROW_COLUMNS[row[0].meta.row ?? "pair"], children: row.map((field) => {
+                            const node = renderField(field, { values, onChange, errors }, opts);
+                            if (!opts.editMode)
+                                return node;
+                            const hidden = opts.fieldVisibility?.[field.name] === false;
+                            // Adjacency within THIS section's own visible order —
+                            // same scope `fieldOrder` already reorders within (see
+                            // `onMoveField`'s own doc comment for why cross-section
+                            // is out of scope).
+                            const idx = visible.indexOf(field);
+                            const upNeighbor = idx > 0 ? visible[idx - 1].name : undefined;
+                            const downNeighbor = idx < visible.length - 1 ? visible[idx + 1].name : undefined;
+                            return (_jsx(FieldVisibilityEditWrapper, { hidden: hidden, 
+                                // The stored value IS the new `isVisible()` result
+                                // (`true` = shown, `false` = hidden), and `hidden`
+                                // is true exactly when the stored value is `false`
+                                // — so the value to store on toggle equals `hidden`
+                                // itself: hidden→store true (becomes shown),
+                                // shown→store false (becomes hidden).
+                                onToggle: () => opts.onToggleFieldVisibility?.(field.name, hidden), onMoveUp: upNeighbor ? () => opts.onMoveField?.(field.name, upNeighbor) : undefined, onMoveDown: downNeighbor ? () => opts.onMoveField?.(field.name, downNeighbor) : undefined, children: node }, `${field.name}-visibility`));
+                        }) }, `${sectionId}-row-${i}`))) }));
             },
         };
     });
+    // Admin-defined fields with no schema presence (3B item 1b) — always
+    // LAST, never interleaved with a schema-derived section. Omitted entirely
+    // for a non-admin viewer with none defined, so an unconfigured surface
+    // renders this function's output byte-identical to before this option
+    // existed. Rendered (empty, with just the "Add field" row) in edit mode
+    // even with zero custom fields — otherwise there is no way to define the
+    // FIRST one.
+    const hasCustomFields = (opts.customFields?.length ?? 0) > 0;
+    if (hasCustomFields || (opts.editMode && opts.onAddCustomField)) {
+        sections.push(buildCustomFieldsSection(opts.customFields ?? [], opts));
+    }
+    return sections;
+}
+/**
+ * Partition an already-built `SectionDef[]` into wizard pages, one per
+ * `FormStep`. A section is assigned to the step owning its FIRST-declared
+ * field (`SectionDef.fields`, in source-declaration order) — never split
+ * across two steps, since `<SectionForm>` renders a section as one unit.
+ *
+ * Sections with no field named in ANY step are appended as a final,
+ * untitled page rather than silently dropped — a step config that forgot
+ * the custom-fields section (added after `steps` was authored) must not
+ * make that section vanish.
+ *
+ * `steps.length === 0` returns `[{ title: "", sections }]` — one page
+ * holding everything, so a caller can unconditionally map over the result
+ * without a separate "no steps" branch.
+ */
+export function groupSectionsByStep(sections, steps) {
+    if (steps.length === 0)
+        return [{ title: "", sections }];
+    const stepOfField = new Map();
+    steps.forEach((step, i) => step.fields.forEach((name) => {
+        if (!stepOfField.has(name))
+            stepOfField.set(name, i);
+    }));
+    const pages = steps.map(() => []);
+    const unassigned = [];
+    for (const section of sections) {
+        const firstNamed = section.fields?.find((name) => stepOfField.has(name));
+        const stepIndex = firstNamed !== undefined ? stepOfField.get(firstNamed) : undefined;
+        if (stepIndex !== undefined)
+            pages[stepIndex].push(section);
+        else
+            unassigned.push(section);
+    }
+    const out = steps.map((step, i) => ({ title: step.title, sections: pages[i] }));
+    if (unassigned.length > 0)
+        out.push({ title: "", sections: unassigned });
+    return out;
+}
+/**
+ * The one section every `customFields`-carrying surface gets, rendering
+ * each definition through a small fixed `type → control` map — never
+ * through `renderers`, which is keyed by a real schema field name these are
+ * not.
+ */
+function buildCustomFieldsSection(customFields, opts) {
+    return {
+        id: CUSTOM_FIELDS_SECTION_ID,
+        label: "Custom fields",
+        required: false,
+        quick: false,
+        // Holds the "Add field" draft's own uncommitted input — collapsing
+        // must not discard it, same reasoning media sections already use.
+        keepMounted: true,
+        fields: customFields.map((f) => f.key),
+        render: () => (_jsxs(_Fragment, { children: [customFields.map((field) => (_jsx(FormGroup, { columns: opts.editMode ? 1 : 1, children: opts.editMode ? (_jsxs(Row, { gap: "xs", align: "start", children: [_jsx(Div, { className: "flex-1", children: renderCustomField(field, opts) }), _jsx(IconButton, { "aria-label": `Remove custom field "${field.label}"`, icon: _jsx(Icon, { name: "delete", size: "sm" }), size: "sm", variant: "ghost", onClick: () => opts.onRemoveCustomField?.(field.key) })] })) : (renderCustomField(field, opts)) }, field.key))), opts.editMode && opts.onAddCustomField && (_jsx(FormGroup, { columns: 1, children: _jsx(AddCustomFieldRow, { existingKeys: customFields.map((f) => f.key), onAdd: opts.onAddCustomField }) }))] })),
+    };
+}
+/**
+ * Edit-mode-only — the small form that defines a brand-new field with no
+ * schema presence. Its own local state (the draft key/label/type) is
+ * uncommitted input belonging to the EDITOR, not to the surface's real
+ * form values, so it lives here rather than threading through `T`.
+ */
+function AddCustomFieldRow({ existingKeys, onAdd, }) {
+    const [draft, setDraft] = useState({ key: "", label: "", type: "text" });
+    const [error, setError] = useState();
+    const submit = () => {
+        const key = draft.key.trim();
+        const label = draft.label.trim();
+        if (!key || !label) {
+            setError("Give the field a key and a label.");
+            return;
+        }
+        if (existingKeys.includes(key)) {
+            setError(`"${key}" already exists on this surface.`);
+            return;
+        }
+        onAdd({ key, label, type: draft.type });
+        setDraft({ key: "", label: "", type: "text" });
+        setError(undefined);
+    };
+    return (_jsxs(Stack, { gap: "xs", surface: "subtle", padding: "sm", rounded: "md", children: [_jsx(Text, { size: "xs", weight: "medium", color: "muted", children: "Add a custom field" }), _jsxs(Row, { gap: "xs", wrap: true, children: [_jsx(FieldInput, { name: "newCustomFieldKey", label: "Key", hint: "Storage key \u2014 letters/numbers only", value: draft.key, onChange: (v) => setDraft((d) => ({ ...d, key: v.replace(/[^a-zA-Z0-9_]/g, "") })) }), _jsx(FieldInput, { name: "newCustomFieldLabel", label: "Label", value: draft.label, onChange: (v) => setDraft((d) => ({ ...d, label: v })) }), _jsx(FieldSelect, { name: "newCustomFieldType", label: "Type", value: draft.type, options: [
+                            { value: "text", label: "Text" },
+                            { value: "number", label: "Number" },
+                            { value: "select", label: "Select" },
+                            { value: "boolean", label: "Toggle" },
+                            { value: "date", label: "Date" },
+                        ], onChange: (v) => setDraft((d) => ({ ...d, type: v })) })] }), error && _jsx(Text, { size: "xs", color: "error", children: error }), _jsx(IconButton, { "aria-label": "Add field", icon: _jsx(Icon, { name: "create", size: "sm" }), size: "sm", variant: "outline", onClick: submit })] }));
+}
+function renderCustomField(field, opts) {
+    const value = opts.customFieldValues?.[field.key];
+    const set = (v) => opts.onCustomFieldChange?.(field.key, v);
+    switch (field.type) {
+        case "boolean":
+            return (_jsx(FieldCheckbox, { name: field.key, label: field.label, checked: Boolean(value), onChange: set }, field.key));
+        case "select":
+            return (_jsx(FieldSelect, { name: field.key, label: field.label, required: field.required, value: typeof value === "string" ? value : "", options: (field.options ?? []).map((o) => ({ value: o, label: o })), onChange: set }, field.key));
+        case "number":
+            return (_jsx(FieldInput, { name: field.key, type: "number", label: field.label, required: field.required, value: value == null ? "" : String(value), onChange: (v) => set(v === "" ? undefined : Number(v)) }, field.key));
+        case "date":
+            return (_jsx(FieldInput, { name: field.key, type: "date", label: field.label, required: field.required, value: typeof value === "string" ? value.slice(0, 10) : "", onChange: set }, field.key));
+        default:
+            return (_jsx(FieldInput, { name: field.key, type: "text", label: field.label, required: field.required, maxLength: field.maxLength, value: typeof value === "string" ? value : value == null ? "" : String(value), onChange: set }, field.key));
+    }
+}
+/**
+ * Edit-mode-only chrome around one field — a small eye/eye-off toggle, and a
+ * dimmed "Hidden from form" label when the admin has switched the field off
+ * for everyone else. Only ever rendered when `BuildSectionsOptions.editMode`
+ * is `true`; every other caller never mounts this and sees byte-identical
+ * output to before this mechanism existed.
+ */
+function FieldVisibilityEditWrapper({ hidden, onToggle, onMoveUp, onMoveDown, children, }) {
+    return (_jsxs(Div, { className: hidden ? "opacity-50" : undefined, children: [_jsxs(Row, { gap: "xs", align: "center", justify: "between", className: "mb-1", children: [hidden && _jsx(Text, { size: "xs", color: "muted", children: "Hidden from form" }), _jsxs(Row, { gap: "xs", className: "ml-auto", children: [_jsx(IconButton, { "aria-label": "Move this field up", icon: _jsx(Icon, { name: "arrow-up", size: "sm" }), size: "sm", variant: "ghost", disabled: !onMoveUp, onClick: onMoveUp }), _jsx(IconButton, { "aria-label": "Move this field down", icon: _jsx(Icon, { name: "arrow-down", size: "sm" }), size: "sm", variant: "ghost", disabled: !onMoveDown, onClick: onMoveDown }), _jsx(IconButton, { "aria-label": hidden ? "Show this field" : "Hide this field", icon: _jsx(Icon, { name: hidden ? "hide" : "view", size: "sm" }), size: "sm", variant: "ghost", onClick: onToggle })] })] }), children] }));
 }
 function renderField(field, ctx, opts) {
     const override = opts.renderers?.[field.name];

package/dist/features/shell/field-ui-meta.d.ts

@@ -3,6 +3,23 @@ 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. */
 export type FieldRow = "full" | "pair" | "third" | "quarter";
+/**
+ * Wizard grouping (3B item 1b's `SurfaceTemplate.steps`, 2026-11-04) — an
+ * admin-authored grouping of an already-built `SectionDef[]` into
+ * next/back-gated pages. `fields` names which SCHEMA fields belong to this
+ * step; `groupSectionsByStep` (`build-sections.tsx`) resolves that to whole
+ * sections (a section is assigned to the step owning its FIRST-declared
+ * field, so a section is never split across two steps).
+ *
+ * Absent/empty `steps` is the default for every surface and renders exactly
+ * as before this existed — `<WizardFormSteps>` falls back to the
+ * unconditional `<SectionForm>` rendering `SectionForm.tsx`'s 25+ other
+ * callers already use, never gating navigation.
+ */
+export interface FormStep {
+    title: string;
+    fields: string[];
+}
 /** Which input primitive renders the field, and its default row span. */
 export type FieldKind = "text" | "number" | "date" | "select" | "toggle" | "textarea" | "media" | "list";
 /**
@@ -156,6 +173,58 @@ 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>;
+/**
+ * An admin-defined field with NO presence in the owning Zod schema — part of
+ * the Universal Template System (3B item 1b). Its VALUE never becomes a
+ * typed schema property; it lands in the document's `customFieldValues`
+ * bag, validated only against this definition (type/required/maxLength),
+ * same reasoning `FieldUiMeta` already uses for everything else here: one
+ * small, closed set of control kinds, never `unknown`.
+ */
+export interface CustomFieldDef {
+    /** Key inside `customFieldValues`. Never a real schema property name. */
+    key: string;
+    label: string;
+    type: "text" | "number" | "select" | "boolean" | "date";
+    required?: boolean;
+    /** For `type: "select"`. */
+    options?: string[];
+    maxLength?: number;
+}
+/**
+ * 3B item 1b — THE canonical hide/reorder primitive, used by every
+ * subsystem (forms' `fieldOrder`, toolbars' `applyToggleVisibility`,
+ * bottom-bars' `applyBottomActionVisibility`, catalogue-cards' content
+ * blocks, search/facets' admin facets). Extracted 2026-11-04 after the
+ * SAME sort-by-position-in-fieldOrder algorithm was independently
+ * hand-written four times (Rule of Three, exceeded) — "no drift" per the
+ * owner's own instruction means this is the ONE implementation from here
+ * on; a fifth hand-inlined copy is the bug this extraction exists to rule
+ * out structurally, not just by convention.
+ *
+ * Items named in `fieldOrder` sort by their index there; items not named
+ * keep their original relative order, appended after (stable sort).
+ * `getKey` lets this work over any shape — a bare string id
+ * (`ProductCard`'s content blocks), `{id}` (`BottomAction`), `{label}`
+ * (`ListingToolbarToggle`), or `{key}` (`CustomFieldDef`).
+ */
+export declare function sortByFieldOrder<T>(items: T[], fieldOrder: string[], getKey: (item: T) => string): T[];
+/**
+ * The reorder half of the same primitive — produces the NEXT `fieldOrder`
+ * array for a caller's `setFieldOrder`/persist call, given two item keys to
+ * swap. Completes `currentOrder` against `allKeys` first (in `allKeys`'
+ * own order) before swapping, so a swap always operates on every real item
+ * — swapping within a partial list would silently drop every unlisted
+ * item's position the moment the result is persisted.
+ *
+ * Callers resolve WHICH two keys are adjacent (e.g. `build-sections.tsx`
+ * resolves field adjacency within one section); this function only knows
+ * how to produce a valid full order from a swap, the one piece every
+ * caller would otherwise reimplement.
+ */
+export declare function swapFieldOrder(currentOrder: string[], allKeys: string[], a: string, b: string): string[];
+/** The hide half of the same primitive — paired with `sortByFieldOrder` above. */
+export declare function filterByFieldVisibility<T>(items: T[], fields: Record<string, boolean>, getKey: (item: T) => string): T[];
 /**
  * Above this many options a select becomes a searchable `<PaginatedSelect>`.
  * The standing UI rule (CLAUDE.md § UI Primitive Rules): more than five options

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

@@ -362,6 +362,62 @@ export function inferFieldUiMeta(name, schema) {
     }
     return meta;
 }
+/**
+ * 3B item 1b — THE canonical hide/reorder primitive, used by every
+ * subsystem (forms' `fieldOrder`, toolbars' `applyToggleVisibility`,
+ * bottom-bars' `applyBottomActionVisibility`, catalogue-cards' content
+ * blocks, search/facets' admin facets). Extracted 2026-11-04 after the
+ * SAME sort-by-position-in-fieldOrder algorithm was independently
+ * hand-written four times (Rule of Three, exceeded) — "no drift" per the
+ * owner's own instruction means this is the ONE implementation from here
+ * on; a fifth hand-inlined copy is the bug this extraction exists to rule
+ * out structurally, not just by convention.
+ *
+ * Items named in `fieldOrder` sort by their index there; items not named
+ * keep their original relative order, appended after (stable sort).
+ * `getKey` lets this work over any shape — a bare string id
+ * (`ProductCard`'s content blocks), `{id}` (`BottomAction`), `{label}`
+ * (`ListingToolbarToggle`), or `{key}` (`CustomFieldDef`).
+ */
+export function sortByFieldOrder(items, fieldOrder, getKey) {
+    if (fieldOrder.length === 0)
+        return items;
+    const position = new Map(fieldOrder.map((key, i) => [key, i]));
+    return [...items].sort((a, b) => {
+        const pa = position.get(getKey(a)) ?? Number.MAX_SAFE_INTEGER;
+        const pb = position.get(getKey(b)) ?? Number.MAX_SAFE_INTEGER;
+        return pa - pb;
+    });
+}
+/**
+ * The reorder half of the same primitive — produces the NEXT `fieldOrder`
+ * array for a caller's `setFieldOrder`/persist call, given two item keys to
+ * swap. Completes `currentOrder` against `allKeys` first (in `allKeys`'
+ * own order) before swapping, so a swap always operates on every real item
+ * — swapping within a partial list would silently drop every unlisted
+ * item's position the moment the result is persisted.
+ *
+ * Callers resolve WHICH two keys are adjacent (e.g. `build-sections.tsx`
+ * resolves field adjacency within one section); this function only knows
+ * how to produce a valid full order from a swap, the one piece every
+ * caller would otherwise reimplement.
+ */
+export function swapFieldOrder(currentOrder, allKeys, a, b) {
+    const complete = currentOrder.length > 0
+        ? [...currentOrder, ...allKeys.filter((k) => !currentOrder.includes(k))]
+        : [...allKeys];
+    const ia = complete.indexOf(a);
+    const ib = complete.indexOf(b);
+    if (ia === -1 || ib === -1)
+        return complete;
+    const next = [...complete];
+    [next[ia], next[ib]] = [next[ib], next[ia]];
+    return next;
+}
+/** The hide half of the same primitive — paired with `sortByFieldOrder` above. */
+export function filterByFieldVisibility(items, fields, getKey) {
+    return items.filter((item) => fields[getKey(item)] !== false);
+}
 /**
  * Above this many options a select becomes a searchable `<PaginatedSelect>`.
  * The standing UI rule (CLAUDE.md § UI Primitive Rules): more than five options

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

@@ -12,5 +12,7 @@ export type { FieldUiMeta, FieldRow, FieldKind, CalculatedTier, } from "./field-
 export { ui, annotate, ROW_COLUMNS, inferFieldUiMeta, resolveFieldUiMeta, unwrapSchema, schemaEnumOptions, schemaIsOptional, objectShape, } from "./field-ui-meta";
 export type { ResolvedField, FieldRenderer, BuildSectionsOptions, } from "./build-sections";
 export { buildSectionsFromSchema, resolveFields, groupFieldsBySection, packRows, visibleValues, } from "./build-sections";
+export type { UseFieldVisibilityResult } from "./useFieldVisibility";
+export { useFieldVisibility } from "./useFieldVisibility";
 export type { TitleDescriptionGroupProps, ImageFieldGroupProps, SeoFieldGroupProps, StatusFieldGroupProps, StatusFieldGroupOption, } from "./field-groups";
 export { TitleDescriptionGroup, ImageFieldGroup, SeoFieldGroup, StatusFieldGroup, } from "./field-groups";

package/dist/features/shell/index.js

@@ -9,4 +9,5 @@ export { buildSectionsFromSchema, resolveFields, groupFieldsBySection, packRows,
 // draft can still carry a field the user can no longer see — build the
 // submitted object from this, never from the raw draft.
 visibleValues, } from "./build-sections.js";
+export { useFieldVisibility } from "./useFieldVisibility.js";
 export { TitleDescriptionGroup, ImageFieldGroup, SeoFieldGroup, StatusFieldGroup, } from "./field-groups/index.js";

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

@@ -0,0 +1,22 @@
+import { type NavSearchable } from "../../_internal/shared/features/layout/matchesNavQuery";
+/**
+ * `priority` (9-ii, overhaul brief — the Android-Settings reference: "only
+ * the important cards and toggles show up over the garbage stuff") is a
+ * TIEBREAKER ONLY — applied strictly after `score`, never instead of it, so
+ * an important-but-fuzzy match can never outrank a genuine exact label hit.
+ * Absent means `0`, which is every existing caller's current behaviour
+ * unchanged — only `TOGGLE_CATALOG`/`SETTINGS_PREVIEW` entries that
+ * explicitly set one get a real tiebreak.
+ */
+export type NavSearchGroupedItem = NavSearchable & {
+    groupTitle: string;
+    priority?: number;
+};
+/**
+ * Ranks `items` against `query`, flattened across their groups.
+ *
+ * Returns `items` unchanged, in their original order, when `query` is blank
+ * — callers rely on this to show the full set before the user has typed
+ * anything, without a separate "no query" branch of their own.
+ */
+export declare function rankNavSearchResults<T extends NavSearchGroupedItem>(items: T[], query: string): T[];

package/dist/features/shell/searchNavItems.js

@@ -0,0 +1,61 @@
+/*
+ * WHY: `CommandPalette`'s ⌘K search was plain substring on `label` +
+ *      `groupTitle` only — genuinely behind the sidebar's own "Search
+ *      navigation…" box, which already reads label+description+keywords via
+ *      `matchesNavQuery`. Typing "maintenance" in ⌘K found nothing, because
+ *      the toggle lives inside "Site Settings" and neither the label nor the
+ *      group title says "maintenance".
+ * WHAT: One thin, group-aware wrapper around `matchesNavQuery` — flattens
+ *       groups, scores, sorts — shared by the ⌘K palette and the new
+ *       dashboard-landing quick-jump search (Phase 9, overhaul brief), so
+ *       both surfaces rank identically instead of carrying two drifting
+ *       copies of "what counts as a good match."
+ *
+ * ## The group-title fallback is additive, not a replacement
+ *
+ * Before this wrapper existed, typing "maintenance" in ⌘K matched every item
+ * *in* the Maintenance group, even ones with no "maintenance" in their own
+ * label/description/keywords — because the old matcher checked
+ * `groupTitle.includes(q)` directly. Swapping straight to `matchesNavQuery`
+ * alone would regress that: an item scores via `matchesNavQuery` first, and
+ * only when that is `0` does a group-title substring match fall back to a
+ * low constant score — below every real `matchesNavQuery` tier, including
+ * `description` — so a genuine label/keyword/description hit always outranks
+ * a "this item merely lives in a matching group" hit.
+ *
+ * EXPORTS: rankNavSearchResults, type NavSearchGroupedItem
+ *
+ * @tag domain:layout
+ * @tag layer:client
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:CommandPalette,DashboardQuickJump
+ * @tag sideEffects:none
+ */
+import { matchesNavQuery } from "../../_internal/shared/features/layout/matchesNavQuery.js";
+/** Score a group-title substring match falls back to when nothing else hits. Below every `matchesNavQuery` tier (lowest is `description: 10`). */
+const GROUP_TITLE_FALLBACK_SCORE = 5;
+/**
+ * Ranks `items` against `query`, flattened across their groups.
+ *
+ * Returns `items` unchanged, in their original order, when `query` is blank
+ * — callers rely on this to show the full set before the user has typed
+ * anything, without a separate "no query" branch of their own.
+ */
+export function rankNavSearchResults(items, query) {
+    const q = query.trim();
+    if (!q)
+        return items;
+    const qLower = q.toLowerCase();
+    const scored = items
+        .map((item) => {
+        const navScore = matchesNavQuery(item, q);
+        const score = navScore > 0 ? navScore : item.groupTitle.toLowerCase().includes(qLower) ? GROUP_TITLE_FALLBACK_SCORE : 0;
+        return { item, score };
+    })
+        .filter((entry) => entry.score > 0);
+    // Array.prototype.sort is stable (ES2019+) — equal (score, priority) pairs keep their original relative order.
+    return scored
+        .sort((a, b) => b.score - a.score || (b.item.priority ?? 0) - (a.item.priority ?? 0))
+        .map((entry) => entry.item);
+}

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

@@ -0,0 +1,43 @@
+import type { CustomFieldDef, FormStep } from "./field-ui-meta";
+export interface UseFieldVisibilityResult {
+    /** The raw map — pass directly as `BuildSectionsOptions.fieldVisibility`. */
+    fields: Record<string, boolean>;
+    isVisible: (fieldName: string) => boolean;
+    setVisible: (fieldName: string, next: boolean) => void;
+    /** Field names in admin-chosen render order. Pass to `BuildSectionsOptions.fieldOrder`. */
+    fieldOrder: string[];
+    setFieldOrder: (next: string[]) => void;
+    /** Admin-defined fields with no schema presence. Pass to `BuildSectionsOptions.customFields`. */
+    customFields: CustomFieldDef[];
+    setCustomFields: (next: CustomFieldDef[]) => void;
+    /** Wizard grouping. Pass to `<WizardFormSteps steps>`. Empty = single-page, unchanged. */
+    steps: FormStep[];
+    setSteps: (next: FormStep[]) => void;
+    /** True while a debounced write is in flight. */
+    saving: boolean;
+}
+/**
+ * Admin field-visibility override (Phase 3B widget system) — the write-side
+ * counterpart to `getFieldVisibility()` (appkit `server.ts`). Same
+ * debounced-persist shape as `usePageRegion` for writes. Reads differ
+ * deliberately: `usePageRegion`'s caller is always SSR (an admin dashboard
+ * page), so it only ever needs `initialCards` server-rendered. This hook's
+ * real first consumer (`StoreCreateForm`, mounted from a fully `"use
+ * client"` page with no SSR data-fetch opportunity) has no such option, so
+ * this hook fetches on mount via `GET /api/admin/field-visibility/{id}`
+ * (open to any signed-in viewer — reading "what's hidden" is not
+ * sensitive) whenever `initial` is omitted. An SSR caller that DOES have a
+ * server-rendered value may still pass it as `initial` to skip the fetch
+ * and avoid a loading flash, same as `usePageRegion`'s own contract.
+ *
+ * `surfaceId` identifies which `fieldVisibility/{surfaceId}` document this
+ * hook reads and writes — a stable, hand-chosen id per form/display
+ * surface (e.g. `"store-create"`, `"admin-site-settings"`), same
+ * "not route-derived" rule `usePageRegion`'s own doc comment states.
+ *
+ * Consumed directly by `buildSectionsFromSchema`'s `fieldVisibility` option
+ * (`features/shell/build-sections.tsx`) for FORM fields, and by any
+ * read-only display surface that wants to hide a field row, via
+ * `isVisible(fieldName)` directly.
+ */
+export declare function useFieldVisibility(surfaceId: string, initial?: Record<string, boolean>): UseFieldVisibilityResult;