@terreno/blocks 57.12.0 → 57.13.0

package/src/golden.test.ts

@@ -0,0 +1,234 @@
+import {describe, expect, it} from "bun:test";
+import {readFileSync} from "node:fs";
+import {join} from "node:path";
+
+import {parseBlocks} from "./parse";
+import {blockPlainText} from "./plainText";
+import type {Block, BlocksDocument} from "./schema";
+import {validateBlocks} from "./validate";
+
+const goldenPath = join(import.meta.dir, "fixtures", "golden", "sunday-roast.yaml");
+
+// The roast reply needs these options: https images and both host callbacks.
+const goldenOptions = {
+  checklistActions: ["toggleChecklist"],
+  hostActions: ["scaleStepper", "toggleChecklist"],
+  imageHosts: ["images.example.com"],
+  stepperActions: ["scaleStepper"],
+};
+
+const loadGolden = (): BlocksDocument => {
+  const parsed = parseBlocks(readFileSync(goldenPath, "utf8"));
+  if (!parsed.ok) {
+    throw new Error(`sunday-roast.yaml did not parse: ${JSON.stringify(parsed.errors)}`);
+  }
+  const validated = validateBlocks(parsed.value, goldenOptions);
+  if (!validated.ok) {
+    throw new Error(`sunday-roast.yaml did not validate: ${JSON.stringify(validated.errors)}`);
+  }
+  return validated.doc;
+};
+
+const allBlocks = (blocks: readonly Block[]): Block[] => {
+  return blocks.flatMap((block) =>
+    block.type === "card" || block.type === "columns" ? [block, ...block.children] : [block]
+  );
+};
+
+const blocksOfType = <T extends Block["type"]>(
+  doc: BlocksDocument,
+  type: T
+): Extract<Block, {type: T}>[] => {
+  return allBlocks(doc.blocks).filter(
+    (block): block is Extract<Block, {type: T}> => block.type === type
+  );
+};
+
+describe("sunday roast golden document", () => {
+  it("validates with the roast host options and no warnings", () => {
+    const parsed = parseBlocks(readFileSync(goldenPath, "utf8"));
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) {
+      return;
+    }
+    const validated = validateBlocks(parsed.value, goldenOptions);
+    expect(validated.ok).toBe(true);
+    expect(validated.warnings).toEqual([]);
+    expect(allBlocks(loadGolden().blocks).length).toBeLessThanOrEqual(50);
+  });
+
+  it("fails without imageHosts, so it stays out of the option-less valid/ loop", () => {
+    const parsed = parseBlocks(readFileSync(goldenPath, "utf8"));
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) {
+      return;
+    }
+    const validated = validateBlocks(parsed.value);
+    expect(validated.ok).toBe(false);
+    if (validated.ok) {
+      return;
+    }
+    expect(new Set(validated.errors.map((error) => error.code))).toEqual(
+      new Set(["IMAGE_HOST_NOT_ALLOWED"])
+    );
+  });
+
+  it("rejects the stepper and checklist callbacks when the host lacks those actions", () => {
+    const parsed = parseBlocks(readFileSync(goldenPath, "utf8"));
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) {
+      return;
+    }
+    const validated = validateBlocks(parsed.value, {
+      checklistActions: [],
+      hostActions: [],
+      imageHosts: ["images.example.com"],
+      stepperActions: [],
+    });
+    expect(validated.ok).toBe(false);
+    if (validated.ok) {
+      return;
+    }
+    expect(validated.errors.map((error) => error.code)).toEqual([
+      "UNKNOWN_HOST_ACTION",
+      "UNKNOWN_HOST_ACTION",
+    ]);
+  });
+
+  it("reproduces the GPT-6 reply: title, gallery, summary card, and photo menu", () => {
+    const doc = loadGolden();
+    expect(doc.blocks[0]).toEqual({size: "lg", text: "Your Sunday lamb roast 🍷", type: "heading"});
+
+    const [gallery] = blocksOfType(doc, "gallery");
+    expect(gallery?.images.map((image) => image.alt)).toEqual([
+      "Roast lamb",
+      "Crispy roast potatoes",
+      "Sunday roast inspiration",
+    ]);
+
+    const summary = blocksOfType(doc, "card").find((card) => card.eyebrow !== undefined);
+    expect(summary?.eyebrow).toBe("Your dinner plan");
+    expect(summary?.title).toBe("Sunday roast with friends");
+    expect(summary?.children[0]?.type).toBe("text");
+
+    const [menu] = blocksOfType(doc, "list");
+    expect(menu?.items).toHaveLength(5);
+    for (const item of menu?.items ?? []) {
+      expect(item.image?.src).toStartWith("https://images.example.com/");
+      expect(item.text).toBeDefined();
+    }
+  });
+
+  it("puts the stepper and its copy button in one card", () => {
+    const doc = loadGolden();
+    const card = blocksOfType(doc, "card").find((block) =>
+      block.children.some((child) => child.type === "stepper")
+    );
+    expect(card).toBeDefined();
+    const stepper = card?.children.find((child) => child.type === "stepper");
+    if (stepper?.type !== "stepper") {
+      throw new Error("expected a stepper in the shopping card");
+    }
+    expect(stepper.itemsTitle).toBe("Your shopping quantities");
+    expect(stepper.items).toHaveLength(6);
+    expect(stepper.callback).toEqual({name: "scaleStepper"});
+    expect([stepper.value, stepper.min, stepper.max, stepper.unit]).toEqual([5, 1, 20, "People"]);
+
+    const copyActions = card?.children
+      .filter((child) => child.type === "actions")
+      .flatMap((child) => child.elements)
+      .filter((element) => element.type === "button" && element.action.kind === "copy");
+    expect(copyActions).toHaveLength(1);
+    const [copyButton] = copyActions ?? [];
+    expect(copyButton?.type === "button" ? copyButton.text : undefined).toBe("Copy shopping list");
+    expect(copyButton?.type === "button" ? copyButton.action : undefined).toEqual({
+      kind: "copy",
+      target: stepper.id,
+    });
+
+    expect(blockPlainText(stepper)).toBe(
+      [
+        "Number of people: 5 People",
+        "Bone-in leg of lamb: 2.0 kg",
+        "Potatoes: 1500 g",
+        "Carrots: 8",
+        "Parsnips: 5",
+        "Tenderstem broccoli: 625 g",
+        "Apples for crumble: 4",
+      ].join("\n")
+    );
+  });
+
+  it("has the 8-item cooking checklist with the first item ticked, then the USDA note", () => {
+    const doc = loadGolden();
+    const [checklist] = blocksOfType(doc, "checklist");
+    expect(checklist?.title).toBe("Cooking checklist");
+    expect(checklist?.callback).toEqual({name: "toggleChecklist"});
+    expect(checklist?.items).toHaveLength(8);
+    expect(checklist?.items.map((item) => item.checked === true)).toEqual([
+      true,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+    ]);
+    expect(checklist?.items.map((item) => item.meta)).toEqual([
+      "Saturday",
+      "12:30 PM",
+      "1:30 PM",
+      "2:30 PM",
+      "3:30 PM",
+      "4:15 PM",
+      "4:45 PM",
+      "5:00 PM",
+    ]);
+
+    const index = doc.blocks.findIndex((block) => block.type === "checklist");
+    const note = doc.blocks[index + 1];
+    expect(note?.type).toBe("context");
+    expect(note?.type === "context" ? note.text : "").toContain("USDA");
+  });
+
+  it("includes the GPT-5.6 'How much lamb?' table bound to an inline dataset", () => {
+    const doc = loadGolden();
+    const [table] = blocksOfType(doc, "table");
+    expect(table?.title).toBe("How much lamb?");
+    const dataset = table?.data === undefined ? undefined : doc.datasets?.[table.data];
+    expect(dataset).toEqual({
+      columns: [
+        {name: "guests", type: "number"},
+        {name: "bone_in_lamb", type: "string"},
+        {name: "potatoes", type: "string"},
+      ],
+      rows: [
+        [4, "3–4 lb", "2 lb"],
+        [6, "4–5 lb", "3 lb"],
+        [8, "5–6 lb", "4 lb"],
+        [10, "6–7½ lb", "5 lb"],
+      ],
+    });
+  });
+
+  it("ends with the hosting tips as text and three follow-up reply buttons", () => {
+    const doc = loadGolden();
+    const tips = blocksOfType(doc, "text").find((block) => block.id === "hosting_tips");
+    expect(tips?.markdown).toContain("**Buy the lamb last:**");
+
+    const last = doc.blocks[doc.blocks.length - 1];
+    if (last?.type !== "actions") {
+      throw new Error("expected the reply to end with follow-up actions");
+    }
+    expect(
+      last.elements.map((element) =>
+        element.type === "button" && element.action.kind === "reply" ? element.action.text : ""
+      )
+    ).toEqual([
+      "Help me adjust the lamb roast plan for 5 guests",
+      "Add vegetarian side dish options for the lamb roast menu",
+      "Advise on making the lamb roast plan gluten-free",
+    ]);
+  });
+});

package/src/index.test.ts

@@ -16,16 +16,25 @@ describe("@terreno/blocks public exports", () => {
     "CALLOUT_STATUSES",
     "CHART_HEIGHTS",
     "CHART_KINDS",
+    "COPY_TARGET_TYPES",
     "DATASET_COLUMN_TYPES",
     "DATASET_GRAINS",
     "HEADING_SIZES",
     "HTML_HEIGHTS",
     "METRIC_TRENDS",
+    "STEPPER_ROUNDING",
+    "applyChecklistState",
+    "blockPlainText",
     "blocksJsonSchema",
     "blocksPromptSection",
     "blocksSchema",
+    "checklistElementId",
+    "isStepperValueAllowed",
     "parseBlocks",
     "parseBlocksPartial",
+    "scaleStepperBlock",
+    "stepperElementIds",
+    "unknownChecklistItemIds",
     "validateBlocks",
     "wrapAsTextDocument",
 

package/src/index.ts

@@ -118,13 +118,23 @@ 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 type {ChecklistTick} from "./interactive";
+export {
+  applyChecklistState,
+  isStepperValueAllowed,
+  scaleStepperBlock,
+  unknownChecklistItemIds,
+} from "./interactive";
 export {blocksJsonSchema} from "./jsonSchema";
 export {BLOCK_LIMITS} from "./limits";
 export type {KnownDataset, LintBlocksOptions} from "./lint";
+export {checklistElementId, stepperElementIds} from "./lint";
 export type {ParseBlocksResult} from "./parse";
 export {parseBlocks} from "./parse";
 export type {ParseBlocksPartialResult} from "./parsePartial";
 export {parseBlocksPartial} from "./parsePartial";
+export type {BlockPlainTextOptions} from "./plainText";
+export {blockPlainText} from "./plainText";
 export {blocksPromptSection} from "./prompt";
 export type {
   ActionsBlock,
@@ -137,23 +147,35 @@ export type {
   CalloutBlock,
   CardBlock,
   ChartBlock,
+  ChecklistBlock,
+  ChecklistCallback,
+  ChecklistItem,
   ColumnsBlock,
   ContextBlock,
+  CopyAction,
   Dataset,
   DatasetColumn,
   DetailsBlock,
   DividerBlock,
+  GalleryBlock,
+  GalleryImage,
   HeadingBlock,
   HtmlBlock,
   ImageBlock,
   InlineDataset,
   LeafBlock,
+  ListBlock,
+  ListItem,
+  ListItemImage,
   MetricBlock,
   OpenAction,
   RefDataset,
   ReplyAction,
   SegmentedElement,
   SelectAction,
+  StepperBlock,
+  StepperCallback,
+  StepperItem,
   TableBlock,
   TextBlock,
 } from "./schema";
@@ -164,11 +186,13 @@ export {
   CALLOUT_STATUSES,
   CHART_HEIGHTS,
   CHART_KINDS,
+  COPY_TARGET_TYPES,
   DATASET_COLUMN_TYPES,
   DATASET_GRAINS,
   HEADING_SIZES,
   HTML_HEIGHTS,
   METRIC_TRENDS,
+  STEPPER_ROUNDING,
   wrapAsTextDocument,
 } from "./schema";
 export type {ValidateBlocksResult} from "./validate";

package/src/interactive.test.ts

@@ -0,0 +1,141 @@
+import {describe, expect, it} from "bun:test";
+
+import {
+  applyChecklistState,
+  isStepperValueAllowed,
+  scaleStepperBlock,
+  unknownChecklistItemIds,
+} from "./interactive";
+import type {Block, BlocksDocument, ChecklistBlock, StepperBlock} from "./schema";
+import {validateBlocks} from "./validate";
+
+// Built key by key because validateBlocks wants `v` before `blocks`.
+const documentOf = (block: Block): BlocksDocument => {
+  const doc = {v: 1} as BlocksDocument;
+  doc.blocks = [block];
+  return doc;
+};
+
+const STEPPER: StepperBlock = {
+  callback: {name: "scaleStepper", payload: {recipe: "roast"}},
+  id: "guests",
+  items: [
+    {amount: 2, decimals: 1, label: "Lamb", unit: "kg"},
+    {amount: 7, label: "Parsnips", round: "up"},
+    {amount: 625, label: "Broccoli", unit: "g"},
+  ],
+  label: "Number of people",
+  max: 20,
+  min: 1,
+  note: "Generous portions.",
+  type: "stepper",
+  unit: "People",
+  value: 5,
+};
+
+const CHECKLIST: ChecklistBlock = {
+  callback: {name: "toggleChecklist"},
+  id: "cooking",
+  items: [
+    {checked: true, id: "oven", meta: "1:00 pm", text: "Preheat the oven"},
+    {id: "lamb_in", text: "Put the lamb in"},
+    {id: "rest", text: "Rest the lamb"},
+  ],
+  title: "Cooking checklist",
+  type: "checklist",
+};
+
+describe("scaleStepperBlock", () => {
+  it("scales every item linearly from the original by its decimals and rounding", () => {
+    const scaled = scaleStepperBlock(STEPPER, 6);
+    expect(scaled.value).toBe(6);
+    expect(scaled.items?.map((item) => item.amount)).toEqual([2.4, 9, 750]);
+    expect(scaled.items?.[0]).toEqual({amount: 2.4, decimals: 1, label: "Lamb", unit: "kg"});
+    expect(scaled.note).toBe("Generous portions.");
+    expect(validateBlocks(documentOf(scaled)).ok).toBe(true);
+  });
+
+  it("returns the agent's amounts when scaled back to the original value", () => {
+    expect(scaleStepperBlock(STEPPER, 5)).toEqual(STEPPER);
+  });
+
+  it("does not mutate the original", () => {
+    const before = structuredClone(STEPPER);
+    scaleStepperBlock(STEPPER, 10);
+    expect(STEPPER).toEqual(before);
+  });
+
+  it("keeps the amounts as written when the original value is 0", () => {
+    const zero: StepperBlock = {...STEPPER, min: 0, value: 0};
+    expect(scaleStepperBlock(zero, 3).items?.map((item) => item.amount)).toEqual([2, 7, 625]);
+  });
+
+  it("only changes the value when there are no items", () => {
+    const {items: _items, ...bare} = STEPPER;
+    expect(scaleStepperBlock(bare, 9)).toEqual({...bare, value: 9});
+  });
+});
+
+describe("isStepperValueAllowed", () => {
+  it("accepts a finite value within the range on the step grid from the original", () => {
+    expect(isStepperValueAllowed(STEPPER, 1)).toBe(true);
+    expect(isStepperValueAllowed(STEPPER, 20)).toBe(true);
+    expect(isStepperValueAllowed({...STEPPER, step: 0.5}, 5.5)).toBe(true);
+  });
+
+  it("rejects values outside the range, off the grid, or not finite", () => {
+    expect(isStepperValueAllowed(STEPPER, 0)).toBe(false);
+    expect(isStepperValueAllowed(STEPPER, 21)).toBe(false);
+    expect(isStepperValueAllowed({...STEPPER, step: 2}, 6)).toBe(false);
+    expect(isStepperValueAllowed(STEPPER, Number.NaN)).toBe(false);
+    expect(isStepperValueAllowed(STEPPER, Number.POSITIVE_INFINITY)).toBe(false);
+  });
+});
+
+describe("applyChecklistState", () => {
+  it("takes every item's checked from state, with the ticked item taking checked", () => {
+    const ticked = applyChecklistState(CHECKLIST, {
+      checked: true,
+      itemId: "lamb_in",
+      state: {lamb_in: false, oven: true},
+    });
+    expect(ticked.items.map((item) => item.checked)).toEqual([true, true, false]);
+    expect(ticked.items[0]).toEqual({
+      checked: true,
+      id: "oven",
+      meta: "1:00 pm",
+      text: "Preheat the oven",
+    });
+    expect(ticked.title).toBe("Cooking checklist");
+    expect(validateBlocks(documentOf(ticked)).ok).toBe(true);
+  });
+
+  it("unchecks an item missing from state, even one the agent wrote as checked", () => {
+    const ticked = applyChecklistState(CHECKLIST, {checked: true, itemId: "rest", state: {}});
+    expect(ticked.items.map((item) => item.checked)).toEqual([false, false, true]);
+  });
+
+  it("does not mutate the original", () => {
+    const before = structuredClone(CHECKLIST);
+    applyChecklistState(CHECKLIST, {checked: false, itemId: "oven", state: {}});
+    expect(CHECKLIST).toEqual(before);
+  });
+});
+
+describe("unknownChecklistItemIds", () => {
+  it("lists each id in the tick or state that the checklist does not have, once", () => {
+    expect(
+      unknownChecklistItemIds(CHECKLIST, {
+        checked: true,
+        itemId: "gravy",
+        state: {gravy: true, oven: true, salad: false},
+      })
+    ).toEqual(["gravy", "salad"]);
+  });
+
+  it("is empty for a tick over known items", () => {
+    expect(
+      unknownChecklistItemIds(CHECKLIST, {checked: true, itemId: "oven", state: {rest: true}})
+    ).toEqual([]);
+  });
+});

package/src/interactive.ts

@@ -0,0 +1,75 @@
+import type {ChecklistBlock, StepperBlock, StepperItem} from "./schema";
+
+/** Tolerance for float noise when checking the step grid and rounding up. */
+const EPSILON = 1e-9;
+
+/** A checklist tick as the renderer sends it: the ticked item and every item's state. */
+export interface ChecklistTick {
+  checked: boolean;
+  itemId: string;
+  state: Record<string, boolean>;
+}
+
+const roundAmount = (amount: number, item: StepperItem): number => {
+  const factor = 10 ** (item.decimals ?? 0);
+  const scaled = amount * factor;
+  const rounded = item.round === "up" ? Math.ceil(scaled - EPSILON) : Math.round(scaled);
+  return Number((rounded / factor).toFixed(item.decimals ?? 0));
+};
+
+/**
+ * True when `value` is finite, within `min`..`max`, and a whole number of `step`s from the
+ * stepper's own `value`.
+ */
+export const isStepperValueAllowed = (stepper: StepperBlock, value: number): boolean => {
+  if (!Number.isFinite(value) || value < stepper.min || value > stepper.max) {
+    return false;
+  }
+  const steps = (value - stepper.value) / (stepper.step ?? 1);
+  return Math.abs(steps - Math.round(steps)) < EPSILON;
+};
+
+/**
+ * Returns `original` at `value` with every item scaled linearly from `original`, rounded by its
+ * `decimals` and `round`. Always scale from the block the agent wrote, not the last result, so
+ * rounding never drifts tap after tap. An original `value` of 0 keeps the amounts as written.
+ * Check the value with `isStepperValueAllowed` first.
+ */
+export const scaleStepperBlock = (original: StepperBlock, value: number): StepperBlock => {
+  if (original.items === undefined) {
+    return {...original, value};
+  }
+  const ratio = original.value === 0 ? 1 : value / original.value;
+  return {
+    ...original,
+    items: original.items.map((item) => ({
+      ...item,
+      amount: roundAmount(item.amount * ratio, item),
+    })),
+    value,
+  };
+};
+
+/** The ids in a tick (its `itemId` and `state` keys) that `checklist` has no item for, once each. */
+export const unknownChecklistItemIds = (
+  checklist: ChecklistBlock,
+  tick: ChecklistTick
+): string[] => {
+  const itemIds = new Set(checklist.items.map((item) => item.id));
+  return [...new Set([tick.itemId, ...Object.keys(tick.state)])].filter((id) => !itemIds.has(id));
+};
+
+/**
+ * Returns `checklist` with every item's `checked` taken from `tick.state`. An item missing from
+ * `state` is unchecked, and the ticked item always takes `tick.checked`.
+ */
+export const applyChecklistState = (
+  checklist: ChecklistBlock,
+  tick: ChecklistTick
+): ChecklistBlock => ({
+  ...checklist,
+  items: checklist.items.map((item) => ({
+    ...item,
+    checked: item.id === tick.itemId ? tick.checked : tick.state[item.id] === true,
+  })),
+});

package/src/limits.ts

@@ -6,16 +6,35 @@ export const BLOCK_LIMITS = {
   badgeTextMaxLength: 80,
   barCategoryWarning: 60,
   blockTextMaxLength: 4_000,
+  cardEyebrowMaxLength: 60,
   cardTitleMaxLength: 120,
+  checklistIdMaxLength: 31,
+  checklistItemDetailMaxLength: 280,
+  checklistItemIdMaxLength: 32,
+  checklistItemMetaMaxLength: 40,
+  checklistItemsMax: 30,
+  checklistItemsMin: 1,
+  checklistItemTextMaxLength: 120,
+  checklistTitleMaxLength: 120,
   columnsMax: 4,
   columnsMin: 2,
   contextTextMaxLength: 280,
+  copyTextMaxLength: 4_000,
   datasetColumnMax: 12,
   datasetRowMax: 500,
   documentTextMaxLength: 20_000,
   donutSliceWarning: 8,
+  galleryAltMaxLength: 200,
+  galleryCaptionMaxLength: 120,
+  galleryImagesMax: 6,
+  galleryImagesMin: 2,
   headingTextMaxLength: 200,
   htmlMaxBytes: 100_000,
+  listItemMetaMaxLength: 40,
+  listItemsMax: 12,
+  listItemsMin: 1,
+  listItemTextMaxLength: 500,
+  listItemTitleMaxLength: 120,
   maxBlocks: 50,
   maxDatasets: 8,
   maxDepth: 2,
@@ -24,4 +43,11 @@ export const BLOCK_LIMITS = {
   metricLabelMaxLength: 80,
   metricValueMaxLength: 80,
   refLimitMax: 1_000,
+  stepperDecimalsMax: 3,
+  stepperIdMaxLength: 54,
+  stepperItemsMax: 12,
+  stepperItemUnitMaxLength: 20,
+  stepperLabelMaxLength: 80,
+  stepperNoteMaxLength: 280,
+  stepperUnitMaxLength: 40,
 } as const;