@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/components/signature-pad.d.ts

@@ -0,0 +1,85 @@
+import * as React from "react";
+/** A point: x, y in pad pixels and pressure 0–1. */
+export type SignaturePoint = [x: number, y: number, pressure: number];
+export interface SignatureValue {
+    kind: "drawn" | "typed";
+    /** Standalone SVG document; ink is always solid dark so it prints on paper. */
+    svg: string;
+    /** PNG data URL (with `exportPng`). */
+    png?: string;
+    /** The typed name (typed signatures). */
+    text?: string;
+    /** Raw strokes of a drawn signature (keeps undo working after reload). */
+    strokes?: SignaturePoint[][];
+    /** Size of the pad the strokes were drawn on. */
+    width?: number;
+    height?: number;
+    /** ISO instant. */
+    signedAt: string;
+}
+/** Exported ink colour: the same in light and dark themes, so stored signatures print correctly. */
+export declare const SIGNATURE_INK = "#14170f";
+/** SVG path data for a perfect-freehand outline. */
+export declare function outlineToPath(outline: number[][]): string;
+/** SVG path for one stroke (a dot when it is a single tap). */
+export declare function strokeToPath(points: SignaturePoint[], simulatePressure?: boolean): string;
+/** Standalone SVG of drawn strokes. */
+export declare function strokesToSvg(strokes: SignaturePoint[][], width: number, height: number): string;
+/** Standalone SVG of a typed name. */
+export declare function textToSvg(text: string, width: number, height: number): string;
+/** PNG data URL of drawn strokes (transparent background). */
+export declare function strokesToPng(strokes: SignaturePoint[][], width: number, height: number): string | undefined;
+/** SVG data URL, for `<img src>` (safe: images never run scripts). */
+export declare const svgDataUrl: (svg: string) => string;
+declare const signatureLabels: {
+    draw: string;
+    type: string;
+    clear: string;
+    undo: string;
+    placeholder: string;
+    typePlaceholder: string;
+    typeLabel: string;
+    pad: string;
+    drawn: string;
+    preview: string;
+    signed: string;
+    signature: string;
+    empty: string;
+    cleared: string;
+};
+export type SignaturePadLabels = typeof signatureLabels;
+export interface SignaturePadProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "defaultValue" | "onChange"> {
+    value?: SignatureValue | null;
+    defaultValue?: SignatureValue | null;
+    onValueChange?: (value: SignatureValue | null) => void;
+    /** Available modes. Default both — Type is the keyboard-accessible path, keep it unless another one exists. */
+    modes?: ("draw" | "type")[];
+    /** Pad height in px. Default 176. */
+    height?: number;
+    /** On-screen ink. Exported ink is always solid dark. Default `"fg"`. */
+    penColor?: "fg" | "accent";
+    /** Include a PNG data URL in the value (and in the hidden input instead of SVG). */
+    exportPng?: boolean;
+    /** Hidden input name; carries the SVG (or the PNG data URL with `exportPng`). */
+    name?: string;
+    disabled?: boolean;
+    /** Shows the stored signature as an image with its timestamp. */
+    readOnly?: boolean;
+    invalid?: boolean;
+    required?: boolean;
+    labels?: Partial<SignaturePadLabels>;
+}
+/**
+ * Captures a handwritten (pointer: mouse, pen with pressure, touch) or typed signature. Strokes
+ * are smoothed with `perfect-freehand` and exported as SVG (and PNG on request); the ink you
+ * export is always dark, so stored signatures print correctly in any theme.
+ *
+ * A drawn or typed image is not a qualified electronic signature (eIDAS, Turkey's Law 5070) —
+ * the legal wording around it is the app's responsibility.
+ *
+ * ```tsx
+ * <Field label="Customer signature" required><SignaturePad name="signature" exportPng /></Field>
+ * ```
+ */
+export declare const SignaturePad: React.ForwardRefExoticComponent<SignaturePadProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/components/signature-pad.js

@@ -0,0 +1,283 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { getStroke } from "perfect-freehand";
+import { Eraser, PenLine, Type, Undo2 } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { mergeIds } from "../lib/compose-refs.js";
+import { useFieldContext } from "../lib/field-context.js";
+import { useLabels } from "../lib/labels.js";
+import { useFormat } from "../lib/locale.js";
+import { useControllableState, useLatest } from "../lib/use-controllable-state.js";
+import { useContainerWidth } from "../lib/use-container-width.js";
+import { Button } from "./button.js";
+import { Input } from "./input.js";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "./tabs.js";
+/** Exported ink colour: the same in light and dark themes, so stored signatures print correctly. */
+export const SIGNATURE_INK = "#14170f";
+/** Font stack for typed signatures (override `--font-signature` to load a handwriting font). */
+const TYPED_FONT = "var(--font-signature)";
+const TYPED_FONT_EXPORT = '"Segoe Script", "Snell Roundhand", "Brush Script MT", "Apple Chancery", cursive';
+const STROKE_OPTIONS = { size: 3.4, thinning: 0.62, smoothing: 0.55, streamline: 0.45, start: { taper: 6 }, end: { taper: 10 } };
+/** SVG path data for a perfect-freehand outline. */
+export function outlineToPath(outline) {
+    if (outline.length < 2)
+        return "";
+    const r = (n) => Math.round(n * 100) / 100;
+    let d = `M${r(outline[0][0])} ${r(outline[0][1])}Q`;
+    for (let i = 0; i < outline.length; i++) {
+        const [x0, y0] = outline[i];
+        const [x1, y1] = outline[(i + 1) % outline.length];
+        d += `${r(x0)} ${r(y0)} ${r((x0 + x1) / 2)} ${r((y0 + y1) / 2)} `;
+    }
+    return `${d.trim()}Z`;
+}
+/** SVG path for one stroke (a dot when it is a single tap). */
+export function strokeToPath(points, simulatePressure = true) {
+    return outlineToPath(getStroke(points, { ...STROKE_OPTIONS, simulatePressure }));
+}
+const escapeXml = (s) => s.replace(/[<>&"']/g, (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;", '"': "&quot;", "'": "&apos;" })[c]);
+/** Standalone SVG of drawn strokes. */
+export function strokesToSvg(strokes, width, height) {
+    const paths = strokes.map((s) => `<path d="${strokeToPath(s)}"/>`).join("");
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${Math.round(width)} ${Math.round(height)}" width="${Math.round(width)}" height="${Math.round(height)}" fill="${SIGNATURE_INK}">${paths}</svg>`;
+}
+function typedFontSize(height) {
+    return Math.round(Math.min(56, height * 0.32));
+}
+/** Standalone SVG of a typed name. */
+export function textToSvg(text, width, height) {
+    const size = typedFontSize(height);
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${Math.round(width)} ${Math.round(height)}" width="${Math.round(width)}" height="${Math.round(height)}"><text x="24" y="${Math.round(height * 0.68)}" font-family='${TYPED_FONT_EXPORT}' font-size="${size}" font-style="italic" fill="${SIGNATURE_INK}">${escapeXml(text)}</text></svg>`;
+}
+function toPng(width, height, draw) {
+    try {
+        if (typeof document === "undefined")
+            return undefined;
+        const scale = 2;
+        const canvas = document.createElement("canvas");
+        canvas.width = Math.round(width * scale);
+        canvas.height = Math.round(height * scale);
+        const ctx = canvas.getContext("2d");
+        if (!ctx)
+            return undefined;
+        ctx.scale(scale, scale);
+        ctx.fillStyle = SIGNATURE_INK;
+        draw(ctx);
+        return canvas.toDataURL("image/png");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** PNG data URL of drawn strokes (transparent background). */
+export function strokesToPng(strokes, width, height) {
+    if (typeof Path2D === "undefined")
+        return undefined;
+    return toPng(width, height, (ctx) => strokes.forEach((s) => ctx.fill(new Path2D(strokeToPath(s)))));
+}
+/** SVG data URL, for `<img src>` (safe: images never run scripts). */
+export const svgDataUrl = (svg) => `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+/* ------------------------------------------------------------------ */
+/* SignaturePad                                                        */
+/* ------------------------------------------------------------------ */
+const signatureLabels = {
+    draw: "Draw",
+    type: "Type",
+    clear: "Clear",
+    undo: "Undo",
+    placeholder: "Sign here",
+    typePlaceholder: "Type your full name",
+    typeLabel: "Full name",
+    pad: "Signature pad. Drawing needs a mouse, pen or finger; use Type to sign with the keyboard.",
+    drawn: "Signature drawn, {count, plural, one {# stroke} other {# strokes}}",
+    preview: "Signature preview",
+    signed: "Signed {date}",
+    signature: "Signature",
+    empty: "Not signed",
+    cleared: "Signature cleared",
+};
+/**
+ * Captures a handwritten (pointer: mouse, pen with pressure, touch) or typed signature. Strokes
+ * are smoothed with `perfect-freehand` and exported as SVG (and PNG on request); the ink you
+ * export is always dark, so stored signatures print correctly in any theme.
+ *
+ * A drawn or typed image is not a qualified electronic signature (eIDAS, Turkey's Law 5070) —
+ * the legal wording around it is the app's responsibility.
+ *
+ * ```tsx
+ * <Field label="Customer signature" required><SignaturePad name="signature" exportPng /></Field>
+ * ```
+ */
+export const SignaturePad = React.forwardRef(function SignaturePad(props, ref) {
+    const { value, defaultValue, onValueChange, modes = ["draw", "type"], height = 176, penColor = "fg", exportPng = false, name, disabled: disabledProp, readOnly: readOnlyProp, invalid: invalidProp, required: requiredProp, labels, className, id, "aria-describedby": describedBy, ...rest } = props;
+    const field = useFieldContext();
+    const disabled = disabledProp ?? field?.disabled ?? false;
+    const readOnly = readOnlyProp ?? field?.readOnly ?? false;
+    const invalid = invalidProp ?? field?.invalid ?? false;
+    const required = requiredProp ?? field?.required ?? false;
+    const submitName = name ?? field?.name;
+    const t = useLabels("signature", signatureLabels, labels);
+    const f = useFormat();
+    const autoId = React.useId();
+    const rootId = id ?? field?.id ?? `sig${autoId.replace(/:/g, "")}`;
+    const [sig, setSig] = useControllableState({ value, defaultValue: defaultValue ?? null, onChange: onValueChange, name: "SignaturePad" });
+    const [mode, setMode] = React.useState(sig?.kind === "typed" && modes.includes("type") ? "type" : modes[0] ?? "draw");
+    const [strokes, setStrokes] = React.useState(() => (sig?.kind === "drawn" ? sig.strokes ?? [] : []));
+    const [current, setCurrent] = React.useState(null);
+    const [typed, setTyped] = React.useState(sig?.kind === "typed" ? sig.text ?? "" : "");
+    const [announce, setAnnounce] = React.useState("");
+    const { ref: measureRef, width: measured } = useContainerWidth();
+    const width = measured ?? 480;
+    const padSize = React.useRef(sig?.width && sig.height ? { w: sig.width, h: sig.height } : null);
+    const drawing = React.useRef(null);
+    const currentRef = React.useRef(null);
+    const latest = useLatest({ strokes, typed, width, height, exportPng });
+    // Controlled reset (e.g. parent clears the value).
+    React.useEffect(() => {
+        if (value === undefined)
+            return;
+        if (value === null) {
+            setStrokes([]);
+            setTyped("");
+            padSize.current = null;
+        }
+        else if (value.kind === "drawn" && value.strokes && value.strokes !== latest.current.strokes) {
+            setStrokes(value.strokes);
+            if (value.width && value.height)
+                padSize.current = { w: value.width, h: value.height };
+        }
+        else if (value.kind === "typed" && value.text !== undefined && value.text !== latest.current.typed)
+            setTyped(value.text);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [value]);
+    const emitDrawn = (next) => {
+        if (!next.length) {
+            setSig(null);
+            return;
+        }
+        const size = padSize.current ?? { w: latest.current.width, h: latest.current.height };
+        setSig({
+            kind: "drawn",
+            svg: strokesToSvg(next, size.w, size.h),
+            png: latest.current.exportPng ? strokesToPng(next, size.w, size.h) : undefined,
+            strokes: next,
+            width: size.w,
+            height: size.h,
+            signedAt: new Date().toISOString(),
+        });
+    };
+    const emitTyped = (text) => {
+        const name = text.trim();
+        if (!name) {
+            setSig(null);
+            return;
+        }
+        const { width: w, height: h, exportPng: png } = latest.current;
+        setSig({
+            kind: "typed",
+            text: name,
+            svg: textToSvg(name, w, h),
+            png: png
+                ? toPng(w, h, (ctx) => {
+                    ctx.font = `italic ${typedFontSize(h)}px ${TYPED_FONT_EXPORT}`;
+                    ctx.fillText(name, 24, h * 0.68);
+                })
+                : undefined,
+            width: w,
+            height: h,
+            signedAt: new Date().toISOString(),
+        });
+    };
+    const inert = disabled || readOnly;
+    const point = (e, rect) => {
+        const size = padSize.current;
+        const sx = size ? size.w / rect.width : 1;
+        const sy = size ? size.h / rect.height : 1;
+        return [(e.clientX - rect.left) * sx, (e.clientY - rect.top) * sy, e.pointerType === "pen" ? e.pressure || 0.5 : 0.5];
+    };
+    const onPointerDown = (e) => {
+        if (inert || (e.pointerType === "mouse" && e.button !== 0))
+            return;
+        e.preventDefault();
+        const rect = e.currentTarget.getBoundingClientRect();
+        if (!padSize.current)
+            padSize.current = { w: rect.width || width, h: rect.height || height };
+        try {
+            e.currentTarget.setPointerCapture(e.pointerId);
+        }
+        catch {
+            /* ignore */
+        }
+        drawing.current = { id: e.pointerId, pen: e.pointerType === "pen", rect };
+        currentRef.current = [point(e, rect)];
+        setCurrent(currentRef.current);
+    };
+    const onPointerMove = (e) => {
+        const d = drawing.current;
+        if (!d || d.id !== e.pointerId)
+            return;
+        const events = typeof e.nativeEvent.getCoalescedEvents === "function" ? e.nativeEvent.getCoalescedEvents() : [];
+        const pts = (events.length ? events : [e.nativeEvent]).map((ev) => point(ev, d.rect));
+        if (!currentRef.current)
+            return;
+        currentRef.current = [...currentRef.current, ...pts];
+        setCurrent(currentRef.current);
+    };
+    const finish = (e) => {
+        const d = drawing.current;
+        if (!d || d.id !== e.pointerId)
+            return;
+        drawing.current = null;
+        const c = currentRef.current;
+        currentRef.current = null;
+        setCurrent(null);
+        if (!c?.length)
+            return;
+        const next = [...latest.current.strokes, c];
+        setStrokes(next);
+        emitDrawn(next);
+        setAnnounce(t("drawn", { count: next.length }));
+    };
+    const undo = () => {
+        if (mode === "type") {
+            setTyped("");
+            emitTyped("");
+            return;
+        }
+        const next = strokes.slice(0, -1);
+        setStrokes(next);
+        if (!next.length)
+            padSize.current = null;
+        emitDrawn(next);
+        setAnnounce(next.length ? t("drawn", { count: next.length }) : t("cleared"));
+    };
+    const clear = () => {
+        setStrokes([]);
+        setTyped("");
+        padSize.current = null;
+        setSig(null);
+        setAnnounce(t("cleared"));
+    };
+    const ink = penColor === "accent" ? "text-accent-ink" : "text-fg";
+    const viewW = padSize.current?.w ?? width;
+    const viewH = padSize.current?.h ?? height;
+    const hasDrawing = strokes.length > 0 || !!current;
+    const empty = mode === "draw" ? !hasDrawing : !typed.trim();
+    const hidden = submitName ? _jsx("input", { type: "hidden", name: submitName, value: sig ? (exportPng && sig.png ? sig.png : sig.svg) : "", disabled: disabled }) : null;
+    const groupLabel = field?.labelId ? { "aria-labelledby": field.labelId } : { "aria-label": t("signature") };
+    const surface = cn("ui-signature relative w-full overflow-hidden rounded-ui border bg-field select-none touch-none", invalid ? "border-danger" : "border-field-border", disabled && "opacity-50");
+    const baseline = (_jsx("span", { "aria-hidden": true, className: "pointer-events-none absolute inset-x-6 bottom-[26%] flex items-end gap-2 border-b border-dashed border-line pb-1", children: _jsx("span", { className: "font-display text-lg leading-none text-fg-subtle", children: "\u00D7" }) }));
+    /* ---------------- read-only ---------------- */
+    if (readOnly) {
+        return (_jsxs("div", { ref: ref, ...rest, id: rootId, role: "group", ...groupLabel, "aria-describedby": mergeIds(field?.describedBy, describedBy), "data-slot": "signature-pad", "data-readonly": "", className: cn("grid min-w-0 gap-1.5", className), children: [_jsxs("div", { className: cn(surface, "border-dashed bg-transparent"), style: { height }, children: [sig ? _jsx("img", { src: svgDataUrl(sig.svg), alt: sig.kind === "typed" && sig.text ? `${t("signature")}: ${sig.text}` : t("signature"), className: "ui-signature-ink absolute inset-0 size-full object-contain object-left p-3" }) : _jsx("span", { className: "absolute inset-0 flex items-center justify-center text-sm text-fg-subtle", children: t("empty") }), baseline] }), sig ? _jsx("p", { className: "text-xs text-fg-subtle tabular", children: t("signed", { date: f.dateTime(sig.signedAt) }) }) : null, hidden] }));
+    }
+    /* ---------------- editable ---------------- */
+    const drawPad = (_jsxs("div", { ref: measureRef, className: surface, style: { height }, "data-empty": !hasDrawing ? "" : undefined, children: [baseline, !hasDrawing ? (_jsx("span", { "aria-hidden": true, className: "pointer-events-none absolute bottom-[calc(26%+0.5rem)] start-12 text-sm text-fg-subtle", children: t("placeholder") })) : null, _jsxs("svg", { role: "img", "aria-label": t("pad"), viewBox: `0 0 ${viewW} ${viewH}`, preserveAspectRatio: "xMinYMid meet", className: cn("absolute inset-0 size-full", ink, inert ? "cursor-not-allowed" : "cursor-crosshair"), fill: "currentColor", onPointerDown: onPointerDown, onPointerMove: onPointerMove, onPointerUp: finish, onPointerCancel: finish, "data-slot": "signature-pad-canvas", children: [strokes.map((s, i) => (_jsx("path", { d: strokeToPath(s) }, i))), current ? _jsx("path", { d: strokeToPath(current, !drawing.current?.pen) }) : null] })] }));
+    const typePad = (_jsxs("div", { className: "grid gap-2.5", children: [_jsxs("div", { className: surface, style: { height }, children: [baseline, _jsx("span", { "aria-hidden": true, className: cn("pointer-events-none absolute start-6 bottom-[calc(26%+0.25rem)] max-w-[calc(100%-3rem)] truncate italic leading-none", ink, !typed.trim() && "text-fg-subtle opacity-60"), style: { fontFamily: TYPED_FONT, fontSize: typedFontSize(height) }, children: typed.trim() || t("placeholder") })] }), _jsx(Input, { "aria-label": t("typeLabel"), placeholder: t("typePlaceholder"), value: typed, disabled: disabled, autoComplete: "name", "aria-invalid": invalid || undefined, onChange: (e) => {
+                    setTyped(e.currentTarget.value);
+                    emitTyped(e.currentTarget.value);
+                } })] }));
+    const toolbar = (_jsxs("div", { className: "flex items-center gap-1", children: [_jsx(Button, { size: "xs", variant: "ghost", onClick: undo, disabled: inert || empty, "aria-label": t("undo"), title: t("undo"), className: "px-1.5", children: _jsx(Undo2, { "aria-hidden": true, className: "rtl:-scale-x-100" }) }), _jsxs(Button, { size: "xs", variant: "ghost", onClick: clear, disabled: inert || (empty && !sig), children: [_jsx(Eraser, { "aria-hidden": true }), " ", t("clear")] })] }));
+    return (_jsxs("div", { ref: ref, ...rest, id: rootId, role: "group", ...groupLabel, "aria-describedby": mergeIds(field?.describedBy, describedBy), "aria-invalid": invalid || undefined, "data-required": required ? "" : undefined, "aria-disabled": disabled || undefined, "data-slot": "signature-pad", "data-mode": mode, "data-signed": sig ? "" : undefined, className: cn("grid min-w-0 gap-2", className), children: [modes.length > 1 ? (_jsxs(Tabs, { value: mode, onValueChange: (m) => setMode(m), className: "gap-2", children: [_jsxs("div", { className: "flex items-center justify-between gap-2", children: [_jsxs(TabsList, { variant: "segmented", size: "sm", overflow: "none", children: [modes.includes("draw") ? (_jsx(TabsTrigger, { value: "draw", icon: _jsx(PenLine, {}), disabled: disabled, children: t("draw") })) : null, modes.includes("type") ? (_jsx(TabsTrigger, { value: "type", icon: _jsx(Type, {}), disabled: disabled, children: t("type") })) : null] }), toolbar] }), _jsx(TabsContent, { value: "draw", className: "focus-visible:outline-none", tabIndex: -1, children: drawPad }), _jsx(TabsContent, { value: "type", className: "focus-visible:outline-none", tabIndex: -1, children: typePad })] })) : (_jsxs(_Fragment, { children: [_jsx("div", { className: "flex justify-end", children: toolbar }), mode === "draw" ? drawPad : typePad] })), _jsx("span", { className: "sr-only", "aria-live": "polite", children: announce }), hidden] }));
+});

package/dist/components/skeleton.d.ts

@@ -0,0 +1,64 @@
+import * as React from "react";
+import { type VariantProps } from "class-variance-authority";
+export declare const skeletonVariants: (props?: ({
+    shape?: "text" | "circle" | "rect" | null | undefined;
+    shimmer?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export interface SkeletonProps extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof skeletonVariants> {
+}
+/**
+ * A placeholder block while content loads. Size it with classes (`h-4 w-32`).
+ * Skeletons are hidden from assistive tech; wrap a loading region in `SkeletonGroup` so it is
+ * announced once (`aria-busy` + one hidden "Loading…").
+ *
+ * The shimmer runs in the reading direction (RTL-aware) and stops under `prefers-reduced-motion`.
+ */
+export declare const Skeleton: React.ForwardRefExoticComponent<SkeletonProps & React.RefAttributes<HTMLDivElement>>;
+export interface SkeletonTextProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Default 3. */
+    lines?: number;
+    /** Width of the last line. Default `"62%"`. */
+    lastLineWidth?: string;
+    shimmer?: boolean;
+    /** Classes for every line (e.g. `h-3`). */
+    lineClassName?: string;
+}
+/** Paragraph placeholder: full-width lines with a shorter last line. */
+export declare const SkeletonText: React.ForwardRefExoticComponent<SkeletonTextProps & React.RefAttributes<HTMLDivElement>>;
+declare const AVATAR: {
+    readonly xs: "size-5";
+    readonly sm: "size-6";
+    readonly md: "size-8";
+    readonly lg: "size-10";
+    readonly xl: "size-14";
+};
+/** Round placeholder matching the Avatar sizes (20/24/32/40/56). */
+export declare function SkeletonAvatar({ size, shape, className, ...props }: Omit<SkeletonProps, "shape"> & {
+    size?: keyof typeof AVATAR;
+    shape?: "circle" | "square";
+}): React.JSX.Element;
+export interface SkeletonRowProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Default 4. */
+    columns?: number;
+    /** Leading avatar + two lines in the first column. */
+    avatar?: boolean;
+    shimmer?: boolean;
+}
+/** A table/list row placeholder; height follows `--row-h`, padding `--cell-px`. */
+export declare const SkeletonRow: React.ForwardRefExoticComponent<SkeletonRowProps & React.RefAttributes<HTMLDivElement>>;
+export interface SkeletonGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Announced once for the whole region. Default from the dictionary (`skeleton.loading`). */
+    label?: string;
+    /** While `false`, children render normally and the region is no longer busy. Default `true`. */
+    loading?: boolean;
+}
+/**
+ * Wraps a loading region: sets `aria-busy` and announces one hidden status text instead of
+ * reading every skeleton.
+ *
+ * ```tsx
+ * <SkeletonGroup loading={isLoading}>{isLoading ? <SkeletonText /> : <Article />}</SkeletonGroup>
+ * ```
+ */
+export declare const SkeletonGroup: React.ForwardRefExoticComponent<SkeletonGroupProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/components/skeleton.js

@@ -0,0 +1,53 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cva } from "class-variance-authority";
+import { cn } from "../lib/cn.js";
+import { LocalizedText } from "../lib/islands.js";
+export const skeletonVariants = cva("block bg-skeleton", {
+    variants: {
+        shape: {
+            rect: "rounded-ui-sm",
+            /** One line of text: height follows the font size. */
+            text: "h-[0.8em] rounded-full",
+            circle: "aspect-square rounded-full",
+        },
+        shimmer: { true: "ui-shimmer", false: "" },
+    },
+    defaultVariants: { shape: "rect", shimmer: true },
+});
+/**
+ * A placeholder block while content loads. Size it with classes (`h-4 w-32`).
+ * Skeletons are hidden from assistive tech; wrap a loading region in `SkeletonGroup` so it is
+ * announced once (`aria-busy` + one hidden "Loading…").
+ *
+ * The shimmer runs in the reading direction (RTL-aware) and stops under `prefers-reduced-motion`.
+ */
+export const Skeleton = React.forwardRef(function Skeleton({ className, shape, shimmer, ...props }, ref) {
+    return _jsx("div", { ref: ref, "aria-hidden": true, "data-slot": "skeleton", className: cn(skeletonVariants({ shape, shimmer }), className), ...props });
+});
+/** Paragraph placeholder: full-width lines with a shorter last line. */
+export const SkeletonText = React.forwardRef(function SkeletonText({ lines = 3, lastLineWidth = "62%", shimmer, lineClassName, className, ...props }, ref) {
+    return (_jsx("div", { ref: ref, "aria-hidden": true, "data-slot": "skeleton-text", className: cn("grid gap-2.5 text-sm", className), ...props, children: Array.from({ length: lines }, (_, i) => (_jsx(Skeleton, { shape: "text", shimmer: shimmer, className: lineClassName, style: i === lines - 1 && lines > 1 ? { width: lastLineWidth } : undefined }, i))) }));
+});
+const AVATAR = { xs: "size-5", sm: "size-6", md: "size-8", lg: "size-10", xl: "size-14" };
+/** Round placeholder matching the Avatar sizes (20/24/32/40/56). */
+export function SkeletonAvatar({ size = "md", shape = "circle", className, ...props }) {
+    return _jsx(Skeleton, { shape: shape === "circle" ? "circle" : "rect", className: cn(AVATAR[size], className), ...props });
+}
+const COLUMN_WIDTHS = ["72%", "48%", "60%", "36%", "54%", "40%"];
+/** A table/list row placeholder; height follows `--row-h`, padding `--cell-px`. */
+export const SkeletonRow = React.forwardRef(function SkeletonRow({ columns = 4, avatar, shimmer, className, ...props }, ref) {
+    return (_jsx("div", { ref: ref, "aria-hidden": true, "data-slot": "skeleton-row", className: cn("grid h-(--row-h) items-center gap-4 border-b border-line px-(--cell-px) text-sm last:border-b-0", className), style: { gridTemplateColumns: `minmax(0,2fr) repeat(${Math.max(columns - 1, 0)}, minmax(0,1fr))` }, ...props, children: Array.from({ length: columns }, (_, i) => i === 0 && avatar ? (_jsxs("div", { className: "flex min-w-0 items-center gap-3", children: [_jsx(SkeletonAvatar, { size: "md", shimmer: shimmer }), _jsxs("div", { className: "grid min-w-0 flex-1 gap-1.5", children: [_jsx(Skeleton, { shape: "text", shimmer: shimmer, style: { width: "70%" } }), _jsx(Skeleton, { shape: "text", shimmer: shimmer, className: "h-[0.65em]", style: { width: "45%" } })] })] }, i)) : (_jsx(Skeleton, { shape: "text", shimmer: shimmer, style: { width: COLUMN_WIDTHS[i % COLUMN_WIDTHS.length] } }, i))) }));
+});
+const skeletonLabels = { loading: "Loading…" };
+/**
+ * Wraps a loading region: sets `aria-busy` and announces one hidden status text instead of
+ * reading every skeleton.
+ *
+ * ```tsx
+ * <SkeletonGroup loading={isLoading}>{isLoading ? <SkeletonText /> : <Article />}</SkeletonGroup>
+ * ```
+ */
+export const SkeletonGroup = React.forwardRef(function SkeletonGroup({ label, loading = true, children, ...props }, ref) {
+    return (_jsxs("div", { ref: ref, "data-slot": "skeleton-group", "aria-busy": loading || undefined, ...props, children: [loading ? (_jsx("span", { role: "status", className: "sr-only", children: label ?? _jsx(LocalizedText, { namespace: "skeleton", id: "loading", defaults: skeletonLabels }) })) : null, children] }));
+});

package/dist/components/sla-timer.d.ts

@@ -0,0 +1,75 @@
+import * as React from "react";
+export type SlaState = "on-track" | "at-risk" | "breached" | "met" | "missed" | "paused";
+export declare const slaTimerLabels: {
+    dueIn: string;
+    overdue: string;
+    met: string;
+    missed: string;
+    paused: string;
+    pausedOverdue: string;
+    stateOnTrack: string;
+    stateAtRisk: string;
+    stateBreached: string;
+    stateMet: string;
+    stateMissed: string;
+    statePaused: string;
+};
+export type SlaTimerLabels = typeof slaTimerLabels;
+type DateLike = string | number | Date;
+export interface SlaModel {
+    state: SlaState;
+    /** Milliseconds left (negative when overdue); frozen for met/missed/paused. */
+    remaining: number;
+    /** Share of the window used, 0…1+ (needs `start`). */
+    used: number | null;
+}
+/**
+ * Pure SLA state: `on-track`, `at-risk` (less than `warnAt` of the window or `warnMinutes`
+ * left), `breached`, and the final `met` / `missed` once `completedAt` is set.
+ */
+export declare function slaState({ due, start, completedAt, pausedAt, now, warnAt, warnMinutes }: {
+    due: DateLike;
+    start?: DateLike;
+    completedAt?: DateLike | null;
+    pausedAt?: DateLike | null;
+    now: number;
+    warnAt?: number;
+    warnMinutes?: number;
+}): SlaModel;
+export interface SlaTimerProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> {
+    /** Deadline (ISO string, epoch ms or Date). */
+    due: DateLike;
+    /** When the clock started — enables the proportional warning and the bar. */
+    start?: DateLike;
+    /** Target reached (first reply sent, ticket solved) → `met` or `missed`, frozen. */
+    completedAt?: DateLike | null;
+    /** Clock stopped (waiting on customer) → `paused`, frozen. */
+    pausedAt?: DateLike | null;
+    /** Fixed "now" (epoch ms) for static screens, tests and screenshots. Omit to tick live. */
+    now?: number;
+    /** Warn when less than this share of the window is left (needs `start`). Default `0.25`. */
+    warnAt?: number;
+    /** Warn when fewer minutes than this are left (overrides `warnAt`). */
+    warnMinutes?: number;
+    /** `"badge"` (default), `"inline"`, or `"bar"` (label row + progress line). */
+    variant?: "badge" | "inline" | "bar";
+    /** What the SLA measures, prefixed to the accessible text: "First response". */
+    label?: string;
+    /** Show seconds under an hour left. Default `true`. */
+    seconds?: boolean;
+    /** Hide the icon (badge / inline). */
+    hideIcon?: boolean;
+    labels?: Partial<SlaTimerLabels>;
+}
+/**
+ * Countdown to a service-level deadline — first response, resolution, delivery window.
+ * Colour follows the state (on track → at risk → breached), and it freezes as met/missed
+ * once `completedAt` is set. `role="timer"` with a full sentence for screen readers.
+ *
+ * ```tsx
+ * <SlaTimer label="First response" start={ticket.createdAt} due={ticket.firstResponseDue} />
+ * <SlaTimer variant="bar" label="Resolution" start={t.createdAt} due={t.resolveDue} completedAt={t.solvedAt} />
+ * ```
+ */
+export declare const SlaTimer: React.ForwardRefExoticComponent<SlaTimerProps & React.RefAttributes<HTMLSpanElement>>;
+export {};