@terreno/blocks 57.10.1

package/dist/parse.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseBlocks = exports.stripBlocksFence = void 0;
+const yaml_1 = require("yaml");
+const errors_1 = require("./errors");
+const FENCE = /^```(?:yaml|yml|json)?[^\n]*\n([\s\S]*?)\n?```$/i;
+const notADocument = () => ({
+    code: "NOT_A_DOCUMENT",
+    fix: "Reply with one document: v, then optional datasets, then blocks.",
+    message: errors_1.BLOCK_ERROR_CODES.NOT_A_DOCUMENT,
+    path: "",
+});
+const yamlFeatureDisallowed = () => ({
+    code: "YAML_FEATURE_DISALLOWED",
+    fix: "Remove YAML anchors, aliases, and custom tags. Use plain mappings and sequences.",
+    message: errors_1.BLOCK_ERROR_CODES.YAML_FEATURE_DISALLOWED,
+    path: "",
+});
+/** Drops one surrounding markdown fence so a model that adds one still parses. */
+const stripBlocksFence = (text) => {
+    const trimmed = text.trim();
+    const match = FENCE.exec(trimmed);
+    if (match?.[1] !== undefined) {
+        return match[1];
+    }
+    return trimmed;
+};
+exports.stripBlocksFence = stripBlocksFence;
+const hasExplicitTag = (tag) => typeof tag === "string" && tag.length > 0;
+const usesDisallowedYaml = (doc) => {
+    const hasTagError = doc.errors.some((error) => error.code === "TAG_RESOLVE_FAILED" || error.code === "BAD_ALIAS");
+    if (hasTagError) {
+        return true;
+    }
+    let disallowed = false;
+    (0, yaml_1.visit)(doc, {
+        Alias() {
+            disallowed = true;
+        },
+        Map(_key, node) {
+            if (node.anchor || hasExplicitTag(node.tag)) {
+                disallowed = true;
+            }
+        },
+        Scalar(_key, node) {
+            if (node.anchor || hasExplicitTag(node.tag)) {
+                disallowed = true;
+            }
+        },
+        Seq(_key, node) {
+            if (node.anchor || hasExplicitTag(node.tag)) {
+                disallowed = true;
+            }
+        },
+    });
+    return disallowed;
+};
+const isPlainMapping = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    return Object.getPrototypeOf(value) === Object.prototype;
+};
+/**
+ * Parses one assistant reply into a plain value.
+ * A surrounding markdown fence is ignored. Anchors, aliases, and custom tags are rejected.
+ * Anything that is not a mapping with `v` is `NOT_A_DOCUMENT`.
+ */
+const parseBlocks = (text) => {
+    const stripped = (0, exports.stripBlocksFence)(text);
+    if (stripped.trim() === "") {
+        return { errors: [notADocument()], ok: false };
+    }
+    const docs = (0, yaml_1.parseAllDocuments)(stripped, {
+        schema: "core",
+        strict: true,
+        uniqueKeys: true,
+    });
+    const doc = docs[0];
+    if (docs.length !== 1 || doc === undefined) {
+        return { errors: [notADocument()], ok: false };
+    }
+    if (usesDisallowedYaml(doc)) {
+        return { errors: [yamlFeatureDisallowed()], ok: false };
+    }
+    if (doc.errors.length > 0) {
+        return { errors: [notADocument()], ok: false };
+    }
+    const value = doc.toJS();
+    if (!isPlainMapping(value) || !Object.hasOwn(value, "v")) {
+        return { errors: [notADocument()], ok: false };
+    }
+    return { ok: true, value };
+};
+exports.parseBlocks = parseBlocks;

package/dist/parsePartial.d.ts

@@ -0,0 +1,12 @@
+export interface ParseBlocksPartialResult {
+    blocks: unknown[];
+    datasets?: Record<string, unknown>;
+    pending: boolean;
+}
+/**
+ * Reads a truncated reply while it is still streaming.
+ * A finished, valid document returns every block with `pending: false`.
+ * A cut reply returns only the top-level blocks that already ended (the next `- ` arrived)
+ * and sets `pending: true`. It never throws.
+ */
+export declare const parseBlocksPartial: (text: string) => ParseBlocksPartialResult;

package/dist/parsePartial.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseBlocksPartial = void 0;
+const parse_1 = require("./parse");
+const validate_1 = require("./validate");
+const emptyPending = () => ({ blocks: [], pending: true });
+const isPlainMapping = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    return Object.getPrototypeOf(value) === Object.prototype;
+};
+const datasetsFrom = (value) => {
+    if (!isPlainMapping(value) || !isPlainMapping(value.datasets)) {
+        return undefined;
+    }
+    return value.datasets;
+};
+const blocksFrom = (value) => {
+    if (!isPlainMapping(value) || !Array.isArray(value.blocks)) {
+        return undefined;
+    }
+    return value.blocks;
+};
+/**
+ * Top-level block items are the lines indented exactly two spaces that start a sequence entry.
+ * Nested lists sit deeper, so they stay inside the current item.
+ */
+const topLevelItems = (body) => {
+    const items = [];
+    let current = null;
+    for (const line of body.split("\n")) {
+        if (line.startsWith("  - ")) {
+            if (current !== null) {
+                items.push(current.join("\n"));
+            }
+            current = [line];
+            continue;
+        }
+        if (current !== null) {
+            current.push(line);
+        }
+    }
+    if (current !== null) {
+        items.push(current.join("\n"));
+    }
+    return items;
+};
+const blockFromItem = (item) => {
+    const parsed = (0, parse_1.parseBlocks)(`v: 1\nblocks:\n${item}\n`);
+    if (!parsed.ok) {
+        return undefined;
+    }
+    const blocks = blocksFrom(parsed.value);
+    return blocks?.[0];
+};
+/**
+ * Reads a truncated reply while it is still streaming.
+ * A finished, valid document returns every block with `pending: false`.
+ * A cut reply returns only the top-level blocks that already ended (the next `- ` arrived)
+ * and sets `pending: true`. It never throws.
+ */
+const parseBlocksPartial = (text) => {
+    try {
+        const stripped = (0, parse_1.stripBlocksFence)(text);
+        if (stripped.trim() === "") {
+            return emptyPending();
+        }
+        const parsed = (0, parse_1.parseBlocks)(stripped);
+        if (parsed.ok) {
+            const blocks = blocksFrom(parsed.value);
+            if (blocks !== undefined && (0, validate_1.validateBlocks)(parsed.value).ok) {
+                return {
+                    blocks,
+                    datasets: datasetsFrom(parsed.value),
+                    pending: false,
+                };
+            }
+        }
+        const lines = stripped.split("\n");
+        const blocksLine = lines.findIndex((line) => line === "blocks:" || line.startsWith("blocks: "));
+        if (blocksLine < 0) {
+            return emptyPending();
+        }
+        const prefix = lines.slice(0, blocksLine).join("\n");
+        let datasets;
+        if (prefix.includes("datasets:")) {
+            const closed = (0, parse_1.parseBlocks)(`${prefix}\nblocks:\n  - type: divider\n`);
+            if (closed.ok) {
+                datasets = datasetsFrom(closed.value);
+            }
+        }
+        const items = topLevelItems(lines.slice(blocksLine + 1).join("\n"));
+        const completeItems = items.slice(0, -1);
+        const blocks = completeItems.flatMap((item) => {
+            const block = blockFromItem(item);
+            return block === undefined ? [] : [block];
+        });
+        return { blocks, datasets, pending: true };
+    }
+    catch {
+        return emptyPending();
+    }
+};
+exports.parseBlocksPartial = parseBlocksPartial;

package/dist/prompt.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The system-prompt section a host prepends when a reply must be one block document.
+ * Every cap is read from `BLOCK_LIMITS` so the prompt, the schema, and the reference stay aligned.
+ */
+export declare const blocksPromptSection: ({ allowHtml, hostActions, imageHosts, }?: {
+    allowHtml?: boolean;
+    hostActions?: readonly string[];
+    imageHosts?: readonly string[];
+}) => string;

package/dist/prompt.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blocksPromptSection = void 0;
+const limits_1 = require("./limits");
+const DATA_EXAMPLE = `v: 1
+datasets:
+  signups:
+    columns:
+      - name: month
+        type: string
+      - name: count
+        type: number
+    rows:
+      - [Jan, 120]
+      - [Feb, 180]
+blocks:
+  - type: chart
+    id: signups_chart
+    kind: bar
+    data: signups
+    x: month
+    y: count
+    title: Signups by month
+  - type: actions
+    id: followups
+    elements:
+      - type: button
+        id: weekly
+        text: Show weekly
+        action:
+          kind: reply
+          text: Show weekly signups for this quarter`;
+const PROSE_EXAMPLE = `v: 1
+blocks:
+  - type: text
+    markdown: I could not find any signups for that range. Try a wider date window.`;
+/**
+ * The system-prompt section a host prepends when a reply must be one block document.
+ * Every cap is read from `BLOCK_LIMITS` so the prompt, the schema, and the reference stay aligned.
+ */
+const blocksPromptSection = ({ allowHtml = false, hostActions = [], imageHosts = [], } = {}) => {
+    const callbacks = hostActions.length === 0
+        ? "No callback names are registered. Do not emit kind callback."
+        : `A callback name must be one of: ${hostActions.join(", ")}.`;
+    const imageHostsLine = imageHosts.length === 0
+        ? "Do not emit an https image src. Use a data:image URL or a file: ref."
+        : `An https image src must use one of these hosts: ${imageHosts.join(", ")}.`;
+    return [
+        "Your entire reply is one document; no prose outside it; no text before tool calls.",
+        "The document is YAML or JSON. Keys, when present, are in this order: v, datasets, blocks.",
+        "v is 1.",
+        allowHtml
+            ? "Block types: heading, text, metric, badge, divider, context, chart, table, actions, columns, card, html, callout, image, details."
+            : "Block types: heading, text, metric, badge, divider, context, chart, table, actions, columns, card, callout, image, details. Do not emit type html.",
+        `An html field is at most ${limits_1.BLOCK_LIMITS.htmlMaxBytes} bytes.`,
+        ...(allowHtml
+            ? [
+                "html requires html and may set title and height (sm, md, or lg). It is a display preview: no scripts, no links, no network.",
+            ]
+            : []),
+        "callout requires text and may set status to info, warning, or alert.",
+        "image requires alt and src. src is a data:image URL, a file: ref, or an https URL on an allowed host.",
+        imageHostsLine,
+        "details requires title and text.",
+        "heading requires text. text requires markdown. metric requires label and value. badge requires text. context requires text.",
+        "chart kind is line, bar, area, or donut. Bind it with data, x, and y, or with points of label and value.",
+        "table requires data, the name of a dataset. actions requires id and elements.",
+        "An element is a button (id, text, action) or a segmented control (id, target, options of label and data).",
+        "action.kind is reply (text), open (url or route, exactly one), select (target and data), or callback (name and optional payload).",
+        "columns has 2 to 4 children. card has children and an optional title. Do not nest columns or card inside columns or card.",
+        `At most ${limits_1.BLOCK_LIMITS.maxBlocks} blocks, including nested blocks.`,
+        `Depth is at most ${limits_1.BLOCK_LIMITS.maxDepth}.`,
+        `An actions block has at most ${limits_1.BLOCK_LIMITS.actionElementsMax} elements.`,
+        `columns has ${limits_1.BLOCK_LIMITS.columnsMin} to ${limits_1.BLOCK_LIMITS.columnsMax} children.`,
+        `At most ${limits_1.BLOCK_LIMITS.maxDatasets} datasets.`,
+        `An inline dataset has at most ${limits_1.BLOCK_LIMITS.datasetRowMax} rows and ${limits_1.BLOCK_LIMITS.datasetColumnMax} columns.`,
+        `A ref dataset limit is at most ${limits_1.BLOCK_LIMITS.refLimitMax}.`,
+        `A text block has at most ${limits_1.BLOCK_LIMITS.blockTextMaxLength} characters.`,
+        `A document has at most ${limits_1.BLOCK_LIMITS.documentTextMaxLength} characters of text.`,
+        `Heading text is at most ${limits_1.BLOCK_LIMITS.headingTextMaxLength} characters.`,
+        `Badge text is at most ${limits_1.BLOCK_LIMITS.badgeTextMaxLength} characters.`,
+        `Context text is at most ${limits_1.BLOCK_LIMITS.contextTextMaxLength} characters.`,
+        `A card title is at most ${limits_1.BLOCK_LIMITS.cardTitleMaxLength} characters.`,
+        `A metric label is at most ${limits_1.BLOCK_LIMITS.metricLabelMaxLength} characters, its value ${limits_1.BLOCK_LIMITS.metricValueMaxLength}, its delta ${limits_1.BLOCK_LIMITS.metricDeltaMaxLength}, and its helper ${limits_1.BLOCK_LIMITS.metricHelperMaxLength}.`,
+        `A bar chart warns above ${limits_1.BLOCK_LIMITS.barCategoryWarning} categories.`,
+        `A donut chart warns above ${limits_1.BLOCK_LIMITS.donutSliceWarning} slices.`,
+        "Use the datasetId a tool returned; never paste more than 500 rows.",
+        callbacks,
+        "Example with data:",
+        DATA_EXAMPLE,
+        "Example with prose only:",
+        PROSE_EXAMPLE,
+    ].join("\n");
+};
+exports.blocksPromptSection = blocksPromptSection;

package/dist/schema.d.ts

@@ -0,0 +1,199 @@
+import { z } from "zod";
+export declare const HEADING_SIZES: readonly ["sm", "md", "lg", "xl", "2xl"];
+export declare const HTML_HEIGHTS: readonly ["sm", "md", "lg"];
+export declare const CALLOUT_STATUSES: readonly ["info", "warning", "alert"];
+export declare const BADGE_STATUSES: readonly ["info", "error", "warning", "success", "neutral", "active"];
+export declare const METRIC_TRENDS: readonly ["up", "down", "flat"];
+export declare const LAYOUT_BLOCK_TYPES: readonly ["columns", "card"];
+export interface HeadingBlock {
+    id?: string;
+    size?: (typeof HEADING_SIZES)[number];
+    text: string;
+    type: "heading";
+}
+export interface TextBlock {
+    id?: string;
+    markdown: string;
+    type: "text";
+}
+export interface MetricBlock {
+    delta?: string;
+    helper?: string;
+    id?: string;
+    label: string;
+    trend?: (typeof METRIC_TRENDS)[number];
+    type: "metric";
+    value: string;
+}
+export interface BadgeBlock {
+    id?: string;
+    status?: (typeof BADGE_STATUSES)[number];
+    text: string;
+    type: "badge";
+}
+export interface DividerBlock {
+    id?: string;
+    type: "divider";
+}
+export interface ContextBlock {
+    id?: string;
+    text: string;
+    type: "context";
+}
+export declare const CHART_KINDS: readonly ["line", "bar", "area", "donut"];
+export declare const CHART_HEIGHTS: readonly ["sm", "md", "lg"];
+export declare const DATASET_COLUMN_TYPES: readonly ["string", "number", "date"];
+export declare const DATASET_GRAINS: readonly ["hour", "day", "week", "month"];
+export interface DatasetColumn {
+    name: string;
+    type: (typeof DATASET_COLUMN_TYPES)[number];
+}
+export interface InlineDataset {
+    columns: DatasetColumn[];
+    rows: unknown[][];
+    source?: "inline";
+}
+export interface RefDataset {
+    grain?: (typeof DATASET_GRAINS)[number];
+    id: string;
+    limit?: number;
+    source: "ref";
+}
+export type Dataset = InlineDataset | RefDataset;
+export interface ChartBlock {
+    data?: string;
+    emptyText?: string;
+    height?: (typeof CHART_HEIGHTS)[number];
+    id?: string;
+    kind: (typeof CHART_KINDS)[number];
+    legend?: boolean;
+    points?: {
+        label: string;
+        value: number;
+    }[];
+    title?: string;
+    type: "chart";
+    x?: string;
+    y?: string;
+}
+export interface TableBlock {
+    columns?: string[];
+    data: string;
+    id?: string;
+    title?: string;
+    type: "table";
+}
+export declare const BUTTON_VARIANTS: readonly ["primary", "secondary", "outline", "ghost", "destructive"];
+export interface ReplyAction {
+    kind: "reply";
+    text: string;
+}
+export interface OpenAction {
+    kind: "open";
+    route?: string;
+    url?: string;
+}
+export interface SelectAction {
+    data: string;
+    kind: "select";
+    target: string;
+}
+export interface CallbackAction {
+    kind: "callback";
+    name: string;
+    payload?: Record<string, unknown>;
+}
+export type BlockAction = ReplyAction | OpenAction | SelectAction | CallbackAction;
+export interface ButtonElement {
+    action: BlockAction;
+    iconName?: string;
+    id: string;
+    text: string;
+    type: "button";
+    variant?: (typeof BUTTON_VARIANTS)[number];
+}
+export interface SegmentedElement {
+    id: string;
+    options: {
+        data: string;
+        label: string;
+    }[];
+    target: string;
+    type: "segmented";
+}
+export interface ActionsBlock {
+    elements: (ButtonElement | SegmentedElement)[];
+    id: string;
+    type: "actions";
+}
+export interface HtmlBlock {
+    height?: (typeof HTML_HEIGHTS)[number];
+    html: string;
+    id?: string;
+    title?: string;
+    type: "html";
+}
+export interface CalloutBlock {
+    id?: string;
+    status?: (typeof CALLOUT_STATUSES)[number];
+    text: string;
+    type: "callout";
+}
+export interface ImageBlock {
+    alt: string;
+    id?: string;
+    src: string;
+    type: "image";
+}
+export interface DetailsBlock {
+    id?: string;
+    text: string;
+    title: string;
+    type: "details";
+}
+export interface ColumnsBlock {
+    children: Block[];
+    id?: string;
+    type: "columns";
+}
+export interface CardBlock {
+    children: Block[];
+    id?: string;
+    title?: string;
+    type: "card";
+}
+export type LeafBlock = HeadingBlock | TextBlock | MetricBlock | BadgeBlock | DividerBlock | ContextBlock | ChartBlock | TableBlock | ActionsBlock | HtmlBlock | CalloutBlock | ImageBlock | DetailsBlock;
+export type Block = LeafBlock | ColumnsBlock | CardBlock;
+export interface BlocksDocument {
+    blocks: Block[];
+    datasets?: Record<string, Dataset>;
+    v: 1;
+}
+/** Document schema. Semantic dataset and chart checks run in `lintDocument`. */
+export declare const blocksSchema: z.ZodObject<{
+    blocks: z.ZodArray<z.ZodType<Block, unknown, z.core.$ZodTypeInternals<Block, unknown>>>;
+    datasets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        grain: z.ZodOptional<z.ZodEnum<{
+            hour: "hour";
+            day: "day";
+            week: "week";
+            month: "month";
+        }>>;
+        id: z.ZodString;
+        limit: z.ZodOptional<z.ZodNumber>;
+        source: z.ZodLiteral<"ref">;
+    }, z.core.$strict>, z.ZodObject<{
+        columns: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodEnum<{
+                string: "string";
+                number: "number";
+                date: "date";
+            }>;
+        }, z.core.$strict>>;
+        rows: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodNull]>>>;
+        source: z.ZodOptional<z.ZodLiteral<"inline">>;
+    }, z.core.$strict>]>>>;
+    v: z.ZodLiteral<1>;
+}, z.core.$strict>;
+export declare const wrapAsTextDocument: (text: string) => BlocksDocument;