@mohasinac/appkit 4.9.5 → 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/ImageLightbox.js

@@ -2,11 +2,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { createPortal } from "react-dom";
-import { ChevronLeft, ChevronRight, X, ZoomIn, ZoomOut, RotateCw, Maximize2 } from "lucide-react";
+import { ChevronLeft, ChevronRight, X, ZoomIn, ZoomOut, RotateCw, Maximize2, Minimize2 } from "lucide-react";
 import { Button } from "./Button";
 import { Div } from "./Div";
 import { Text, Span } from "./Typography";
 import { MediaImage } from "../../features/media/MediaImage";
+import { getYouTubeVideoId } from "../../utils/media-url";
 const CLS_CLOSE_BTN = "w-10 h-10 p-0 !min-h-0 rounded-full bg-white/15 hover:bg-error-surface text-white flex items-center justify-center";
 const MIN_ZOOM = 10;
 const MAX_ZOOM = 300;
@@ -15,6 +16,7 @@ export function ImageLightbox({ images, activeIndex, onClose, onNavigate, showTh
     const [currentIndex, setCurrentIndex] = useState(activeIndex ?? 0);
     const [zoom, setZoom] = useState(100);
     const [rotation, setRotation] = useState(0);
+    const [isFullscreen, setIsFullscreen] = useState(false);
     const overlayRef = useRef(null);
     // Sync external activeIndex and reset transforms
     useEffect(() => {
@@ -33,6 +35,37 @@ export function ImageLightbox({ images, activeIndex, onClose, onNavigate, showTh
         document.body.style.overflow = "hidden";
         return () => { document.body.style.overflow = prev; };
     }, [isOpen]);
+    // Track native Fullscreen API state so the toggle button + icon stay in sync
+    // even when the user exits via Esc/browser chrome rather than our button.
+    useEffect(() => {
+        const onFsChange = () => {
+            const doc = document;
+            const fsEl = document.fullscreenElement ?? doc.webkitFullscreenElement ?? null;
+            setIsFullscreen(fsEl === overlayRef.current);
+        };
+        document.addEventListener("fullscreenchange", onFsChange);
+        document.addEventListener("webkitfullscreenchange", onFsChange);
+        return () => {
+            document.removeEventListener("fullscreenchange", onFsChange);
+            document.removeEventListener("webkitfullscreenchange", onFsChange);
+        };
+    }, []);
+    // Exit native fullscreen when the lightbox itself closes.
+    useEffect(() => {
+        const doc = document;
+        if (!isOpen && (document.fullscreenElement || doc.webkitFullscreenElement)) {
+            (document.exitFullscreen?.() ?? doc.webkitExitFullscreen?.())?.catch?.(() => { });
+        }
+    }, [isOpen]);
+    const toggleFullscreen = useCallback(() => {
+        const doc = document;
+        if (document.fullscreenElement || doc.webkitFullscreenElement) {
+            (document.exitFullscreen?.() ?? doc.webkitExitFullscreen?.())?.catch?.(() => { });
+            return;
+        }
+        const el = overlayRef.current;
+        (el?.requestFullscreen?.() ?? el?.webkitRequestFullscreen?.())?.catch?.(() => { });
+    }, []);
     const navigate = useCallback((dir) => {
         setCurrentIndex((prev) => {
             const next = (prev + dir + images.length) % images.length;
@@ -89,11 +122,12 @@ export function ImageLightbox({ images, activeIndex, onClose, onNavigate, showTh
         return null;
     const image = images[currentIndex];
     const hasMultiple = images.length > 1;
+    const youtubeId = image.kind === "video" ? getYouTubeVideoId(image.src) : null;
     const iconBtnClass = "w-10 h-10 p-0 !min-h-0 rounded-full bg-white/15 hover:bg-white/30 text-white flex items-center justify-center";
-    return createPortal(_jsxs("div", { ref: overlayRef, tabIndex: -1, className: "appkit-lightbox", role: "dialog", "aria-modal": "true", "aria-label": "Image lightbox", onKeyDown: handleKeyDown, onWheel: handleWheel, children: [_jsxs("div", { className: "absolute top-0 left-0 right-0 z-10 flex items-center justify-between px-4 py-3 bg-gradient-to-b from-black/60 to-transparent", children: [_jsx(Span, { size: "sm", weight: "medium", className: "text-white/70", children: hasMultiple ? `${currentIndex + 1} / ${images.length}` : "" }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Button, { variant: "ghost", size: "sm", type: "button", onClick: () => adjustZoom(-ZOOM_STEP), className: iconBtnClass, "aria-label": "Zoom out", disabled: zoom <= MIN_ZOOM, children: _jsx(ZoomOut, { className: "w-4 h-4" }) }), _jsxs("button", { type: "button", onClick: () => { setZoom(100); setRotation(0); }, className: "text-white/70 hover:text-white text-xs font-mono min-w-[3rem] text-center", "aria-label": "Reset zoom", children: [zoom, "%"] }), _jsx(Button, { variant: "ghost", size: "sm", type: "button", onClick: () => adjustZoom(ZOOM_STEP), className: iconBtnClass, "aria-label": "Zoom in", disabled: zoom >= MAX_ZOOM, children: _jsx(ZoomIn, { className: "w-4 h-4" }) }), _jsx(Button, { variant: "ghost", size: "sm", type: "button", onClick: () => setRotation((r) => (r + 90) % 360), className: iconBtnClass, "aria-label": "Rotate 90\u00B0", children: _jsx(RotateCw, { className: "w-4 h-4" }) }), _jsx(Button, { variant: "ghost", size: "sm", type: "button", onClick: () => { setZoom(100); setRotation(0); }, className: iconBtnClass, "aria-label": "Reset", children: _jsx(Maximize2, { className: "w-4 h-4" }) }), _jsx(Button, { variant: "ghost", size: "sm", type: "button", onClick: onClose, className: CLS_CLOSE_BTN, "aria-label": "Close lightbox", children: _jsx(X, { className: "w-5 h-5" }) })] })] }), hasMultiple && (_jsx(Button, { variant: "ghost", size: "sm", type: "button", onClick: () => navigate(-1), className: "absolute left-4 top-1/2 -translate-y-1/2 w-12 h-12 p-0 !min-h-0 rounded-full bg-white/15 hover:bg-white/30 text-white z-10 flex items-center justify-center", "aria-label": "Previous image", children: _jsx(ChevronLeft, { className: "w-7 h-7" }) })), _jsxs("div", { className: "appkit-lightbox__image-wrap", style: { cursor: zoom > 100 ? "grab" : "default" }, children: [image.kind === "video" ? (_jsx("video", { src: image.src, poster: image.poster, controls: true, playsInline: true, "aria-label": image.alt ?? "Video", className: "appkit-lightbox__img", style: {
+    return createPortal(_jsxs("div", { ref: overlayRef, tabIndex: -1, className: "appkit-lightbox", role: "dialog", "aria-modal": "true", "aria-label": "Image lightbox", onKeyDown: handleKeyDown, onWheel: handleWheel, children: [_jsxs("div", { className: "absolute top-0 left-0 right-0 z-10 flex items-center justify-between px-4 py-3 bg-gradient-to-b from-black/60 to-transparent", children: [_jsx(Span, { size: "sm", weight: "medium", className: "text-white/70", children: hasMultiple ? `${currentIndex + 1} / ${images.length}` : "" }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Button, { variant: "ghost", size: "sm", type: "button", onClick: () => adjustZoom(-ZOOM_STEP), className: iconBtnClass, "aria-label": "Zoom out", disabled: zoom <= MIN_ZOOM, children: _jsx(ZoomOut, { className: "w-4 h-4" }) }), _jsxs("button", { type: "button", onClick: () => { setZoom(100); setRotation(0); }, className: "text-white/70 hover:text-white text-xs font-mono min-w-[3rem] text-center", "aria-label": "Reset zoom", children: [zoom, "%"] }), _jsx(Button, { variant: "ghost", size: "sm", type: "button", onClick: () => adjustZoom(ZOOM_STEP), className: iconBtnClass, "aria-label": "Zoom in", disabled: zoom >= MAX_ZOOM, children: _jsx(ZoomIn, { className: "w-4 h-4" }) }), _jsx(Button, { variant: "ghost", size: "sm", type: "button", onClick: () => setRotation((r) => (r + 90) % 360), className: iconBtnClass, "aria-label": "Rotate 90\u00B0", children: _jsx(RotateCw, { className: "w-4 h-4" }) }), _jsx(Button, { variant: "ghost", size: "sm", type: "button", onClick: toggleFullscreen, className: iconBtnClass, "aria-label": isFullscreen ? "Exit fullscreen" : "Enter fullscreen", children: isFullscreen ? _jsx(Minimize2, { className: "w-4 h-4" }) : _jsx(Maximize2, { className: "w-4 h-4" }) }), _jsx(Button, { variant: "ghost", size: "sm", type: "button", onClick: onClose, className: CLS_CLOSE_BTN, "aria-label": "Close lightbox", children: _jsx(X, { className: "w-5 h-5" }) })] })] }), hasMultiple && (_jsx(Button, { variant: "ghost", size: "sm", type: "button", onClick: () => navigate(-1), className: "absolute left-4 top-1/2 -translate-y-1/2 w-12 h-12 p-0 !min-h-0 rounded-full bg-white/15 hover:bg-white/30 text-white z-10 flex items-center justify-center", "aria-label": "Previous image", children: _jsx(ChevronLeft, { className: "w-7 h-7" }) })), _jsxs("div", { className: "appkit-lightbox__image-wrap", style: { cursor: zoom > 100 ? "grab" : "default" }, children: [image.kind === "video" ? (youtubeId ? (_jsx("iframe", { src: `https://www.youtube-nocookie.com/embed/${youtubeId}?playsinline=1&rel=0`, title: image.alt ?? "Video", allow: "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share", allowFullScreen: true, className: "appkit-lightbox__img appkit-lightbox__video border-0" })) : (_jsx("video", { src: image.src, poster: image.poster, controls: true, playsInline: true, "aria-label": image.alt ?? "Video", className: "appkit-lightbox__img appkit-lightbox__video", style: {
                             transform: `scale(${zoom / 100}) rotate(${rotation}deg)`,
                             transition: "transform 0.2s ease",
-                        } })) : (_jsx(MediaImage, { src: image.src, alt: image.alt ?? "", size: "hero", objectFit: "contain", className: "appkit-lightbox__img", style: {
+                        } }))) : (_jsx(MediaImage, { src: image.src, alt: image.alt ?? "", size: "hero", objectFit: "contain", className: "appkit-lightbox__img", style: {
                             transform: `scale(${zoom / 100}) rotate(${rotation}deg)`,
                             transition: "transform 0.2s ease",
                         } })), image.badge && (_jsx(Div, { className: "absolute left-3 top-3 rounded bg-black/70 px-2 py-1 text-xs font-semibold text-white pointer-events-none", children: image.badge }))] }), (image.caption || image.sub) && (_jsxs("div", { className: "flex-shrink-0 text-center px-8 pb-2", children: [image.caption && (_jsx(Text, { size: "sm", variant: "secondary", className: "!text-white/80", children: image.caption })), image.sub && (_jsx(Text, { size: "sm", variant: "secondary", className: "!text-white/50", children: image.sub }))] })), showThumbnails && images.length > 1 && (_jsx("div", { className: "flex-shrink-0 flex gap-2 overflow-x-auto px-4 pb-3 justify-center", children: images.map((thumb, i) => (_jsx("button", { type: "button", onClick: () => {

package/dist/ui/components/ImageLightbox.style.css

@@ -37,6 +37,14 @@
   position: relative;
 }
 
+@media (max-width: 640px) {
+  .appkit-lightbox__image-wrap {
+    /* Tighter than the desktop 4rem so a video's min-width (below) has room
+       to fit inside narrow phone viewports without forcing horizontal scroll. */
+    padding: 1.5rem 1rem;
+  }
+}
+
 .appkit-lightbox__img {
   max-height: 100%;
   max-width: 100%;
@@ -44,6 +52,26 @@
   user-select: none;
 }
 
+/* -- Video / YouTube-embed area ----------------------- */
+/* Applied alongside .appkit-lightbox__img on the theater-mode <video>/<iframe>
+   so a video always occupies a real, tappable box — never the browser's tiny
+   ~300x150 default when a src fails to load or an embed reports no intrinsic
+   size (Recurrent Root Cause Pattern #27-adjacent: video needs its own sizing
+   contract, it can't just inherit the image one). */
+.appkit-lightbox__video {
+  width: 100%;
+  height: 100%;
+  min-width: 260px;
+  min-height: 190px;
+}
+
+@media (min-width: 768px) {
+  .appkit-lightbox__video {
+    min-width: 480px;
+    min-height: 320px;
+  }
+}
+
 /* -- Zoom hint --------------------------------------- */
 
 .appkit-lightbox__zoom-hint {

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";