@mohasinac/appkit 4.71.0 → 4.72.0

package/dist/ui/components/dialog-shell.d.ts

@@ -0,0 +1,32 @@
+import * as React from "react";
+export interface DialogShellProps {
+    open: boolean;
+    onClose: () => void;
+    /**
+     * The dialog's accessible name, independent of whatever visible heading
+     * the caller renders inside `children`. Radix requires a `Dialog.Title`;
+     * this keeps that requirement decoupled from each caller's own visual
+     * header so no caller ends up with two titles on screen.
+     */
+    dialogLabel: string;
+    wrapperClassName: string;
+    overlayClassName: string;
+    contentClassName: string;
+    contentRef?: React.Ref<HTMLDivElement>;
+    onKeyDownCapture?: React.KeyboardEventHandler<HTMLDivElement>;
+    children: React.ReactNode;
+}
+/**
+ * Shared Radix Dialog composition for `Modal`, `ConfirmDeleteModal`, and
+ * `Button`'s internal confirmation dialog — the only three overlay surfaces
+ * that actually render anywhere in this app (Phase 3a measurement: every
+ * `<Tooltip`/`<Dropdown`/`<Menu` hit in the repo was dead or belonged to a
+ * different library). Owns focus trap, Escape, outside-click, and portal
+ * mounting so each caller's own component stops hand-rolling those.
+ *
+ * Callers keep their existing BEM classes on the wrapper/overlay/content —
+ * only who owns `role`/`aria-modal`/focus changes, not the DOM class names,
+ * so existing CSS needs only `[data-state]` animation variants added, not a
+ * rewrite.
+ */
+export declare function DialogShell({ open, onClose, dialogLabel, wrapperClassName, overlayClassName, contentClassName, contentRef, onKeyDownCapture, children, }: DialogShellProps): React.JSX.Element;

package/dist/ui/components/dialog-shell.js

@@ -0,0 +1,23 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as RadixDialog from "@radix-ui/react-dialog";
+import { OverlayContext } from "./overlay-context.js";
+/**
+ * Shared Radix Dialog composition for `Modal`, `ConfirmDeleteModal`, and
+ * `Button`'s internal confirmation dialog — the only three overlay surfaces
+ * that actually render anywhere in this app (Phase 3a measurement: every
+ * `<Tooltip`/`<Dropdown`/`<Menu` hit in the repo was dead or belonged to a
+ * different library). Owns focus trap, Escape, outside-click, and portal
+ * mounting so each caller's own component stops hand-rolling those.
+ *
+ * Callers keep their existing BEM classes on the wrapper/overlay/content —
+ * only who owns `role`/`aria-modal`/focus changes, not the DOM class names,
+ * so existing CSS needs only `[data-state]` animation variants added, not a
+ * rewrite.
+ */
+export function DialogShell({ open, onClose, dialogLabel, wrapperClassName, overlayClassName, contentClassName, contentRef, onKeyDownCapture, children, }) {
+    return (_jsx(RadixDialog.Root, { open: open, onOpenChange: (next) => {
+            if (!next)
+                onClose();
+        }, children: _jsx(RadixDialog.Portal, { children: _jsx(OverlayContext.Provider, { value: true, children: _jsxs("div", { className: wrapperClassName, children: [_jsx(RadixDialog.Overlay, { className: overlayClassName }), _jsxs(RadixDialog.Content, { ref: contentRef, className: contentClassName, "aria-describedby": undefined, onKeyDownCapture: onKeyDownCapture, children: [_jsx(RadixDialog.Title, { className: "appkit-sr-only", children: dialogLabel }), children] })] }) }) }) }));
+}

package/dist/ui/components/form-field-registry.d.ts

@@ -0,0 +1,43 @@
+import type { ReactNode } from "react";
+/**
+ * Runtime renderer registry for FormField.tsx's "image"/"media" branches.
+ *
+ * FormField.tsx is a ui/ primitive, but the image/video upload widgets it
+ * renders for those two types are a features/media concern (crop, trim,
+ * YouTube embed, etc.) -- a static import there is the edge that put
+ * react-advanced-cropper's CSS into appkit's server graph (see FormField.tsx's
+ * own header comment). This registry lets FormField call a renderer without
+ * importing from features/ at all; features/media registers itself into it.
+ *
+ * Right-sized for "2 branches, same default behavior at every call site" --
+ * a per-call-site render-prop would force every one of FormField's existing
+ * callers to start passing a slot just to keep working.
+ */
+export interface FormFieldImageRendererProps {
+    currentImage: string | undefined;
+    onUpload: (file: File) => Promise<string>;
+    onChange: (url: string) => void;
+    label: string | undefined;
+    helperText: string | undefined;
+    captureSource: "file-only" | "camera-only" | "both";
+    accept: string | undefined;
+    maxSizeMB: number | undefined;
+}
+export interface FormFieldMediaRendererProps {
+    label: string;
+    value: string;
+    onChange: (url: string) => void;
+    onUpload: (file: File) => Promise<string>;
+    disabled: boolean;
+    helperText: string | undefined;
+    captureSource: "file-only" | "camera-only" | "both";
+    captureMode: "photo" | "video" | "both";
+    accept: string | undefined;
+    maxSizeMB: number | undefined;
+}
+export type FormFieldImageRenderer = (props: FormFieldImageRendererProps) => ReactNode;
+export type FormFieldMediaRenderer = (props: FormFieldMediaRendererProps) => ReactNode;
+export declare function registerFormFieldRenderer(type: "image", renderer: FormFieldImageRenderer): void;
+export declare function registerFormFieldRenderer(type: "media", renderer: FormFieldMediaRenderer): void;
+export declare function getFormFieldRenderer(type: "image"): FormFieldImageRenderer | undefined;
+export declare function getFormFieldRenderer(type: "media"): FormFieldMediaRenderer | undefined;

package/dist/ui/components/form-field-registry.js

@@ -0,0 +1,7 @@
+const registry = new Map();
+export function registerFormFieldRenderer(type, renderer) {
+    registry.set(type, renderer);
+}
+export function getFormFieldRenderer(type) {
+    return registry.get(type);
+}

package/dist/ui/components/surface-tokens.d.ts

@@ -60,7 +60,7 @@ export declare const PADDING_MAP: {
     readonly inline: "px-[var(--appkit-space-4)] py-[var(--appkit-space-3)]";
     readonly inlineSm: "px-[var(--appkit-space-3)] py-[var(--appkit-space-2)]";
     readonly inlineLg: "px-[var(--appkit-space-6)] py-[var(--appkit-space-4)]";
-    /** Tiny pill chip — `px-1.5 py-0.5`. Used by Bundle/PrizeDraw badge labels. */
+    /** Tiny pill chip — `px-1.5 py-0.5`. Used by Bundle/Clearance badge labels. */
     readonly "chip-2xs": "px-[var(--appkit-space-1-5)] py-[var(--appkit-space-0-5)]";
     readonly "y-2xs": "py-[var(--appkit-space-1)]";
     readonly "y-xs": "py-[var(--appkit-space-2)]";
@@ -89,6 +89,8 @@ export declare const PADDING_MAP: {
     readonly "b-lg": "pb-[var(--appkit-space-6)]";
     readonly "b-xl": "pb-[var(--appkit-space-8)]";
     readonly "b-2xl": "pb-[var(--appkit-space-10)]";
+    /** Right-only — clears room for an absolutely-positioned icon cluster overlaid on a card's top-right corner. */
+    readonly "r-xl": "pr-[var(--appkit-space-14)]";
     readonly "y-2-5xl": "py-[var(--appkit-space-14)]";
     readonly "y-5xl": "py-[var(--appkit-space-20)]";
     readonly "y-6xl": "py-[var(--appkit-space-24)]";
@@ -190,7 +192,7 @@ export declare const PADDING_PRESETS: {
     readonly inline: "px-[var(--appkit-space-4)] py-[var(--appkit-space-3)]";
     readonly inlineSm: "px-[var(--appkit-space-3)] py-[var(--appkit-space-2)]";
     readonly inlineLg: "px-[var(--appkit-space-6)] py-[var(--appkit-space-4)]";
-    /** Tiny pill chip — `px-1.5 py-0.5`. Used by Bundle/PrizeDraw badge labels. */
+    /** Tiny pill chip — `px-1.5 py-0.5`. Used by Bundle/Clearance badge labels. */
     readonly "chip-2xs": "px-[var(--appkit-space-1-5)] py-[var(--appkit-space-0-5)]";
     readonly "y-2xs": "py-[var(--appkit-space-1)]";
     readonly "y-xs": "py-[var(--appkit-space-2)]";
@@ -219,6 +221,8 @@ export declare const PADDING_PRESETS: {
     readonly "b-lg": "pb-[var(--appkit-space-6)]";
     readonly "b-xl": "pb-[var(--appkit-space-8)]";
     readonly "b-2xl": "pb-[var(--appkit-space-10)]";
+    /** Right-only — clears room for an absolutely-positioned icon cluster overlaid on a card's top-right corner. */
+    readonly "r-xl": "pr-[var(--appkit-space-14)]";
     readonly "y-2-5xl": "py-[var(--appkit-space-14)]";
     readonly "y-5xl": "py-[var(--appkit-space-20)]";
     readonly "y-6xl": "py-[var(--appkit-space-24)]";

package/dist/ui/components/surface-tokens.js

@@ -73,7 +73,7 @@ export const PADDING_MAP = {
     inline: "px-[var(--appkit-space-4)] py-[var(--appkit-space-3)]",
     inlineSm: "px-[var(--appkit-space-3)] py-[var(--appkit-space-2)]",
     inlineLg: "px-[var(--appkit-space-6)] py-[var(--appkit-space-4)]",
-    /** Tiny pill chip — `px-1.5 py-0.5`. Used by Bundle/PrizeDraw badge labels. */
+    /** Tiny pill chip — `px-1.5 py-0.5`. Used by Bundle/Clearance badge labels. */
     "chip-2xs": "px-[var(--appkit-space-1-5)] py-[var(--appkit-space-0-5)]",
     // Vertical-only presets — the variant-catalogue codemod migrates raw
     // `py-N` / `py-N md:py-M` className tokens into these names.
@@ -106,6 +106,8 @@ export const PADDING_MAP = {
     "b-lg": "pb-[var(--appkit-space-6)]",
     "b-xl": "pb-[var(--appkit-space-8)]",
     "b-2xl": "pb-[var(--appkit-space-10)]",
+    /** Right-only — clears room for an absolutely-positioned icon cluster overlaid on a card's top-right corner. */
+    "r-xl": "pr-[var(--appkit-space-14)]",
     // Fill-in vertical sizes.
     "y-2-5xl": "py-[var(--appkit-space-14)]",
     "y-5xl": "py-[var(--appkit-space-20)]",

package/dist/ui/design-pack.d.ts

@@ -0,0 +1,21 @@
+export interface IDesignPack {
+    /** `--appkit-color-{token}`, e.g. `color("primary")`. Theme-overridable. */
+    color(token: string): string;
+    /** `--appkit-font-{token}`. Theme-overridable. */
+    font(token: string): string;
+    /** `--appkit-space-{token}`. Theme-overridable. */
+    spacing(token: string): string;
+    /** `--appkit-radius-{token}`. Tailwind-static, not theme-overridable. */
+    radius(token: string): string;
+    /** `--appkit-tracking-{token}`. Tailwind-static, not theme-overridable. */
+    tracking(token: string): string;
+    /** `--appkit-duration-{token}`. Tailwind-static, not theme-overridable. */
+    motion(token: string): string;
+}
+/**
+ * The one real `IDesignPack` implementation — see this file's header for
+ * why a second one isn't a design gap to fill. `element` lets a caller
+ * read tokens off a scoped subtree (e.g. inside a themed preview panel)
+ * rather than always the document root.
+ */
+export declare function cssVarDesignPack(element?: HTMLElement): IDesignPack;

package/dist/ui/design-pack.js

@@ -0,0 +1,47 @@
+/*
+ * WHY: 2A (overhaul brief) — a `IDesignPack` contract was proposed to
+ *      abstract color/font/spacing/radius/tracking/motion behind one
+ *      interface. Correctly NOT built as a multi-implementation
+ *      abstraction: colors/fonts/spacing are already Firestore-theme-driven
+ *      (`SiteSettingsThemeRecord.tokens`, injected as CSS custom properties
+ *      by `LayoutShellClient`), and radius/tracking/motion are Tailwind's
+ *      own static, compiled tokens — both paths already resolve to the
+ *      SAME mechanism (a `--appkit-*` CSS custom property), which is what
+ *      makes a single, real implementation correct rather than premature:
+ *      there is no second design-token SOURCE to abstract over, only one
+ *      access pattern worth naming.
+ * WHAT: `IDesignPack` (6 typed accessors) + `cssVarDesignPack`, the one
+ *       real implementation, reading computed `--appkit-*` custom
+ *       properties off a given element (default: the document root).
+ *
+ * EXPORTS: IDesignPack, cssVarDesignPack
+ *
+ * @tag domain:ui
+ * @tag layer:client
+ * @tag pattern:none
+ * @tag access:client-only
+ * @tag consumers:none-yet
+ * @tag sideEffects:none
+ */
+function readVar(prefix, token, element) {
+    const el = element ?? (typeof document !== "undefined" ? document.documentElement : undefined);
+    if (!el || typeof getComputedStyle !== "function")
+        return "";
+    return getComputedStyle(el).getPropertyValue(`--appkit-${prefix}-${token}`).trim();
+}
+/**
+ * The one real `IDesignPack` implementation — see this file's header for
+ * why a second one isn't a design gap to fill. `element` lets a caller
+ * read tokens off a scoped subtree (e.g. inside a themed preview panel)
+ * rather than always the document root.
+ */
+export function cssVarDesignPack(element) {
+    return {
+        color: (token) => readVar("color", token, element),
+        font: (token) => readVar("font", token, element),
+        spacing: (token) => readVar("space", token, element),
+        radius: (token) => readVar("radius", token, element),
+        tracking: (token) => readVar("tracking", token, element),
+        motion: (token) => readVar("duration", token, element),
+    };
+}

package/dist/ui/forms/FormShell.js

@@ -80,7 +80,20 @@ export function useFormShellState(schema, nav, opts) {
     const navFieldMap = nav?.fieldToSectionIndex;
     const shellCtx = useMemo(() => ({
         errors,
-        touched: Object.fromEntries(Object.keys(errors).map((k) => [k, true])),
+        /*
+         * 🛑 GATED ON `submitAttempted`, not unconditionally `true`.
+         *
+         * `validate()` above is deliberately called from mount effects (see its
+         * own comment) to keep the summary/submit-button state live without
+         * marking an attempt — but this map used to set every errored field's
+         * `touched` to `true` regardless, so `FormField`'s per-field gate
+         * (`touched != null ? touched && !!error : !!error`) saw a present,
+         * truthy `touched` entry and showed the error on first paint anyway.
+         * The key must still be PRESENT (not absent) before an attempt, or
+         * `FormField` falls through to its unconditional-show fallback — hence
+         * `submitAttempted` as the value rather than omitting the entry.
+         */
+        touched: Object.fromEntries(Object.keys(errors).map((k) => [k, submitAttempted])),
         setFieldError,
         setFieldTouched: () => { },
         clearFieldError: (name) => setFieldError(name, null),

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

@@ -0,0 +1,78 @@
+import { type FormShellContextValue } from "./FormShell";
+import type { BottomAction } from "../chrome/BottomActionsContext";
+export interface UseFormBottomActionsOptions {
+    /** Runs when the pinned primary button is pressed. */
+    onSubmit: () => void | Promise<void>;
+    /** Omit to render no Cancel button — a settings page with nowhere to go back to. */
+    onCancel?: () => void;
+    submitLabel?: string;
+    cancelLabel?: string;
+    isLoading?: boolean;
+    disabled?: boolean;
+    /** Set false to leave the bar to someone else on this route. */
+    enabled?: boolean;
+    /**
+     * Read the form state from here instead of the ambient context. `<Form>`
+     * needs it: the hook runs in `Form`'s body, which is ABOVE the provider
+     * `Form` itself renders, so the ambient lookup would find the parent's
+     * context or none at all.
+     */
+    /**
+     * Destructive action for this record, mirrored from `SectionForm`. Pushed
+     * to the FRONT of the bar so it is furthest from where the thumb rests on
+     * the primary action.
+     */
+    destructiveAction?: {
+        label: string;
+        onClick: () => void;
+        disabled?: boolean;
+    };
+    /**
+     * Further actions this form offers, spliced between the destructive one and
+     * Submit so the ordering rule survives: destructive furthest from the thumb,
+     * submit under it.
+     *
+     * Exists because the bar was hard-capped at three. `/admin/users` needs five
+     * (three forms plus soft-ban and hard-ban), so its extra actions had nowhere
+     * to go and stayed as an inline row the pinned bar then competed with.
+     */
+    extraActions?: BottomAction[];
+    ctx?: FormShellContextValue;
+}
+/**
+ * Pin a form's Save/Cancel row to the bottom of a phone screen, and turn its
+ * validation errors into a pull-up sheet above it.
+ *
+ * ## Nothing here is new chrome
+ *
+ * This is `useBottomActions` with a form-shaped payload. The cart's bottom bar
+ * — "Total ₹777 · Details ⌃" over a pinned CTA — is 100% that primitive's
+ * output already, so the sheet mechanics, the collapse rule
+ * (`grid-rows-[1fr] ↔ [0fr]`, background on the innermost div),
+ * click-outside-to-close, the `ResizeObserver` that publishes
+ * `--bottom-chrome-height`, and all three bottom-edge offsets come for free.
+ * Re-deriving any of that would be a second, worse copy.
+ *
+ * ## Three details that will bite anyone editing this
+ *
+ * 1. **The label must encode the count.** `useBottomActions` re-publishes
+ *    `infoPanel` only when `hasInfoPanel`, `infoLabel` or `secondaryLabel`
+ *    change — a ReactNode is a fresh object every render and cannot be a
+ *    dependency without looping. "Fix 6 issues" → "Fix 5 issues" is
+ *    therefore what pushes the updated list through. A generic label like
+ *    "Errors" would freeze the sheet's contents at whatever they were the
+ *    first time it opened.
+ *
+ * 2. **The panel is rendered outside the form's provider.** `BottomActions`
+ *    lives in the layout shell, so the detached node cannot reach
+ *    `FormShellContext` by itself — hence `<FormErrorList ctx={ctx}>` with
+ *    the context passed explicitly.
+ *
+ * 3. **Suppressed inside a Modal or SideDrawer.** An overlay owns its own
+ *    footer, and a viewport-fixed bar would render *behind* the backdrop,
+ *    below the dialog it belongs to. `useIsInsideOverlay()` is how the
+ *    overlay tells us, because neither portal leaves a detectable trace in
+ *    the DOM at the form's position.
+ */
+export declare function useFormBottomActions({ onSubmit, onCancel, submitLabel, cancelLabel, isLoading, disabled, enabled, destructiveAction, extraActions, ctx: ctxProp, }: UseFormBottomActionsOptions): void;
+export default useFormBottomActions;

package/dist/ui/forms/useFormBottomActions.js

@@ -0,0 +1,128 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useContext, useMemo } from "react";
+import { FormShellContext } from "./FormShell.js";
+import { FormErrorList } from "./FormErrorList.js";
+import { Div } from "../components/Div.js";
+import { useIsInsideOverlay } from "../components/overlay-context.js";
+import { useBottomActions } from "../chrome/useBottomActions.js";
+/**
+ * Pin a form's Save/Cancel row to the bottom of a phone screen, and turn its
+ * validation errors into a pull-up sheet above it.
+ *
+ * ## Nothing here is new chrome
+ *
+ * This is `useBottomActions` with a form-shaped payload. The cart's bottom bar
+ * — "Total ₹777 · Details ⌃" over a pinned CTA — is 100% that primitive's
+ * output already, so the sheet mechanics, the collapse rule
+ * (`grid-rows-[1fr] ↔ [0fr]`, background on the innermost div),
+ * click-outside-to-close, the `ResizeObserver` that publishes
+ * `--bottom-chrome-height`, and all three bottom-edge offsets come for free.
+ * Re-deriving any of that would be a second, worse copy.
+ *
+ * ## Three details that will bite anyone editing this
+ *
+ * 1. **The label must encode the count.** `useBottomActions` re-publishes
+ *    `infoPanel` only when `hasInfoPanel`, `infoLabel` or `secondaryLabel`
+ *    change — a ReactNode is a fresh object every render and cannot be a
+ *    dependency without looping. "Fix 6 issues" → "Fix 5 issues" is
+ *    therefore what pushes the updated list through. A generic label like
+ *    "Errors" would freeze the sheet's contents at whatever they were the
+ *    first time it opened.
+ *
+ * 2. **The panel is rendered outside the form's provider.** `BottomActions`
+ *    lives in the layout shell, so the detached node cannot reach
+ *    `FormShellContext` by itself — hence `<FormErrorList ctx={ctx}>` with
+ *    the context passed explicitly.
+ *
+ * 3. **Suppressed inside a Modal or SideDrawer.** An overlay owns its own
+ *    footer, and a viewport-fixed bar would render *behind* the backdrop,
+ *    below the dialog it belongs to. `useIsInsideOverlay()` is how the
+ *    overlay tells us, because neither portal leaves a detectable trace in
+ *    the DOM at the form's position.
+ */
+export function useFormBottomActions({ onSubmit, onCancel, submitLabel = "Save", cancelLabel = "Cancel", isLoading = false, disabled = false, enabled = true, destructiveAction, extraActions, ctx: ctxProp, }) {
+    const ambient = useContext(FormShellContext);
+    const ctx = ctxProp ?? ambient;
+    const insideOverlay = useIsInsideOverlay();
+    const active = enabled && !insideOverlay && ctx != null;
+    const errorCount = ctx ? Object.keys(ctx.errors).length : 0;
+    const showErrors = !!ctx?.submitAttempted && errorCount > 0;
+    const actions = useMemo(() => {
+        if (!active)
+            return [];
+        const list = [];
+        /*
+         * Destructive FIRST, so it is furthest from the thumb's resting position
+         * on the primary action, which BottomActions renders last.
+         *
+         * None of these set a width. `grow` no longer exists on BottomAction —
+         * ActionRow sizes every action from its own label and shares only the
+         * leftover, so "Cancel" and "Save" each get a width that fits their text
+         * instead of Cancel collapsing to a 44px square while Save took the rest.
+         */
+        if (destructiveAction) {
+            list.push({
+                id: "form-destructive",
+                label: destructiveAction.label,
+                variant: "danger",
+                onClick: destructiveAction.onClick,
+                disabled: destructiveAction.disabled || isLoading,
+            });
+        }
+        if (onCancel) {
+            list.push({
+                id: "form-cancel",
+                label: cancelLabel,
+                variant: "outline",
+                onClick: onCancel,
+                disabled: isLoading,
+            });
+        }
+        if (extraActions?.length)
+            list.push(...extraActions);
+        // Submit LAST: BottomActions treats the final action as the primary and
+        // gives it its own full-width line once the bar holds three or more.
+        list.push({
+            id: "form-submit",
+            label: submitLabel,
+            variant: "primary",
+            loading: isLoading,
+            disabled: disabled || isLoading,
+            onClick: () => void onSubmit(),
+        });
+        return list;
+    }, [active, onCancel, cancelLabel, submitLabel, isLoading, disabled, onSubmit, destructiveAction, extraActions]);
+    useBottomActions({
+        actions,
+        // Encodes the count on purpose — see (1) in the header.
+        infoLabel: showErrors
+            ? `Fix ${errorCount} ${errorCount === 1 ? "issue" : "issues"}`
+            : undefined,
+        /*
+         * 🛑 The alert region lives HERE, not in `FormErrorList`.
+         *
+         * Without it a failed submit on a phone announced nothing at all: the
+         * list has no role, `InfoPanel` has no role, and the only signal was the
+         * disclosure button's text changing — which a screen reader does not read
+         * out unprompted. This is the whole error surface on mobile, since
+         * `useBottomActions` defaults to `desktop: "hidden"`.
+         *
+         * It cannot go on `FormErrorList` itself: the list's other consumer is
+         * `<FormErrorSummary>`, whose wrapper is already `role="alert"`, and
+         * nesting one alert region inside another makes the announcement
+         * ambiguous and duplicated.
+         *
+         * `aria-live="polite"` rather than `role="alert"`'s implicit assertive —
+         * the user has just pressed Save and is expecting a response, so there is
+         * nothing to interrupt. Same choice `FormErrorSummary` makes.
+         */
+        infoPanel: showErrors && ctx ? (_jsx(Div, { role: "alert", "aria-live": "polite", children: _jsx(FormErrorList, { ctx: ctx }) })) : undefined,
+        // Bumped by every submit attempt, so a second failed Save re-opens a
+        // sheet the user collapsed — while an ordinary re-render does not.
+        infoOpenSignal: showErrors ? ctx?.submitAttemptCount : undefined,
+        // No claim at all when inactive — see UseBottomActionsOptions.enabled.
+        enabled: active,
+    });
+}
+export default useFormBottomActions;

package/dist/ui/icons/icon-registry.d.ts

@@ -49,7 +49,12 @@ export declare const ICONS: {
     readonly filter: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly settings: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly expand: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly "arrow-up": import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly "arrow-down": import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly user: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    /** A group of people — "join the community", never a single-user context (use `user`). */
+    readonly users: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly phone: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly notification: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly compare: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly help: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
@@ -59,7 +64,7 @@ export declare const ICONS: {
     readonly themeDark: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly deals: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly preOrder: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
-    readonly prizeDraw: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly clearance: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly digitalCode: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly art: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly stickers: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;

package/dist/ui/icons/icon-registry.js

@@ -39,7 +39,7 @@
  * @tag consumers:Button,RowActionMenu,BulkActionBar,action-registry
  * @tag sideEffects:none
  */
-import { Archive, ArrowLeft, Ban, Coins, Bell, Check, CheckCircle, ChevronDown, Copy, Download, Edit, Eye, EyeOff, FileDown, Filter, Flag, Gavel, HelpCircle, Heart, Link as LinkIcon, Lock, Mail, Menu, MessageSquare, Moon, Package, Pause, Play, Plus, RefreshCw, Reply, RotateCcw, Save, Search, Send, Settings, Share2, ShieldCheck, ShoppingCart, Star, Sun, Scale, Tag, Trash2, TrendingUp, Truck, Upload, User, X, XCircle, CalendarClock, Gift, KeyRound, Palette, Sticker, Puzzle, PawPrint, } from "lucide-react";
+import { Archive, ArrowDown, ArrowLeft, ArrowUp, Ban, Coins, Bell, Check, CheckCircle, ChevronDown, Copy, Download, Edit, Eye, EyeOff, FileDown, Filter, Flag, Gavel, HelpCircle, Heart, Link as LinkIcon, Lock, Mail, Menu, MessageSquare, Moon, Package, Pause, Phone, Play, Plus, RefreshCw, Reply, RotateCcw, Save, Search, Send, Settings, Share2, ShieldCheck, ShoppingCart, Star, Sun, Scale, Tag, Trash2, TrendingUp, Truck, Upload, User, Users, X, XCircle, CalendarClock, Gift, KeyRound, Palette, Sticker, Puzzle, PawPrint, } from "lucide-react";
 /**
  * Semantic name → component.
  *
@@ -97,7 +97,16 @@ export const ICONS = {
     filter: Filter,
     settings: Settings,
     expand: ChevronDown,
+    // Reorder — a discrete up/down BUTTON pair, never drag-and-drop
+    // (`NavPermissionsManager.tsx`'s own ▲/▼ precedent, and the project-wide
+    // "no drag-and-drop" constraint). Added for `build-sections.tsx`'s
+    // `onMoveField` edit-mode controls, 2026-11-04.
+    "arrow-up": ArrowUp,
+    "arrow-down": ArrowDown,
     user: User,
+    /** A group of people — "join the community", never a single-user context (use `user`). */
+    users: Users,
+    phone: Phone,
     // Header chrome. Added 2026-08-27 when TitleBarLayout stopped hand-inlining
     // ten raw <svg> elements — a raw <svg> carries no `shrink-0`, so inside a
     // padded flex control it silently shrank rather than rendering at its stated
@@ -115,13 +124,13 @@ export const ICONS = {
      * `ListingTypePlugin.iconKey` so a type chip can carry a leading visual.
      *
      * 🛑 Four of the nine reuse an existing verb rather than minting a new icon:
-     * `standard` is `order` (Package), `auction` is `bid` (Gavel), `classified`
+     * `standard` is `order` (Package), `collector drop` is `bid` (Gavel), `classified`
      * is `deals` (Tag), `live` is the only animal glyph here. This registry's
      * header is explicit that it is deliberately small and not a re-export of
      * lucide — so a type earns a new entry only when nothing already means it.
      */
     preOrder: CalendarClock,
-    prizeDraw: Gift,
+    clearance: Gift,
     digitalCode: KeyRound,
     art: Palette,
     stickers: Sticker,

package/dist/ui/rich-text/RichText.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useMemo } from "react";
+import { useEffect, useMemo, useState } from "react";
 import { Div } from "../components/Div.js";
 import { normalizeRichTextHtml } from "../../utils/string.formatter.js";
 import { useSiteSettings } from "../../core/hooks/useSiteSettings.js";
@@ -234,19 +234,46 @@ export function RichText({ html, className = "", proseClass = "prose max-w-none
      */
     const { data: settings } = useSiteSettings();
     const closedPrefixes = settings?.hiddenSurfacePrefixes ?? [];
-    const safe = useMemo(() => {
-        const sanitized = unwrapClosedLinks(sanitiseHtml(normalizeRichTextHtml(html)), closedPrefixes);
-        if (!highlightCode || typeof document === "undefined")
-            return sanitized;
+    /*
+     * Identical between server and client's FIRST render — only sanitising,
+     * which (per `sanitiseHtml`'s own contract) is server-safe.
+     */
+    const baseSafe = useMemo(() => sanitiseHtml(normalizeRichTextHtml(html)), [html]);
+    /*
+     * 🛑 `mounted`-deferred, NOT computed inline above — found 2026-11-02 via
+     * a real, reproducible hydration mismatch (a FAQ answer's link to
+     * `/tools/authenticity` present in the server HTML, stripped client-side,
+     * the instant `useSiteSettings()` resolved `hiddenSurfacePrefixes`).
+     * `unwrapClosedLinks` and the syntax-highlighting step both use real DOM
+     * APIs (`document.createElement`), which only work client-side — so
+     * computing them inline makes the server render `baseSafe` unmodified
+     * while the client's very first paint (before this effect has even run)
+     * already has `document` and renders the TRANSFORMED html, which is
+     * exactly what hydration compares and rejects. Deferring both to a
+     * `useEffect` makes the first client render match the server (closed-
+     * surface links briefly visible, code briefly unhighlighted), then
+     * applies both transforms in one client-only re-render right after mount.
+     */
+    const [safe, setSafe] = useState(baseSafe);
+    useEffect(() => {
+        const unwrapped = unwrapClosedLinks(baseSafe, closedPrefixes);
+        if (!highlightCode || typeof document === "undefined") {
+            setSafe(unwrapped);
+            return;
+        }
         const container = document.createElement("div");
-        container.innerHTML = sanitized;
+        container.innerHTML = unwrapped;
         container.querySelectorAll("pre > code").forEach((codeEl) => {
             const langClass = Array.from(codeEl.classList).find((c) => c.startsWith("language-"));
             const lang = langClass ? langClass.replace("language-", "") : "plaintext";
             codeEl.innerHTML = highlightCode(codeEl.textContent ?? "", lang);
         });
-        return container.innerHTML;
-    }, [html, highlightCode]);
+        setSafe(container.innerHTML);
+        // `closedPrefixes` is `settings?.hiddenSurfacePrefixes ?? []` — a FRESH
+        // array reference every render whenever settings is still loading, so
+        // depending on the array itself would re-run this effect every render
+        // until the query settles. `.join(",")` compares CONTENT, not identity.
+    }, [baseSafe, closedPrefixes.join(","), highlightCode]);
     const ref = (el) => {
         if (el && copyableCode) {
             attachCopyButtons(el);

package/dist/ui/types/image-crop.d.ts

@@ -0,0 +1,8 @@
+export interface ImageCropData {
+    url: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    zoom: number;
+}

package/dist/ui/types/quick-field.d.ts

@@ -0,0 +1,33 @@
+import type { FormFieldValue } from "../../schemas/types";
+/**
+ * `"image"` added Phase 3B (2026-11-03) for the widget system's `form`
+ * `CardElement` kind, which would need to express a real short
+ * create-listing form (`QuickProductForm`'s own 5-field set includes a
+ * required image) — groundwork only, currently UNUSED by any real
+ * `QuickFieldDef[]` array or any renderer.
+ *
+ * 🛑 No renderer handles it yet, anywhere. `QuickFormDrawer.tsx`'s own
+ * field-render loop does NOT handle this value (no upload plumbing, no
+ * existing call site needs one). `DashboardCardRenderer.tsx`'s own
+ * `CardElement.kind === "form"` branch now has a real, plural
+ * `FORM_WIDGET_REGISTRY` (`quick-add-faq`, `quick-open-support-ticket`,
+ * 2026-11-05) — neither entry needs an image field, so this value is still
+ * unused there, not because a registry couldn't support it. If a real
+ * inline-form field ever needs an upload, it should reuse `FormField`'s own
+ * `type="image"` + `onUpload` contract, the same one `QuickProductForm.tsx`
+ * already uses.
+ */
+export type QuickFieldType = "text" | "number" | "select" | "toggle" | "date" | "textarea" | "email" | "url" | "image";
+export interface QuickFieldDef {
+    name: string;
+    label: string;
+    type: QuickFieldType;
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    required?: boolean;
+    placeholder?: string;
+    helperText?: string;
+    defaultValue?: FormFieldValue;
+}