@terreno/blocks 57.10.1

package/src/index.ts

@@ -0,0 +1,175 @@
+export type {AskErrorCode, AskValidationError} from "./asks/errors";
+export {ASK_ERROR_CODES} from "./asks/errors";
+export type {AskFileAccept, AskFileMimeType, SniffedFileType} from "./asks/files";
+export {
+  ASK_FILE_ACCEPT,
+  ASK_FILE_ACCEPT_MIME_TYPES,
+  acceptedFileMimeTypes,
+  checkAskFileBytes,
+  fileNotOwnedError,
+  isTextFileMimeType,
+  parseAskDataUrl,
+  sniffFileBytes,
+} from "./asks/files";
+export type {FormValue} from "./asks/formValues";
+export {formDefaultValues, formTextMaxLength} from "./asks/formValues";
+export type {
+  AskResponseWithToolCallId,
+  PendingAskListItem,
+  PendingAskSummary,
+  TurnRequest,
+  TurnResult,
+} from "./asks/headless";
+export {
+  askResponseWithToolCallIdSchema,
+  askSurfaceSchema,
+  pendingAskListItemSchema,
+  pendingAskListSchema,
+  pendingAskSummarySchema,
+  turnRequestSchema,
+  turnResultSchema,
+} from "./asks/headless";
+export {askJsonSchemas} from "./asks/jsonSchema";
+export {ASK_LIMITS} from "./asks/limits";
+export {askPromptSection} from "./asks/prompt";
+export type {
+  Ask,
+  AskFileRef,
+  AskKind,
+  AskResponse,
+  AskSurface,
+  ChoiceAnswer,
+  ChoiceAsk,
+  ChoiceAskInput,
+  ChoiceAskResponse,
+  ChoiceOption,
+  ChoiceSelectMode,
+  CompactAskKind,
+  ConfirmAnswer,
+  ConfirmAsk,
+  ConfirmAskInput,
+  ConfirmAskResponse,
+  FilesAnswer,
+  FilesAsk,
+  FilesAskInput,
+  FilesAskResponse,
+  FormAnswer,
+  FormAsk,
+  FormAskInput,
+  FormAskResponse,
+  FormField,
+  FormFieldType,
+  MarkdownAnswer,
+  MarkdownAsk,
+  MarkdownAskInput,
+  MarkdownAskResponse,
+} from "./asks/schema";
+export {
+  ASK_CANCEL_REASONS,
+  ASK_KINDS,
+  ASK_SURFACES,
+  askAcceptResponseSchema,
+  askAllowsDecline,
+  askCancelResponseSchema,
+  askDeclineResponseSchema,
+  askFileRefSchema,
+  askInputSchemaFor,
+  askInputSchemas,
+  askKindsForSurface,
+  askOutputSchemas,
+  askResponseSchema,
+  CHOICE_SELECT_MODES,
+  COMPACT_ASK_KINDS,
+  choiceAnswerSchema,
+  choiceAskInputSchema,
+  choiceAskResponseSchema,
+  choiceOptionSchema,
+  choiceSelectionBounds,
+  compactAskInputSchemas,
+  compactChoiceAskInputSchema,
+  confirmAnswerSchema,
+  confirmAskInputSchema,
+  confirmAskResponseSchema,
+  confirmButtonLabels,
+  FORM_FIELD_TYPES,
+  filesAnswerSchema,
+  filesAskInputSchema,
+  filesAskResponseSchema,
+  filesCountBounds,
+  formAnswerSchema,
+  formAskInputSchema,
+  formAskResponseSchema,
+  formFieldSchema,
+  isCompactAskKind,
+  markdownAnswerSchema,
+  markdownAskInputSchema,
+  markdownAskResponseSchema,
+  markdownLengthBounds,
+} from "./asks/schema";
+export type {SimpleCard, SimpleCardButton} from "./asks/simpleCard";
+export {
+  resolveButtonAnswer,
+  SIMPLE_CARD_BUTTON_STYLES,
+  simpleCardButtonSchema,
+  simpleCardSchema,
+  toSimpleCard,
+} from "./asks/simpleCard";
+export {validateAskInput} from "./asks/validateInput";
+export {validateAskResponse} from "./asks/validateResponse";
+export type {BlockError, BlockErrorCode, BlockWarningCode} from "./errors";
+export {BLOCK_ERROR_CODES, BLOCK_WARNING_CODES} from "./errors";
+export {blocksJsonSchema} from "./jsonSchema";
+export {BLOCK_LIMITS} from "./limits";
+export type {KnownDataset, LintBlocksOptions} from "./lint";
+export type {ParseBlocksResult} from "./parse";
+export {parseBlocks} from "./parse";
+export type {ParseBlocksPartialResult} from "./parsePartial";
+export {parseBlocksPartial} from "./parsePartial";
+export {blocksPromptSection} from "./prompt";
+export type {
+  ActionsBlock,
+  BadgeBlock,
+  Block,
+  BlockAction,
+  BlocksDocument,
+  ButtonElement,
+  CallbackAction,
+  CalloutBlock,
+  CardBlock,
+  ChartBlock,
+  ColumnsBlock,
+  ContextBlock,
+  Dataset,
+  DatasetColumn,
+  DetailsBlock,
+  DividerBlock,
+  HeadingBlock,
+  HtmlBlock,
+  ImageBlock,
+  InlineDataset,
+  LeafBlock,
+  MetricBlock,
+  OpenAction,
+  RefDataset,
+  ReplyAction,
+  SegmentedElement,
+  SelectAction,
+  TableBlock,
+  TextBlock,
+} from "./schema";
+export {
+  BADGE_STATUSES,
+  BUTTON_VARIANTS,
+  blocksSchema,
+  CALLOUT_STATUSES,
+  CHART_HEIGHTS,
+  CHART_KINDS,
+  DATASET_COLUMN_TYPES,
+  DATASET_GRAINS,
+  HEADING_SIZES,
+  HTML_HEIGHTS,
+  METRIC_TRENDS,
+  wrapAsTextDocument,
+} from "./schema";
+export type {ValidateBlocksResult} from "./validate";
+export {validateBlocks} from "./validate";

package/src/jsonSchema.test.ts

@@ -0,0 +1,33 @@
+import {describe, expect, it} from "bun:test";
+import {readdirSync, readFileSync} from "node:fs";
+import {join} from "node:path";
+import Ajv from "ajv";
+
+import {blocksJsonSchema} from "./jsonSchema";
+import {parseBlocks} from "./parse";
+import {blocksSchema} from "./schema";
+
+const fixturesDir = join(import.meta.dir, "fixtures");
+
+describe("blocksJsonSchema", () => {
+  it("accepts and rejects the same parsed fixtures as the Zod schema", () => {
+    const ajv = new Ajv({allErrors: true, strict: false});
+    const validate = ajv.compile(blocksJsonSchema);
+    const files = [
+      ...readdirSync(join(fixturesDir, "valid")).map((name) => join("valid", name)),
+      ...readdirSync(join(fixturesDir, "invalid")).map((name) => join("invalid", name)),
+    ];
+    let compared = 0;
+    for (const name of files) {
+      const parsed = parseBlocks(readFileSync(join(fixturesDir, name), "utf8"));
+      if (!parsed.ok) {
+        continue;
+      }
+      compared += 1;
+      const zodOk = blocksSchema.safeParse(parsed.value).success;
+      const ajvOk = validate(parsed.value) === true;
+      expect(ajvOk).toBe(zodOk);
+    }
+    expect(compared).toBeGreaterThan(0);
+  });
+});

package/src/jsonSchema.ts

@@ -0,0 +1,11 @@
+import {z} from "zod";
+
+import {blocksSchema} from "./schema";
+
+/**
+ * JSON Schema for the same document `blocksSchema` checks.
+ * Semantic lint (dataset columns, select targets, host callbacks) is not expressible here.
+ */
+export const blocksJsonSchema: Record<string, unknown> = z.toJSONSchema(blocksSchema, {
+  target: "draft-07",
+});

package/src/limits.ts

@@ -0,0 +1,27 @@
+/**
+ * Caps shared by the schema, the prompt, and the reference page.
+ */
+export const BLOCK_LIMITS = {
+  actionElementsMax: 25,
+  badgeTextMaxLength: 80,
+  barCategoryWarning: 60,
+  blockTextMaxLength: 4_000,
+  cardTitleMaxLength: 120,
+  columnsMax: 4,
+  columnsMin: 2,
+  contextTextMaxLength: 280,
+  datasetColumnMax: 12,
+  datasetRowMax: 500,
+  documentTextMaxLength: 20_000,
+  donutSliceWarning: 8,
+  headingTextMaxLength: 200,
+  htmlMaxBytes: 100_000,
+  maxBlocks: 50,
+  maxDatasets: 8,
+  maxDepth: 2,
+  metricDeltaMaxLength: 40,
+  metricHelperMaxLength: 120,
+  metricLabelMaxLength: 80,
+  metricValueMaxLength: 80,
+  refLimitMax: 1_000,
+} as const;

package/src/lint.test.ts

@@ -0,0 +1,289 @@
+import {describe, expect, it} from "bun:test";
+
+import {validateBlocks} from "./validate";
+
+const documentWith = ({
+  blocks,
+  datasets,
+}: {
+  blocks: unknown[];
+  datasets?: Record<string, unknown>;
+}): Record<string, unknown> => {
+  const doc: Record<string, unknown> = {};
+  doc.v = 1;
+  if (datasets !== undefined) {
+    doc.datasets = datasets;
+  }
+  doc.blocks = blocks;
+  return doc;
+};
+
+const inline = {
+  columns: [
+    {name: "month", type: "string"},
+    {name: "count", type: "number"},
+  ],
+  rows: [
+    ["Jan", 1],
+    ["Feb", 2],
+  ],
+};
+
+describe("lintDocument", () => {
+  it("rejects an element id that matches another id in the document", () => {
+    const validated = validateBlocks(
+      documentWith({
+        blocks: [
+          {
+            elements: [
+              {
+                action: {kind: "reply", text: "Again"},
+                id: "followups",
+                text: "Again",
+                type: "button",
+              },
+            ],
+            id: "followups",
+            type: "actions",
+          },
+        ],
+      })
+    );
+    expect(validated.ok).toBe(false);
+    if (validated.ok) {
+      return;
+    }
+    expect(validated.errors.map((error) => error.code)).toEqual(["DUPLICATE_ID"]);
+    expect(validated.errors[0]?.path).toBe("blocks[0].elements[0].id");
+  });
+
+  it("rejects a callback that is not in the host allowlist", () => {
+    const doc = documentWith({
+      blocks: [
+        {
+          elements: [
+            {
+              action: {kind: "callback", name: "exportDataset"},
+              id: "export",
+              text: "Export",
+              type: "button",
+            },
+          ],
+          id: "followups",
+          type: "actions",
+        },
+      ],
+    });
+    const allowed = validateBlocks(doc, {hostActions: ["exportDataset"]});
+    expect(allowed.ok).toBe(true);
+
+    const rejected = validateBlocks(doc, {hostActions: ["other"]});
+    expect(rejected.ok).toBe(false);
+    if (rejected.ok) {
+      return;
+    }
+    expect(rejected.errors.map((error) => error.code)).toEqual(["UNKNOWN_HOST_ACTION"]);
+
+    const unchecked = validateBlocks(doc);
+    expect(unchecked.ok).toBe(true);
+  });
+
+  it("requires an open action to set url or route, not both", () => {
+    const open = (action: Record<string, unknown>): Record<string, unknown> =>
+      documentWith({
+        blocks: [
+          {
+            elements: [{action, id: "go", text: "Go", type: "button"}],
+            id: "followups",
+            type: "actions",
+          },
+        ],
+      });
+    expect(validateBlocks(open({kind: "open", route: "/reports"})).ok).toBe(true);
+    expect(validateBlocks(open({kind: "open", url: "https://example.com"})).ok).toBe(true);
+    const neither = validateBlocks(open({kind: "open"}));
+    expect(neither.ok).toBe(false);
+    if (!neither.ok) {
+      expect(neither.errors.map((error) => ({code: error.code, path: error.path}))).toEqual([
+        {code: "MISSING_REQUIRED", path: "blocks[0].elements[0].action"},
+      ]);
+    }
+    expect(
+      validateBlocks(open({kind: "open", route: "/reports", url: "https://example.com"})).ok
+    ).toBe(false);
+  });
+
+  it("warns when a bar, donut, or line chart is a poor fit", () => {
+    const rows = Array.from({length: 61}, (_unused, index) => [`m${index}`, index]);
+    const bar = validateBlocks(
+      documentWith({
+        blocks: [{data: "signups", kind: "bar", type: "chart", x: "month", y: "count"}],
+        datasets: {signups: {...inline, rows}},
+      })
+    );
+    expect(bar.ok).toBe(true);
+    if (!bar.ok) {
+      return;
+    }
+    expect(bar.warnings.map((warning) => warning.code)).toEqual(["BAR_TOO_MANY_CATEGORIES"]);
+
+    const donut = validateBlocks(
+      documentWith({
+        blocks: [
+          {
+            kind: "donut",
+            points: Array.from({length: 9}, (_unused, index) => ({
+              label: `s${index}`,
+              value: index,
+            })),
+            type: "chart",
+          },
+        ],
+      })
+    );
+    expect(donut.ok).toBe(true);
+    if (!donut.ok) {
+      return;
+    }
+    expect(donut.warnings.map((warning) => warning.code)).toEqual(["DONUT_TOO_MANY_SLICES"]);
+
+    const line = validateBlocks(
+      documentWith({
+        blocks: [{data: "signups", kind: "line", type: "chart", x: "month", y: "count"}],
+        datasets: {signups: {...inline, rows: [["Jan", 1]]}},
+      })
+    );
+    expect(line.ok).toBe(true);
+    if (!line.ok) {
+      return;
+    }
+    expect(line.warnings.map((warning) => warning.code)).toEqual(["LINE_SINGLE_POINT"]);
+  });
+
+  it("checks ref columns only when the handle is known", () => {
+    const doc = documentWith({
+      blocks: [{data: "daily", kind: "line", type: "chart", x: "day", y: "count"}],
+      datasets: {daily: {id: "ds_1", limit: 200, source: "ref"}},
+    });
+    expect(validateBlocks(doc).ok).toBe(true);
+    const checked = validateBlocks(doc, {
+      knownDatasets: {
+        ds_1: {
+          columns: [
+            {name: "day", type: "date"},
+            {name: "count", type: "string"},
+          ],
+        },
+      },
+    });
+    expect(checked.ok).toBe(false);
+    if (checked.ok) {
+      return;
+    }
+    expect(checked.errors.map((error) => ({code: error.code, path: error.path}))).toEqual([
+      {code: "COLUMN_TYPE_MISMATCH", path: "blocks[0].y"},
+    ]);
+  });
+
+  it("rejects a number stored in a string column", () => {
+    const validated = validateBlocks(
+      documentWith({
+        blocks: [{type: "divider"}],
+        datasets: {signups: {...inline, rows: [[1, 2]]}},
+      })
+    );
+    expect(validated.ok).toBe(false);
+    if (validated.ok) {
+      return;
+    }
+    expect(validated.errors.map((error) => error.code)).toEqual(["COLUMN_TYPE_MISMATCH"]);
+  });
+
+  it("rejects more than 500 inline rows", () => {
+    const rows = Array.from({length: 501}, (_unused, index) => [`m${index}`, index]);
+    const validated = validateBlocks(
+      documentWith({
+        blocks: [{type: "divider"}],
+        datasets: {signups: {...inline, rows}},
+      })
+    );
+    expect(validated.ok).toBe(false);
+    if (validated.ok) {
+      return;
+    }
+    expect(validated.errors.map((error) => ({code: error.code, path: error.path}))).toEqual([
+      {code: "DATASET_TOO_LARGE", path: "datasets.signups.rows"},
+    ]);
+    expect(validated.errors[0]?.fix).toContain("500");
+  });
+
+  it("rejects dataset, chart, table, and image mistakes the schema still allows", () => {
+    const datasets: Record<string, unknown> = {};
+    for (let index = 0; index < 9; index += 1) {
+      datasets[`set${index}`] = {
+        columns: [
+          {name: "month", type: "string"},
+          {name: "month", type: "string"},
+        ],
+        rows: [["Jan", "Jan"]],
+      };
+    }
+    datasets.signups = {
+      columns: [
+        {name: "n", type: "number"},
+        {name: "count", type: "number"},
+      ],
+      rows: [[1, 2]],
+    };
+    const validated = validateBlocks(
+      documentWith({
+        blocks: [
+          {alt: "Chart", src: "not a url", type: "image"},
+          {
+            data: "signups",
+            kind: "bar",
+            points: [{label: "Jan", value: 1}],
+            type: "chart",
+            x: "month",
+            y: "count",
+          },
+          {kind: "line", type: "chart"},
+          {data: "signups", kind: "bar", type: "chart", x: "n", y: "count"},
+          {data: "signups", kind: "bar", type: "chart", x: "n", y: "missing"},
+          {
+            elements: [
+              {
+                id: "grain",
+                options: [
+                  {data: "signups", label: "Month"},
+                  {data: "other", label: "Week"},
+                ],
+                target: "missing_chart",
+                type: "segmented",
+              },
+            ],
+            id: "row",
+            type: "actions",
+          },
+          {data: "missing", type: "table"},
+          {columns: ["missing"], data: "signups", type: "table"},
+        ],
+        datasets,
+      })
+    );
+    expect(validated.ok).toBe(false);
+    if (validated.ok) {
+      return;
+    }
+    const codes = new Set(validated.errors.map((error) => error.code));
+    expect(codes.has("TOO_MANY")).toBe(true);
+    expect(codes.has("DUPLICATE_ID")).toBe(true);
+    expect(codes.has("IMAGE_HOST_NOT_ALLOWED")).toBe(true);
+    expect(codes.has("INVALID_TYPE")).toBe(true);
+    expect(codes.has("MISSING_REQUIRED")).toBe(true);
+    expect(codes.has("COLUMN_TYPE_MISMATCH")).toBe(true);
+    expect(codes.has("COLUMN_NOT_FOUND")).toBe(true);
+    expect(codes.has("SELECT_TARGET_INVALID")).toBe(true);
+    expect(codes.has("DATASET_NOT_FOUND")).toBe(true);
+  });
+});