@mohasinac/appkit 4.10.0 → 4.11.0

package/dist/ui/components/Form.d.ts

@@ -1,7 +1,7 @@
 import React from "react";
 import type { ZodTypeAny } from "zod";
 import { type SurfaceProps } from "./surface-tokens";
-import { type UseFormShellStateResult } from "../forms/FormShell";
+import { type FormShellContextValue, type UseFormShellStateResult } from "../forms/FormShell";
 export type FormSpacing = "none" | "xs" | "sm" | "md" | "lg" | "xl";
 export interface FormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement>, "children">, SurfaceProps {
     /**
@@ -19,13 +19,22 @@ export interface FormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement
      * boilerplate per callsite.
      */
     schema?: ZodTypeAny;
+    /**
+     * Use an externally-computed `FormShellContextValue` (e.g. from a parent's
+     * own `useFormShellState(schema)` call) instead of `<Form>` creating its
+     * own. Needed when other elements outside this `<form>` — a submit button
+     * in a separate sidebar, associated via the HTML `form` attribute — must
+     * share the exact same validation state; otherwise `<Form>`'s own internal
+     * provider would shadow the parent's for everything rendered as `children`.
+     */
+    shellCtx?: FormShellContextValue;
     /** Cross-axis alignment of flex/grid children. Replaces raw `items-*` className. */
     align?: "start" | "center" | "end" | "stretch";
     /** Gap between children — use instead of raw `gap-*` className. */
     gap?: GapToken;
 }
 export type GapToken = "none" | "xs" | "sm" | "md" | "lg" | "xl";
-export declare function Form({ children, spacing, schema, align, gap, surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, className, ...props }: FormProps): React.JSX.Element;
+export declare function Form({ children, spacing, schema, shellCtx: shellCtxProp, align, gap, surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, className, ...props }: FormProps): React.JSX.Element;
 export interface FormGroupProps {
     children: React.ReactNode;
     columns?: 1 | 2 | 3 | 4;

package/dist/ui/components/Form.js

@@ -43,12 +43,13 @@ const FORM_ALIGN_MAP = {
     end: "items-end",
     stretch: "items-stretch",
 };
-export function Form({ children, spacing, schema, align, gap, surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, className = "", ...props }) {
+export function Form({ children, spacing, schema, shellCtx: shellCtxProp, align, gap, surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, className = "", ...props }) {
     const helpers = useFormShellState(schema);
+    const effectiveCtx = shellCtxProp ?? helpers.shellCtx;
     const content = typeof children === "function"
-        ? children(helpers)
+        ? children({ ...helpers, shellCtx: effectiveCtx })
         : children;
-    return (_jsx(FormShellContext.Provider, { value: helpers.shellCtx, children: _jsx("form", { className: [
+    return (_jsx(FormShellContext.Provider, { value: effectiveCtx, children: _jsx("form", { className: [
                 "appkit-form",
                 spacing ? FORM_SPACING_MAP[spacing] : "",
                 align ? FORM_ALIGN_MAP[align] : "",

package/dist/ui/components/FormField.d.ts

@@ -8,7 +8,9 @@ export interface FormFieldProps {
     value?: string;
     onChange?: (value: string) => void;
     onBlur?: () => void;
+    /** Override error — falls back to FormShell context error for this field */
     error?: string;
+    /** Override touched — falls back to FormShell context touched state for this field */
     touched?: boolean;
     placeholder?: string;
     required?: boolean;
@@ -24,5 +26,5 @@ export interface FormFieldProps {
     accept?: string;
     maxSizeMB?: number;
 }
-export declare function FormField({ label, name, card, type, value, onChange, onBlur, error, touched, placeholder, required, disabled, autoComplete, rows, hint, helpText, options, onUpload, captureSource, captureMode, accept, maxSizeMB, }: FormFieldProps): React.JSX.Element;
+export declare function FormField({ label, name, card, type, value, onChange, onBlur, error: errorProp, touched: touchedProp, placeholder, required, disabled, autoComplete, rows, hint, helpText, options, onUpload, captureSource, captureMode, accept, maxSizeMB, }: FormFieldProps): React.JSX.Element;
 export default FormField;

package/dist/ui/components/FormField.js

@@ -1,13 +1,22 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useContext } from "react";
 import { Input } from "./Input";
 import { Select } from "./Select";
 import { Textarea } from "./Textarea";
 import { Label, Text, Span } from "./Typography";
 import { ImageUpload, MediaUploadField } from "../../features/media";
+import { FormShellContext } from "../forms/FormShell";
 const CARD_CLASS = "appkit-form-field appkit-form-field--card";
 const BASE_CLASS = "appkit-form-field";
-export function FormField({ label, name, card = false, type = "text", value = "", onChange, onBlur, error, touched, placeholder, required = false, disabled = false, autoComplete, rows, hint, helpText, options = [], onUpload, captureSource, captureMode, accept, maxSizeMB, }) {
+export function FormField({ label, name, card = false, type = "text", value = "", onChange, onBlur, error: errorProp, touched: touchedProp, placeholder, required = false, disabled = false, autoComplete, rows, hint, helpText, options = [], onUpload, captureSource, captureMode, accept, maxSizeMB, }) {
+    // Falls back to FormShellContext (the same context FieldInput/FieldSelect
+    // read) whenever the caller doesn't pass an explicit error/touched prop —
+    // an explicit prop always wins, preserving back-compat for the handful of
+    // call sites that already manage their own error state manually.
+    const ctx = useContext(FormShellContext);
+    const error = errorProp ?? ctx?.errors[name];
+    const touched = touchedProp ?? ctx?.touched[name];
     const showError = error
         ? touched != null
             ? touched && !!error
@@ -16,12 +25,21 @@ export function FormField({ label, name, card = false, type = "text", value = ""
     const inputId = `field-${name}`;
     const errorId = `${inputId}-error`;
     const describedBy = showError ? errorId : undefined;
+    function handleFieldChange(newValue) {
+        onChange?.(newValue);
+        if (showError)
+            ctx?.clearFieldError(name);
+    }
+    function handleFieldBlur() {
+        ctx?.setFieldTouched(name);
+        onBlur?.();
+    }
     if (type === "image" && onUpload) {
-        return (_jsxs("div", { className: card ? CARD_CLASS : BASE_CLASS, "data-section": "formfield-div-505", children: [_jsx("div", { "aria-disabled": disabled || undefined, className: disabled ? "pointer-events-none opacity-60" : undefined, children: _jsx(ImageUpload, { currentImage: value || undefined, onUpload: onUpload, onChange: (url) => onChange?.(url), label: label ? `${label}${required ? " *" : ""}` : undefined, helperText: hint ?? helpText, captureSource: captureSource ?? "file-only", accept: accept, maxSizeMB: maxSizeMB }) }), showError ? (_jsx(Text, { id: errorId, size: "sm", variant: "error", className: "appkit-form-field__error", role: "alert", children: error })) : null] }));
+        return (_jsxs("div", { className: card ? CARD_CLASS : BASE_CLASS, "data-section": "formfield-div-505", children: [_jsx("div", { "aria-disabled": disabled || undefined, className: disabled ? "pointer-events-none opacity-60" : undefined, children: _jsx(ImageUpload, { currentImage: value || undefined, onUpload: onUpload, onChange: (url) => handleFieldChange(url), label: label ? `${label}${required ? " *" : ""}` : undefined, helperText: hint ?? helpText, captureSource: captureSource ?? "file-only", accept: accept, maxSizeMB: maxSizeMB }) }), showError ? (_jsx(Text, { id: errorId, size: "sm", variant: "error", className: "appkit-form-field__error", role: "alert", children: error })) : null] }));
     }
     if (type === "media" && onUpload) {
-        return (_jsxs("div", { className: card ? CARD_CLASS : BASE_CLASS, "data-section": "formfield-div-506", children: [_jsx(MediaUploadField, { label: `${label || name}${required ? " *" : ""}`, value: value, onChange: (url) => onChange?.(url), onUpload: onUpload, disabled: disabled, helperText: hint ?? helpText, captureSource: captureSource ?? "file-only", captureMode: captureMode ?? "both", accept: accept, maxSizeMB: maxSizeMB }), showError ? (_jsx(Text, { id: errorId, size: "sm", variant: "error", className: "appkit-form-field__error", role: "alert", children: error })) : null] }));
+        return (_jsxs("div", { className: card ? CARD_CLASS : BASE_CLASS, "data-section": "formfield-div-506", children: [_jsx(MediaUploadField, { label: `${label || name}${required ? " *" : ""}`, value: value, onChange: (url) => handleFieldChange(url), onUpload: onUpload, disabled: disabled, helperText: hint ?? helpText, captureSource: captureSource ?? "file-only", captureMode: captureMode ?? "both", accept: accept, maxSizeMB: maxSizeMB }), showError ? (_jsx(Text, { id: errorId, size: "sm", variant: "error", className: "appkit-form-field__error", role: "alert", children: error })) : null] }));
     }
-    return (_jsxs("div", { className: card ? CARD_CLASS : BASE_CLASS, "data-section": "formfield-div-507", children: [label ? (_jsxs(Label, { htmlFor: inputId, className: "appkit-form-field__label", children: [label, required ? (_jsx(Span, { className: "appkit-form-field__required", children: "*" })) : null] })) : null, type === "select" ? (_jsx(Select, { id: inputId, name: name, value: value, onChange: (event) => onChange?.(event.target.value), onBlur: onBlur, disabled: disabled, options: options, "aria-required": required || undefined, "aria-invalid": showError || undefined, "aria-describedby": describedBy })) : type === "textarea" ? (_jsx(Textarea, { id: inputId, name: name, value: value, onChange: (event) => onChange?.(event.target.value), onBlur: onBlur, placeholder: placeholder, disabled: disabled, rows: rows, "aria-required": required || undefined, "aria-invalid": showError || undefined, "aria-describedby": describedBy })) : (_jsx(Input, { id: inputId, name: name, type: type, value: value, onChange: (event) => onChange?.(event.target.value), onBlur: onBlur, placeholder: placeholder, disabled: disabled, autoComplete: autoComplete, "aria-required": required || undefined, "aria-invalid": showError || undefined, "aria-describedby": describedBy })), !showError && (hint || helpText) ? (_jsx(Text, { size: "sm", variant: "secondary", className: "appkit-form-field__hint", children: hint ?? helpText })) : null, showError ? (_jsx(Text, { id: errorId, size: "sm", variant: "error", className: "appkit-form-field__error", role: "alert", children: error })) : null] }));
+    return (_jsxs("div", { className: card ? CARD_CLASS : BASE_CLASS, "data-section": "formfield-div-507", children: [label ? (_jsxs(Label, { htmlFor: inputId, className: "appkit-form-field__label", children: [label, required ? (_jsx(Span, { className: "appkit-form-field__required", children: "*" })) : null] })) : null, type === "select" ? (_jsx(Select, { id: inputId, name: name, value: value, onChange: (event) => handleFieldChange(event.target.value), onBlur: handleFieldBlur, disabled: disabled, options: options, "aria-required": required || undefined, "aria-invalid": showError || undefined, "aria-describedby": describedBy })) : type === "textarea" ? (_jsx(Textarea, { id: inputId, name: name, value: value, onChange: (event) => handleFieldChange(event.target.value), onBlur: handleFieldBlur, placeholder: placeholder, disabled: disabled, rows: rows, "aria-required": required || undefined, "aria-invalid": showError || undefined, "aria-describedby": describedBy })) : (_jsx(Input, { id: inputId, name: name, type: type, value: value, onChange: (event) => handleFieldChange(event.target.value), onBlur: handleFieldBlur, placeholder: placeholder, disabled: disabled, autoComplete: autoComplete, "aria-required": required || undefined, "aria-invalid": showError || undefined, "aria-describedby": describedBy })), !showError && (hint || helpText) ? (_jsx(Text, { size: "sm", variant: "secondary", className: "appkit-form-field__hint", children: hint ?? helpText })) : null, showError ? (_jsx(Text, { id: errorId, size: "sm", variant: "error", className: "appkit-form-field__error", role: "alert", children: error })) : null] }));
 }
 export default FormField;

package/dist/ui/components/ListingLayout.d.ts

@@ -59,7 +59,6 @@ export interface ListingLayoutProps {
     /** Count of filter changes staged but not yet committed. Shows in Apply button. */
     filterPendingCount?: number;
     className?: string;
-    loading?: boolean;
     errorSlot?: ReactNode;
     labels?: ListingLayoutLabels;
     /** Portal context — sets `isDashboard` default (admin/seller=true, user/public=false). */
@@ -69,4 +68,4 @@ export interface ListingLayoutProps {
     /** When provided, the entire layout is replaced with this view (detail/edit mode). */
     detailView?: ReactNode;
 }
-export declare function ListingLayout({ headerSlot, statusTabsSlot, filterContent, filterActiveCount, onFilterApply, onFilterClear, filterTitle, activeFiltersSlot, resultCountSlot, searchSlot, sortSlot, viewToggleSlot, actionsSlot, selectedCount, onClearSelection, bulkActionItems, toolbarPaginationSlot, paginationSlot, children, isDashboard, defaultSidebarOpen, filterPendingCount, className, loading: _loading, errorSlot, labels, portal, overlays, detailView, }: ListingLayoutProps): import("react").JSX.Element;
+export declare function ListingLayout({ headerSlot, statusTabsSlot, filterContent, filterActiveCount, onFilterApply, onFilterClear, filterTitle, activeFiltersSlot, resultCountSlot, searchSlot, sortSlot, viewToggleSlot, actionsSlot, selectedCount, onClearSelection, bulkActionItems, toolbarPaginationSlot, paginationSlot, children, isDashboard, defaultSidebarOpen, filterPendingCount, className, errorSlot, labels, portal, overlays, detailView, }: ListingLayoutProps): import("react").JSX.Element;

package/dist/ui/components/ListingLayout.js

@@ -35,7 +35,7 @@ const DEFAULT_LABELS = {
     hideFilters: "Hide filters",
     filterActiveCount: (count) => `${count} active`,
 };
-export function ListingLayout({ headerSlot, statusTabsSlot, filterContent, filterActiveCount = 0, onFilterApply, onFilterClear, filterTitle, activeFiltersSlot, resultCountSlot, searchSlot, sortSlot, viewToggleSlot, actionsSlot, selectedCount = 0, onClearSelection, bulkActionItems, toolbarPaginationSlot, paginationSlot, children, isDashboard, defaultSidebarOpen = false, filterPendingCount, className = "", loading: _loading = false, errorSlot, labels, portal, overlays, detailView, }) {
+export function ListingLayout({ headerSlot, statusTabsSlot, filterContent, filterActiveCount = 0, onFilterApply, onFilterClear, filterTitle, activeFiltersSlot, resultCountSlot, searchSlot, sortSlot, viewToggleSlot, actionsSlot, selectedCount = 0, onClearSelection, bulkActionItems, toolbarPaginationSlot, paginationSlot, children, isDashboard, defaultSidebarOpen = false, filterPendingCount, className = "", errorSlot, labels, portal, overlays, detailView, }) {
     // useState must run unconditionally on every render — these were
     // previously declared after the detail-view early return below, which
     // skipped both hook calls whenever `detailView` was passed, violating the

package/dist/ui/components/RecordDetailModal.d.ts

@@ -0,0 +1,68 @@
+/**
+ * RecordDetailModal — the shared "open one listing row and actually read it"
+ * surface.
+ *
+ * Built 2026-08-21 when `audit-listing-detail-affordance` found 16 of 70
+ * dashboard listing views were dead ends: rows the user could see but never
+ * open. Two distinct failure shapes, both fixed by this one primitive:
+ *
+ *  1. Data fetched then discarded — AdminCartsView/AdminWishlistsView/
+ *     AdminHistoryView all compute `items.length` for the row subtitle and
+ *     throw the `items[]` array itself away, with no surface to show it
+ *     (CLAUDE.md Recurrent Root Cause #52).
+ *  2. Acting blind — AdminCatalogueApprovalsView offers Approve/Reject, and
+ *     AdminTesterFeedbackListView offers "Confirm bug", on records whose
+ *     content (photos, description, the tester's comment/screenshot) was
+ *     never rendered anywhere.
+ *
+ * Sixteen bespoke modals would have tripped the Duplication Decision
+ * Framework's Rule of Three immediately, so this is deliberately one
+ * primitive with three optional content slots — `fields` (definition rows),
+ * `items` (a thumbnail list, the Root Cause #52 fix), and `metadata` (a raw
+ * JSON payload dump) — rather than a per-feature component each time.
+ *
+ * Consumers pass plain data, not JSX, so a listing view's detail wiring stays
+ * the ~20-line "map the raw row into fields/items" shape at every call site.
+ */
+import type { ReactNode } from "react";
+import type { JsonValue } from "../../schemas/types";
+export interface RecordDetailField {
+    label: string;
+    /** Rendered as-is when a node; plain strings/numbers get default styling. */
+    value: ReactNode;
+}
+export interface RecordDetailItem {
+    /** Thumbnail URL — falls back to MediaImage's placeholder when absent. */
+    image?: string;
+    title: string;
+    subtitle?: string;
+    /** Right-aligned trailing text (price, quantity, timestamp). */
+    trailing?: string;
+    /** When set, the title becomes a link to this record's own detail page. */
+    href?: string;
+}
+export interface RecordDetailBadge {
+    label: string;
+    variant?: "default" | "success" | "warning" | "danger" | "info" | "secondary";
+}
+export interface RecordDetailModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    title: string;
+    /** Small status chips under the title (status, read-state, role, etc). */
+    badges?: RecordDetailBadge[];
+    /** Free-text lead paragraph — a comment body, description, or message. */
+    description?: string;
+    /** Definition rows: the record's scalar fields. */
+    fields?: RecordDetailField[];
+    /** A nested collection on the record (cart items, wishlist entries, …). */
+    items?: {
+        heading: string;
+        entries: RecordDetailItem[];
+    };
+    /** Raw payload dump for records that carry an open-ended object. */
+    metadata?: Record<string, JsonValue>;
+    /** Action buttons rendered at the bottom (approve/reject/etc). */
+    footer?: ReactNode;
+}
+export declare function RecordDetailModal({ isOpen, onClose, title, badges, description, fields, items, metadata, footer, }: RecordDetailModalProps): import("react").JSX.Element;

package/dist/ui/components/RecordDetailModal.js

@@ -0,0 +1,8 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Anchor, Badge, Code, Div, Modal, Row, Stack, Text } from "../index";
+import { MediaImage } from "../../features/media/MediaImage";
+export function RecordDetailModal({ isOpen, onClose, title, badges, description, fields, items, metadata, footer, }) {
+    const hasMetadata = Boolean(metadata && Object.keys(metadata).length > 0);
+    return (_jsx(Modal, { isOpen: isOpen, onClose: onClose, title: title, children: _jsxs(Stack, { gap: "md", children: [badges && badges.length > 0 && (_jsx(Row, { gap: "sm", align: "center", wrap: true, children: badges.map((b) => (_jsx(Badge, { variant: b.variant ?? "default", children: b.label }, b.label))) })), description && (_jsx(Div, { rounded: "lg", padding: "sm", surface: "muted", border: "default", children: _jsx(Text, { size: "sm", children: description }) })), fields && fields.length > 0 && (_jsx(Stack, { gap: "xs", children: fields.map((f) => (_jsxs(Row, { justify: "between", gap: "md", children: [_jsx(Text, { size: "sm", color: "muted", children: f.label }), _jsx(Text, { size: "sm", weight: "medium", className: "text-right", children: f.value })] }, f.label))) })), items && items.entries.length > 0 && (_jsxs(Stack, { gap: "xs", children: [_jsxs(Text, { size: "xs", weight: "semibold", color: "muted", children: [items.heading, " (", items.entries.length, ")"] }), _jsx(Div, { className: "divide-y divide-[var(--appkit-color-border)] border border-[var(--appkit-color-border)]", rounded: "lg", children: items.entries.map((entry, i) => (_jsxs(Row, { gap: "sm", align: "center", justify: "between", paddingY: "y-xs-tall", padding: "x-sm", children: [_jsxs(Row, { gap: "sm", align: "center", className: "min-w-0", children: [_jsx(Div, { className: "h-10 w-10 shrink-0", rounded: "md", overflow: "hidden", children: _jsx(MediaImage, { src: entry.image, alt: entry.title, size: "thumbnail" }) }), _jsxs(Stack, { gap: "none", className: "min-w-0", children: [entry.href ? (_jsx(Anchor, { href: entry.href, tone: "brand", size: "sm", weight: "medium", children: entry.title })) : (_jsx(Text, { size: "sm", weight: "medium", className: "truncate", children: entry.title })), entry.subtitle && (_jsx(Text, { size: "xs", color: "muted", children: entry.subtitle }))] })] }), entry.trailing && (_jsx(Text, { size: "sm", weight: "medium", className: "shrink-0", children: entry.trailing }))] }, `${entry.title}-${i}`))) })] })), hasMetadata && (_jsxs(Div, { rounded: "lg", padding: "sm", surface: "muted", border: "default", children: [_jsx(Text, { size: "xs", weight: "semibold", color: "muted", className: "mb-1", children: "Details" }), _jsx(Code, { size: "xs", className: "block whitespace-pre-wrap font-mono", children: JSON.stringify(metadata, null, 2) })] })), footer && _jsx(Row, { justify: "end", gap: "sm", children: footer })] }) }));
+}

package/dist/ui/components/SlottedListingView.js

@@ -25,7 +25,15 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { useState } from "react";
 import { Div } from "./Div";
 import { Heading } from "./Typography";
-export function SlottedListingView({ title, labels = {}, portal, renderHeader, renderTabs, renderSearch, renderSort, renderFilters, renderActiveFilters, renderBulkActions, renderTable, renderPagination, overlays, manageSearch: _manageSearch, manageSelection, manageSort: _manageSort = false, inlineToolbar = false, total = 0, isLoading = false, className = "", }) {
+export function SlottedListingView({ title, labels = {}, portal, renderHeader, renderTabs, renderSearch, renderSort, renderFilters, renderActiveFilters, renderBulkActions, renderTable, renderPagination, overlays, 
+// audit-dead-underscore-prop-ok: deliberately unused — see the doc comment
+// on `manageSearch` above; wiring this to gate renderSearch would break
+// real consumers with self-contained closures.
+manageSearch: _manageSearch, manageSelection, 
+// audit-dead-underscore-prop-ok: deliberately unused — see the doc comment
+// on `manageSort` above; wiring this to gate renderSort would break real
+// consumers with self-contained closures.
+manageSort: _manageSort = false, inlineToolbar = false, total = 0, isLoading = false, className = "", }) {
     const effectiveManageSelection = manageSelection ?? (portal === "admin" || portal === "seller");
     const [search, setSearch] = useState("");
     const [selectedIds, setSelectedIds] = useState([]);

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

@@ -0,0 +1,25 @@
+export interface FormErrorSummaryProps {
+    /** Hide the whole block when there are currently no errors. Default true. */
+    hideWhenEmpty?: boolean;
+    className?: string;
+    /** Heading shown above the error list. */
+    title?: string;
+}
+/**
+ * Shared, live validation-error summary — supplements (does not replace) the
+ * per-field inline errors `FieldInput`/`FieldSelect`/`FormField` already
+ * render. Reads `FormShellContext` directly (no required props), so it's
+ * placed once beside a form's Submit/Save button and reflects every current
+ * error immediately as fields change — not gated by `touched`, unlike the
+ * inline per-field errors.
+ *
+ * For multi-step forms whose step engine populates
+ * `FormShellContextValue.fieldToStepIndex`, each entry names its owning step
+ * and is clickable to jump there. Falls back to a flat list when no step
+ * context exists (single-step `<Form>` usage).
+ *
+ * Uses the `.appkit-formshell__error-summary` class family already defined
+ * in `FormShell.style.css` for this exact purpose.
+ */
+export declare function FormErrorSummary({ hideWhenEmpty, className, title, }: FormErrorSummaryProps): import("react").JSX.Element | null;
+export default FormErrorSummary;

package/dist/ui/forms/FormErrorSummary.js

@@ -0,0 +1,37 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useContext } from "react";
+import { FormShellContext } from "./FormShell";
+import { Span } from "../components/Typography";
+/**
+ * Shared, live validation-error summary — supplements (does not replace) the
+ * per-field inline errors `FieldInput`/`FieldSelect`/`FormField` already
+ * render. Reads `FormShellContext` directly (no required props), so it's
+ * placed once beside a form's Submit/Save button and reflects every current
+ * error immediately as fields change — not gated by `touched`, unlike the
+ * inline per-field errors.
+ *
+ * For multi-step forms whose step engine populates
+ * `FormShellContextValue.fieldToStepIndex`, each entry names its owning step
+ * and is clickable to jump there. Falls back to a flat list when no step
+ * context exists (single-step `<Form>` usage).
+ *
+ * Uses the `.appkit-formshell__error-summary` class family already defined
+ * in `FormShell.style.css` for this exact purpose.
+ */
+export function FormErrorSummary({ hideWhenEmpty = true, className, title = "Please fix the following:", }) {
+    const ctx = useContext(FormShellContext);
+    if (!ctx)
+        return null;
+    const entries = Object.entries(ctx.errors);
+    if (entries.length === 0 && hideWhenEmpty)
+        return null;
+    if (entries.length === 0)
+        return null;
+    return (_jsxs("div", { role: "alert", "aria-live": "polite", className: ["appkit-formshell__error-summary", className].filter(Boolean).join(" "), children: [_jsx("div", { className: "appkit-formshell__error-summary__title", children: title }), _jsx("ul", { className: "appkit-formshell__error-summary__list", children: entries.map(([key, message]) => {
+                    const stepIndex = ctx.fieldToStepIndex?.[key];
+                    const stepLabel = stepIndex != null ? ctx.steps[stepIndex]?.label : undefined;
+                    return (_jsx("li", { children: stepLabel ? (_jsxs("button", { type: "button", className: "appkit-formshell__error-summary__step-link", onClick: () => ctx.goToStep(stepIndex), children: [_jsxs(Span, { weight: "semibold", children: [stepLabel, ":"] }), " ", message] })) : (_jsx(Span, { children: message })) }, key));
+                }) })] }));
+}
+export default FormErrorSummary;

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

@@ -30,6 +30,14 @@ export interface FormShellContextValue {
     isDirty: boolean;
     isSubmitting: boolean;
     stepErrorCounts: number[];
+    /**
+     * Maps an error key (same key shape `errors` uses) to the index into
+     * `steps` that owns it. Populated only by step-aware producers (the
+     * `features/shell` wizard chrome/step engine) — undefined for single-step
+     * forms (`<Form>`, `useFormShellState` with no steps). `<FormErrorSummary>`
+     * treats undefined as "no step context" and renders a flat list.
+     */
+    fieldToStepIndex?: Record<string, number>;
 }
 export declare const FormShellContext: React.Context<FormShellContextValue | null>;
 export declare function useFormShell(): FormShellContextValue;
@@ -43,12 +51,22 @@ export interface UseFormShellStateResult {
      * supplied values, write inline errors via `setFieldError`, and return the
      * parsed value on success or null on failure.
      */
-    validate: <T = unknown>(values: FormValues) => T | null;
+    validate: <T = unknown>(values: unknown) => T | null;
 }
 /**
  * `applyZodIssues` — pipe every issue from a Zod safeParse failure into the
  * FormShellContext error map. Use after `schema.safeParse(values)` returns
  * `success: false` to surface inline errors on `<FieldInput>` etc.
+ *
+ * Keys are the full dotted/indexed path (`"video.duration"`, `"images.2"`),
+ * not just the top-level segment — a plain `issue.path[0]` key would collapse
+ * every nested issue under one object onto the same map entry, silently
+ * dropping all but the last. Top-level-only fields (the common case) are
+ * unaffected: a single-segment path joins to the same string as before.
+ *
+ * Root-level `.refine()` issues (empty `path: []`, no owning field) are still
+ * skipped — there is no field to attach them to, and no schema in this
+ * codebase currently relies on one being surfaced this way.
  */
 export declare function applyZodIssues(issues: ReadonlyArray<{
     path: ReadonlyArray<PropertyKey>;
@@ -70,5 +88,22 @@ export interface FormShellProviderProps {
     autoSaveDelayMs?: number;
     /** Current form values — passed into onSaveDraft on auto-save */
     values?: FormValues;
+    /**
+     * Optional Zod schema — when supplied, the provider runs `.safeParse(values)`
+     * live (every time `values` changes, not just on submit) and populates its
+     * own `errors` map from the issues, so `<FieldInput>`/`<FormField>`/
+     * `<FormErrorSummary>` descendants get real validation without the parent
+     * component having to reach into the provider's internal state itself.
+     */
+    schema?: import("zod").ZodTypeAny;
+    /**
+     * Maps an error key to the index of the step that owns it — forwarded
+     * as-is into the context value for `<FormErrorSummary>` to consume. The
+     * provider itself has no concept of "steps"; the caller (typically a
+     * step-wizard shell) computes this from its own step definitions.
+     */
+    fieldToStepIndex?: Record<string, number>;
+    /** Wired into `FormShellContextValue.goToStep` when the caller has real step navigation to drive (e.g. a step-wizard's `setCurrentStep`). */
+    onGoToStep?: (n: number) => void;
 }
-export declare function FormShellProvider({ children, onSaveDraft, isDirty, autoSaveDelayMs, values, }: FormShellProviderProps): React.JSX.Element;
+export declare function FormShellProvider({ children, onSaveDraft, isDirty, autoSaveDelayMs, values, schema, fieldToStepIndex, onGoToStep, }: FormShellProviderProps): React.JSX.Element;

package/dist/ui/forms/FormShell.js

@@ -13,13 +13,23 @@ export function useFormShell() {
  * `applyZodIssues` — pipe every issue from a Zod safeParse failure into the
  * FormShellContext error map. Use after `schema.safeParse(values)` returns
  * `success: false` to surface inline errors on `<FieldInput>` etc.
+ *
+ * Keys are the full dotted/indexed path (`"video.duration"`, `"images.2"`),
+ * not just the top-level segment — a plain `issue.path[0]` key would collapse
+ * every nested issue under one object onto the same map entry, silently
+ * dropping all but the last. Top-level-only fields (the common case) are
+ * unaffected: a single-segment path joins to the same string as before.
+ *
+ * Root-level `.refine()` issues (empty `path: []`, no owning field) are still
+ * skipped — there is no field to attach them to, and no schema in this
+ * codebase currently relies on one being surfaced this way.
  */
 export function applyZodIssues(issues, setFieldError) {
     for (const issue of issues) {
-        const key = issue.path[0];
-        if (key == null)
+        if (!issue.path || issue.path.length === 0)
             continue;
-        setFieldError(String(key), issue.message);
+        const key = issue.path.map(String).join(".");
+        setFieldError(key, issue.message);
     }
 }
 /**
@@ -72,7 +82,7 @@ export function useFormShellState(schema) {
     }), [errors, setFieldError]);
     return { shellCtx, setFieldError, clearErrors, hasErrors: Object.keys(errors).length > 0, validate };
 }
-export function FormShellProvider({ children, onSaveDraft, isDirty = false, autoSaveDelayMs = 2000, values = {}, }) {
+export function FormShellProvider({ children, onSaveDraft, isDirty = false, autoSaveDelayMs = 2000, values = {}, schema, fieldToStepIndex, onGoToStep, }) {
     const [errors, setErrors] = useState({});
     const [touched, setTouched] = useState({});
     const autoSaveTimer = useRef(null);
@@ -89,6 +99,25 @@ export function FormShellProvider({ children, onSaveDraft, isDirty = false, auto
         return () => { if (autoSaveTimer.current)
             clearTimeout(autoSaveTimer.current); };
     }, [values, isDirty, onSaveDraft, autoSaveDelayMs]);
+    useEffect(() => {
+        if (!schema)
+            return;
+        // audit-unvalidated-safeparse-ok: bulk-replaces the whole errors map from
+        // the full parse result (so a field that just became valid is cleared),
+        // which applyZodIssues (incremental setFieldError-per-issue) can't do.
+        const parsed = schema.safeParse(values);
+        if (parsed.success) {
+            setErrors({});
+            return;
+        }
+        const next = {};
+        for (const issue of parsed.error.issues) {
+            if (!issue.path || issue.path.length === 0)
+                continue;
+            next[issue.path.map(String).join(".")] = issue.message;
+        }
+        setErrors(next);
+    }, [schema, values]);
     const setFieldError = useCallback((name, error) => {
         setErrors((prev) => {
             if (!error) {
@@ -121,13 +150,14 @@ export function FormShellProvider({ children, onSaveDraft, isDirty = false, auto
         clearFieldError,
         steps: [],
         currentStep: 0,
-        goToStep: () => { },
+        goToStep: onGoToStep ?? (() => { }),
         nextStep: () => { },
         prevStep: () => { },
-        isPublishReady: true,
+        isPublishReady: Object.keys(errors).length === 0,
         isDirty,
         isSubmitting: false,
         stepErrorCounts: [],
-    }), [errors, touched, setFieldError, setFieldTouched, clearFieldError, isDirty]);
+        fieldToStepIndex,
+    }), [errors, touched, setFieldError, setFieldTouched, clearFieldError, isDirty, onGoToStep, fieldToStepIndex]);
     return _jsx(FormShellContext.Provider, { value: ctx, children: children });
 }

package/dist/ui/forms/FormShell.style.css

@@ -142,6 +142,23 @@
   gap: var(--appkit-spacing-1, 0.25rem);
 }
 
+.appkit-formshell__error-summary__step-link {
+  background: none;
+  border: none;
+  padding: 0;
+  margin: 0;
+  font: inherit;
+  color: inherit;
+  text-align: left;
+  cursor: pointer;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.appkit-formshell__error-summary__step-link:hover {
+  color: var(--appkit-color-error, #dc2626);
+}
+
 /* ─── Body + Steps ───────────────────────────────────────────────────────── */
 
 .appkit-formshell__body {

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

@@ -10,3 +10,5 @@ export type { FieldTextareaProps } from "./FieldTextarea";
 export { FieldTextarea } from "./FieldTextarea";
 export type { ColorPickerFieldProps } from "./ColorPickerField";
 export { ColorPickerField } from "./ColorPickerField";
+export type { FormErrorSummaryProps } from "./FormErrorSummary";
+export { FormErrorSummary } from "./FormErrorSummary";

package/dist/ui/forms/index.js

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

package/dist/ui/index.d.ts

@@ -10,6 +10,8 @@ export type { FieldCheckboxProps } from "./forms";
 export { FieldCheckbox } from "./forms";
 export type { FieldTextareaProps } from "./forms";
 export { FieldTextarea } from "./forms";
+export type { FormErrorSummaryProps } from "./forms";
+export { FormErrorSummary } from "./forms";
 export { buildColumns, createColumnBuilder, renderBoolean, renderCurrency, renderCurrencyCompact, renderCount, renderNullable, renderRating, getStatusTone, getResourceIcon, } from "./columns";
 export type { BooleanRenderOpts, RatingMode, RatingRenderOpts, StatusTone, } from "./columns";
 export type { SectionProps, SectionBackgroundConfig, ArticleProps, MainProps, AsideProps, NavProps, BlockHeaderProps, BlockFooterProps, UlProps, OlProps, LiProps, TableProps, TheadProps, TbodyProps, TrProps, ThProps, TdProps, CodeProps, PreProps, BlockquoteProps, FigureProps, FigcaptionProps, DlProps, DtProps, DdProps, } from "./components/Semantic";
@@ -229,3 +231,5 @@ export { Show, Hide } from "./components/Responsive";
 export type { ShowProps, HideProps } from "./components/Responsive";
 export { CollapsibleSection } from "./components/CollapsibleSection";
 export type { CollapsibleSectionProps } from "./components/CollapsibleSection";
+export { RecordDetailModal } from "./components/RecordDetailModal";
+export type { RecordDetailModalProps, RecordDetailField, RecordDetailItem, RecordDetailBadge, } from "./components/RecordDetailModal";

package/dist/ui/index.js

@@ -5,6 +5,7 @@ export { FieldInput } from "./forms";
 export { FieldSelect } from "./forms";
 export { FieldCheckbox } from "./forms";
 export { FieldTextarea } from "./forms";
+export { FormErrorSummary } from "./forms";
 // --- Column utilities ---------------------------------------------------------
 export { buildColumns, createColumnBuilder, renderBoolean, renderCurrency, renderCurrencyCompact, renderCount, renderNullable, renderRating, getStatusTone, getResourceIcon, } from "./columns";
 export { Section, sectionBackgroundStyle, Article, Main, Aside, Nav, BlockHeader, BlockFooter, Ul, Ol, Li, Table, Thead, Tbody, Tr, Th, Td, Code, Pre, Blockquote, Figure, Figcaption, Dl, Dt, Dd, } from "./components/Semantic";
@@ -120,3 +121,7 @@ export { Kbd } from "./components/Kbd";
 export { StickyToolbar } from "./components/StickyToolbar";
 export { Show, Hide } from "./components/Responsive";
 export { CollapsibleSection } from "./components/CollapsibleSection";
+// RecordDetailModal — shared "open one listing row and read it" surface.
+// Backs the 2026-08-21 dead-end-listing sweep; see the component's own
+// header comment and scripts/audit-listing-detail-affordance.mjs.
+export { RecordDetailModal } from "./components/RecordDetailModal";

package/dist/utils/media-url.d.ts

@@ -10,9 +10,11 @@ export declare const GCS_HOST = "storage.googleapis.com";
 /**
  * Normalise any image URL so it goes through the watermark proxy:
  *  - /media/<path>         → return as-is (already proxied via Firebase Storage)
+ *  - blob: / data: URI     → return as-is (local-only, never fetchable server-side)
  *  - Firebase Storage URL  → extract /o/ path → /media/<path>
+ *  - GCS (storage.googleapis.com) URL → drop the bucket segment → /media/<path>
  *  - Any other absolute URL → /api/media/ext?url=<encoded> (ext watermark proxy)
- *  - Relative / data: URI  → return as-is
+ *  - Relative URI          → return as-is
  *  - Falsy                 → undefined
  */
 export declare function resolveMediaUrl(url: string | null | undefined): string | undefined;

package/dist/utils/media-url.js

@@ -13,9 +13,11 @@ const PROXY_PREFIX = "/media/";
 /**
  * Normalise any image URL so it goes through the watermark proxy:
  *  - /media/<path>         → return as-is (already proxied via Firebase Storage)
+ *  - blob: / data: URI     → return as-is (local-only, never fetchable server-side)
  *  - Firebase Storage URL  → extract /o/ path → /media/<path>
+ *  - GCS (storage.googleapis.com) URL → drop the bucket segment → /media/<path>
  *  - Any other absolute URL → /api/media/ext?url=<encoded> (ext watermark proxy)
- *  - Relative / data: URI  → return as-is
+ *  - Relative URI          → return as-is
  *  - Falsy                 → undefined
  */
 export function resolveMediaUrl(url) {
@@ -23,6 +25,13 @@ export function resolveMediaUrl(url) {
         return undefined;
     if (url.startsWith(PROXY_PREFIX))
         return url;
+    // A blob:/data: URI is only ever valid in the tab that created it (e.g. a
+    // freshly-selected file preview via URL.createObjectURL, or a FileReader
+    // data URL fed to a crop modal). Routing it through the external-URL
+    // watermark proxy would try to fetch it server-side and 400 — it must be
+    // rendered directly instead.
+    if (url.startsWith("blob:") || url.startsWith("data:"))
+        return url;
     try {
         const parsed = new URL(url);
         if (parsed.hostname.endsWith(FIREBASE_STORAGE_HOST)) {
@@ -30,6 +39,16 @@ export function resolveMediaUrl(url) {
             if (m)
                 return `${PROXY_PREFIX}${decodeURIComponent(m[1])}`;
         }
+        if (parsed.hostname === GCS_HOST) {
+            // Path shape: /<bucket>/<object-path...> — drop the bucket segment,
+            // proxy the rest like a Firebase Storage URL (consistent watermarking
+            // + caching instead of falling through to the external-URL proxy).
+            const parts = parsed.pathname.replace(/^\//, "").split("/");
+            if (parts.length > 1) {
+                const objectPath = parts.slice(1).join("/");
+                return `${PROXY_PREFIX}${decodeURIComponent(objectPath)}`;
+            }
+        }
         return MEDIA_ENDPOINTS.EXT_URL(url);
     }
     catch (_err) {

package/dist/validation/schemas.d.ts

@@ -114,17 +114,17 @@ export declare const changePasswordSchema: z.ZodEffects<z.ZodObject<{
     currentPassword: z.ZodString;
     newPassword: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
 }, "strip", z.ZodTypeAny, {
-    currentPassword: string;
     newPassword: string;
-}, {
     currentPassword: string;
+}, {
     newPassword: string;
-}>, {
     currentPassword: string;
+}>, {
     newPassword: string;
-}, {
     currentPassword: string;
+}, {
     newPassword: string;
+    currentPassword: string;
 }>;
 export declare const cropDataSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodObject<{
     sourceUrl: z.ZodEffects<z.ZodString, string, string>;

package/package.json

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