@usetheo/ui 0.1.0-next.0 → 0.3.0-next.0

package/dist/whiteboard/index.d.ts

@@ -0,0 +1,258 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { z } from 'zod';
+
+/**
+ * Zod schema for the Whiteboard JSON v1 (`WhiteboardScene`).
+ *
+ * Design goals (see RFC 0001 §4 and ADR D4 in the plan):
+ *   - LLM-friendly: minimal fields per element.
+ *   - Discriminated union by `type` for exhaustive typing in TS.
+ *   - Defensive against LLM mistakes:
+ *     - EC-3: `.finite()` everywhere — rejects NaN / Infinity.
+ *     - EC-4: `.max()` on dimensions to cap absurd values from the model.
+ */
+
+declare const whiteboardScene: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    background: z.ZodOptional<z.ZodString>;
+    elements: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        stroke: z.ZodOptional<z.ZodString>;
+        strokeWidth: z.ZodOptional<z.ZodNumber>;
+        strokeStyle: z.ZodOptional<z.ZodEnum<{
+            solid: "solid";
+            dashed: "dashed";
+            dotted: "dotted";
+        }>>;
+        fill: z.ZodOptional<z.ZodString>;
+        fillStyle: z.ZodOptional<z.ZodEnum<{
+            solid: "solid";
+            hachure: "hachure";
+            "cross-hatch": "cross-hatch";
+            zigzag: "zigzag";
+        }>>;
+        opacity: z.ZodOptional<z.ZodNumber>;
+        roughness: z.ZodOptional<z.ZodNumber>;
+        seed: z.ZodOptional<z.ZodNumber>;
+        type: z.ZodLiteral<"rect">;
+        w: z.ZodNumber;
+        h: z.ZodNumber;
+        label: z.ZodOptional<z.ZodString>;
+        roundness: z.ZodOptional<z.ZodEnum<{
+            sharp: "sharp";
+            round: "round";
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        stroke: z.ZodOptional<z.ZodString>;
+        strokeWidth: z.ZodOptional<z.ZodNumber>;
+        strokeStyle: z.ZodOptional<z.ZodEnum<{
+            solid: "solid";
+            dashed: "dashed";
+            dotted: "dotted";
+        }>>;
+        fill: z.ZodOptional<z.ZodString>;
+        fillStyle: z.ZodOptional<z.ZodEnum<{
+            solid: "solid";
+            hachure: "hachure";
+            "cross-hatch": "cross-hatch";
+            zigzag: "zigzag";
+        }>>;
+        opacity: z.ZodOptional<z.ZodNumber>;
+        roughness: z.ZodOptional<z.ZodNumber>;
+        seed: z.ZodOptional<z.ZodNumber>;
+        type: z.ZodLiteral<"ellipse">;
+        w: z.ZodNumber;
+        h: z.ZodNumber;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        stroke: z.ZodOptional<z.ZodString>;
+        strokeWidth: z.ZodOptional<z.ZodNumber>;
+        strokeStyle: z.ZodOptional<z.ZodEnum<{
+            solid: "solid";
+            dashed: "dashed";
+            dotted: "dotted";
+        }>>;
+        fill: z.ZodOptional<z.ZodString>;
+        fillStyle: z.ZodOptional<z.ZodEnum<{
+            solid: "solid";
+            hachure: "hachure";
+            "cross-hatch": "cross-hatch";
+            zigzag: "zigzag";
+        }>>;
+        opacity: z.ZodOptional<z.ZodNumber>;
+        roughness: z.ZodOptional<z.ZodNumber>;
+        seed: z.ZodOptional<z.ZodNumber>;
+        type: z.ZodLiteral<"diamond">;
+        w: z.ZodNumber;
+        h: z.ZodNumber;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        stroke: z.ZodOptional<z.ZodString>;
+        strokeWidth: z.ZodOptional<z.ZodNumber>;
+        strokeStyle: z.ZodOptional<z.ZodEnum<{
+            solid: "solid";
+            dashed: "dashed";
+            dotted: "dotted";
+        }>>;
+        fill: z.ZodOptional<z.ZodString>;
+        fillStyle: z.ZodOptional<z.ZodEnum<{
+            solid: "solid";
+            hachure: "hachure";
+            "cross-hatch": "cross-hatch";
+            zigzag: "zigzag";
+        }>>;
+        opacity: z.ZodOptional<z.ZodNumber>;
+        roughness: z.ZodOptional<z.ZodNumber>;
+        seed: z.ZodOptional<z.ZodNumber>;
+        type: z.ZodLiteral<"line">;
+        to: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        stroke: z.ZodOptional<z.ZodString>;
+        strokeWidth: z.ZodOptional<z.ZodNumber>;
+        strokeStyle: z.ZodOptional<z.ZodEnum<{
+            solid: "solid";
+            dashed: "dashed";
+            dotted: "dotted";
+        }>>;
+        fill: z.ZodOptional<z.ZodString>;
+        fillStyle: z.ZodOptional<z.ZodEnum<{
+            solid: "solid";
+            hachure: "hachure";
+            "cross-hatch": "cross-hatch";
+            zigzag: "zigzag";
+        }>>;
+        opacity: z.ZodOptional<z.ZodNumber>;
+        roughness: z.ZodOptional<z.ZodNumber>;
+        seed: z.ZodOptional<z.ZodNumber>;
+        type: z.ZodLiteral<"arrow">;
+        to: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+        label: z.ZodOptional<z.ZodString>;
+        headStart: z.ZodOptional<z.ZodBoolean>;
+        headEnd: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        stroke: z.ZodOptional<z.ZodString>;
+        strokeWidth: z.ZodOptional<z.ZodNumber>;
+        strokeStyle: z.ZodOptional<z.ZodEnum<{
+            solid: "solid";
+            dashed: "dashed";
+            dotted: "dotted";
+        }>>;
+        fill: z.ZodOptional<z.ZodString>;
+        fillStyle: z.ZodOptional<z.ZodEnum<{
+            solid: "solid";
+            hachure: "hachure";
+            "cross-hatch": "cross-hatch";
+            zigzag: "zigzag";
+        }>>;
+        opacity: z.ZodOptional<z.ZodNumber>;
+        roughness: z.ZodOptional<z.ZodNumber>;
+        seed: z.ZodOptional<z.ZodNumber>;
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+        fontSize: z.ZodOptional<z.ZodNumber>;
+        align: z.ZodOptional<z.ZodEnum<{
+            left: "left";
+            center: "center";
+            right: "right";
+        }>>;
+        fontFamily: z.ZodOptional<z.ZodEnum<{
+            sans: "sans";
+            serif: "serif";
+            mono: "mono";
+            hand: "hand";
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        stroke: z.ZodOptional<z.ZodString>;
+        strokeWidth: z.ZodOptional<z.ZodNumber>;
+        strokeStyle: z.ZodOptional<z.ZodEnum<{
+            solid: "solid";
+            dashed: "dashed";
+            dotted: "dotted";
+        }>>;
+        fill: z.ZodOptional<z.ZodString>;
+        fillStyle: z.ZodOptional<z.ZodEnum<{
+            solid: "solid";
+            hachure: "hachure";
+            "cross-hatch": "cross-hatch";
+            zigzag: "zigzag";
+        }>>;
+        opacity: z.ZodOptional<z.ZodNumber>;
+        roughness: z.ZodOptional<z.ZodNumber>;
+        seed: z.ZodOptional<z.ZodNumber>;
+        type: z.ZodLiteral<"freedraw">;
+        points: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodOptional<z.ZodNumber>], null>>;
+    }, z.core.$strip>], "type">>;
+}, z.core.$strip>;
+type WhiteboardScene = z.output<typeof whiteboardScene>;
+type WhiteboardSceneInput = z.input<typeof whiteboardScene>;
+
+/**
+ * Public validator for `WhiteboardScene` JSON. Wraps Zod and converts errors
+ * into a structured shape that an LLM can consume to self-correct.
+ *
+ * Returns `{ ok: true, scene }` on success or `{ ok: false, errors }` with
+ * each error carrying `{ path, message, code, got? }`. See RFC 0001 §4.
+ */
+
+interface ValidationError {
+    /** Dot-joined Zod path, e.g. "elements.2.type" or "width". */
+    path: string;
+    /** Human-readable explanation (passes through Zod's message). */
+    message: string;
+    /** Zod issue code: `invalid_type`, `too_small`, `invalid_literal`, ... */
+    code: string;
+    /** Actual value received at `path`. Populated for type mismatches, discriminator mismatches, and any issue where Zod's `received` is absent but the value can be recovered by walking the original input along `path`. */
+    got?: unknown;
+}
+type ValidationResult = {
+    ok: true;
+    scene: WhiteboardScene;
+} | {
+    ok: false;
+    errors: ValidationError[];
+};
+declare function validateScene(input: unknown): ValidationResult;
+
+/** Input type accepted by the component (defaults like `headEnd` are optional). */
+type WhiteboardData = WhiteboardSceneInput;
+
+interface WhiteboardProps {
+    /** The scene to render. Validated with Zod on every change. */
+    data: WhiteboardData | unknown;
+    className?: string;
+    /** Starting zoom level (clamped 0.1–8). Default 1. */
+    initialZoom?: number;
+    /** World coordinate centered in the viewport on first render. */
+    initialCenter?: [number, number];
+    /** When true, computes a bounding box of all elements and zooms to fit. */
+    fitOnLoad?: boolean;
+    /** Called once per validation failure with the list of errors (EC-6: in useEffect, not render). */
+    onValidationError?: (errors: ValidationError[]) => void;
+    /** Accessible label for the SVG (defaults to "Whiteboard diagram"). */
+    "aria-label"?: string;
+}
+declare function Whiteboard({ data, className, initialZoom, initialCenter, fitOnLoad, onValidationError, "aria-label": ariaLabel, }: WhiteboardProps): react_jsx_runtime.JSX.Element;
+
+export { type ValidationError, type ValidationResult, Whiteboard, type WhiteboardData, type WhiteboardProps, validateScene };