@terreno/blocks 57.10.1

package/src/errors.ts

@@ -0,0 +1,125 @@
+/** Error codes for whole-reply documents. Warnings never block rendering. */
+export const BLOCK_ERROR_CODES = {
+  COLUMN_NOT_FOUND: "A chart or table names a column the dataset does not have.",
+  COLUMN_TYPE_MISMATCH: "A column value does not match the column type.",
+  DATASET_NOT_FOUND: "A chart or table names a dataset the document does not define.",
+  DATASET_TOO_LARGE: "A dataset has more rows or columns than allowed.",
+  DEPTH_EXCEEDED: "A columns or card block is nested inside another columns or card block.",
+  DUPLICATE_ID: "An id or a column name is used more than once.",
+  HTML_DISABLED: "An html block is present and this host has not turned HTML on.",
+  HTML_TOO_LARGE: "An html block is larger than 100,000 bytes.",
+  IMAGE_HOST_NOT_ALLOWED:
+    "An image URL is not a data:image URL, a file: ref, or an https URL on an allowed host.",
+  INVALID_ENUM: "A value is not one of the allowed values.",
+  INVALID_FORMAT: "A string does not match its required format.",
+  INVALID_TYPE: "A value has the wrong type.",
+  KEY_ORDER: "Top-level keys are not in the order v, datasets, blocks.",
+  MISSING_REQUIRED: "A required field is missing.",
+  NOT_A_DOCUMENT: "The reply is not one YAML or JSON mapping with a v field.",
+  ROW_ARITY_MISMATCH: "A dataset row does not have one value per column.",
+  SELECT_TARGET_INVALID: "A select action names a block that is not a chart or table.",
+  TABLE_TOO_WIDE: "A table lists more columns than allowed.",
+  TOO_FEW: "A list has fewer items than allowed.",
+  TOO_LONG: "A string is longer than allowed.",
+  TOO_MANY: "A list has more items than allowed.",
+  TOO_MANY_BLOCKS: "The document has more than the maximum number of blocks.",
+  TOO_MANY_POINTS: "A ref dataset asks for more rendered rows than allowed.",
+  TOO_SHORT: "A string is empty or only whitespace.",
+  UNKNOWN_HOST_ACTION: "A callback names a host action that is not registered.",
+  UNKNOWN_KEY: "An object has a field that its schema does not define.",
+  UNSUPPORTED_VERSION: "The document version is not 1.",
+  YAML_FEATURE_DISALLOWED: "The document uses a YAML anchor, alias, or custom tag.",
+} as const;
+
+/** Chart heuristics. They ride along on a valid document and do not block rendering. */
+export const BLOCK_WARNING_CODES = {
+  BAR_TOO_MANY_CATEGORIES: "A bar chart has more categories than fit comfortably.",
+  DONUT_TOO_MANY_SLICES: "A donut chart has more slices than fit comfortably.",
+  LINE_SINGLE_POINT: "A line chart has only one point.",
+} as const;
+
+export type BlockWarningCode = keyof typeof BLOCK_WARNING_CODES;
+
+export type BlockErrorCode = keyof typeof BLOCK_ERROR_CODES;
+
+export interface BlockError {
+  /** A key of `BLOCK_ERROR_CODES` or `BLOCK_WARNING_CODES`. */
+  code: BlockErrorCode | BlockWarningCode;
+  /** One instruction that fixes the error. */
+  fix: string;
+  /** What is wrong, in one sentence. */
+  message: string;
+  /** Where the error is, such as `blocks[0].text`. The root is an empty string. */
+  path: string;
+}
+
+export const formatBlockPath = (segments: readonly PropertyKey[]): string =>
+  segments.reduce<string>((path, segment) => {
+    if (typeof segment === "number") {
+      return `${path}[${segment}]`;
+    }
+    const key = String(segment);
+    if (path === "") {
+      return key;
+    }
+    return `${path}.${key}`;
+  }, "");
+
+const pathIndex = (segment: string): number | string => {
+  const index = Number(segment);
+  if (segment !== "" && String(index) === segment) {
+    return index;
+  }
+  return segment;
+};
+
+/** Splits `blocks[0].text` into comparable pieces so indexes sort numerically. */
+const blockPathSegments = (path: string): readonly (string | number)[] => {
+  const parts: (string | number)[] = [];
+  const pattern = /([^[\].]+)|\[(\d+)\]/g;
+  for (const match of path.matchAll(pattern)) {
+    const index = match[2];
+    if (index !== undefined) {
+      parts.push(pathIndex(index));
+      continue;
+    }
+    const key = match[1];
+    if (key !== undefined) {
+      parts.push(key);
+    }
+  }
+  return parts;
+};
+
+const compareBlockPaths = (left: string, right: string): number => {
+  const leftParts = blockPathSegments(left);
+  const rightParts = blockPathSegments(right);
+  const length = Math.max(leftParts.length, rightParts.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftPart = leftParts[index];
+    const rightPart = rightParts[index];
+    if (leftPart === undefined) {
+      return -1;
+    }
+    if (rightPart === undefined) {
+      return 1;
+    }
+    if (leftPart === rightPart) {
+      continue;
+    }
+    if (typeof leftPart === "number" && typeof rightPart === "number") {
+      return leftPart - rightPart;
+    }
+    return String(leftPart) < String(rightPart) ? -1 : 1;
+  }
+  return 0;
+};
+
+export const sortBlockErrors = (errors: readonly BlockError[]): BlockError[] =>
+  [...errors].sort((left, right) => {
+    const byPath = compareBlockPaths(left.path, right.path);
+    if (byPath !== 0) {
+      return byPath;
+    }
+    return left.code < right.code ? -1 : 1;
+  });

package/src/fixtures/invalid/column-not-found.yaml

@@ -0,0 +1,14 @@
+v: 1
+datasets:
+  signups:
+    columns:
+      - {name: month, type: string}
+      - {name: count, type: number}
+    rows:
+      - [Jan, 120]
+blocks:
+  - type: chart
+    kind: bar
+    data: signups
+    x: day
+    y: count

package/src/fixtures/invalid/column-type.yaml

@@ -0,0 +1,14 @@
+v: 1
+datasets:
+  signups:
+    columns:
+      - {name: month, type: string}
+      - {name: count, type: number}
+    rows:
+      - [Jan, 120]
+blocks:
+  - type: chart
+    kind: bar
+    data: signups
+    x: month
+    y: month

package/src/fixtures/invalid/dataset-not-found.yaml

@@ -0,0 +1,7 @@
+v: 1
+blocks:
+  - type: chart
+    kind: bar
+    data: missing
+    x: month
+    y: count

package/src/fixtures/invalid/dataset-too-large.yaml

@@ -0,0 +1,20 @@
+v: 1
+datasets:
+  signups:
+    columns:
+      - {name: a, type: string}
+      - {name: b, type: string}
+      - {name: c, type: string}
+      - {name: d, type: string}
+      - {name: e, type: string}
+      - {name: f, type: string}
+      - {name: g, type: string}
+      - {name: h, type: string}
+      - {name: i, type: string}
+      - {name: j, type: string}
+      - {name: k, type: string}
+      - {name: l, type: string}
+      - {name: m, type: string}
+    rows: []
+blocks:
+  - type: divider

package/src/fixtures/invalid/depth-exceeded.yaml

@@ -0,0 +1,10 @@
+v: 1
+blocks:
+  - type: columns
+    children:
+      - type: card
+        children:
+          - type: text
+            markdown: Nested
+      - type: text
+        markdown: Beside

package/src/fixtures/invalid/duplicate-id.yaml

@@ -0,0 +1,6 @@
+v: 1
+blocks:
+  - type: divider
+    id: twice
+  - type: divider
+    id: twice

package/src/fixtures/invalid/invalid-enum.yaml

@@ -0,0 +1,5 @@
+v: 1
+blocks:
+  - type: heading
+    text: Hello
+    size: huge

package/src/fixtures/invalid/key-order.yaml

@@ -0,0 +1,4 @@
+blocks:
+  - type: text
+    markdown: Hello
+v: 1

package/src/fixtures/invalid/missing-required.yaml

@@ -0,0 +1,3 @@
+v: 1
+blocks:
+  - type: text

package/src/fixtures/invalid/not-a-document.txt

@@ -0,0 +1 @@
+Just a sentence, not a document.

package/src/fixtures/invalid/row-arity.yaml

@@ -0,0 +1,11 @@
+v: 1
+datasets:
+  signups:
+    columns:
+      - {name: month, type: string}
+      - {name: count, type: number}
+    rows:
+      - [Jan]
+blocks:
+  - type: table
+    data: signups

package/src/fixtures/invalid/select-target.yaml

@@ -0,0 +1,12 @@
+v: 1
+blocks:
+  - type: actions
+    id: followups
+    elements:
+      - type: button
+        id: weekly
+        text: Show weekly
+        action:
+          kind: select
+          target: missing_chart
+          data: signups

package/src/fixtures/invalid/table-too-wide.yaml

@@ -0,0 +1,9 @@
+v: 1
+datasets:
+  signups:
+    source: ref
+    id: ds_1
+blocks:
+  - type: table
+    data: signups
+    columns: [a, b, c, d, e, f, g, h, i, j, k, l, m]

package/src/fixtures/invalid/too-many-points.yaml

@@ -0,0 +1,8 @@
+v: 1
+datasets:
+  signups:
+    source: ref
+    id: ds_1
+    limit: 1001
+blocks:
+  - type: divider

package/src/fixtures/invalid/unknown-key.yaml

@@ -0,0 +1,5 @@
+v: 1
+blocks:
+  - type: heading
+    text: Hello
+    color: primary

package/src/fixtures/invalid/unsupported-version.yaml

@@ -0,0 +1,4 @@
+v: 2
+blocks:
+  - type: text
+    markdown: Hello

package/src/fixtures/invalid/yaml-anchor.yaml

@@ -0,0 +1,6 @@
+v: 1
+blocks:
+  - &item
+    type: text
+    markdown: Hello
+  - *item

package/src/fixtures/partial/cut-after-divider.yaml

@@ -0,0 +1,5 @@
+v: 1
+blocks:
+  - type: divider
+  - type: text
+    markdown: "hello

package/src/fixtures/valid/actions.yaml

@@ -0,0 +1,32 @@
+v: 1
+blocks:
+  - type: chart
+    id: signups_chart
+    kind: bar
+    points:
+      - label: Jan
+        value: 120
+  - type: actions
+    id: followups
+    elements:
+      - type: button
+        id: weekly
+        text: Show weekly
+        action:
+          kind: reply
+          text: Show weekly signups for this quarter
+      - type: button
+        id: open_report
+        text: Open report
+        variant: outline
+        action:
+          kind: open
+          route: /reports
+      - type: segmented
+        id: grain
+        target: signups_chart
+        options:
+          - label: Month
+            data: signups
+          - label: Week
+            data: signups_weekly

package/src/fixtures/valid/chart.yaml

@@ -0,0 +1,20 @@
+v: 1
+datasets:
+  signups:
+    columns:
+      - {name: month, type: string}
+      - {name: count, type: number}
+    rows:
+      - [Jan, 120]
+      - [Feb, 145]
+blocks:
+  - type: chart
+    id: signups_chart
+    kind: bar
+    data: signups
+    x: month
+    y: count
+    title: Signups by month
+  - type: table
+    data: signups
+    columns: [month, count]

package/src/fixtures/valid/layout.yaml

@@ -0,0 +1,26 @@
+v: 1
+blocks:
+  - type: heading
+    text: Signups this quarter
+    size: lg
+  - type: text
+    markdown: Signups grew **12%** quarter over quarter.
+  - type: columns
+    children:
+      - type: metric
+        label: Total
+        value: "403"
+        delta: "+12%"
+        trend: up
+      - type: metric
+        label: Best month
+        value: Feb
+  - type: card
+    title: Notes
+    children:
+      - type: badge
+        text: Draft
+        status: info
+      - type: context
+        text: February was the strongest month.
+      - type: divider

package/src/fixtures/valid/prose.yaml

@@ -0,0 +1,4 @@
+v: 1
+blocks:
+  - type: text
+    markdown: I could not find any signups for that range.

package/src/html.test.ts

@@ -0,0 +1,52 @@
+import {describe, expect, it} from "bun:test";
+
+import {BLOCK_LIMITS} from "./limits";
+import {blocksPromptSection} from "./prompt";
+import {validateBlocks} from "./validate";
+
+const htmlDocument = (html: string): unknown => {
+  const block: Record<string, unknown> = {};
+  block.type = "html";
+  block.title = "Invoice preview";
+  block.height = "md";
+  block.html = html;
+  const doc: Record<string, unknown> = {};
+  doc.v = 1;
+  doc.blocks = [block];
+  return doc;
+};
+
+describe("html blocks", () => {
+  it("rejects html unless the host turns it on", () => {
+    const result = validateBlocks(htmlDocument("<p>Invoice</p>"));
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.errors.map((error) => error.code)).toContain("HTML_DISABLED");
+    }
+  });
+
+  it("accepts a short html block when HTML is on", () => {
+    const result = validateBlocks(htmlDocument("<h1>Invoice #1042</h1>"), {allowHtml: true});
+
+    expect(result.ok).toBe(true);
+  });
+
+  it("accepts html at 100,000 bytes and rejects one more byte", () => {
+    const atLimit = "a".repeat(BLOCK_LIMITS.htmlMaxBytes);
+    const over = `${atLimit}b`;
+
+    expect(validateBlocks(htmlDocument(atLimit), {allowHtml: true}).ok).toBe(true);
+    const result = validateBlocks(htmlDocument(over), {allowHtml: true});
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.errors.map((error) => error.code)).toContain("HTML_TOO_LARGE");
+    }
+  });
+
+  it("mentions html in the prompt only when it is allowed", () => {
+    expect(blocksPromptSection()).toContain("Do not emit type html");
+    expect(blocksPromptSection({allowHtml: true})).toContain("card, html");
+    expect(blocksPromptSection({allowHtml: true})).toContain(String(BLOCK_LIMITS.htmlMaxBytes));
+  });
+});

package/src/index.test.ts

@@ -0,0 +1,114 @@
+import {describe, expect, it} from "bun:test";
+
+import * as terrenoBlocks from "./index";
+
+/**
+ * Guards the public entrypoint of @terreno/blocks: a missing or renamed export here breaks
+ * @terreno/ai, @terreno/ui, and apps, and the per-module tests import the modules directly.
+ */
+describe("@terreno/blocks public exports", () => {
+  const expectedExports = [
+    "BADGE_STATUSES",
+    "BLOCK_ERROR_CODES",
+    "BLOCK_LIMITS",
+    "BLOCK_WARNING_CODES",
+    "BUTTON_VARIANTS",
+    "CALLOUT_STATUSES",
+    "CHART_HEIGHTS",
+    "CHART_KINDS",
+    "DATASET_COLUMN_TYPES",
+    "DATASET_GRAINS",
+    "HEADING_SIZES",
+    "HTML_HEIGHTS",
+    "METRIC_TRENDS",
+    "blocksJsonSchema",
+    "blocksPromptSection",
+    "blocksSchema",
+    "parseBlocks",
+    "parseBlocksPartial",
+    "validateBlocks",
+    "wrapAsTextDocument",
+
+    "ASK_ERROR_CODES",
+
+    "ASK_FILE_ACCEPT",
+    "ASK_FILE_ACCEPT_MIME_TYPES",
+    "acceptedFileMimeTypes",
+    "checkAskFileBytes",
+    "fileNotOwnedError",
+    "isTextFileMimeType",
+    "parseAskDataUrl",
+    "sniffFileBytes",
+
+    "askResponseWithToolCallIdSchema",
+    "askSurfaceSchema",
+    "pendingAskListItemSchema",
+    "pendingAskListSchema",
+    "pendingAskSummarySchema",
+    "turnRequestSchema",
+    "turnResultSchema",
+
+    "askJsonSchemas",
+
+    "formDefaultValues",
+    "formTextMaxLength",
+
+    "ASK_LIMITS",
+
+    "askPromptSection",
+
+    "ASK_CANCEL_REASONS",
+    "ASK_KINDS",
+    "ASK_SURFACES",
+    "CHOICE_SELECT_MODES",
+    "COMPACT_ASK_KINDS",
+    "askAcceptResponseSchema",
+    "askAllowsDecline",
+    "askCancelResponseSchema",
+    "askDeclineResponseSchema",
+    "askInputSchemaFor",
+    "askInputSchemas",
+    "askKindsForSurface",
+    "askOutputSchemas",
+    "askResponseSchema",
+    "choiceAnswerSchema",
+    "choiceAskInputSchema",
+    "choiceAskResponseSchema",
+    "choiceOptionSchema",
+    "choiceSelectionBounds",
+    "compactAskInputSchemas",
+    "compactChoiceAskInputSchema",
+    "confirmAnswerSchema",
+    "confirmAskInputSchema",
+    "confirmAskResponseSchema",
+    "confirmButtonLabels",
+    "FORM_FIELD_TYPES",
+    "askFileRefSchema",
+    "filesAnswerSchema",
+    "filesAskInputSchema",
+    "filesAskResponseSchema",
+    "filesCountBounds",
+    "formAnswerSchema",
+    "formAskInputSchema",
+    "formAskResponseSchema",
+    "formFieldSchema",
+    "isCompactAskKind",
+    "markdownAnswerSchema",
+    "markdownAskInputSchema",
+    "markdownAskResponseSchema",
+    "markdownLengthBounds",
+
+    "SIMPLE_CARD_BUTTON_STYLES",
+    "resolveButtonAnswer",
+    "simpleCardButtonSchema",
+    "simpleCardSchema",
+    "toSimpleCard",
+
+    "validateAskInput",
+    "validateAskResponse",
+  ];
+
+  it("exports exactly the public runtime API", () => {
+    expect(Object.keys(terrenoBlocks).sort()).toEqual([...expectedExports].sort());
+  });
+});