@vantageos/mosaic 0.2.2 → 0.3.0-alpha.1

package/README.md

@@ -52,6 +52,143 @@ export function MyComponent({ progress, label }: { progress: number; label: stri
 }
 ```
 
+## Forms (v0.3.0-alpha.1)
+
+`@vantageos/mosaic/{react,preact}/forms` — composite form primitives wrapping `react-hook-form` + `@hookform/resolvers/zod`. Default validation mode is `onBlur` (Chi co-validated, Day 102 DM). Cross-runtime: same imports, React 19 path or Preact 10 path.
+
+### Install peers
+
+```sh
+npm install react-hook-form@^7.54.0 @hookform/resolvers@^3.10.0
+```
+
+Both peers are declared optional in `peerDependenciesMeta` — only install them if you use the forms surface.
+
+### Quick start
+
+```tsx
+import { z } from "zod";
+import {
+  useMosaicForm,
+  FormProvider,
+  FormField,
+  ErrorDisplay,
+  SubmitButton,
+} from "@vantageos/mosaic/react/forms";
+
+const schema = z.object({
+  email: z.string().email("Invalid email"),
+  age: z.number().min(18, "Must be 18+"),
+});
+
+export function SignupForm({ onSubmit }: { onSubmit: (data: z.infer<typeof schema>) => void }) {
+  const form = useMosaicForm({
+    schema,
+    defaultValues: { email: "", age: 0 },
+    // mode defaults to "onBlur" — Mosaic doctrine
+  });
+
+  return (
+    <FormProvider form={form}>
+      <form onSubmit={form.handleSubmit(onSubmit)}>
+        <FormField name="email">
+          {({ field, fieldState }) => (
+            <label>
+              Email
+              <input {...field} value={(field.value as string) ?? ""} />
+              <ErrorDisplay error={fieldState.error} />
+            </label>
+          )}
+        </FormField>
+        <SubmitButton label="Sign up" />
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+### Surface
+
+| Export | Purpose |
+|---|---|
+| `useMosaicForm({ schema, defaultValues, mode? })` | Wrapper around `useForm` + `zodResolver`. Returns RHF's `UseFormReturn` extended with `mosaicSchema` + `mosaicMode`. |
+| `<FormProvider form={...}>` | Wraps RHF's `FormProvider` AND a Mosaic-specific context. Use `useMosaicFormContext()` inside descendants. |
+| `<FormField name="...">{({ field, fieldState, formState }) => ...}</FormField>` | Render-prop wrapper around RHF's `Controller`. |
+| `<ErrorDisplay error={...} messageMap={...} />` | Single-field error formatter. Renders nothing when no error. Priority: `error.message` → `messageMap[type]` → generic fallback. |
+| `<SubmitButton label="..." loadingLabel="..." />` | Bound to the surrounding `FormProvider`. Disabled while invalid OR submitting. |
+| `<Input name="..." type="text\|email\|password\|number\|url" label="..." placeholder? disabled? autoComplete? />` | Single-field `<input>` bound to the surrounding `FormProvider`. `label` is required (consumer-driven i18n). Emits `aria-invalid` + `aria-describedby` on validation error. |
+
+Field primitives (Textarea, Select, Checkbox, MultiSelect, RadioGroup, FieldArray) land in T12-T20 — see `docs/v0.3.0-plan.md` §7.
+| `<Textarea name="..." rows? maxLength? autoResize? placeholder? disabled? label?  />` | Multi-line text input field primitive. `rows` default 3, `maxLength` enforced via shared logic gate, optional `autoResize` grows to content. `aria-invalid` + `aria-describedby` on error. |
+
+Remaining field primitives (Input shipped T11, Select, Checkbox, MultiSelect, RadioGroup, FieldArray) land in T13-T20 — see `docs/v0.3.0-plan.md` §7.
+| `useFieldArray({ name, control? })` | Thin wrapper around RHF's `useFieldArray`. Returns `{ fields, append, remove, move, swap }` + the rest of RHF's native return for advanced cases. Reads `control` from `FormProvider` when omitted. |
+| `<FieldArray name="...">{({ field, index }, { append, remove, move, swap, fields }) => ...}</FieldArray>` | Render-prop wrapper around `useFieldArray`. Emits `role="list"` shell + `role="listitem"` per row, keyed by RHF's stable `field.id` (NOT array index). Powers PromptForm Add Variable, Hermes variable mappings, Demeter filter chips. |
+
+| `<Checkbox name="..." label="..." indeterminate? description? disabled? />` | Boolean checkbox primitive. `indeterminate=true` → `aria-checked="mixed"` + DOM `.indeterminate=true` via ref. `description` wired via `aria-describedby`. `aria-invalid` + `aria-describedby` on error. |
+| `<RadioGroup name="..." label="..." options={[...]} orientation? disabled? />` | WCAG-AA radiogroup. Roving tabIndex, Arrow key selection sync, Home/End, Space/Enter. |
+
+Remaining field primitives (Input, Textarea, Select, MultiSelect) land in T11-T15 + T18-T20 — see `docs/v0.3.0-plan.md` §7.
+
+### RadioGroup
+
+Mutually exclusive single-choice field. Keyboard navigation follows WAI-ARIA radiogroup pattern (§3.10): Arrow keys move focus AND select simultaneously (roving tabindex). Disabled options are skipped during navigation.
+
+```tsx
+import { z } from "zod";
+import {
+  useMosaicForm,
+  FormProvider,
+  RadioGroup,
+} from "@vantageos/mosaic/react/forms";
+
+const schema = z.object({
+  plan: z.string().min(1, "Please select a plan"),
+});
+
+export function PlanSelector() {
+  const form = useMosaicForm({
+    schema,
+    defaultValues: { plan: "" },
+  });
+
+  return (
+    <FormProvider form={form}>
+      <form onSubmit={form.handleSubmit(console.log)}>
+        <RadioGroup
+          name="plan"
+          label="Select a plan"
+          options={[
+            { value: "free", label: "Free", description: "Up to 3 projects" },
+            { value: "pro", label: "Pro", description: "Unlimited projects" },
+            { value: "team", label: "Team", description: "Multi-user", disabled: false },
+          ]}
+          orientation="vertical"
+        />
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+**WCAG-AA contract:**
+- `role="radiogroup"` + `aria-labelledby` on container
+- `role="radio"` + `aria-checked` + roving `tabIndex` per option
+- `aria-labelledby` per option → its visible label span
+- `aria-describedby` per option → its description span (when present)
+- `aria-disabled` on disabled options; disabled options skipped in arrow nav
+- `aria-orientation` reflects `orientation` prop
+
+Field primitives (Textarea, Select, MultiSelect, RadioGroup, FieldArray) land in T12-T20 — see `docs/v0.3.0-plan.md` §7.
+| `<MultiSelect name="..." label="..." options={...} placeholder? disabled? searchable? maxItems? />` | Multi-value dropdown. RHF value is `string[]`. Selected items render as removable chips (Backspace/Delete on trigger removes last, per-chip × removes specific). WCAG-AA combobox (`role=combobox aria-multiselectable=true`), Arrow/Enter keyboard nav, optional case-insensitive search, optional `maxItems` cap. |
+
+Remaining field primitives (Input + Textarea + MultiSelect shipped T11/T12/T15; Select, Checkbox, RadioGroup, FieldArray) land in T13-T20 — see `docs/v0.3.0-plan.md` §7.
+| `<Select name="..." label="..." options={[...]} />` | Single-select dropdown (combobox+listbox APG). Optional `searchable` prop enables in-popup filter. Full keyboard nav + type-ahead. WCAG-AA strict. |
+
+Field primitives (Input, Textarea, Checkbox, MultiSelect, RadioGroup, FieldArray) land in T11, T14-T20 — see `docs/v0.3.0-plan.md` §7.
+
+
+
 ## Server (MCP UI)
 
 ```ts
@@ -64,6 +201,50 @@ const resource = createMosaicResource({
 // returns a SEP-1865-compliant MCP UI resource with text/html;profile=mcp-app MIME
 ```
 
+
+## Components
+
+### Display
+
+#### VirtualList
+
+Generic virtualized list for large datasets. Uses @tanstack/react-virtual v3 (already bundled via TableView). Cross-runtime: React 19 + Preact 10.
+
+```tsx
+import { VirtualList } from "@vantageos/mosaic/react/display";
+// Preact: import { VirtualList } from "@vantageos/mosaic/preact/display";
+
+type Task = { id: string; title: string; status: string };
+
+<VirtualList<Task>
+  items={tasks}
+  itemHeight={56}               // fixed px height
+  renderItem={(task, index) => (
+    <div key={task.id}>
+      <span>{task.title}</span>
+      <span>{task.status}</span>
+    </div>
+  )}
+  onRowClick={(task, index) => router.push('/tasks/' + task.id)}
+  overscan={5}                  // rows outside viewport (default 5)
+  className="task-list"
+  locale="en"                   // "en" | "fr"
+/>
+```
+
+**Props**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `items` | `T[]` | required | Items to render |
+| `itemHeight` | `number` | -- | Fixed row height px (mutually exclusive with `estimateSize`) |
+| `estimateSize` | `(index) => number` | -- | Variable height estimator |
+| `renderItem` | `(item: T, index: number) => ReactNode` | required | Row renderer |
+| `onRowClick` | `(item: T, index: number) => void` | `undefined` | Click handler — triggers WCAG-AA a11y (role=button + tabIndex=0 + Enter/Space) |
+| `overscan` | `number` | `5` | Rows outside visible area |
+| `className` | `string` | `undefined` | CSS class on scroll container |
+| `locale` | `"en" or "fr"` | `"en"` | Built-in string locale |
+
 ## Doctrine
 
 - **Pattern 1 (Zod runtime validation)** — every component validates props at the MCP host boundary; invalid props render an a11y fallback (`role="alert"`), never white-screen.

package/dist/Alert.schema-BQsZGG6P.d.cts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+
+/**
+ * Alert component props schema.
+ *
+ * Persistent inline banner (vs Toast which is ephemeral + auto-dismissing).
+ *
+ * variant      — controls visual style + ARIA role auto-assignment:
+ *                "error" → role="alert"  (assertive, interrupts screen reader)
+ *                all others → role="status" (polite, non-intrusive)
+ * title        — consumer-driven; caller passes already-localized string
+ * description  — optional supporting text beneath the title
+ * dismissible  — when true, renders a dismiss button (default: false)
+ * onDismiss    — callback fired when dismiss button is clicked
+ * locale       — controls dismiss button aria-label language
+ */
+declare const AlertPropsSchema: z.ZodObject<{
+    variant: z.ZodEnum<["success", "error", "info", "warning"]>;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    dismissible: z.ZodDefault<z.ZodBoolean>;
+    locale: z.ZodDefault<z.ZodEnum<["en", "fr"]>>;
+}, "strip", z.ZodTypeAny, {
+    locale: "en" | "fr";
+    title: string;
+    variant: "warning" | "error" | "success" | "info";
+    dismissible: boolean;
+    description?: string | undefined;
+}, {
+    title: string;
+    variant: "warning" | "error" | "success" | "info";
+    locale?: "en" | "fr" | undefined;
+    description?: string | undefined;
+    dismissible?: boolean | undefined;
+}>;
+type AlertProps = z.infer<typeof AlertPropsSchema> & {
+    onDismiss?: () => void;
+};
+declare function validateAlertProps(raw: unknown): z.infer<typeof AlertPropsSchema>;
+
+export { type AlertProps as A, AlertPropsSchema as a, validateAlertProps as v };

package/dist/Alert.schema-BQsZGG6P.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+
+/**
+ * Alert component props schema.
+ *
+ * Persistent inline banner (vs Toast which is ephemeral + auto-dismissing).
+ *
+ * variant      — controls visual style + ARIA role auto-assignment:
+ *                "error" → role="alert"  (assertive, interrupts screen reader)
+ *                all others → role="status" (polite, non-intrusive)
+ * title        — consumer-driven; caller passes already-localized string
+ * description  — optional supporting text beneath the title
+ * dismissible  — when true, renders a dismiss button (default: false)
+ * onDismiss    — callback fired when dismiss button is clicked
+ * locale       — controls dismiss button aria-label language
+ */
+declare const AlertPropsSchema: z.ZodObject<{
+    variant: z.ZodEnum<["success", "error", "info", "warning"]>;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    dismissible: z.ZodDefault<z.ZodBoolean>;
+    locale: z.ZodDefault<z.ZodEnum<["en", "fr"]>>;
+}, "strip", z.ZodTypeAny, {
+    locale: "en" | "fr";
+    title: string;
+    variant: "warning" | "error" | "success" | "info";
+    dismissible: boolean;
+    description?: string | undefined;
+}, {
+    title: string;
+    variant: "warning" | "error" | "success" | "info";
+    locale?: "en" | "fr" | undefined;
+    description?: string | undefined;
+    dismissible?: boolean | undefined;
+}>;
+type AlertProps = z.infer<typeof AlertPropsSchema> & {
+    onDismiss?: () => void;
+};
+declare function validateAlertProps(raw: unknown): z.infer<typeof AlertPropsSchema>;
+
+export { type AlertProps as A, AlertPropsSchema as a, validateAlertProps as v };

package/dist/ConfirmDialog-B3CQQGmJ.d.cts

@@ -0,0 +1,34 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { z } from 'zod';
+
+declare const ConfirmDialogPropsSchema: z.ZodObject<{
+    title: z.ZodString;
+    message: z.ZodString;
+    confirmLabel: z.ZodString;
+    cancelLabel: z.ZodString;
+    variant: z.ZodDefault<z.ZodEnum<["default", "danger"]>>;
+    locale: z.ZodDefault<z.ZodEnum<["en", "fr"]>>;
+}, "strip", z.ZodTypeAny, {
+    locale: "en" | "fr";
+    message: string;
+    title: string;
+    confirmLabel: string;
+    cancelLabel: string;
+    variant: "default" | "danger";
+}, {
+    message: string;
+    title: string;
+    confirmLabel: string;
+    cancelLabel: string;
+    locale?: "en" | "fr" | undefined;
+    variant?: "default" | "danger" | undefined;
+}>;
+type ConfirmDialogProps = z.infer<typeof ConfirmDialogPropsSchema> & {
+    onConfirm: () => void;
+    onCancel: () => void;
+};
+declare function validateConfirmDialogProps(raw: unknown): z.infer<typeof ConfirmDialogPropsSchema>;
+
+declare function ConfirmDialog(raw: Omit<ConfirmDialogProps, "variant" | "locale"> & Partial<Pick<ConfirmDialogProps, "variant" | "locale">>): react_jsx_runtime.JSX.Element | null;
+
+export { ConfirmDialog as C, type ConfirmDialogProps as a, ConfirmDialogPropsSchema as b, validateConfirmDialogProps as v };

package/dist/ConfirmDialog-B3CQQGmJ.d.ts

@@ -0,0 +1,34 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { z } from 'zod';
+
+declare const ConfirmDialogPropsSchema: z.ZodObject<{
+    title: z.ZodString;
+    message: z.ZodString;
+    confirmLabel: z.ZodString;
+    cancelLabel: z.ZodString;
+    variant: z.ZodDefault<z.ZodEnum<["default", "danger"]>>;
+    locale: z.ZodDefault<z.ZodEnum<["en", "fr"]>>;
+}, "strip", z.ZodTypeAny, {
+    locale: "en" | "fr";
+    message: string;
+    title: string;
+    confirmLabel: string;
+    cancelLabel: string;
+    variant: "default" | "danger";
+}, {
+    message: string;
+    title: string;
+    confirmLabel: string;
+    cancelLabel: string;
+    locale?: "en" | "fr" | undefined;
+    variant?: "default" | "danger" | undefined;
+}>;
+type ConfirmDialogProps = z.infer<typeof ConfirmDialogPropsSchema> & {
+    onConfirm: () => void;
+    onCancel: () => void;
+};
+declare function validateConfirmDialogProps(raw: unknown): z.infer<typeof ConfirmDialogPropsSchema>;
+
+declare function ConfirmDialog(raw: Omit<ConfirmDialogProps, "variant" | "locale"> & Partial<Pick<ConfirmDialogProps, "variant" | "locale">>): react_jsx_runtime.JSX.Element | null;
+
+export { ConfirmDialog as C, type ConfirmDialogProps as a, ConfirmDialogPropsSchema as b, validateConfirmDialogProps as v };

package/dist/Skeleton.schema-BO0ca2UX.d.cts

@@ -0,0 +1,135 @@
+import { z } from 'zod';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * EmptyState component props schema.
+ *
+ * Empty-set illustration + title + description + optional CTA.
+ * Consumer-driven i18n: caller passes already-localized strings.
+ *
+ * icon        — optional ReactNode / PreactNode passed by the caller
+ * title       — required heading (h2, consumer-driven i18n)
+ * description — optional supporting text
+ * action      — optional CTA: { label, onClick, variant? }
+ */
+declare const EmptyStatePropsSchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    action: z.ZodOptional<z.ZodObject<{
+        label: z.ZodString;
+        variant: z.ZodDefault<z.ZodEnum<["primary", "secondary"]>>;
+    }, "strip", z.ZodTypeAny, {
+        label: string;
+        variant: "primary" | "secondary";
+    }, {
+        label: string;
+        variant?: "primary" | "secondary" | undefined;
+    }>>;
+    locale: z.ZodDefault<z.ZodEnum<["en", "fr"]>>;
+}, "strip", z.ZodTypeAny, {
+    locale: "en" | "fr";
+    title: string;
+    description?: string | undefined;
+    action?: {
+        label: string;
+        variant: "primary" | "secondary";
+    } | undefined;
+}, {
+    title: string;
+    locale?: "en" | "fr" | undefined;
+    description?: string | undefined;
+    action?: {
+        label: string;
+        variant?: "primary" | "secondary" | undefined;
+    } | undefined;
+}>;
+type EmptyStatePropsSchemaInput = z.input<typeof EmptyStatePropsSchema>;
+type EmptyStatePropsSchemaOutput = z.output<typeof EmptyStatePropsSchema>;
+/**
+ * Full EmptyState props including framework-specific node types and callback.
+ * `icon` and `action.onClick` are excluded from Zod (functions/nodes are not serializable).
+ *
+ * Note: action.variant is optional for callers — Zod applies "primary" default at parse time.
+ */
+type EmptyStateProps = Omit<EmptyStatePropsSchemaOutput, "action"> & {
+    icon?: any;
+    action?: {
+        label: string;
+        variant?: "primary" | "secondary";
+        onClick: () => void;
+    };
+};
+declare function validateEmptyStateProps(raw: unknown): EmptyStatePropsSchemaOutput;
+
+/**
+ * Skeleton — cross-runtime loading placeholder (React 19 implementation).
+ *
+ * Accepts `Record<string, unknown>` for MCP postMessage injection safety.
+ * Zod validation narrows before render. Invalid props → accessible error span.
+ *
+ * Animation "none" is auto-applied when prefers-reduced-motion is set (via
+ * Tailwind's animate-pulse which respects the media query natively), or by
+ * passing animation="none" explicitly.
+ *
+ * WCAG-AA:
+ * - role="status" + aria-busy="true" on the container
+ * - aria-label resolves via t() in EN/FR
+ * - aria-hidden="true" on individual line spans (status role covers the group)
+ */
+declare function Skeleton(raw: Record<string, unknown>): react_jsx_runtime.JSX.Element;
+
+/**
+ * Skeleton component props schema.
+ *
+ * variant  — shape of the placeholder:
+ *            "rect"   → rectangular block (default)
+ *            "circle" → circular avatar / icon placeholder
+ *            "text"   → single or multi-line text placeholder
+ *
+ * width / height — CSS values (string) or pixels (number).
+ *   "rect" defaults: width="100%", height=100
+ *   "circle" defaults: width=height (equal, square rendered as circle)
+ *   "text" defaults: width="100%", height=16
+ *
+ * count  — number of text line spans (only meaningful for variant="text").
+ *          Default 1. Ignored for rect/circle.
+ *
+ * animation — shimmer style:
+ *   "pulse" → opacity pulse (default)
+ *   "wave"  → left-to-right gradient sweep
+ *   "none"  → static placeholder (auto-selected when prefers-reduced-motion)
+ */
+declare const SkeletonPropsSchema: z.ZodObject<{
+    variant: z.ZodDefault<z.ZodEnum<["rect", "circle", "text"]>>;
+    width: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    height: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    count: z.ZodDefault<z.ZodNumber>;
+    animation: z.ZodDefault<z.ZodEnum<["pulse", "wave", "none"]>>;
+    locale: z.ZodDefault<z.ZodEnum<["en", "fr"]>>;
+}, "strip", z.ZodTypeAny, {
+    locale: "en" | "fr";
+    variant: "text" | "rect" | "circle";
+    count: number;
+    animation: "none" | "pulse" | "wave";
+    width?: string | number | undefined;
+    height?: string | number | undefined;
+}, {
+    locale?: "en" | "fr" | undefined;
+    width?: string | number | undefined;
+    variant?: "text" | "rect" | "circle" | undefined;
+    count?: number | undefined;
+    height?: string | number | undefined;
+    animation?: "none" | "pulse" | "wave" | undefined;
+}>;
+type SkeletonProps = z.infer<typeof SkeletonPropsSchema>;
+declare function validateSkeletonProps(raw: unknown): SkeletonProps;
+/**
+ * Resolve final width/height CSS values given the variant and raw props.
+ * Centralised here so React + Preact runtimes share identical defaults.
+ */
+declare function resolveSkeletonDimensions(variant: SkeletonProps["variant"], width: SkeletonProps["width"], height: SkeletonProps["height"]): {
+    widthCss: string;
+    heightCss: string;
+};
+
+export { type EmptyStateProps as E, Skeleton as S, EmptyStatePropsSchema as a, type EmptyStatePropsSchemaInput as b, type EmptyStatePropsSchemaOutput as c, type SkeletonProps as d, SkeletonPropsSchema as e, validateSkeletonProps as f, resolveSkeletonDimensions as r, validateEmptyStateProps as v };

package/dist/Skeleton.schema-BO0ca2UX.d.ts

@@ -0,0 +1,135 @@
+import { z } from 'zod';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * EmptyState component props schema.
+ *
+ * Empty-set illustration + title + description + optional CTA.
+ * Consumer-driven i18n: caller passes already-localized strings.
+ *
+ * icon        — optional ReactNode / PreactNode passed by the caller
+ * title       — required heading (h2, consumer-driven i18n)
+ * description — optional supporting text
+ * action      — optional CTA: { label, onClick, variant? }
+ */
+declare const EmptyStatePropsSchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    action: z.ZodOptional<z.ZodObject<{
+        label: z.ZodString;
+        variant: z.ZodDefault<z.ZodEnum<["primary", "secondary"]>>;
+    }, "strip", z.ZodTypeAny, {
+        label: string;
+        variant: "primary" | "secondary";
+    }, {
+        label: string;
+        variant?: "primary" | "secondary" | undefined;
+    }>>;
+    locale: z.ZodDefault<z.ZodEnum<["en", "fr"]>>;
+}, "strip", z.ZodTypeAny, {
+    locale: "en" | "fr";
+    title: string;
+    description?: string | undefined;
+    action?: {
+        label: string;
+        variant: "primary" | "secondary";
+    } | undefined;
+}, {
+    title: string;
+    locale?: "en" | "fr" | undefined;
+    description?: string | undefined;
+    action?: {
+        label: string;
+        variant?: "primary" | "secondary" | undefined;
+    } | undefined;
+}>;
+type EmptyStatePropsSchemaInput = z.input<typeof EmptyStatePropsSchema>;
+type EmptyStatePropsSchemaOutput = z.output<typeof EmptyStatePropsSchema>;
+/**
+ * Full EmptyState props including framework-specific node types and callback.
+ * `icon` and `action.onClick` are excluded from Zod (functions/nodes are not serializable).
+ *
+ * Note: action.variant is optional for callers — Zod applies "primary" default at parse time.
+ */
+type EmptyStateProps = Omit<EmptyStatePropsSchemaOutput, "action"> & {
+    icon?: any;
+    action?: {
+        label: string;
+        variant?: "primary" | "secondary";
+        onClick: () => void;
+    };
+};
+declare function validateEmptyStateProps(raw: unknown): EmptyStatePropsSchemaOutput;
+
+/**
+ * Skeleton — cross-runtime loading placeholder (React 19 implementation).
+ *
+ * Accepts `Record<string, unknown>` for MCP postMessage injection safety.
+ * Zod validation narrows before render. Invalid props → accessible error span.
+ *
+ * Animation "none" is auto-applied when prefers-reduced-motion is set (via
+ * Tailwind's animate-pulse which respects the media query natively), or by
+ * passing animation="none" explicitly.
+ *
+ * WCAG-AA:
+ * - role="status" + aria-busy="true" on the container
+ * - aria-label resolves via t() in EN/FR
+ * - aria-hidden="true" on individual line spans (status role covers the group)
+ */
+declare function Skeleton(raw: Record<string, unknown>): react_jsx_runtime.JSX.Element;
+
+/**
+ * Skeleton component props schema.
+ *
+ * variant  — shape of the placeholder:
+ *            "rect"   → rectangular block (default)
+ *            "circle" → circular avatar / icon placeholder
+ *            "text"   → single or multi-line text placeholder
+ *
+ * width / height — CSS values (string) or pixels (number).
+ *   "rect" defaults: width="100%", height=100
+ *   "circle" defaults: width=height (equal, square rendered as circle)
+ *   "text" defaults: width="100%", height=16
+ *
+ * count  — number of text line spans (only meaningful for variant="text").
+ *          Default 1. Ignored for rect/circle.
+ *
+ * animation — shimmer style:
+ *   "pulse" → opacity pulse (default)
+ *   "wave"  → left-to-right gradient sweep
+ *   "none"  → static placeholder (auto-selected when prefers-reduced-motion)
+ */
+declare const SkeletonPropsSchema: z.ZodObject<{
+    variant: z.ZodDefault<z.ZodEnum<["rect", "circle", "text"]>>;
+    width: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    height: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    count: z.ZodDefault<z.ZodNumber>;
+    animation: z.ZodDefault<z.ZodEnum<["pulse", "wave", "none"]>>;
+    locale: z.ZodDefault<z.ZodEnum<["en", "fr"]>>;
+}, "strip", z.ZodTypeAny, {
+    locale: "en" | "fr";
+    variant: "text" | "rect" | "circle";
+    count: number;
+    animation: "none" | "pulse" | "wave";
+    width?: string | number | undefined;
+    height?: string | number | undefined;
+}, {
+    locale?: "en" | "fr" | undefined;
+    width?: string | number | undefined;
+    variant?: "text" | "rect" | "circle" | undefined;
+    count?: number | undefined;
+    height?: string | number | undefined;
+    animation?: "none" | "pulse" | "wave" | undefined;
+}>;
+type SkeletonProps = z.infer<typeof SkeletonPropsSchema>;
+declare function validateSkeletonProps(raw: unknown): SkeletonProps;
+/**
+ * Resolve final width/height CSS values given the variant and raw props.
+ * Centralised here so React + Preact runtimes share identical defaults.
+ */
+declare function resolveSkeletonDimensions(variant: SkeletonProps["variant"], width: SkeletonProps["width"], height: SkeletonProps["height"]): {
+    widthCss: string;
+    heightCss: string;
+};
+
+export { type EmptyStateProps as E, Skeleton as S, EmptyStatePropsSchema as a, type EmptyStatePropsSchemaInput as b, type EmptyStatePropsSchemaOutput as c, type SkeletonProps as d, SkeletonPropsSchema as e, validateSkeletonProps as f, resolveSkeletonDimensions as r, validateEmptyStateProps as v };