@flikk/ui 1.0.0-beta.3 → 1.0.0-beta.30

package/dist/components/generative/schemaTypes.d.ts

@@ -0,0 +1,30 @@
+import { JSONValue } from "./types";
+/**
+ * The schema vocabulary the generator emits and the validator consumes.
+ * Deliberately tiny — NOT a general JSON Schema engine (PER-139 scope guard).
+ */
+export type SchemaPropKind = "enum" | "string" | "number" | "boolean" | "union" | "icon" | "text" | "shape";
+export interface SchemaProp {
+    kind: SchemaPropKind;
+    options?: JSONValue[];
+    types?: string[];
+    required?: boolean;
+    default?: JSONValue;
+    description?: string;
+    shape?: string;
+}
+export interface ComponentSchema {
+    role: "container" | "leaf";
+    description?: string;
+    props: Record<string, SchemaProp>;
+}
+export interface GenerativeSchemaDoc {
+    version: number;
+    /** Closed icon NAME set (mirrors DEFAULT_ICONS in resolvers.tsx). */
+    icons: string[];
+    components: Record<string, ComponentSchema>;
+    /** Named data-shape documentation referenced by `kind:"shape"` props. */
+    shapes: Record<string, JSONValue>;
+    /** Canonical spec examples (not codegen examples). */
+    examples: JSONValue[];
+}

package/dist/components/generative/streaming.d.ts

@@ -0,0 +1,39 @@
+import { UISpec, JSONValue } from "./types";
+import { GenerativeSchemaDoc } from "./schemaTypes";
+/**
+ * Streaming render support (PER-140).
+ *
+ * The model streams ONE recursive UINode tree as JSON (the P2 tools.json
+ * contract) — we parse the truncated text permissively, render containers as
+ * soon as they're identifiable, and stand in correctly-sized Skeletons for
+ * leaves whose JSON hasn't fully arrived yet.
+ */
+/** Pseudo component name for placeholder nodes (rendered natively by GenerativeView). */
+export declare const SKELETON_NODE = "__skeleton__";
+/** Per-component Skeleton heights (px) — approximate final footprint so hydration doesn't shift layout. */
+export declare const SKELETON_PRESETS: Record<string, number>;
+/** True when the parser saw this object/array's closing bracket. Primitives count as complete. */
+export declare function isJSONComplete(value: JSONValue | undefined): boolean;
+/**
+ * Parse possibly-truncated JSON text. Never throws. Objects/arrays carry a
+ * completeness mark readable via isJSONComplete().
+ */
+export declare function parsePartialJSON(text: string): JSONValue | undefined;
+export interface StreamingSpecResult {
+    /** Renderable spec: settled nodes + __skeleton__ placeholders. Null while nothing parseable arrived. */
+    spec: UISpec | null;
+    /** Number of placeholder nodes still pending. */
+    pending: number;
+    /** True once the root JSON closed and nothing is pending. */
+    complete: boolean;
+}
+export interface ParseStreamingSpecOptions {
+    schema?: GenerativeSchemaDoc;
+}
+/**
+ * Turn accumulating JSON text into a progressively-renderable spec:
+ * - containers render as soon as their `component` is known (children stream in)
+ * - incomplete leaves become __skeleton__ nodes sized by preset/sizeHint
+ * - a complete spec passes through untouched (one-shot fallback)
+ */
+export declare function parseStreamingSpec(text: string, options?: ParseStreamingSpecOptions): StreamingSpecResult;

package/dist/components/generative/streaming.js

@@ -0,0 +1,283 @@
+import { GENERATIVE_SCHEMA } from './schema.generated.js';
+
+/**
+ * Streaming render support (PER-140).
+ *
+ * The model streams ONE recursive UINode tree as JSON (the P2 tools.json
+ * contract) — we parse the truncated text permissively, render containers as
+ * soon as they're identifiable, and stand in correctly-sized Skeletons for
+ * leaves whose JSON hasn't fully arrived yet.
+ */
+/** Pseudo component name for placeholder nodes (rendered natively by GenerativeView). */
+const SKELETON_NODE = "__skeleton__";
+/** Per-component Skeleton heights (px) — approximate final footprint so hydration doesn't shift layout. */
+const SKELETON_PRESETS = {
+    Metric: 96,
+    KPI: 128,
+    Alert: 64,
+    Badge: 24,
+    Avatar: 40,
+    Progress: 16,
+    Separator: 1,
+    Table: 280,
+    Timeline: 220,
+    Feed: 220,
+    DescriptionList: 160,
+    AreaChart: 264,
+    BarChart: 264,
+    DonutChart: 240,
+};
+const DEFAULT_SKELETON_HEIGHT = 80;
+/* ────────────────────────────────────────────────────────────────────────
+ * Permissive JSON parser — tolerates EOF anywhere. Every object/array is
+ * tagged with a non-enumerable completeness symbol (true once its closing
+ * bracket was actually seen in the input).
+ * ──────────────────────────────────────────────────────────────────────── */
+const COMPLETE = Symbol("flikkui.json.complete");
+const WS = new Set([" ", "\t", "\n", "\r"]);
+const skipWs = (s, i) => {
+    while (i < s.length && WS.has(s[i]))
+        i++;
+    return i;
+};
+function markComplete(value, complete) {
+    if (value !== null && typeof value === "object") {
+        Object.defineProperty(value, COMPLETE, { value: complete, enumerable: false });
+    }
+}
+/** True when the parser saw this object/array's closing bracket. Primitives count as complete. */
+function isJSONComplete(value) {
+    if (value === undefined)
+        return false;
+    if (value === null || typeof value !== "object")
+        return true;
+    return value[COMPLETE] === true;
+}
+function parseString(s, i) {
+    var _a;
+    // s[i] === '"'
+    i++;
+    let out = "";
+    while (i < s.length) {
+        const ch = s[i];
+        if (ch === '"')
+            return { value: out, end: i + 1, complete: true };
+        if (ch === "\\") {
+            if (i + 1 >= s.length)
+                return { value: out, end: s.length, complete: false }; // truncated escape
+            const esc = s[i + 1];
+            if (esc === "u") {
+                if (i + 6 > s.length)
+                    return { value: out, end: s.length, complete: false };
+                const hex = s.slice(i + 2, i + 6);
+                if (/^[0-9a-fA-F]{4}$/.test(hex))
+                    out += String.fromCharCode(parseInt(hex, 16));
+                i += 6;
+                continue;
+            }
+            const map = { '"': '"', "\\": "\\", "/": "/", b: "\b", f: "\f", n: "\n", r: "\r", t: "\t" };
+            out += (_a = map[esc]) !== null && _a !== void 0 ? _a : esc;
+            i += 2;
+            continue;
+        }
+        out += ch;
+        i++;
+    }
+    return { value: out, end: s.length, complete: false };
+}
+function parseNumber(s, i) {
+    const match = /^-?\d*\.?\d*(?:[eE][+-]?\d*)?/.exec(s.slice(i));
+    const raw = match ? match[0] : "";
+    const end = i + raw.length;
+    // trim trailing chars that make the prefix unparseable ("-", "12.", "1e", "1e-")
+    const trimmed = raw.replace(/[.eE+-]+$/, "");
+    const value = trimmed === "" ? undefined : Number(trimmed);
+    const complete = end < s.length; // a number followed by anything is finished; at EOF it might still grow
+    return { value: Number.isNaN(value) ? undefined : value, end, complete };
+}
+function parseLiteral(s, i) {
+    for (const [word, val] of [["true", true], ["false", false], ["null", null]]) {
+        if (s.startsWith(word, i))
+            return { value: val, end: i + word.length, complete: true };
+        if (word.startsWith(s.slice(i)) && s.length - i < word.length)
+            return { value: undefined, end: s.length, complete: false };
+    }
+    return { value: undefined, end: i + 1, complete: false }; // unknown char — skip it
+}
+function parseArray(s, i) {
+    // s[i] === '['
+    i++;
+    const arr = [];
+    for (;;) {
+        i = skipWs(s, i);
+        if (i >= s.length) {
+            markComplete(arr, false);
+            return { value: arr, end: i, complete: false };
+        }
+        if (s[i] === "]") {
+            markComplete(arr, true);
+            return { value: arr, end: i + 1, complete: true };
+        }
+        if (s[i] === ",") {
+            i++;
+            continue;
+        }
+        const item = parseValue(s, i);
+        if (item.value !== undefined)
+            arr.push(item.value);
+        i = item.end;
+        if (!item.complete) {
+            markComplete(arr, false);
+            return { value: arr, end: i, complete: false };
+        }
+    }
+}
+function parseObject(s, i) {
+    // s[i] === '{'
+    i++;
+    const obj = {};
+    for (;;) {
+        i = skipWs(s, i);
+        if (i >= s.length) {
+            markComplete(obj, false);
+            return { value: obj, end: i, complete: false };
+        }
+        if (s[i] === "}") {
+            markComplete(obj, true);
+            return { value: obj, end: i + 1, complete: true };
+        }
+        if (s[i] === ",") {
+            i++;
+            continue;
+        }
+        if (s[i] !== '"') {
+            // malformed — stop here rather than guessing
+            markComplete(obj, false);
+            return { value: obj, end: i, complete: false };
+        }
+        const key = parseString(s, i);
+        if (!key.complete) {
+            // truncated key — drop it
+            markComplete(obj, false);
+            return { value: obj, end: s.length, complete: false };
+        }
+        i = skipWs(s, key.end);
+        if (i >= s.length || s[i] !== ":") {
+            markComplete(obj, false);
+            return { value: obj, end: i, complete: false };
+        }
+        i = skipWs(s, i + 1);
+        if (i >= s.length) {
+            // key with no value yet — drop it
+            markComplete(obj, false);
+            return { value: obj, end: i, complete: false };
+        }
+        const val = parseValue(s, i);
+        if (val.value !== undefined)
+            obj[key.value] = val.value;
+        i = val.end;
+        if (!val.complete) {
+            markComplete(obj, false);
+            return { value: obj, end: i, complete: false };
+        }
+    }
+}
+function parseValue(s, i) {
+    i = skipWs(s, i);
+    if (i >= s.length)
+        return { value: undefined, end: i, complete: false };
+    const ch = s[i];
+    if (ch === "{")
+        return parseObject(s, i);
+    if (ch === "[")
+        return parseArray(s, i);
+    if (ch === '"')
+        return parseString(s, i);
+    if (ch === "-" || (ch >= "0" && ch <= "9"))
+        return parseNumber(s, i);
+    return parseLiteral(s, i);
+}
+/**
+ * Parse possibly-truncated JSON text. Never throws. Objects/arrays carry a
+ * completeness mark readable via isJSONComplete().
+ */
+function parsePartialJSON(text) {
+    // strip markdown fences a model may wrap around the JSON
+    let s = text;
+    const fence = s.indexOf("```");
+    if (fence !== -1 && fence < 20) {
+        s = s.slice(s.indexOf("\n", fence) + 1);
+        const closing = s.lastIndexOf("```");
+        if (closing !== -1)
+            s = s.slice(0, closing);
+    }
+    const start = s.search(/[{[]/);
+    if (start === -1)
+        return undefined;
+    return parseValue(s, start).value;
+}
+const skeletonHeight = (component, node) => {
+    var _a;
+    const hinted = (_a = node === null || node === void 0 ? void 0 : node.sizeHint) === null || _a === void 0 ? void 0 : _a.height;
+    if (hinted !== undefined)
+        return hinted;
+    return (component && SKELETON_PRESETS[component]) || DEFAULT_SKELETON_HEIGHT;
+};
+/**
+ * Turn accumulating JSON text into a progressively-renderable spec:
+ * - containers render as soon as their `component` is known (children stream in)
+ * - incomplete leaves become __skeleton__ nodes sized by preset/sizeHint
+ * - a complete spec passes through untouched (one-shot fallback)
+ */
+function parseStreamingSpec(text, options = {}) {
+    var _a;
+    const schema = (_a = options.schema) !== null && _a !== void 0 ? _a : GENERATIVE_SCHEMA;
+    let root = parsePartialJSON(text);
+    if (root === undefined || root === null || typeof root !== "object")
+        return { spec: null, pending: 0, complete: false };
+    // tool-call args arrive as { "spec": <tree> } (the tools.json shape) — unwrap
+    if (!Array.isArray(root) && typeof root.component !== "string" && root.spec !== undefined) {
+        const inner = root.spec;
+        if (inner === null || typeof inner !== "object")
+            return { spec: null, pending: 0, complete: false };
+        root = inner;
+    }
+    const state = { pending: 0 };
+    const skeleton = (forComponent, source) => {
+        state.pending++;
+        return {
+            component: SKELETON_NODE,
+            props: { height: skeletonHeight(forComponent, source), forComponent: forComponent !== null && forComponent !== void 0 ? forComponent : null },
+        };
+    };
+    const transform = (value) => {
+        var _a;
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            return skeleton();
+        const node = value;
+        const name = node.component;
+        if (typeof name !== "string" || name.length === 0)
+            return skeleton(undefined, node);
+        const role = (_a = schema.components[name]) === null || _a === void 0 ? void 0 : _a.role;
+        const nodeComplete = isJSONComplete(value);
+        if (role === "container") {
+            // render immediately; children hydrate beneath it
+            const kids = Array.isArray(node.children) ? node.children.map((c) => transform(c)) : undefined;
+            return {
+                component: name,
+                ...(node.id ? { id: node.id } : {}),
+                ...(node.sizeHint ? { sizeHint: node.sizeHint } : {}),
+                ...(node.props && typeof node.props === "object" ? { props: node.props } : {}),
+                ...(kids && kids.length ? { children: kids } : {}),
+            };
+        }
+        // leaf (or unknown component): only hydrate once its JSON object closed
+        if (!nodeComplete)
+            return skeleton(role ? name : undefined, node);
+        return node;
+    };
+    const spec = Array.isArray(root) ? root.map(transform) : transform(root);
+    return { spec, pending: state.pending, complete: state.pending === 0 && isJSONComplete(root) };
+}
+
+export { SKELETON_NODE, SKELETON_PRESETS, isJSONComplete, parsePartialJSON, parseStreamingSpec };

package/dist/components/generative/streaming.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/generative/tools.d.ts

@@ -0,0 +1,21 @@
+import { GenerativeSchemaDoc } from "./schemaTypes";
+import { JSONValue } from "./types";
+/** Anthropic/OpenAI-compatible tool definition for spec emission. */
+export interface GenerativeToolDefinition {
+    name: string;
+    description: string;
+    input_schema: Record<string, JSONValue>;
+    /** Per-component prop contracts — inline into the system prompt or tool description. */
+    contracts: GenerativeSchemaDoc["components"];
+    icons: string[];
+    shapes: GenerativeSchemaDoc["shapes"];
+    examples: GenerativeSchemaDoc["examples"];
+}
+/**
+ * Build the render_ui tool definition from a generative schema. The build
+ * script uses this same function to emit dist/tools.json — one builder, no
+ * drift between the runtime export and the artifact.
+ */
+export declare function buildToolDefinition(schema?: GenerativeSchemaDoc): GenerativeToolDefinition;
+/** The default tool definition, built from the checked-in generated schema. */
+export declare const GENERATIVE_TOOL: GenerativeToolDefinition;

package/dist/components/generative/tools.js

@@ -0,0 +1,54 @@
+import { GENERATIVE_SCHEMA } from './schema.generated.js';
+
+/**
+ * Build the render_ui tool definition from a generative schema. The build
+ * script uses this same function to emit dist/tools.json — one builder, no
+ * drift between the runtime export and the artifact.
+ */
+function buildToolDefinition(schema = GENERATIVE_SCHEMA) {
+    const componentNames = Object.keys(schema.components);
+    return {
+        name: "render_ui",
+        description: "Render a UI from FlikkUI components. Emit a recursive UINode spec: containers (Grid/Stack/Section/Card) take children; leaves take serializable props only. Icons are NAMES from the closed icon set. Follow the per-component contracts.",
+        input_schema: {
+            type: "object",
+            properties: { spec: { $ref: "#/$defs/UINode" } },
+            required: ["spec"],
+            $defs: {
+                UINode: {
+                    type: "object",
+                    properties: {
+                        component: { type: "string", enum: componentNames },
+                        props: { type: "object" },
+                        children: { type: "array", items: { $ref: "#/$defs/UINode" } },
+                        id: { type: "string" },
+                        sizeHint: {
+                            type: "object",
+                            description: "Optional height hint (px or CSS size) so streaming skeletons reserve the right space.",
+                            properties: { height: { type: ["number", "string"] } },
+                        },
+                        actions: {
+                            type: "object",
+                            description: 'Named interactions: { click: { type, payload? } } on Button/leaves; { rowClick: { type, payload? } } on Table (the clicked row arrives as dispatch context). Fully serializable.',
+                            additionalProperties: {
+                                type: "object",
+                                properties: { type: { type: "string" }, payload: {} },
+                                required: ["type"],
+                            },
+                        },
+                    },
+                    required: ["component"],
+                    additionalProperties: false,
+                },
+            },
+        },
+        contracts: schema.components,
+        icons: schema.icons,
+        shapes: schema.shapes,
+        examples: schema.examples,
+    };
+}
+/** The default tool definition, built from the checked-in generated schema. */
+const GENERATIVE_TOOL = buildToolDefinition();
+
+export { GENERATIVE_TOOL, buildToolDefinition };

package/dist/components/generative/tools.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/generative/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The serializable spec format a model emits. A spec contains ONLY
+ * JSON-serializable values — icons are NAMES, table cell renderers are
+ * `cellType` hints; the resolver chain hydrates them into React at render
+ * time. This is what gets saved to a DB and replayed with no LLM.
+ */
+/** Any JSON-serializable value. */
+export type JSONValue = string | number | boolean | null | JSONValue[] | {
+    [key: string]: JSONValue;
+};
+/**
+ * A serializable description of an interaction (P4 wires dispatch; the type
+ * ships now so specs are forward-compatible).
+ */
+export interface ActionDescriptor {
+    type: string;
+    payload?: JSONValue;
+}
+/** One node of the recursive UI tree. */
+export interface UINode {
+    /** Registry key — must exist in the registry's `components` map. */
+    component: string;
+    /** Fully serializable props (icon NAMES, `cellType` hints — never JSX/functions). */
+    props?: Record<string, JSONValue>;
+    /** Recursive children — only rendered by container components (Grid/Stack/Section/Card). */
+    children?: UINode[];
+    /** Named interactions, e.g. { click: { type: "select-order", payload: { id } } }. */
+    actions?: Record<string, ActionDescriptor>;
+    /** Stable identity for streaming/patching; falls back to the child index. */
+    id?: string;
+    /**
+     * Optional footprint hint for streaming Skeleton placeholders (height in px
+     * or any CSS size). Width comes from the parent container, which renders
+     * before its children — so height is the only axis that needs reserving.
+     */
+    sizeHint?: {
+        height?: number | string;
+    };
+}
+/** A complete spec: a single root node, or a list of top-level siblings. */
+export type UISpec = UINode | UINode[];

package/dist/components/generative/useGenerativeStream.d.ts

@@ -0,0 +1,37 @@
+import { useStreamingSSE } from "../../hooks/useStreamingSSE";
+import { StreamingSpecResult } from "./streaming";
+import { GenerativeSchemaDoc } from "./schemaTypes";
+type SSEPassThrough = Omit<Parameters<typeof useStreamingSSE>[0], "url" | "onToken" | "onComplete">;
+export interface UseGenerativeStreamOptions extends Partial<SSEPassThrough> {
+    /**
+     * Transport-agnostic mode: pass the accumulated (possibly truncated) JSON
+     * text from ANY source — an SDK's tool-call partial args, a websocket, a
+     * replayed fixture. When set, `url` is ignored and no request is made.
+     */
+    text?: string;
+    /** SSE mode: stream from this endpoint via useStreamingSSE. */
+    url?: string;
+    /** Schema for container/leaf roles. @default GENERATIVE_SCHEMA */
+    schema?: GenerativeSchemaDoc;
+}
+export interface UseGenerativeStreamReturn extends StreamingSpecResult {
+    /** The raw accumulated JSON text the spec was parsed from. */
+    rawText: string;
+    /** SSE-mode stream state (always false/null in text mode). */
+    isStreaming: boolean;
+    error: ReturnType<typeof useStreamingSSE>["error"];
+    start: () => void;
+    stop: () => void;
+    reset: () => void;
+}
+/**
+ * Progressive spec streaming: feeds accumulating JSON text through
+ * parseStreamingSpec so GenerativeView can render skeletons → content.
+ * Falls back to a plain one-shot parse when handed complete text.
+ *
+ * Note: for provider tool-call streams (e.g. Anthropic `input_json_delta`),
+ * pass a custom `format` parser to extract `partial_json` deltas, or use
+ * text mode with your SDK's accumulated arguments string.
+ */
+export declare function useGenerativeStream(options: UseGenerativeStreamOptions): UseGenerativeStreamReturn;
+export {};

package/dist/components/generative/useGenerativeStream.js

@@ -0,0 +1,37 @@
+"use client";
+import { useMemo } from 'react';
+import { useStreamingSSE } from '../../hooks/useStreamingSSE.js';
+import { parseStreamingSpec } from './streaming.js';
+
+/**
+ * Progressive spec streaming: feeds accumulating JSON text through
+ * parseStreamingSpec so GenerativeView can render skeletons → content.
+ * Falls back to a plain one-shot parse when handed complete text.
+ *
+ * Note: for provider tool-call streams (e.g. Anthropic `input_json_delta`),
+ * pass a custom `format` parser to extract `partial_json` deltas, or use
+ * text mode with your SDK's accumulated arguments string.
+ */
+function useGenerativeStream(options) {
+    var _a;
+    const { text, url, schema, ...sseOptions } = options;
+    const sseMode = text === undefined && !!url;
+    const sse = useStreamingSSE({
+        ...sseOptions,
+        url: url !== null && url !== void 0 ? url : "",
+        autoStart: sseMode ? (_a = sseOptions.autoStart) !== null && _a !== void 0 ? _a : true : false,
+    });
+    const rawText = text !== null && text !== void 0 ? text : sse.accumulatedText;
+    const parsed = useMemo(() => parseStreamingSpec(rawText, { schema }), [rawText, schema]);
+    return {
+        ...parsed,
+        rawText,
+        isStreaming: sseMode ? sse.isStreaming : false,
+        error: sseMode ? sse.error : null,
+        start: sse.start,
+        stop: sse.stop,
+        reset: sse.reset,
+    };
+}
+
+export { useGenerativeStream };

package/dist/components/generative/validate.d.ts

@@ -0,0 +1,24 @@
+import { UISpec } from "./types";
+import { GenerativeSchemaDoc } from "./schemaTypes";
+export interface ValidationIssue {
+    /** JSONPath-ish locator, e.g. `$.children[2].props.color`. */
+    path: string;
+    code: "invalid-node" | "unknown-component" | "blocked-prop" | "unknown-prop" | "invalid-enum" | "coerced-value" | "invalid-value" | "invalid-shape" | "missing-required" | "applied-default" | "children-ignored" | "invalid-action" | "max-depth-exceeded";
+    message: string;
+    severity: "error" | "warning";
+}
+export interface ValidateOptions {
+    /** Override the generated schema (e.g. for a custom registry). */
+    schema?: GenerativeSchemaDoc;
+}
+export interface ValidateResult {
+    spec: UISpec;
+    issues: ValidationIssue[];
+}
+/**
+ * Validate + repair a model-emitted spec against the generated schema.
+ * Never throws; never mutates the input. Every repair is recorded in `issues`.
+ * Unknown components are kept (GenerativeView renders its safe placeholder)
+ * but their props/children are stripped.
+ */
+export declare function validate(spec: UISpec, options?: ValidateOptions): ValidateResult;