@vantageos/mosaic 0.2.2 → 0.3.0

package/dist/preact/display.d.ts

@@ -1,2 +1,367 @@
+import * as preact from 'preact';
+import { ComponentChildren, h } from 'preact';
+import { z } from 'zod';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { Observable } from 'rxjs';
 
-export {  }
+/**
+ * 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, {
+    title: string;
+    locale: "en" | "fr";
+    description?: string | undefined;
+    action?: {
+        label: string;
+        variant: "primary" | "secondary";
+    } | undefined;
+}, {
+    title: string;
+    description?: string | undefined;
+    action?: {
+        label: string;
+        variant?: "primary" | "secondary" | undefined;
+    } | undefined;
+    locale?: "en" | "fr" | undefined;
+}>;
+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;
+
+/**
+ * EmptyState — cross-runtime empty-set display primitive (Preact 10 implementation).
+ *
+ * Accepts `Record<string, unknown>` for MCP postMessage injection safety.
+ * Zod validation narrows before render. Invalid props → accessible error span.
+ *
+ * WCAG-AA:
+ * - <section aria-label={title}> → role="region" landmark (no Biome lint, correct semantics)
+ * - heading hierarchy: h2 (title) — caller manages the h1 context
+ * - action button is keyboard-accessible (tab + enter/space)
+ */
+declare function EmptyState(raw: Omit<EmptyStateProps, "locale"> & Partial<Pick<EmptyStateProps, "locale">> & {
+    icon?: ComponentChildren;
+}): preact.JSX.Element;
+
+/** @jsxRuntime classic */
+/** @jsx h */
+
+/**
+ * Skeleton — cross-runtime loading placeholder (Preact 10 implementation).
+ *
+ * Structurally identical to the React runtime; JSX differences:
+ * - `class` instead of `className`
+ * - Preact h/Fragment imports
+ * - No "use client" directive (Preact runs in extension context)
+ *
+ * WCAG-AA: role="status" + aria-busy="true" + aria-label via t()
+ */
+declare function Skeleton(raw: Record<string, unknown>): h.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, {
+    variant: "circle" | "rect" | "text";
+    locale: "en" | "fr";
+    count: number;
+    animation: "none" | "pulse" | "wave";
+    width?: string | number | undefined;
+    height?: string | number | undefined;
+}, {
+    variant?: "circle" | "rect" | "text" | undefined;
+    locale?: "en" | "fr" | undefined;
+    width?: string | number | undefined;
+    height?: string | number | undefined;
+    count?: 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;
+};
+
+/**
+ * VirtualList Zod props schema.
+ *
+ * Runtime functions (renderItem, estimateSize, onRowClick) are excluded from
+ * Zod per §18.5 (runtime functions not serialisable). They are typed separately
+ * in VirtualListProps<T> below.
+ *
+ * Serialisable fields validated at render time for safe MCP postMessage injection.
+ */
+declare const VirtualListPropsSchema: z.ZodObject<{
+    /** Array of items to render — required, can be empty */
+    items: z.ZodArray<z.ZodUnknown, "many">;
+    /** Fixed row height in px — mutually exclusive with estimateSize */
+    itemHeight: z.ZodOptional<z.ZodNumber>;
+    /** Variable row height estimator — mutually exclusive with itemHeight */
+    estimateSize: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodNumber], z.ZodUnknown>, z.ZodNumber>>;
+    /** Row renderer — required (runtime function, excluded from strict Zod parse but validated for presence) */
+    renderItem: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodUnknown, z.ZodNumber], z.ZodUnknown>, z.ZodUnknown>>;
+    /** Rows to render outside visible area (default: 5) */
+    overscan: z.ZodOptional<z.ZodNumber>;
+    /** CSS class applied to the scroll container */
+    className: z.ZodOptional<z.ZodString>;
+    /** Locale for built-in empty state + error messages */
+    locale: z.ZodOptional<z.ZodEnum<["en", "fr"]>>;
+    /** a11y: when provided, rows become keyboard-activable (role=button + tabIndex=0 + Enter/Space) */
+    onRowClick: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodUnknown, z.ZodNumber], z.ZodUnknown>, z.ZodVoid>>;
+}, "strip", z.ZodTypeAny, {
+    items: unknown[];
+    locale?: "en" | "fr" | undefined;
+    itemHeight?: number | undefined;
+    estimateSize?: ((args_0: number, ...args: unknown[]) => number) | undefined;
+    renderItem?: ((args_0: unknown, args_1: number, ...args: unknown[]) => unknown) | undefined;
+    overscan?: number | undefined;
+    className?: string | undefined;
+    onRowClick?: ((args_0: unknown, args_1: number, ...args: unknown[]) => void) | undefined;
+}, {
+    items: unknown[];
+    locale?: "en" | "fr" | undefined;
+    itemHeight?: number | undefined;
+    estimateSize?: ((args_0: number, ...args: unknown[]) => number) | undefined;
+    renderItem?: ((args_0: unknown, args_1: number, ...args: unknown[]) => unknown) | undefined;
+    overscan?: number | undefined;
+    className?: string | undefined;
+    onRowClick?: ((args_0: unknown, args_1: number, ...args: unknown[]) => void) | undefined;
+}>;
+type VirtualListPropsSchemaOutput = z.output<typeof VirtualListPropsSchema>;
+/**
+ * Full typed VirtualList props for JSX consumers.
+ * Generic over item type T.
+ */
+type VirtualListProps<T = unknown> = {
+    /** Array of items to render */
+    items: T[];
+    /** Fixed row height in px — use when all rows are the same height */
+    itemHeight?: number;
+    /** Variable height estimator — use when rows have different heights */
+    estimateSize?: (index: number) => number;
+    /** Required: renders one item */
+    renderItem: (item: T, index: number) => ReactNode;
+    /** Called when a row is clicked/activated — triggers a11y role=button + keyboard */
+    onRowClick?: (item: T, index: number) => void;
+    /** Rows rendered outside viewport (default: 5) */
+    overscan?: number;
+    /** CSS class applied to the scroll container */
+    className?: string;
+    /** Locale for built-in strings (default: "en") */
+    locale?: "en" | "fr";
+};
+/** Validates serialisable portion of VirtualList props — throws on failure */
+declare function validateVirtualListProps(raw: unknown): VirtualListPropsSchemaOutput;
+
+/**
+ * VirtualList — generic virtualized list component.
+ *
+ * Cross-runtime: same file used by React 19 and Preact 10 (via preact/compat alias in tsup).
+ * Virtualization: @tanstack/react-virtual v3 (already in mosaic deps via TableView).
+ * a11y: WCAG-AA — when onRowClick provided, rows get role=button + tabIndex=0 + Enter/Space.
+ * Zod-validated serialisable props; renders role="alert" fallback on failure.
+ *
+ * API:
+ *   items: T[]                                     — generic item array
+ *   itemHeight?: number                            — fixed px height (mutually exclusive with estimateSize)
+ *   estimateSize?: (index) => number              — variable height estimator
+ *   renderItem: (item, index) => ReactNode        — required row renderer
+ *   onRowClick?: (item, index) => void            — a11y click handler
+ *   overscan?: number                              — rows outside viewport (default: 5)
+ *   className?: string                             — scroll container class
+ *   locale?: "en" | "fr"                          — built-in string locale
+ */
+declare function VirtualList<T = unknown>(props: VirtualListProps<T>): react_jsx_runtime.JSX.Element;
+
+/**
+ * StatusBadge — cross-runtime status indicator badge (Preact 10 implementation).
+ *
+ * Accepts `Record<string, unknown>` for MCP postMessage injection safety.
+ * Zod validation narrows before render. Invalid props → accessible error span.
+ *
+ * WCAG-AA:
+ * - `<output>` has implicit role="status" per ARIA spec §5.3.17
+ * - aria-label from `label` prop (falls back to `status` string)
+ * - `lang` attribute set to locale for correct AT language announcement
+ *
+ * Bilingue: EN/FR strings resolved via t() from i18n/strings — no hardcoded literals.
+ */
+declare function StatusBadge(raw: Record<string, unknown>): preact.JSX.Element;
+
+declare const StatusBadgePropsSchema: z.ZodObject<{
+    status: z.ZodString;
+    variant: z.ZodDefault<z.ZodEnum<["success", "warning", "danger", "info", "neutral"]>>;
+    label: z.ZodOptional<z.ZodString>;
+    locale: z.ZodEnum<["en", "fr"]>;
+}, "strip", z.ZodTypeAny, {
+    variant: "success" | "warning" | "danger" | "info" | "neutral";
+    status: string;
+    locale: "en" | "fr";
+    label?: string | undefined;
+}, {
+    status: string;
+    locale: "en" | "fr";
+    label?: string | undefined;
+    variant?: "success" | "warning" | "danger" | "info" | "neutral" | undefined;
+}>;
+type StatusBadgeProps = z.infer<typeof StatusBadgePropsSchema>;
+declare function validateProps(raw: unknown): StatusBadgeProps;
+
+type ColumnDef<TRow extends Record<string, unknown> = Record<string, unknown>> = {
+    key: string;
+    header: string;
+    render?: (row: TRow) => ReactNode;
+};
+/**
+ * Validates the serialisable (non-function) portion of TableView props.
+ * The `rows$` Observable and `render` callbacks are not Zod-parseable and
+ * must be validated at the call-site type level.
+ */
+declare const TableViewPropsSchema: z.ZodObject<{
+    columns: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        header: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        header: string;
+        key: string;
+    }, {
+        header: string;
+        key: string;
+    }>, "many">;
+    virtualizeThreshold: z.ZodDefault<z.ZodNumber>;
+    ariaLabel: z.ZodString;
+    locale: z.ZodDefault<z.ZodEnum<["en", "fr"]>>;
+}, "strip", z.ZodTypeAny, {
+    locale: "en" | "fr";
+    columns: {
+        header: string;
+        key: string;
+    }[];
+    virtualizeThreshold: number;
+    ariaLabel: string;
+}, {
+    columns: {
+        header: string;
+        key: string;
+    }[];
+    ariaLabel: string;
+    locale?: "en" | "fr" | undefined;
+    virtualizeThreshold?: number | undefined;
+}>;
+type TableViewPropsSchemaOutput = z.output<typeof TableViewPropsSchema>;
+/**
+ * Props for the static TableView — accepts a plain array of rows.
+ * Primary API for already-fetched data (no rxjs required).
+ */
+type TableViewProps<TRow extends Record<string, unknown> = Record<string, unknown>> = {
+    columns: ColumnDef<TRow>[];
+    rows: Partial<TRow>[];
+    virtualizeThreshold?: number;
+    ariaLabel: string;
+    locale?: "en" | "fr";
+    /** v0.2.1+: when provided, rows become keyboard-activable (role=button + tabIndex=0 + Enter/Space). 5-BU ABSOLUTE blocker fix. */
+    onRowClick?: (row: TRow, index: number) => void;
+};
+/**
+ * Props for StreamingTableView — accepts an RxJS Observable for incremental row appending.
+ * Consumers using this variant MUST install rxjs ^7.8.0 in their project.
+ */
+type StreamingTableViewProps<TRow extends Record<string, unknown> = Record<string, unknown>> = {
+    columns: ColumnDef<TRow>[];
+    rows$: Observable<Partial<TRow>[]>;
+    virtualizeThreshold?: number;
+    ariaLabel: string;
+    locale?: "en" | "fr";
+    /** v0.2.1+: same semantics as static TableView. */
+    onRowClick?: (row: TRow, index: number) => void;
+};
+declare function validateTableViewProps(raw: unknown): TableViewPropsSchemaOutput;
+
+/**
+ * TableView — Static rows variant (primary API).
+ *
+ * Accepts `rows: Row[]` for already-fetched data — no rxjs required.
+ * Activates TanStack Virtual v3 windowing when rows.length > virtualizeThreshold.
+ * Zod-validates serialisable props; renders role="alert" fallback on failure.
+ * Fully accessible: aria-rowcount, aria-label, scope="col".
+ */
+declare function TableView<TRow extends Record<string, unknown> = Record<string, unknown>>(props: TableViewProps<TRow>): react_jsx_runtime.JSX.Element;
+/**
+ * StreamingTableView — Streaming rows variant (advanced, opt-in).
+ *
+ * Pattern 4 Streaming Hydration reference implementation.
+ * Consumes an RxJS Observable<Row[]> for incremental row appending.
+ * Consumers MUST install rxjs ^7.8.0 in their project.
+ * Activates TanStack Virtual v3 windowing when rows.length > virtualizeThreshold.
+ * Zod-validates serialisable props; renders role="alert" fallback on failure.
+ * Fully accessible: aria-rowcount, aria-label, scope="col".
+ */
+declare function StreamingTableView<TRow extends Record<string, unknown> = Record<string, unknown>>(props: StreamingTableViewProps<TRow>): react_jsx_runtime.JSX.Element;
+
+export { EmptyState, type EmptyStateProps, EmptyStatePropsSchema, Skeleton, type SkeletonProps, SkeletonPropsSchema, StatusBadge, type StatusBadgeProps, StatusBadgePropsSchema, StreamingTableView, type StreamingTableViewProps, TableView, type TableViewProps, TableViewPropsSchema, VirtualList, type VirtualListProps, VirtualListPropsSchema, resolveSkeletonDimensions, validateEmptyStateProps, validateSkeletonProps, validateProps as validateStatusBadgeProps, validateTableViewProps, validateVirtualListProps };