@terreno/blocks 57.10.1

package/src/schema.ts

@@ -0,0 +1,509 @@
+import {z} from "zod";
+
+import {BLOCK_LIMITS} from "./limits";
+
+export const HEADING_SIZES = ["sm", "md", "lg", "xl", "2xl"] as const;
+export const HTML_HEIGHTS = ["sm", "md", "lg"] as const;
+export const CALLOUT_STATUSES = ["info", "warning", "alert"] as const;
+export const BADGE_STATUSES = ["info", "error", "warning", "success", "neutral", "active"] as const;
+export const METRIC_TRENDS = ["up", "down", "flat"] as const;
+export const LAYOUT_BLOCK_TYPES = ["columns", "card"] as const;
+
+const visibleText = (maxLength: number): z.ZodString =>
+  z
+    .string()
+    .min(1)
+    .max(maxLength)
+    .refine((value) => value.trim().length > 0, {
+      message: "Must contain visible text, not only whitespace.",
+      params: {blockCode: "TOO_SHORT"},
+    });
+
+const blockIdSchema = z
+  .string()
+  .regex(/^[a-z][a-z0-9_]{0,63}$/)
+  .describe("Optional id. Lowercase letters, digits, and underscores, starting with a letter.");
+
+const sharedBlockFields = {
+  id: blockIdSchema.optional(),
+};
+
+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 const CHART_KINDS = ["line", "bar", "area", "donut"] as const;
+export const CHART_HEIGHTS = ["sm", "md", "lg"] as const;
+export const DATASET_COLUMN_TYPES = ["string", "number", "date"] as const;
+export const DATASET_GRAINS = ["hour", "day", "week", "month"] as const;
+
+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 const BUTTON_VARIANTS = ["primary", "secondary", "outline", "ghost", "destructive"] as const;
+
+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;
+}
+
+const headingSchema = z
+  .object({
+    ...sharedBlockFields,
+    size: z.enum(HEADING_SIZES).optional(),
+    text: visibleText(BLOCK_LIMITS.headingTextMaxLength),
+    type: z.literal("heading"),
+  })
+  .strict();
+
+const textSchema = z
+  .object({
+    ...sharedBlockFields,
+    markdown: visibleText(BLOCK_LIMITS.blockTextMaxLength),
+    type: z.literal("text"),
+  })
+  .strict();
+
+const metricSchema = z
+  .object({
+    ...sharedBlockFields,
+    delta: visibleText(BLOCK_LIMITS.metricDeltaMaxLength).optional(),
+    helper: visibleText(BLOCK_LIMITS.metricHelperMaxLength).optional(),
+    label: visibleText(BLOCK_LIMITS.metricLabelMaxLength),
+    trend: z.enum(METRIC_TRENDS).optional(),
+    type: z.literal("metric"),
+    value: visibleText(BLOCK_LIMITS.metricValueMaxLength),
+  })
+  .strict();
+
+const badgeSchema = z
+  .object({
+    ...sharedBlockFields,
+    status: z.enum(BADGE_STATUSES).optional(),
+    text: visibleText(BLOCK_LIMITS.badgeTextMaxLength),
+    type: z.literal("badge"),
+  })
+  .strict();
+
+const dividerSchema = z
+  .object({
+    ...sharedBlockFields,
+    type: z.literal("divider"),
+  })
+  .strict();
+
+const contextSchema = z
+  .object({
+    ...sharedBlockFields,
+    text: visibleText(BLOCK_LIMITS.contextTextMaxLength),
+    type: z.literal("context"),
+  })
+  .strict();
+
+const chartSchema = z
+  .object({
+    ...sharedBlockFields,
+    data: z.string().min(1).max(64).optional(),
+    emptyText: visibleText(BLOCK_LIMITS.contextTextMaxLength).optional(),
+    height: z.enum(CHART_HEIGHTS).optional(),
+    kind: z.enum(CHART_KINDS),
+    legend: z.boolean().optional(),
+    points: z
+      .array(
+        z
+          .object({
+            label: visibleText(BLOCK_LIMITS.metricLabelMaxLength),
+            value: z.number().finite(),
+          })
+          .strict()
+      )
+      .max(BLOCK_LIMITS.datasetRowMax)
+      .optional(),
+    title: visibleText(BLOCK_LIMITS.cardTitleMaxLength).optional(),
+    type: z.literal("chart"),
+    x: z.string().min(1).max(64).optional(),
+    y: z.string().min(1).max(64).optional(),
+  })
+  .strict();
+
+const tableSchema = z
+  .object({
+    ...sharedBlockFields,
+    columns: z.array(z.string().min(1).max(64)).min(1).optional(),
+    data: z.string().min(1).max(64),
+    title: visibleText(BLOCK_LIMITS.cardTitleMaxLength).optional(),
+    type: z.literal("table"),
+  })
+  .strict();
+
+const replyActionSchema = z
+  .object({
+    kind: z.literal("reply"),
+    text: visibleText(BLOCK_LIMITS.blockTextMaxLength),
+  })
+  .strict();
+
+const openActionSchema = z
+  .object({
+    kind: z.literal("open"),
+    route: z.string().min(1).max(200).optional(),
+    url: z.string().min(1).max(2_000).optional(),
+  })
+  .strict();
+
+const selectActionSchema = z
+  .object({
+    data: z.string().min(1).max(64),
+    kind: z.literal("select"),
+    target: z.string().min(1).max(64),
+  })
+  .strict();
+
+const callbackActionSchema = z
+  .object({
+    kind: z.literal("callback"),
+    name: z.string().regex(/^[a-z][A-Za-z0-9_]{0,63}$/),
+    payload: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict();
+
+const actionSchema = z.discriminatedUnion("kind", [
+  replyActionSchema,
+  openActionSchema,
+  selectActionSchema,
+  callbackActionSchema,
+]);
+
+const buttonElementSchema = z
+  .object({
+    action: actionSchema,
+    iconName: z.string().min(1).max(40).optional(),
+    id: blockIdSchema,
+    text: visibleText(80),
+    type: z.literal("button"),
+    variant: z.enum(BUTTON_VARIANTS).optional(),
+  })
+  .strict();
+
+const segmentedElementSchema = z
+  .object({
+    id: blockIdSchema,
+    options: z
+      .array(
+        z
+          .object({
+            data: z.string().min(1).max(64),
+            label: visibleText(40),
+          })
+          .strict()
+      )
+      .min(2)
+      .max(8),
+    target: z.string().min(1).max(64),
+    type: z.literal("segmented"),
+  })
+  .strict();
+
+const htmlSchema = z
+  .object({
+    ...sharedBlockFields,
+    height: z.enum(HTML_HEIGHTS).optional(),
+    html: z.string().min(1),
+    title: visibleText(BLOCK_LIMITS.headingTextMaxLength).optional(),
+    type: z.literal("html"),
+  })
+  .strict();
+
+const calloutSchema = z
+  .object({
+    ...sharedBlockFields,
+    status: z.enum(CALLOUT_STATUSES).optional(),
+    text: visibleText(BLOCK_LIMITS.blockTextMaxLength),
+    type: z.literal("callout"),
+  })
+  .strict();
+
+const imageSchema = z
+  .object({
+    ...sharedBlockFields,
+    alt: visibleText(BLOCK_LIMITS.headingTextMaxLength),
+    src: z.string().min(1).max(BLOCK_LIMITS.htmlMaxBytes),
+    type: z.literal("image"),
+  })
+  .strict();
+
+const detailsSchema = z
+  .object({
+    ...sharedBlockFields,
+    text: visibleText(BLOCK_LIMITS.blockTextMaxLength),
+    title: visibleText(BLOCK_LIMITS.headingTextMaxLength),
+    type: z.literal("details"),
+  })
+  .strict();
+
+const actionsSchema = z
+  .object({
+    elements: z
+      .array(z.discriminatedUnion("type", [buttonElementSchema, segmentedElementSchema]))
+      .min(1)
+      .max(BLOCK_LIMITS.actionElementsMax),
+    id: blockIdSchema,
+    type: z.literal("actions"),
+  })
+  .strict();
+
+const blockSchema: z.ZodType<Block> = z.lazy(() =>
+  z.discriminatedUnion("type", [
+    headingSchema,
+    textSchema,
+    metricSchema,
+    badgeSchema,
+    dividerSchema,
+    contextSchema,
+    chartSchema,
+    tableSchema,
+    actionsSchema,
+    htmlSchema,
+    calloutSchema,
+    imageSchema,
+    detailsSchema,
+    z
+      .object({
+        ...sharedBlockFields,
+        children: z.array(blockSchema).min(BLOCK_LIMITS.columnsMin).max(BLOCK_LIMITS.columnsMax),
+        type: z.literal("columns"),
+      })
+      .strict(),
+    z
+      .object({
+        ...sharedBlockFields,
+        children: z.array(blockSchema).min(1).max(BLOCK_LIMITS.maxBlocks),
+        title: visibleText(BLOCK_LIMITS.cardTitleMaxLength).optional(),
+        type: z.literal("card"),
+      })
+      .strict(),
+  ])
+);
+
+const datasetColumnSchema = z
+  .object({
+    name: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/),
+    type: z.enum(DATASET_COLUMN_TYPES),
+  })
+  .strict();
+
+const inlineDatasetSchema = z
+  .object({
+    columns: z.array(datasetColumnSchema).min(1),
+    rows: z.array(z.array(z.union([z.string(), z.number(), z.null()]))),
+    source: z.literal("inline").optional(),
+  })
+  .strict();
+
+const refDatasetSchema = z
+  .object({
+    grain: z.enum(DATASET_GRAINS).optional(),
+    id: z.string().regex(/^[A-Za-z0-9_-]{1,80}$/),
+    limit: z.number().int().positive().optional(),
+    source: z.literal("ref"),
+  })
+  .strict();
+
+const datasetSchema = z.union([refDatasetSchema, inlineDatasetSchema]);
+
+/** Document schema. Semantic dataset and chart checks run in `lintDocument`. */
+export const blocksSchema = z
+  .object({
+    blocks: z.array(blockSchema).min(1).max(BLOCK_LIMITS.maxBlocks),
+    datasets: z.record(z.string().regex(/^[a-z][a-z0-9_]{0,63}$/), datasetSchema).optional(),
+    v: z.literal(1),
+  })
+  .strict();
+
+export const wrapAsTextDocument = (text: string): BlocksDocument => ({
+  blocks: [{markdown: text, type: "text"}],
+  v: 1,
+});

package/src/tests/askFixtures.ts

@@ -0,0 +1,40 @@
+import {readdirSync, readFileSync} from "node:fs";
+import {join} from "node:path";
+import type {Ask, AskKind} from "../asks/schema";
+import type {SimpleCard} from "../asks/simpleCard";
+
+const FIXTURES_DIR = join(import.meta.dir, "..", "asks", "fixtures");
+
+export type ValidAskFixture = Ask & {
+  name: string;
+  simple: SimpleCard;
+};
+
+export interface InvalidAskFixture {
+  errors: {code: string; path: string}[];
+  input: unknown;
+  kind: AskKind;
+  name: string;
+}
+
+const readFixtures = <T>(folder: "invalid" | "valid"): T[] =>
+  readdirSync(join(FIXTURES_DIR, folder))
+    .filter((file) => file.endsWith(".json"))
+    .sort()
+    .map((file) => ({
+      ...JSON.parse(readFileSync(join(FIXTURES_DIR, folder, file), "utf8")),
+      name: file.replace(/\.json$/, ""),
+    }));
+
+export const validAskFixtures = (): ValidAskFixture[] => readFixtures<ValidAskFixture>("valid");
+
+/** The valid fixtures of one kind, typed as that kind. */
+export const validAskFixturesOf = <Kind extends AskKind>(
+  kind: Kind
+): Extract<ValidAskFixture, {kind: Kind}>[] =>
+  validAskFixtures().filter(
+    (fixture): fixture is Extract<ValidAskFixture, {kind: Kind}> => fixture.kind === kind
+  );
+
+export const invalidAskFixtures = (): InvalidAskFixture[] =>
+  readFixtures<InvalidAskFixture>("invalid");

package/src/validate.perf.test.ts

@@ -0,0 +1,43 @@
+import {describe, expect, it} from "bun:test";
+
+import {validateBlocks} from "./validate";
+
+describe("validateBlocks performance", () => {
+  it("validates a 50-block, 8-dataset document in under 5 ms median", () => {
+    const datasets: Record<
+      string,
+      {columns: {name: string; type: string}[]; rows: [string, number][]}
+    > = {};
+    for (let index = 0; index < 8; index += 1) {
+      datasets[`set_${index}`] = {
+        columns: [
+          {name: "label", type: "string"},
+          {name: "value", type: "number"},
+        ],
+        rows: [
+          ["a", 1],
+          ["b", 2],
+        ],
+      };
+    }
+    const blocks = Array.from({length: 50}, (_unused, index) =>
+      index === 0
+        ? {data: "set_0", kind: "bar", type: "chart", x: "label", y: "value"}
+        : {type: "divider"}
+    );
+    const doc: Record<string, unknown> = {};
+    doc.v = 1;
+    doc.datasets = datasets;
+    doc.blocks = blocks;
+    const samples: number[] = [];
+    for (let run = 0; run < 11; run += 1) {
+      const started = performance.now();
+      const validated = validateBlocks(doc);
+      samples.push(performance.now() - started);
+      expect(validated.ok).toBe(true);
+    }
+    samples.sort((left, right) => left - right);
+    const median = samples[5];
+    expect(median).toBeLessThan(5);
+  });
+});