@terreno/blocks 57.12.0 → 57.14.0

package/src/lint.ts

@@ -1,6 +1,15 @@
 import {BLOCK_ERROR_CODES, BLOCK_WARNING_CODES, type BlockError} from "./errors";
 import {BLOCK_LIMITS} from "./limits";
-import type {Block, BlocksDocument, Dataset, DatasetColumn, InlineDataset} from "./schema";
+import {
+  type Block,
+  type BlocksDocument,
+  type ChecklistBlock,
+  COPY_TARGET_TYPES,
+  type Dataset,
+  type DatasetColumn,
+  type InlineDataset,
+  type StepperBlock,
+} from "./schema";
 
 export interface KnownDataset {
   columns: DatasetColumn[];
@@ -9,10 +18,20 @@ export interface KnownDataset {
 export interface LintBlocksOptions {
   /** When false or omitted, an `html` block fails with `HTML_DISABLED`. */
   allowHtml?: boolean;
+  /**
+   * Host actions that handle a checklist. When set, a checklist `callback.name` outside it fails
+   * with `UNKNOWN_HOST_ACTION`.
+   */
+  checklistActions?: readonly string[];
   hostActions?: readonly string[];
   /** Hostnames allowed on `https` image `src` values. Empty means no https images. */
   imageHosts?: readonly string[];
   knownDatasets?: Record<string, KnownDataset>;
+  /**
+   * Host actions that handle a stepper. When set, a stepper `callback.name` outside it fails with
+   * `UNKNOWN_HOST_ACTION`, even when the name is in `hostActions`. Omitted, `hostActions` applies.
+   */
+  stepperActions?: readonly string[];
 }
 
 const issue = ({code, fix, message, path}: BlockError): BlockError => ({code, fix, message, path});
@@ -49,6 +68,118 @@ const imageSourceIssue = (
   });
 };
 
+/** The element ids a stepper's − and + buttons use in callback events. */
+export const stepperElementIds = (stepperId: string): {decrease: string; increase: string} => ({
+  decrease: `${stepperId}_decrease`,
+  increase: `${stepperId}_increase`,
+});
+
+/** The element id a checklist item's tick uses in callback events. */
+export const checklistElementId = (checklistId: string, itemId: string): string =>
+  `${checklistId}_${itemId}`;
+
+const unknownHostActionIssue = (
+  name: string,
+  hostActions: readonly string[] | undefined,
+  path: string
+): BlockError | undefined => {
+  if (hostActions === undefined || hostActions.includes(name)) {
+    return undefined;
+  }
+  return issue({
+    code: "UNKNOWN_HOST_ACTION",
+    fix: `Use one of: ${hostActions.join(", ") || "(none registered)"}.`,
+    message: BLOCK_ERROR_CODES.UNKNOWN_HOST_ACTION,
+    path,
+  });
+};
+
+const stepperIssues = (
+  block: StepperBlock,
+  path: string,
+  options: LintBlocksOptions | undefined
+): BlockError[] => {
+  const found: BlockError[] = [];
+  if (block.min >= block.max) {
+    found.push(
+      issue({
+        code: "OUT_OF_RANGE",
+        fix: "Set max above min.",
+        message: BLOCK_ERROR_CODES.OUT_OF_RANGE,
+        path: `${path}.max`,
+      })
+    );
+  } else if (block.value < block.min || block.value > block.max) {
+    found.push(
+      issue({
+        code: "OUT_OF_RANGE",
+        fix: `Set value between ${block.min} and ${block.max}.`,
+        message: BLOCK_ERROR_CODES.OUT_OF_RANGE,
+        path: `${path}.value`,
+      })
+    );
+  }
+  if (block.step !== undefined && block.step <= 0) {
+    found.push(
+      issue({
+        code: "OUT_OF_RANGE",
+        fix: "Set step above 0, or leave it out for 1.",
+        message: BLOCK_ERROR_CODES.OUT_OF_RANGE,
+        path: `${path}.step`,
+      })
+    );
+  }
+  const unknown = unknownHostActionIssue(
+    block.callback.name,
+    options?.stepperActions ?? options?.hostActions,
+    `${path}.callback.name`
+  );
+  if (unknown) {
+    found.push(unknown);
+  }
+  return found;
+};
+
+const checklistIssues = (
+  block: ChecklistBlock,
+  path: string,
+  options: LintBlocksOptions | undefined
+): BlockError[] => {
+  const found: BlockError[] = [];
+  const seenItemIds = new Set<string>();
+  block.items.forEach((item, index) => {
+    if (seenItemIds.has(item.id)) {
+      found.push(
+        issue({
+          code: "DUPLICATE_ID",
+          fix: `Give ${path}.items[${index}] an id no other item in this checklist uses.`,
+          message: BLOCK_ERROR_CODES.DUPLICATE_ID,
+          path: `${path}.items[${index}].id`,
+        })
+      );
+    }
+    seenItemIds.add(item.id);
+  });
+  if (block.callback === undefined) {
+    return found;
+  }
+  const unknown = unknownHostActionIssue(
+    block.callback.name,
+    options?.checklistActions ?? options?.hostActions,
+    `${path}.callback.name`
+  );
+  if (unknown) {
+    found.push(unknown);
+  }
+  return found;
+};
+
+const STEPPER_RESERVED_FIX = "A stepper uses <id>_decrease and <id>_increase for its buttons.";
+const CHECKLIST_RESERVED_FIX = "A checklist uses <id>_<item id> for each item's tick.";
+
+const copyTargetTypes: ReadonlySet<string> = new Set(COPY_TARGET_TYPES);
+const COPY_TARGET_FIX = `Set target to the id of a ${COPY_TARGET_TYPES.slice(0, -1).join(", ")}, or ${COPY_TARGET_TYPES.at(-1)} block in this document.`;
+
 const isInline = (dataset: Dataset): dataset is InlineDataset => dataset.source !== "ref";
 
 const columnsFor = (
@@ -203,12 +334,74 @@ export const lintDocument = (
 
   const seenIds = new Set<string>();
   const selectableIds = new Set<string>();
+  // Block ids a copy action may target, collected first so a target may sit before or after it.
+  const copyTargetIds = new Set<string>();
+  // Element ids a renderer derives from a block id, mapped to the fix that explains the clash.
+  const reservedIds = new Map<string, {fix: string; ownerId: string}>();
+  // Two blocks deriving the same element id would send ambiguous callback events. A clash within
+  // one block id is a repeated item or block id, which DUPLICATE_ID already reports elsewhere.
+  const reserve = ({
+    elementId,
+    fix,
+    ownerId,
+    path,
+  }: {
+    elementId: string;
+    fix: string;
+    ownerId: string;
+    path: string;
+  }): void => {
+    const taken = reservedIds.get(elementId);
+    if (taken !== undefined && taken.ownerId !== ownerId) {
+      errors.push(
+        issue({
+          code: "DUPLICATE_ID",
+          fix: `Rename ${path}. Its element id ${elementId} is already used. ${taken.fix}`,
+          message: BLOCK_ERROR_CODES.DUPLICATE_ID,
+          path,
+        })
+      );
+    }
+    reservedIds.set(elementId, {fix, ownerId});
+  };
   const walked = walk(doc.blocks, "blocks");
-  for (const {block} of walked) {
+  for (const {block, path} of walked) {
     if ((block.type === "chart" || block.type === "table") && block.id !== undefined) {
       selectableIds.add(block.id);
     }
+    if (copyTargetTypes.has(block.type) && block.id !== undefined) {
+      copyTargetIds.add(block.id);
+    }
+    if (block.type === "stepper") {
+      const {decrease, increase} = stepperElementIds(block.id);
+      for (const elementId of [decrease, increase]) {
+        reserve({elementId, fix: STEPPER_RESERVED_FIX, ownerId: block.id, path: `${path}.id`});
+      }
+    }
+    if (block.type === "checklist") {
+      block.items.forEach((item, index) => {
+        reserve({
+          elementId: checklistElementId(block.id, item.id),
+          fix: CHECKLIST_RESERVED_FIX,
+          ownerId: block.id,
+          path: `${path}.items[${index}].id`,
+        });
+      });
+    }
   }
+  const idIssue = (id: string, path: string): BlockError | undefined => {
+    const reservedFix = reservedIds.get(id)?.fix;
+    if (!seenIds.has(id) && reservedFix === undefined) {
+      return undefined;
+    }
+    return issue({
+      code: "DUPLICATE_ID",
+      fix:
+        reservedFix === undefined ? `Give ${path} a unique id.` : `Rename ${path}. ${reservedFix}`,
+      message: BLOCK_ERROR_CODES.DUPLICATE_ID,
+      path: `${path}.id`,
+    });
+  };
   for (const {block, path} of walked) {
     if (block.type === "html") {
       if (options?.allowHtml !== true) {
@@ -239,19 +432,46 @@ export const lintDocument = (
         errors.push(imageIssue);
       }
     }
-    if (block.id !== undefined) {
-      if (seenIds.has(block.id)) {
-        errors.push(
-          issue({
-            code: "DUPLICATE_ID",
-            fix: `Give ${path} a unique id.`,
-            message: BLOCK_ERROR_CODES.DUPLICATE_ID,
-            path: `${path}.id`,
-          })
+    if (block.type === "gallery") {
+      block.images.forEach((image, index) => {
+        const tileIssue = imageSourceIssue(
+          image.src,
+          options?.imageHosts,
+          `${path}.images[${index}]`
+        );
+        if (tileIssue) {
+          errors.push(tileIssue);
+        }
+      });
+    }
+    if (block.type === "list") {
+      block.items.forEach((item, index) => {
+        if (item.image === undefined) {
+          return;
+        }
+        const thumbnailIssue = imageSourceIssue(
+          item.image.src,
+          options?.imageHosts,
+          `${path}.items[${index}].image`
         );
+        if (thumbnailIssue) {
+          errors.push(thumbnailIssue);
+        }
+      });
+    }
+    if (block.id !== undefined) {
+      const duplicate = idIssue(block.id, path);
+      if (duplicate) {
+        errors.push(duplicate);
       }
       seenIds.add(block.id);
     }
+    if (block.type === "stepper") {
+      errors.push(...stepperIssues(block, path, options));
+    }
+    if (block.type === "checklist") {
+      errors.push(...checklistIssues(block, path, options));
+    }
     if (block.type === "chart") {
       const hasPoints = block.points !== undefined;
       const hasData = block.data !== undefined || block.x !== undefined || block.y !== undefined;
@@ -371,15 +591,9 @@ export const lintDocument = (
     if (block.type === "actions") {
       block.elements.forEach((element, index) => {
         const elementPath = `${path}.elements[${index}]`;
-        if (seenIds.has(element.id)) {
-          errors.push(
-            issue({
-              code: "DUPLICATE_ID",
-              fix: `Give ${elementPath} a unique id.`,
-              message: BLOCK_ERROR_CODES.DUPLICATE_ID,
-              path: `${elementPath}.id`,
-            })
-          );
+        const duplicate = idIssue(element.id, elementPath);
+        if (duplicate) {
+          errors.push(duplicate);
         }
         seenIds.add(element.id);
         if (element.type === "segmented" && !selectableIds.has(element.target)) {
@@ -406,20 +620,15 @@ export const lintDocument = (
             })
           );
         }
-        if (
-          element.type === "button" &&
-          element.action.kind === "callback" &&
-          options?.hostActions !== undefined &&
-          !options.hostActions.includes(element.action.name)
-        ) {
-          errors.push(
-            issue({
-              code: "UNKNOWN_HOST_ACTION",
-              fix: `Use one of: ${options.hostActions.join(", ") || "(none registered)"}.`,
-              message: BLOCK_ERROR_CODES.UNKNOWN_HOST_ACTION,
-              path: `${elementPath}.action.name`,
-            })
+        if (element.type === "button" && element.action.kind === "callback") {
+          const unknown = unknownHostActionIssue(
+            element.action.name,
+            options?.hostActions,
+            `${elementPath}.action.name`
           );
+          if (unknown) {
+            errors.push(unknown);
+          }
         }
         if (element.type === "button" && element.action.kind === "open") {
           const hasRoute = element.action.route !== undefined;
@@ -435,6 +644,28 @@ export const lintDocument = (
             );
           }
         }
+        if (element.type === "button" && element.action.kind === "copy") {
+          const {target, text} = element.action;
+          if ((target === undefined) === (text === undefined)) {
+            errors.push(
+              issue({
+                code: "MISSING_REQUIRED",
+                fix: "Set either text or target on a copy action.",
+                message: BLOCK_ERROR_CODES.MISSING_REQUIRED,
+                path: `${elementPath}.action`,
+              })
+            );
+          } else if (target !== undefined && !copyTargetIds.has(target)) {
+            errors.push(
+              issue({
+                code: "COPY_TARGET_INVALID",
+                fix: COPY_TARGET_FIX,
+                message: BLOCK_ERROR_CODES.COPY_TARGET_INVALID,
+                path: `${elementPath}.action.target`,
+              })
+            );
+          }
+        }
       });
     }
     if (block.type === "table") {

package/src/parse.test.ts

@@ -9,20 +9,42 @@ import {validateBlocks} from "./validate";
 const fixturesDir = join(import.meta.dir, "fixtures");
 
 const expectedInvalid: Record<string, {code: string; path: string}[]> = {
+  // An empty visibleText string trips both the min(1) and the blank-text checks.
+  "card-eyebrow-empty.yaml": [
+    {code: "TOO_SHORT", path: "blocks[0].eyebrow"},
+    {code: "TOO_SHORT", path: "blocks[0].eyebrow"},
+  ],
+  "card-eyebrow-too-long.yaml": [{code: "TOO_LONG", path: "blocks[0].eyebrow"}],
+  "checklist-duplicate-item.yaml": [{code: "DUPLICATE_ID", path: "blocks[0].items[1].id"}],
+  "checklist-item-id-too-long.yaml": [{code: "TOO_LONG", path: "blocks[0].items[0].id"}],
+  "checklist-reserved-id.yaml": [{code: "DUPLICATE_ID", path: "blocks[1].elements[0].id"}],
   "column-not-found.yaml": [{code: "COLUMN_NOT_FOUND", path: "blocks[0].x"}],
   "column-type.yaml": [{code: "COLUMN_TYPE_MISMATCH", path: "blocks[0].y"}],
+  "copy-missing-text-and-target.yaml": [
+    {code: "MISSING_REQUIRED", path: "blocks[0].elements[0].action"},
+  ],
+  "copy-target.yaml": [{code: "COPY_TARGET_INVALID", path: "blocks[1].elements[0].action.target"}],
   "dataset-not-found.yaml": [{code: "DATASET_NOT_FOUND", path: "blocks[0].data"}],
   "dataset-too-large.yaml": [{code: "DATASET_TOO_LARGE", path: "datasets.signups.columns"}],
   "depth-exceeded.yaml": [{code: "DEPTH_EXCEEDED", path: "blocks[0].children[0]"}],
   "duplicate-id.yaml": [{code: "DUPLICATE_ID", path: "blocks[1].id"}],
+  "gallery-caption-too-long.yaml": [{code: "TOO_LONG", path: "blocks[0].images[1].caption"}],
+  "gallery-image-host.yaml": [{code: "IMAGE_HOST_NOT_ALLOWED", path: "blocks[0].images[2].src"}],
+  "gallery-too-few.yaml": [{code: "TOO_FEW", path: "blocks[0].images"}],
   "invalid-enum.yaml": [{code: "INVALID_ENUM", path: "blocks[0].size"}],
   "key-order.yaml": [{code: "KEY_ORDER", path: "blocks"}],
+  "list-image-host.yaml": [{code: "IMAGE_HOST_NOT_ALLOWED", path: "blocks[0].items[1].image.src"}],
+  "list-missing-title.yaml": [{code: "MISSING_REQUIRED", path: "blocks[0].items[0].title"}],
+  "list-too-many.yaml": [{code: "TOO_MANY", path: "blocks[0].items"}],
   "missing-required.yaml": [{code: "MISSING_REQUIRED", path: "blocks[0].markdown"}],
   "not-a-document.txt": [{code: "NOT_A_DOCUMENT", path: ""}],
   "row-arity.yaml": [{code: "ROW_ARITY_MISMATCH", path: "datasets.signups.rows[0]"}],
   "select-target.yaml": [
     {code: "SELECT_TARGET_INVALID", path: "blocks[0].elements[0].action.target"},
   ],
+  "stepper-decimals.yaml": [{code: "OUT_OF_RANGE", path: "blocks[0].items[0].decimals"}],
+  "stepper-out-of-range.yaml": [{code: "OUT_OF_RANGE", path: "blocks[0].value"}],
+  "stepper-reserved-id.yaml": [{code: "DUPLICATE_ID", path: "blocks[1].elements[0].id"}],
   "table-too-wide.yaml": [{code: "TABLE_TOO_WIDE", path: "blocks[0].columns"}],
   "too-many-points.yaml": [{code: "TOO_MANY_POINTS", path: "datasets.signups.limit"}],
   "unknown-key.yaml": [{code: "UNKNOWN_KEY", path: "blocks[0].color"}],
@@ -279,3 +301,21 @@ describe("validateBlocks limits", () => {
     }
   });
 });
+
+describe("card eyebrow", () => {
+  it("is accepted by validation, whatever the prompt offers", () => {
+    const parsed = parseBlocks(
+      readFileSync(join(fixturesDir, "valid", "card-eyebrow.yaml"), "utf8")
+    );
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) {
+      return;
+    }
+    const validated = validateBlocks(parsed.value);
+    expect(validated.ok).toBe(true);
+    if (!validated.ok) {
+      return;
+    }
+    expect(validated.doc.blocks[0]).toMatchObject({eyebrow: "Your dinner plan", type: "card"});
+  });
+});

package/src/plainText.test.ts

@@ -0,0 +1,158 @@
+import {describe, expect, it} from "bun:test";
+
+import {blockPlainText} from "./plainText";
+import type {
+  ChecklistBlock,
+  InlineDataset,
+  ListBlock,
+  StepperBlock,
+  TableBlock,
+  TextBlock,
+} from "./schema";
+
+const stepper: StepperBlock = {
+  callback: {name: "scaleStepper"},
+  id: "people",
+  items: [
+    {amount: 2, decimals: 1, label: "Bone-in leg of lamb", unit: "kg"},
+    {amount: 8, label: "Carrots"},
+    {amount: 0.625, decimals: 3, label: "Broccoli", unit: "kg"},
+  ],
+  itemsTitle: "Your shopping quantities",
+  label: "Number of people",
+  max: 20,
+  min: 1,
+  note: "Generous portions.",
+  type: "stepper",
+  unit: "People",
+  value: 5,
+};
+
+const checklist: ChecklistBlock = {
+  id: "cooking",
+  items: [
+    {checked: true, id: "oven", meta: "1:00 pm", text: "Preheat the oven"},
+    {detail: "Fat side up.", id: "lamb_in", text: "Put the lamb in"},
+    {id: "rest", text: "Rest the lamb"},
+  ],
+  title: "Cooking checklist",
+  type: "checklist",
+};
+
+const guests: InlineDataset = {
+  columns: [
+    {name: "guests", type: "number"},
+    {name: "lamb_kg", type: "number"},
+    {name: "note", type: "string"},
+  ],
+  rows: [
+    [4, 1.6, "Small"],
+    [6, 2.4, null],
+  ],
+};
+
+const table: TableBlock = {
+  data: "guests",
+  id: "lamb_table",
+  title: "How much lamb?",
+  type: "table",
+};
+
+describe("blockPlainText", () => {
+  describe("stepper", () => {
+    it("writes the label, value, and unit, then one line per item formatted with decimals", () => {
+      expect(blockPlainText(stepper)).toBe(
+        [
+          "Number of people: 5 People",
+          "Bone-in leg of lamb: 2.0 kg",
+          "Carrots: 8",
+          "Broccoli: 0.625 kg",
+        ].join("\n")
+      );
+    });
+
+    it("omits a missing unit without a trailing space and writes only the first line without items", () => {
+      const bare: StepperBlock = {...stepper, items: undefined, unit: undefined, value: 6};
+      expect(blockPlainText(bare)).toBe("Number of people: 6");
+    });
+
+    it("copies the block it is given, so an override's value and amounts are what is copied", () => {
+      const scaled: StepperBlock = {
+        ...stepper,
+        items: [{amount: 2.4, decimals: 1, label: "Bone-in leg of lamb", unit: "kg"}],
+        value: 6,
+      };
+      expect(blockPlainText(scaled)).toBe(
+        "Number of people: 6 People\nBone-in leg of lamb: 2.4 kg"
+      );
+    });
+  });
+
+  describe("checklist", () => {
+    it("writes one [x] or [ ] line per item from each item's checked", () => {
+      expect(blockPlainText(checklist)).toBe(
+        "[x] Preheat the oven\n[ ] Put the lamb in\n[ ] Rest the lamb"
+      );
+    });
+
+    it("uses the current toggles over each item's checked and ignores unknown ids", () => {
+      expect(
+        blockPlainText(checklist, {checked: {lamb_in: true, missing: true, oven: false}})
+      ).toBe("[ ] Preheat the oven\n[x] Put the lamb in\n[ ] Rest the lamb");
+    });
+  });
+
+  describe("list", () => {
+    it("writes one - title: text line per item, and - title when an item has no text", () => {
+      const list: ListBlock = {
+        items: [
+          {meta: "Main", text: "Rubbed with garlic.", title: "Roast leg of lamb"},
+          {image: {alt: "Mint", src: "file:mint"}, title: "Mint sauce"},
+        ],
+        type: "list",
+      };
+      expect(blockPlainText(list)).toBe("- Roast leg of lamb: Rubbed with garlic.\n- Mint sauce");
+    });
+  });
+
+  describe("table", () => {
+    it("writes a header row, then the rows, tab-separated, with null cells empty", () => {
+      expect(blockPlainText(table, {datasets: {guests}})).toBe(
+        "guests\tlamb kg\tnote\n4\t1.6\tSmall\n6\t2.4\t"
+      );
+    });
+
+    it("writes header names with underscores as spaces, as the table shows them", () => {
+      const header = blockPlainText(table, {datasets: {guests}}).split("\n")[0];
+      expect(header).toBe("guests\tlamb kg\tnote");
+      expect(header).not.toContain("_");
+    });
+
+    it("follows the table's columns in their order", () => {
+      expect(blockPlainText({...table, columns: ["lamb_kg", "guests"]}, {datasets: {guests}})).toBe(
+        "lamb kg\tguests\n1.6\t4\n2.4\t6"
+      );
+    });
+
+    it("returns an empty string when the dataset is missing or is an unresolved ref", () => {
+      expect(blockPlainText(table)).toBe("");
+      expect(blockPlainText(table, {datasets: {}})).toBe("");
+      expect(blockPlainText(table, {datasets: {guests: {id: "ds_1", source: "ref"}}})).toBe("");
+    });
+  });
+
+  describe("text", () => {
+    it("returns the markdown as written", () => {
+      const text: TextBlock = {
+        markdown: "**Tips**\n\n- Rest the lamb\n- Warm the plates",
+        type: "text",
+      };
+      expect(blockPlainText(text)).toBe("**Tips**\n\n- Rest the lamb\n- Warm the plates");
+    });
+  });
+
+  it("returns an empty string for a block a copy action cannot target", () => {
+    expect(blockPlainText({text: "Menu", type: "heading"})).toBe("");
+    expect(blockPlainText({children: [{markdown: "Hi", type: "text"}], type: "card"})).toBe("");
+  });
+});

package/src/plainText.ts

@@ -0,0 +1,81 @@
+import type {Block, ChecklistBlock, Dataset, ListBlock, StepperBlock, TableBlock} from "./schema";
+
+export interface BlockPlainTextOptions {
+  /**
+   * Current ticks by checklist item id. An entry overrides that item's `checked`; ids the
+   * checklist does not have are ignored.
+   */
+  checked?: Record<string, boolean>;
+  /** The document's datasets. A table copies only an inline dataset, so resolve refs first. */
+  datasets?: Record<string, Dataset>;
+}
+
+const withUnit = (value: string, unit: string | undefined): string =>
+  unit === undefined ? value : `${value} ${unit}`;
+
+/** Matches the renderer: each amount is fixed to the item's `decimals`, so 2 at 1 is "2.0". */
+const stepperText = (block: StepperBlock): string =>
+  [
+    `${block.label}: ${withUnit(String(block.value), block.unit)}`,
+    ...(block.items ?? []).map(
+      (item) => `${item.label}: ${withUnit(item.amount.toFixed(item.decimals ?? 0), item.unit)}`
+    ),
+  ].join("\n");
+
+const checklistText = (
+  block: ChecklistBlock,
+  checked: Record<string, boolean> | undefined
+): string =>
+  block.items
+    .map((item) => `${(checked?.[item.id] ?? item.checked) === true ? "[x]" : "[ ]"} ${item.text}`)
+    .join("\n");
+
+const listText = (block: ListBlock): string =>
+  block.items
+    .map((item) => (item.text === undefined ? `- ${item.title}` : `- ${item.title}: ${item.text}`))
+    .join("\n");
+
+const cellText = (value: unknown): string => {
+  if (value === null || value === undefined) {
+    return "";
+  }
+  return String(value);
+};
+
+const tableText = (block: TableBlock, datasets: Record<string, Dataset> | undefined): string => {
+  const dataset = datasets?.[block.data];
+  if (dataset === undefined || dataset.source === "ref") {
+    return "";
+  }
+  const names = block.columns ?? dataset.columns.map((column) => column.name);
+  const indexes = names.map((name) => dataset.columns.findIndex((column) => column.name === name));
+  const rows = dataset.rows.map((row) =>
+    indexes.map((index) => (index < 0 ? "" : cellText(row[index]))).join("\t")
+  );
+  // The header matches the table on screen, which shows underscores in column names as spaces.
+  const header = names.map((name) => name.replaceAll("_", " ")).join("\t");
+  return [header, ...rows].join("\n");
+};
+
+/**
+ * The text a copy action writes to the clipboard for its target block. Pass the block as it is
+ * shown now (a host override applied) and the current checklist ticks in `checked`. Blocks a
+ * copy action cannot target return an empty string, as does a table whose dataset is missing or
+ * an unresolved ref.
+ */
+export const blockPlainText = (block: Block, options: BlockPlainTextOptions = {}): string => {
+  switch (block.type) {
+    case "stepper":
+      return stepperText(block);
+    case "checklist":
+      return checklistText(block, options.checked);
+    case "list":
+      return listText(block);
+    case "table":
+      return tableText(block, options.datasets);
+    case "text":
+      return block.markdown;
+    default:
+      return "";
+  }
+};