@mohasinac/appkit 2.8.9 → 3.0.0

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

@@ -21,11 +21,11 @@ export interface ConfirmDeleteModalProps {
  * @example
  * ```tsx
  * <ConfirmDeleteModal
- *   isOpen={isOpen}
- *   onClose={() => setOpen(false)}
- *   onConfirm={handleDelete}
- *   title="Delete product?"
- *   variant="danger"
+ * isOpen={isOpen}
+ * onClose={() => setOpen(false)}
+ * onConfirm={handleDelete}
+ * title="Delete product?"
+ * variant="danger"
  * />
  * ```
  */

package/dist/ui/components/ConfirmDeleteModal.js

@@ -40,11 +40,11 @@ const VARIANT_STYLES = {
  * @example
  * ```tsx
  * <ConfirmDeleteModal
- *   isOpen={isOpen}
- *   onClose={() => setOpen(false)}
- *   onConfirm={handleDelete}
- *   title="Delete product?"
- *   variant="danger"
+ * isOpen={isOpen}
+ * onClose={() => setOpen(false)}
+ * onConfirm={handleDelete}
+ * title="Delete product?"
+ * variant="danger"
  * />
  * ```
  */

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

@@ -15,8 +15,8 @@ export interface DescriptionFieldProps {
  * @example
  * ```tsx
  * <Row as="dl" wrap gap="md">
- *   <DescriptionField label="Store name" value="My Amazing Store" />
- *   <DescriptionField label="Description" value={longDescription} />
+ * <DescriptionField label="Store name" value="My Amazing Store" />
+ * <DescriptionField label="Description" value={longDescription} />
  * </Row>
  * ```
  */

package/dist/ui/components/DescriptionField.js

@@ -9,8 +9,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * @example
  * ```tsx
  * <Row as="dl" wrap gap="md">
- *   <DescriptionField label="Store name" value="My Amazing Store" />
- *   <DescriptionField label="Description" value={longDescription} />
+ * <DescriptionField label="Store name" value="My Amazing Store" />
+ * <DescriptionField label="Description" value={longDescription} />
  * </Row>
  * ```
  */

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

@@ -56,8 +56,10 @@ export interface DetailViewShellProps {
      */
     stickyActionRail?: boolean;
     /**
-     * Top offset for the sticky action rail (e.g. `"top-16"` for a 64px title
-     * bar). Defaults to `"top-6"` (24px, for pages without a sticky header).
+     * Top offset for the sticky action rail. Defaults to
+     * `"top-[var(--header-height,0px)]"` so the rail tracks the runtime header
+     * height. Override only when the rail sits inside a scroll container with
+     * its own header (e.g. modals).
      */
     stickyRailOffset?: string;
     className?: string;

package/dist/ui/components/DetailViewShell.js

@@ -24,7 +24,7 @@ function resolveSlot(slot) {
 }
 export function DetailViewShell({ layout = "stacked", 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-portal, isLoading = false, renderSkeleton, renderNotFound, renderBreadcrumb, mainSlots = [], belowFold = [], afterMain, stickyActionRail = false, stickyRailOffset = "top-6", className = "", }) {
+portal, isLoading = false, renderSkeleton, renderNotFound, renderBreadcrumb, mainSlots = [], belowFold = [], afterMain, stickyActionRail = false, stickyRailOffset = "top-[var(--header-height,0px)]", className = "", }) {
     if (isLoading && renderSkeleton) {
         return _jsx(_Fragment, { children: renderSkeleton() });
     }

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

@@ -0,0 +1,29 @@
+import type { CSSProperties, ReactNode } from "react";
+/** Details + Summary — primitive for native `<details>` disclosure widget. */
+export type DetailsTone = "default" | "muted" | "card";
+export type DetailsPadding = "none" | "sm" | "md" | "lg";
+export interface DetailsProps {
+    children: ReactNode;
+    /** Initial open state. */
+    defaultOpen?: boolean;
+    /** Controlled open state (pair with `onToggle`). */
+    open?: boolean;
+    onToggle?: (open: boolean) => void;
+    tone?: DetailsTone;
+    padding?: DetailsPadding;
+    /** Auto-collapse other `<Details>` with the same `name` (browser-handled). */
+    name?: string;
+    /**
+     * Escape hatch for state-related classNames like `group` that drive
+     * sibling `group-open:` animations. Variant slots (tone/padding) own
+     * the visual styling; this is for behaviour-coupled utility classes.
+     */
+    className?: string;
+    style?: CSSProperties;
+}
+export interface SummaryProps {
+    children: ReactNode;
+    className?: string;
+}
+export declare function Details({ children, defaultOpen, open, onToggle, tone, padding, name, className, style, }: DetailsProps): import("react/jsx-runtime").JSX.Element;
+export declare function Summary({ children, className }: SummaryProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/components/Details.js

@@ -0,0 +1,28 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+const TONE_CLS = {
+    default: "",
+    muted: "rounded-lg bg-[var(--appkit-color-bg)]",
+    card: "rounded-xl bg-[var(--appkit-color-surface)] border border-[var(--appkit-color-border)] shadow-sm",
+};
+const PADDING_CLS = {
+    none: "",
+    sm: "p-2",
+    md: "p-3",
+    lg: "p-4",
+};
+export function Details({ children, defaultOpen, open, onToggle, tone = "default", padding = "md", name, className, style, }) {
+    return (_jsx("details", { open: open ?? defaultOpen, onToggle: (event) => {
+            if (onToggle)
+                onToggle(event.currentTarget.open);
+        }, name: name, 
+        // audit-variant-ok: Details is the catalogued primitive for <details>.
+        className: `${TONE_CLS[tone]} ${PADDING_CLS[padding]}${className ? ` ${className}` : ""}`.trim(), 
+        // audit-inline-style-ok: style is a pass-through prop for the catalogued <details> primitive
+        style: style, children: children }));
+}
+export function Summary({ children, className }) {
+    return (_jsx("summary", { 
+        // audit-variant-ok: Summary is the catalogued primitive for <summary>.
+        className: `cursor-pointer select-none font-medium text-[var(--appkit-color-text)] list-none [&::-webkit-details-marker]:hidden focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--appkit-color-focus-ring)] rounded${className ? ` ${className}` : ""}`, children: children }));
+}

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

@@ -0,0 +1,26 @@
+import { type ReactNode } from "react";
+/**
+ * Dialog — primitive for the native `<dialog>` element.
+ *
+ * Distinct from `<Modal>` (which is a portal + AnimatePresence overlay).
+ * `Dialog` is the right primitive for confirmation prompts that need the
+ * browser's top-layer rendering (focus trap, ESC-to-close, scroll-lock).
+ */
+export type DialogPadding = "sm" | "md" | "lg";
+export interface DialogProps {
+    open: boolean;
+    onClose: () => void;
+    children: ReactNode;
+    padding?: DialogPadding;
+    /** Render as a non-modal dialog (`<dialog>.show()`). Default `false` → `showModal()`. */
+    nonModal?: boolean;
+    /**
+     * Close when clicking the backdrop. Native `<dialog>` does not trigger a
+     * backdrop click by default; we attach a click handler that compares the
+     * event target against the dialog element.
+     */
+    closeOnBackdrop?: boolean;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+}
+export declare function Dialog({ open, onClose, children, padding, nonModal, closeOnBackdrop, ...rest }: DialogProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/components/Dialog.js

@@ -0,0 +1,42 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+const PADDING_CLS = {
+    sm: "p-4",
+    md: "p-6",
+    lg: "p-8",
+};
+export function Dialog({ open, onClose, children, padding = "md", nonModal = false, closeOnBackdrop = true, ...rest }) {
+    const dialogRef = useRef(null);
+    useEffect(() => {
+        const node = dialogRef.current;
+        if (!node)
+            return;
+        if (open && !node.open) {
+            if (nonModal)
+                node.show();
+            else
+                node.showModal();
+        }
+        if (!open && node.open) {
+            node.close();
+        }
+    }, [open, nonModal]);
+    useEffect(() => {
+        const node = dialogRef.current;
+        if (!node)
+            return;
+        const handler = () => onClose();
+        node.addEventListener("close", handler);
+        return () => node.removeEventListener("close", handler);
+    }, [onClose]);
+    return (_jsx("dialog", { ref: dialogRef, "aria-labelledby": rest["aria-labelledby"], "aria-describedby": rest["aria-describedby"], onClick: (event) => {
+            if (!closeOnBackdrop)
+                return;
+            if (event.target === dialogRef.current)
+                onClose();
+        }, 
+        // audit-variant-ok: Dialog is the catalogued primitive for <dialog>.
+        // padding comes from the typed enum.
+        className: `rounded-xl bg-[var(--appkit-color-surface)] text-[var(--appkit-color-text)] shadow-xl border border-[var(--appkit-color-border)] ${PADDING_CLS[padding]} backdrop:bg-black/40 backdrop:backdrop-blur-sm`, children: children }));
+}

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

@@ -1,6 +1,30 @@
 import React from "react";
 import type { SurfaceProps } from "./surface-tokens";
+type DivColor = "default" | "primary" | "muted" | "faint" | "success" | "warning" | "error" | "info" | "inverse";
+type DivTextSize = "xs" | "sm" | "base" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl" | "6xl" | "7xl";
+type DivTextWeight = "normal" | "medium" | "semibold" | "bold";
+type DivLayout = "block" | "flex" | "inline-flex" | "grid" | "inline-block" | "inline";
+type DivGap = "none" | "1" | "2" | "3" | "4" | "5" | "6" | "8";
+type DivAlign = "start" | "center" | "end" | "baseline" | "stretch";
+type DivJustify = "start" | "center" | "end" | "between" | "around" | "evenly";
 export interface DivProps extends React.HTMLAttributes<HTMLDivElement>, SurfaceProps {
+    /** Colour variant cascaded onto Div text. Pragmatic — most Div sites wrap mixed inline content where a `<Text>` wrap would force structural change. */
+    color?: DivColor;
+    /** Cascade font-size to children. Use sparingly — prefer wrapping in `<Text size=…>`. */
+    textSize?: DivTextSize;
+    /** Cascade font-weight to children. Use sparingly — prefer wrapping in `<Text weight=…>`. */
+    textWeight?: DivTextWeight;
+    /** Display layout. Prefer `<Row>`/`<Stack>`/`<Grid>` when intent matches; this is the escape hatch for one-off bare Div containers. */
+    layout?: DivLayout;
+    /** Gap between children (CSS gap). Only takes effect when `layout` is `flex`/`inline-flex`/`grid`. */
+    gap?: DivGap;
+    /** Cross-axis alignment (CSS `items-*`). Only takes effect when `layout` is `flex`/`inline-flex`/`grid`. */
+    align?: DivAlign;
+    /** Responsive cross-axis alignment at the `lg` breakpoint. Used for editor 2-column grids that align tops at lg+. */
+    lgAlign?: DivAlign;
+    /** Main-axis alignment (CSS `justify-*`). Only takes effect when `layout` is `flex`/`inline-flex`/`grid`. */
+    justify?: DivJustify;
     children?: React.ReactNode;
 }
 export declare const Div: React.ForwardRefExoticComponent<DivProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/ui/components/Div.js

@@ -1,5 +1,86 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import React from "react";
 import { buildSurfaceClasses } from "./surface-tokens";
-export const Div = React.forwardRef(({ className = "", surface, padding, rounded, border, shadow, children, ...props }, ref) => (_jsx("div", { ref: ref, className: [buildSurfaceClasses({ surface, padding, rounded, border, shadow }), className].filter(Boolean).join(" "), ...props, children: children })));
+const DIV_COLOR_MAP = {
+    default: "",
+    primary: "appkit-color--primary",
+    muted: "appkit-color--muted",
+    faint: "appkit-color--faint",
+    success: "appkit-color--success",
+    warning: "appkit-color--warning",
+    error: "appkit-color--error",
+    info: "appkit-color--info",
+    inverse: "appkit-color--inverse",
+};
+const DIV_TEXT_SIZE_MAP = {
+    xs: "text-xs",
+    sm: "text-sm",
+    base: "text-base",
+    lg: "text-lg",
+    xl: "text-xl",
+    "2xl": "text-2xl",
+    "3xl": "text-3xl",
+    "4xl": "text-4xl",
+    "5xl": "text-5xl",
+    "6xl": "text-6xl",
+    "7xl": "text-7xl",
+};
+const DIV_TEXT_WEIGHT_MAP = {
+    normal: "font-normal",
+    medium: "font-medium",
+    semibold: "font-semibold",
+    bold: "font-bold",
+};
+const DIV_LAYOUT_MAP = {
+    block: "block",
+    flex: "flex",
+    "inline-flex": "inline-flex",
+    grid: "grid",
+    "inline-block": "inline-block",
+    inline: "inline",
+};
+const DIV_GAP_MAP = {
+    none: "",
+    "1": "gap-1",
+    "2": "gap-2",
+    "3": "gap-3",
+    "4": "gap-4",
+    "5": "gap-5",
+    "6": "gap-6",
+    "8": "gap-8",
+};
+const DIV_ALIGN_MAP = {
+    start: "items-start",
+    center: "items-center",
+    end: "items-end",
+    baseline: "items-baseline",
+    stretch: "items-stretch",
+};
+const DIV_JUSTIFY_MAP = {
+    start: "justify-start",
+    center: "justify-center",
+    end: "justify-end",
+    between: "justify-between",
+    around: "justify-around",
+    evenly: "justify-evenly",
+};
+const DIV_LG_ALIGN_MAP = {
+    start: "lg:items-start",
+    center: "lg:items-center",
+    end: "lg:items-end",
+    baseline: "lg:items-baseline",
+    stretch: "lg:items-stretch",
+};
+export const Div = React.forwardRef(({ className = "", surface, padding, paddingX, paddingY, rounded, border, shadow, color, textSize, textWeight, layout, gap, align, lgAlign, justify, children, ...props }, ref) => (_jsx("div", { ref: ref, className: [
+        buildSurfaceClasses({ surface, padding, paddingX, paddingY, rounded, border, shadow }),
+        color ? DIV_COLOR_MAP[color] : "",
+        textSize ? DIV_TEXT_SIZE_MAP[textSize] : "",
+        textWeight ? DIV_TEXT_WEIGHT_MAP[textWeight] : "",
+        layout ? DIV_LAYOUT_MAP[layout] : "",
+        gap ? DIV_GAP_MAP[gap] : "",
+        align ? DIV_ALIGN_MAP[align] : "",
+        lgAlign ? DIV_LG_ALIGN_MAP[lgAlign] : "",
+        justify ? DIV_JUSTIFY_MAP[justify] : "",
+        className,
+    ].filter(Boolean).join(" "), ...props, children: children })));
 Div.displayName = "Div";

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

@@ -0,0 +1,31 @@
+import type { ReactNode } from "react";
+/**
+ * FallbackShell — primitive used by ErrorBoundary and `app/global-error.tsx`.
+ *
+ * It inlines its critical CSS so it renders correctly when the Tailwind tree
+ * has not loaded yet (or has failed to load). The variant catalogue blocks
+ * consumer-side className on every primitive; this component owns its own
+ * inline styles by design.
+ */
+export type FallbackShellTone = "neutral" | "danger" | "warning";
+export interface FallbackShellProps {
+    /** Title displayed at the top of the shell. */
+    title: ReactNode;
+    /** Optional description paragraph. */
+    description?: ReactNode;
+    /** Optional details block (e.g. error message in dev). */
+    details?: ReactNode;
+    /**
+     * Optional action row (e.g. "Reload" / "Go home"). The shell does not style
+     * children — caller supplies buttons / links.
+     */
+    actions?: ReactNode;
+    /**
+     * Visual tone:
+     *  - `"neutral"` (default) — generic fallback UI.
+     *  - `"danger"` — uncaught error / global-error route boundary.
+     *  - `"warning"` — recoverable issue.
+     */
+    tone?: FallbackShellTone;
+}
+export declare function FallbackShell({ title, description, details, actions, tone, }: FallbackShellProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/components/FallbackShell.js

@@ -0,0 +1,71 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const TONE_BG = {
+    neutral: "var(--appkit-color-surface-muted)",
+    danger: "var(--appkit-color-error-surface)",
+    warning: "var(--appkit-color-warning-surface)",
+};
+const TONE_TITLE = {
+    neutral: "var(--appkit-color-text)",
+    danger: "var(--appkit-color-error-title)",
+    warning: "var(--appkit-color-warning)",
+};
+const TONE_TEXT = {
+    neutral: "var(--appkit-color-text-muted)",
+    danger: "var(--appkit-color-error-text)",
+    warning: "var(--appkit-color-warning)",
+};
+export function FallbackShell({ title, description, details, actions, tone = "neutral", }) {
+    return (_jsx("div", { role: "alert", 
+        // audit-inline-style-ok: FallbackShell ships its own critical CSS so it renders before/without Tailwind. Source-of-truth fallback surface.
+        style: {
+            minHeight: "100vh",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            padding: "2rem 1rem",
+            backgroundColor: TONE_BG[tone],
+            fontFamily: "ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif",
+            color: TONE_TEXT[tone],
+            textAlign: "center",
+        }, children: _jsxs("div", { 
+            // audit-inline-style-ok: FallbackShell critical-CSS container — see parent above.
+            style: { maxWidth: "32rem", width: "100%" }, children: [_jsx("h1", { 
+                    // audit-inline-style-ok: FallbackShell critical CSS — see container above.
+                    style: {
+                        margin: 0,
+                        fontSize: "1.875rem",
+                        lineHeight: 1.15,
+                        fontWeight: 700,
+                        color: TONE_TITLE[tone],
+                        letterSpacing: "-0.02em",
+                    }, children: title }), description ? (_jsx("p", { 
+                    // audit-inline-style-ok: FallbackShell critical CSS — see container above.
+                    style: {
+                        margin: "0.75rem 0 0",
+                        fontSize: "1rem",
+                        lineHeight: 1.5,
+                    }, children: description })) : null, details ? (_jsx("pre", { 
+                    // audit-inline-style-ok: FallbackShell critical CSS — see container above.
+                    style: {
+                        margin: "1.25rem 0 0",
+                        padding: "0.75rem 1rem",
+                        fontSize: "0.75rem",
+                        lineHeight: 1.4,
+                        fontFamily: "ui-monospace, SFMono-Regular, 'Cascadia Mono', Consolas, monospace",
+                        textAlign: "left",
+                        backgroundColor: "rgba(0,0,0,0.04)",
+                        borderRadius: "0.5rem",
+                        whiteSpace: "pre-wrap",
+                        wordBreak: "break-word",
+                        overflowX: "auto",
+                    }, children: details })) : null, actions ? (_jsx("div", { 
+                    // audit-inline-style-ok: FallbackShell critical CSS — see container above.
+                    style: {
+                        marginTop: "1.5rem",
+                        display: "flex",
+                        flexWrap: "wrap",
+                        gap: "0.5rem",
+                        justifyContent: "center",
+                    }, children: actions })) : null] }) }));
+}

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

@@ -0,0 +1,19 @@
+import type { ReactNode } from "react";
+/** Fieldset + Legend — primitive for grouped form controls. */
+export type FieldsetTone = "default" | "muted" | "success" | "warning" | "danger";
+export type FieldsetPadding = "none" | "sm" | "md" | "lg";
+export interface FieldsetProps {
+    children: ReactNode;
+    tone?: FieldsetTone;
+    padding?: FieldsetPadding;
+    disabled?: boolean;
+    form?: string;
+    name?: string;
+}
+export interface LegendProps {
+    children: ReactNode;
+    /** Visually hide the legend (still announced by screen readers). */
+    srOnly?: boolean;
+}
+export declare function Fieldset({ children, tone, padding, disabled, form, name, }: FieldsetProps): import("react/jsx-runtime").JSX.Element;
+export declare function Legend({ children, srOnly }: LegendProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/components/Fieldset.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+const TONE_BORDER = {
+    default: "border border-[var(--appkit-color-border)]",
+    muted: "border border-[var(--appkit-color-border-subtle)]",
+    success: "border border-[var(--appkit-color-success)]",
+    warning: "border border-[var(--appkit-color-warning)]",
+    danger: "border border-[var(--appkit-color-error)]",
+};
+const PADDING_CLS = {
+    none: "",
+    sm: "p-3",
+    md: "p-4",
+    lg: "p-6",
+};
+export function Fieldset({ children, tone = "default", padding = "md", disabled, form, name, }) {
+    return (_jsx("fieldset", { disabled: disabled, form: form, name: name, 
+        // audit-variant-ok: Fieldset is the catalogued primitive for <fieldset>.
+        className: `rounded-lg ${TONE_BORDER[tone]} ${PADDING_CLS[padding]}`, children: children }));
+}
+export function Legend({ children, srOnly = false }) {
+    return (_jsx("legend", { 
+        // audit-variant-ok: Legend is the catalogued primitive for <legend>.
+        className: srOnly
+            ? "sr-only"
+            : "px-1 text-sm font-semibold text-[var(--appkit-color-text)]", children: children }));
+}

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

@@ -11,10 +11,10 @@
  * @example
  * ```tsx
  * <FilterChipGroup
- *   label="Status"
- *   tabs={ADMIN_ORDER_STATUS_TABS}
- *   value={pendingFilters.status}
- *   onChange={(id) => setPendingFilters((p) => ({ ...p, status: id }))}
+ * label="Status"
+ * tabs={ADMIN_ORDER_STATUS_TABS}
+ * value={pendingFilters.status}
+ * onChange={(id) => setPendingFilters((p) => ({ ...p, status: id }))}
  * />
  * ```
  */

package/dist/ui/components/FlowDiagram.js

@@ -1,7 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Text, Span } from "./Typography";
-import { THEME_CONSTANTS } from "../../tokens";
-const { themed, flex } = THEME_CONSTANTS;
+import { THEMED_BG_PRIMARY, THEMED_BG_SECONDARY, THEMED_BORDER, } from "../../_internal/shared/styles/themed";
+const themed = {
+    bgPrimary: THEMED_BG_PRIMARY,
+    bgSecondary: THEMED_BG_SECONDARY,
+    border: THEMED_BORDER,
+};
 export function FlowDiagram({ title, titleClass = "text-primary", connectorClass, steps, stepWidth = "w-[86px]", centered = false, note, className = "", children, }) {
     return (_jsxs("div", { className: `appkit-flow-diagram ${themed.border} ${className}`, "data-section": "flowdiagram-div-496", children: [_jsx("div", { className: `appkit-flow-diagram__header ${themed.bgSecondary} ${themed.border}`, "data-section": "flowdiagram-div-497", children: _jsx(Text, { weight: "semibold", size: "sm", className: titleClass, children: title }) }), _jsxs("div", { className: `appkit-flow-diagram__body ${themed.bgPrimary}`, "data-section": "flowdiagram-div-498", children: [_jsx("div", { className: `appkit-flow-diagram__chain ${centered ? "appkit-flow-diagram__chain--centered" : "appkit-flow-diagram__chain--scroll"}`, "data-section": "flowdiagram-div-499", children: steps.flatMap((step, i) => {
                             const nodes = [

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

@@ -1,12 +1,45 @@
 import React from "react";
-export interface FormProps extends React.FormHTMLAttributes<HTMLFormElement> {
-    children: React.ReactNode;
+import type { ZodTypeAny } from "zod";
+import { type SurfaceProps } from "./surface-tokens";
+import { type UseFormShellStateResult } from "../forms/FormShell";
+export type FormSpacing = "none" | "xs" | "sm" | "md" | "lg" | "xl";
+export interface FormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement>, "children">, SurfaceProps {
+    /**
+     * Either a React node or a render function that receives the FormShell
+     * helpers. Use the function form when the submit handler needs to surface
+     * server-side errors inline on a `<FieldInput>` via `setFieldError`.
+     */
+    children: React.ReactNode | ((helpers: UseFormShellStateResult) => React.ReactNode);
+    /** Vertical spacing between top-level children. */
+    spacing?: FormSpacing;
+    /**
+     * Zod schema that validates the form values. When set, the render-prop
+     * helpers' `validate(values)` returns the parsed Zod result; `setFieldError`
+     * accepts the path of any Zod field. Eliminates the `useFormShellState(schema)`
+     * boilerplate per callsite.
+     */
+    schema?: ZodTypeAny;
 }
 export type GapToken = "none" | "xs" | "sm" | "md" | "lg" | "xl";
 /**
- * Semantic `<form>` wrapper. Passes all standard form attributes through.
+ * Canonical `<Form>` wrapper. Mounts `FormShellContext.Provider` so child
+ * `<FieldInput>` / `<FieldSelect>` / `<FieldTextarea>` / `<FieldCheckbox>`
+ * surface errors inline without any extra wiring.
+ *
+ * For wizard-style multi-step forms with auto-save, draft, publish — use
+ * `<FormShell steps={...}>` instead.
+ *
+ * Example:
+ *   <Form onSubmit={onSubmit}>
+ *     {({ setFieldError }) => (
+ *       <>
+ *         <FieldInput name="email" label="Email" required />
+ *         <Button type="submit">Sign in</Button>
+ *       </>
+ *     )}
+ *   </Form>
  */
-export declare function Form({ children, className, ...props }: FormProps): import("react/jsx-runtime").JSX.Element;
+export declare function Form({ children, spacing, schema, surface, padding, rounded, border, shadow, className, ...props }: FormProps): import("react/jsx-runtime").JSX.Element;
 export interface FormGroupProps {
     children: React.ReactNode;
     columns?: 1 | 2 | 3 | 4;

package/dist/ui/components/Form.js

@@ -1,5 +1,16 @@
+"use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Row } from "./Layout";
+import { buildSurfaceClasses } from "./surface-tokens";
+import { FormShellContext, useFormShellState, } from "../forms/FormShell";
+const FORM_SPACING_MAP = {
+    none: "",
+    xs: "space-y-1",
+    sm: "space-y-2",
+    md: "space-y-4",
+    lg: "space-y-6",
+    xl: "space-y-8",
+};
 const GAP_MAP = {
     none: "gap-0",
     xs: "gap-2",
@@ -9,10 +20,34 @@ const GAP_MAP = {
     xl: "gap-8 lg:gap-10",
 };
 /**
- * Semantic `<form>` wrapper. Passes all standard form attributes through.
+ * Canonical `<Form>` wrapper. Mounts `FormShellContext.Provider` so child
+ * `<FieldInput>` / `<FieldSelect>` / `<FieldTextarea>` / `<FieldCheckbox>`
+ * surface errors inline without any extra wiring.
+ *
+ * For wizard-style multi-step forms with auto-save, draft, publish — use
+ * `<FormShell steps={...}>` instead.
+ *
+ * Example:
+ *   <Form onSubmit={onSubmit}>
+ *     {({ setFieldError }) => (
+ *       <>
+ *         <FieldInput name="email" label="Email" required />
+ *         <Button type="submit">Sign in</Button>
+ *       </>
+ *     )}
+ *   </Form>
  */
-export function Form({ children, className = "", ...props }) {
-    return (_jsx("form", { className: ["appkit-form", className].filter(Boolean).join(" "), ...props, children: children }));
+export function Form({ children, spacing, schema, surface, padding, rounded, border, shadow, className = "", ...props }) {
+    const helpers = useFormShellState(schema);
+    const content = typeof children === "function"
+        ? children(helpers)
+        : children;
+    return (_jsx(FormShellContext.Provider, { value: helpers.shellCtx, children: _jsx("form", { className: [
+                "appkit-form",
+                spacing ? FORM_SPACING_MAP[spacing] : "",
+                buildSurfaceClasses({ surface, padding, rounded, border, shadow }),
+                className,
+            ].filter(Boolean).join(" "), ...props, children: content }) }));
 }
 export function FormGroup({ children, columns = 1, gap = "md", className = "", }) {
     const gridClasses = {

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

@@ -32,9 +32,9 @@ export interface FormFieldProps {
  * @example
  * ```tsx
  * <FormGrid>
- *   <FormField><Label>First name</Label><Input name="firstName" /></FormField>
- *   <FormField><Label>Last name</Label><Input name="lastName" /></FormField>
- *   <FormField span="full"><Label>Bio</Label><Textarea name="bio" /></FormField>
+ * <FormField><Label>First name</Label><Input name="firstName" /></FormField>
+ * <FormField><Label>Last name</Label><Input name="lastName" /></FormField>
+ * <FormField span="full"><Label>Bio</Label><Textarea name="bio" /></FormField>
  * </FormGrid>
  * ```
  */