wizards 0.5.12 → 0.6.0

package/node_modules/@engenty-wizards/shared/dist/shape.js

@@ -0,0 +1,318 @@
+// SPDX-License-Identifier: FSL-1.1-MIT OR MIT
+import { z } from "zod";
+/**
+ * What an agent step's json output holds, in the kinds wizards already use: `output.schema`.
+ * Text, numbers, yes/no, a choice, an entry of another list by its id (`ref`), and lists — of
+ * these or of objects (entries) with lists of their own — every one with a label. The runtime builds the model's JSON Schema from
+ * it, the admin shows and edits the data by it, downloads and views read it.
+ *
+ * `output.fields`, the short form, compiles to the same shape (`shapeOfFields`); two kinds exist
+ * only there: `score` (a decision's levels) and `table` (rows of text or numbers, columns named
+ * or picked by the model).
+ */
+/** Objects nest at most this deep, the step's own object counted. */
+export const MAX_SHAPE_DEPTH = 4;
+/** At most this many keys in all objects together. */
+export const MAX_SHAPE_KEYS = 100;
+const key = z
+    .string()
+    .regex(/^[a-zA-Z][a-zA-Z0-9_]{0,40}$/, "keys are letters, digits and _ and start with a letter");
+const named = {
+    label: z.string().min(1).optional(),
+    description: z.string().optional(),
+};
+const leaves = [
+    z.object({ kind: z.literal("text"), ...named, long: z.boolean().optional() }),
+    z.object({ kind: z.literal("number"), ...named, unit: z.string().optional() }),
+    z.object({
+        kind: z.literal("yesno"),
+        ...named,
+        yes: z.string().optional(),
+        no: z.string().optional(),
+    }),
+    z.object({
+        kind: z.literal("choice"),
+        ...named,
+        options: z.array(z.string().min(1)).min(2).max(40),
+    }),
+    z.object({ kind: z.literal("ref"), ...named, to: key }),
+];
+const LEAF_KINDS = "text, number, yesno, choice, ref";
+/**
+ * The shape of an object `depth` deep, built level by level instead of recursively: JSON Schema
+ * of the definition takes no $ref, and the depth is part of the schema. Objects are the entries
+ * of lists (and the step's own); a field holding one object would only add a level.
+ */
+function objectAt(depth) {
+    const deeper = depth < MAX_SHAPE_DEPTH ? objectAt(depth + 1) : undefined;
+    const of = deeper
+        ? z.discriminatedUnion("kind", [...leaves, deeper], {
+            error: `A list holds ${LEAF_KINDS} or object.`,
+        })
+        : z.discriminatedUnion("kind", [...leaves], {
+            error: `A list this deep holds ${LEAF_KINDS}: objects nest at most ${MAX_SHAPE_DEPTH} deep.`,
+        });
+    const list = z.object({ kind: z.literal("list"), ...named, of });
+    const field = z.discriminatedUnion("kind", [...leaves, list], {
+        error: `"kind" is one of ${LEAF_KINDS}, list.`,
+    });
+    return z.object({
+        kind: z.literal("object"),
+        ...named,
+        fields: z
+            .record(key, field)
+            .refine((f) => Object.keys(f).length > 0, { message: "An object has fields." }),
+    });
+}
+/** Every object of a shape with where it sits, the shape's own first. */
+function objectsOf(shape, at = []) {
+    const out = [{ shape, at }];
+    for (const [k, f] of Object.entries(shape.fields)) {
+        if (f.kind === "list" && f.of.kind === "object") {
+            out.push(...objectsOf(f.of, [...at, "fields", k, "of"]));
+        }
+    }
+    return out;
+}
+/** The list a `ref` points into: a top-level list of objects with an `id`. Null when it is fine. */
+function refProblem(root, to) {
+    const target = root.fields[to];
+    if (target?.kind !== "list" || target.of.kind !== "object") {
+        return `"ref" to "${to}": that is no list of objects at the top of the schema.`;
+    }
+    return target.of.fields.id?.kind === "text"
+        ? null
+        : `"ref" to "${to}": its entries need an "id" text field to be pointed at.`;
+}
+/** `output.schema`: what the step returns. */
+export const outputShapeSchema = objectAt(1).superRefine((shape, ctx) => {
+    const objects = objectsOf(shape);
+    const keys = objects.reduce((n, o) => n + Object.keys(o.shape.fields).length, 0);
+    if (keys > MAX_SHAPE_KEYS) {
+        ctx.addIssue({
+            code: "custom",
+            message: `A schema has at most ${MAX_SHAPE_KEYS} keys in all; this one has ${keys}.`,
+        });
+    }
+    for (const o of objects) {
+        for (const [k, f] of Object.entries(o.shape.fields)) {
+            const ref = f.kind === "ref" ? f : f.kind === "list" && f.of.kind === "ref" ? f.of : null;
+            const problem = ref ? refProblem(shape, ref.to) : null;
+            if (problem) {
+                ctx.addIssue({ code: "custom", message: problem, path: [...o.at, "fields", k] });
+            }
+        }
+    }
+});
+/** The short form as a shape: a field per key, a list of text, a table as it is. */
+export function shapeOfFields(fields) {
+    const one = (f) => {
+        const d = f.description ? { description: f.description } : {};
+        switch (f.kind) {
+            case "number":
+                return { kind: "number", ...d };
+            case "list":
+                return { kind: "list", ...d, of: { kind: "text" } };
+            case "yesno":
+                return { kind: "yesno", ...d };
+            case "choice":
+                return { kind: "choice", ...d, options: f.options ?? [] };
+            case "score":
+                return { kind: "score", ...d, options: f.options ?? [] };
+            case "table":
+                return { kind: "table", ...d, ...(f.columns?.length ? { columns: f.columns } : {}) };
+            default:
+                return { kind: "text", ...d };
+        }
+    };
+    return { kind: "object", fields: Object.fromEntries(fields.map((f) => [f.id, one(f)])) };
+}
+/** The key of an entry's title: its first short text other than its `id`. */
+export function titleKey(shape) {
+    return Object.entries(shape.fields).find(([k, f]) => k !== "id" && f.kind === "text" && !f.long)?.[0];
+}
+/** What people read for a key. */
+export function labelOf(key, shape) {
+    return shape.label ?? key;
+}
+/**
+ * What the model reads about a value beside its title: its description (without label: its key),
+ * its unit, a score's order, where a ref points. Undefined where the title says it all.
+ */
+function about(k, s) {
+    const base = s.description ?? (s.label ? "" : k);
+    const more = s.kind === "number" && s.unit
+        ? `in ${s.unit}`
+        : s.kind === "score"
+            ? "lowest to highest"
+            : s.kind === "ref"
+                ? `the id of an entry of "${s.to}"`
+                : "";
+    return (base && more ? `${base} (${more})` : base || more) || undefined;
+}
+const CELL = z.union([z.string(), z.number(), z.null()]);
+/** The data a shape describes, as Zod: what a model's answer is checked against. */
+export function shapeZod(shape, k = "data") {
+    const description = about(k, shape);
+    const meta = {
+        ...(shape.label ? { title: shape.label } : {}),
+        ...(description ? { description } : {}),
+    };
+    switch (shape.kind) {
+        case "text":
+        case "ref":
+            return z.string().meta(meta);
+        case "number":
+            return z.number().meta(meta);
+        case "yesno":
+            return z.boolean().meta(meta);
+        case "choice":
+        case "score":
+            return z.enum(shape.options).meta(meta);
+        case "list":
+            return z.array(shapeZod(shape.of, k)).meta(meta);
+        case "object":
+            return z
+                .object(Object.fromEntries(Object.entries(shape.fields).map(([n, f]) => [n, shapeZod(f, n)])))
+                .meta(meta);
+        case "table":
+            return (shape.columns?.length
+                ? z.array(z.object(Object.fromEntries(shape.columns.map((c) => [c, CELL]))))
+                : // Free columns come as columns + rows, which a strict schema takes; stored as records.
+                    z.object({ columns: z.array(z.string()), rows: z.array(z.array(CELL)) })).meta(meta);
+    }
+}
+/**
+ * The data as JSON Schema (draft 2020-12): every key required, no other keys — what a model's
+ * structured output takes, and what developers read.
+ */
+export function shapeJsonSchema(shape, title) {
+    const schema = z.toJSONSchema(shapeZod(shape), { target: "draft-2020-12" });
+    return title && !shape.label ? { ...schema, title } : schema;
+}
+/** A table cell as a table takes it: a list joined by spaces, anything else as text. */
+function fitCell(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value === "string" || typeof value === "number") {
+        return value;
+    }
+    if (Array.isArray(value) && value.every((v) => typeof v === "string" || typeof v === "number")) {
+        return value.join(" ");
+    }
+    return typeof value === "boolean" ? String(value) : JSON.stringify(value);
+}
+const isRecord = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
+/**
+ * Data a model wrote itself, fitted to the shape before it is checked: a number where text
+ * belongs as text, a number written as text as a number; in a table a cell's list joined and a
+ * missing column empty. Lists stay lists everywhere else.
+ */
+export function fitData(shape, value) {
+    switch (shape.kind) {
+        case "text":
+        case "ref":
+            return typeof value === "number" ? String(value) : value;
+        case "number":
+            return typeof value === "string" && value.trim() && Number.isFinite(Number(value))
+                ? Number(value)
+                : value;
+        case "list":
+            return Array.isArray(value) ? value.map((v) => fitData(shape.of, v)) : value;
+        case "object":
+            if (!isRecord(value)) {
+                return value;
+            }
+            return {
+                ...value,
+                ...Object.fromEntries(Object.entries(shape.fields)
+                    .filter(([k]) => k in value)
+                    .map(([k, f]) => [k, fitData(f, value[k])])),
+            };
+        case "table": {
+            const columns = shape.columns;
+            return columns?.length && Array.isArray(value)
+                ? value.map((row) => isRecord(row) ? Object.fromEntries(columns.map((c) => [c, fitCell(row[c])])) : row)
+                : value;
+        }
+        default:
+            return value;
+    }
+}
+/** Tables with free columns come back as columns + rows and are stored as records. */
+export function recordsOf(shape, value) {
+    if (shape.kind === "table" && !shape.columns?.length && isRecord(value)) {
+        const t = value;
+        if (t.columns && t.rows) {
+            const columns = t.columns;
+            return t.rows.map((row) => Object.fromEntries(columns.map((c, i) => [c, row[i] ?? null])));
+        }
+    }
+    if (shape.kind === "object" && isRecord(value)) {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => {
+            const f = shape.fields[k];
+            return [k, f ? recordsOf(f, v) : v];
+        }));
+    }
+    if (shape.kind === "list" && Array.isArray(value)) {
+        return value.map((v) => recordsOf(shape.of, v));
+    }
+    return value;
+}
+/** What a value of a shape is, in a word or two: "list of Rezept", "choice: a | b". */
+function kindLine(s) {
+    switch (s.kind) {
+        case "choice":
+        case "score":
+            return `${s.kind}: ${s.options.join(" | ")}`;
+        case "ref":
+            return `ref → /${s.to}[].id`;
+        case "table":
+            return s.columns?.length ? `table: ${s.columns.join(", ")}` : "table";
+        case "list":
+            return s.of.kind === "object" ? "list of entries" : `list of ${s.of.kind}`;
+        default:
+            return s.kind;
+    }
+}
+/** The shape as lines of paths a model binds to: "/recipes[]/title (text): Titel". */
+export function shapeLines(shape, at = "") {
+    const out = [];
+    for (const [k, f] of Object.entries(shape.fields)) {
+        const path = `${at}/${k}`;
+        const words = [f.label, f.description].filter(Boolean).join(" — ");
+        out.push(`- ${path} (${kindLine(f)})${words ? `: ${words}` : ""}`);
+        if (f.kind === "list" && f.of.kind === "object") {
+            out.push(...shapeLines(f.of, `${path}[]`));
+        }
+    }
+    return out;
+}
+/**
+ * The shape at a path: keys of objects, an index (digits) into a list. `any` where the data can
+ * hold anything (a table's row), undefined where the shape has nothing.
+ */
+export function shapeAt(shape, path) {
+    let at = shape;
+    for (const part of path) {
+        if (at.kind === "object") {
+            const next = at.fields[part];
+            if (!next) {
+                return undefined;
+            }
+            at = next;
+        }
+        else if (at.kind === "list" && /^\d+$/.test(part)) {
+            at = at.of;
+        }
+        else if (at.kind === "table") {
+            // A row, and in it whatever columns the model wrote.
+            return /^\d+$/.test(part) ? "any" : undefined;
+        }
+        else {
+            return undefined;
+        }
+    }
+    return at;
+}

package/node_modules/@engenty-wizards/shared/dist/surface.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { type ObjectShape } from "./shape.js";
 /**
  * Surfaces: views composed from a small catalog of native components, bound to a run's data and
  * rendered by the runner itself — themed, on phones, no iframe and nothing to pay per run. A
@@ -8,10 +9,12 @@ import { z } from "zod";
  *
  * A surface is a flat list of components with ids; the one with id "root" is drawn, containers
  * name their children by id. A prop may be a literal or `{ "path": "/json/pointer" }` into the
- * surface's data. A `List` or `Table` repeats over an array: inside a repeated row, a path
- * without a leading slash reads the row ("name"), one with a slash the whole data.
+ * surface's data. A `List`, `Table` or `Group` repeats over an array: inside a repeated row, a
+ * path without a leading slash reads the row ("name"), one with a slash the whole data. A path
+ * may turn what it reads into words: `map` looks the value up (`{ "true": "im Kühlschrank" }`),
+ * `format` sets it into a text ("{} Min").
  */
-export declare const SURFACE_COMPONENTS: readonly ["Column", "Text", "List", "Row", "DetailGrid", "Badge", "Grid", "Metric", "Table", "Image", "BarChart", "LineChart", "DonutChart", "Actions", "Button"];
+export declare const SURFACE_COMPONENTS: readonly ["Column", "Text", "List", "Row", "DetailGrid", "Badge", "Grid", "Metric", "Table", "Image", "BarChart", "LineChart", "DonutChart", "Actions", "Button", "Tabs", "Card", "Fold", "Group", "Chips", "Checklist", "Steps", "Link", "Callout"];
 export type SurfaceComponentName = (typeof SURFACE_COMPONENTS)[number];
 export declare const SURFACE_ACTIONS: readonly ["regenerate", "open"];
 /** One component: its id, its kind, its children (ids, or a template repeated over an array). */
@@ -22,16 +25,25 @@ export declare const surfaceComponentSchema: z.ZodObject<{
         Badge: "Badge";
         BarChart: "BarChart";
         Button: "Button";
+        Callout: "Callout";
+        Card: "Card";
+        Checklist: "Checklist";
+        Chips: "Chips";
         Column: "Column";
         DetailGrid: "DetailGrid";
         DonutChart: "DonutChart";
+        Fold: "Fold";
         Grid: "Grid";
+        Group: "Group";
         Image: "Image";
         LineChart: "LineChart";
+        Link: "Link";
         List: "List";
         Metric: "Metric";
         Row: "Row";
+        Steps: "Steps";
         Table: "Table";
+        Tabs: "Tabs";
         Text: "Text";
     }>;
     children: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
@@ -47,16 +59,25 @@ export declare const surfaceComponentsSchema: z.ZodArray<z.ZodObject<{
         Badge: "Badge";
         BarChart: "BarChart";
         Button: "Button";
+        Callout: "Callout";
+        Card: "Card";
+        Checklist: "Checklist";
+        Chips: "Chips";
         Column: "Column";
         DetailGrid: "DetailGrid";
         DonutChart: "DonutChart";
+        Fold: "Fold";
         Grid: "Grid";
+        Group: "Group";
         Image: "Image";
         LineChart: "LineChart";
+        Link: "Link";
         List: "List";
         Metric: "Metric";
         Row: "Row";
+        Steps: "Steps";
         Table: "Table";
+        Tabs: "Tabs";
         Text: "Text";
     }>;
     children: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
@@ -74,10 +95,10 @@ export interface SurfaceIssue {
 }
 /**
  * What can be wrong with a surface: an unknown or missing component, no root, a child that is
- * not there, an id twice, a loop, a prop missing, and — given the data keys a run will provide —
- * an absolute path into data nothing provides.
+ * not there, an id twice, a loop, a prop missing, and — given the data keys a run will provide,
+ * or the step's schema — a path into data nothing provides.
  */
-export declare function validateSurface(raw: unknown, dataKeys?: string[]): SurfaceIssue[];
+export declare function validateSurface(raw: unknown, data?: string[] | ObjectShape): SurfaceIssue[];
 /** A JSON pointer into data: "/suppliers/0/name". */
 export declare function pointer(data: unknown, path: string): unknown;
 /**
@@ -85,5 +106,10 @@ export declare function pointer(data: unknown, path: string): unknown;
  * from the row a List or Table repeats over.
  */
 export declare function bound(value: unknown, data: unknown, row?: unknown): unknown;
+/** A value turned into words as its path says: looked up in `map`, set into `format`. */
+export declare function worded(raw: unknown, spec: {
+    map?: unknown;
+    format?: unknown;
+}): unknown;
 /** What a model needs to compose a surface: the catalog, briefly. */
-export declare const SURFACE_GUIDE = "A surface is a flat JSON array of components; the one with id \"root\" is drawn. Containers list their children by id.\nComponents and props (a prop may be a literal or {\"path\": \"/key/...\"} into the data):\n- Column { children: [ids] } \u2014 vertical stack (use for root)\n- Text { text, variant?: \"h3\"|\"h4\"|\"body\"|\"muted\" }\n- List { children: {\"path\": \"/rows\", \"componentId\": \"<a Row id>\"} } \u2014 one Row per array entry; inside, paths without \"/\" read the entry (\"name\")\n- Row { title, subtitle?, meta?, badge?, image? }\n- DetailGrid { rows: [{ label, value }] } \u2014 label/value facts\n- Badge { label, tone?: \"default\"|\"success\"|\"warning\" }\n- Grid { children: [ids], columns?: 2|3|4 } \u2014 tiles side by side\n- Metric { label, value, caption? } \u2014 a key figure\n- Table { rows: {\"path\": \"/rows\"}, columns?: [{ key, label }] }\n- Image { src: an asset id or {\"path\": ...}, alt? }\n- BarChart / LineChart { title?, points: [{ label, value }] or {\"path\": ...}, labelKey?, valueKey? }\n- DonutChart { title?, slices: [{ label, value }] or {\"path\": ...}, labelKey?, valueKey? }\n  (labelKey / valueKey: the columns of bound rows that hold the label and the number, e.g. \"name\", \"price\")\n- Actions { children: [Button ids] } / Button { label, action: \"regenerate\"|\"open\" }\nKeep it small: what the person needs to see first, then the details. Never invent numbers: bind them by path.";
+export declare const SURFACE_GUIDE = "A surface is a flat JSON array of components; the one with id \"root\" is drawn. Containers list their children by id.\nComponents and props (a prop may be a literal or {\"path\": \"/key/...\"} into the data):\n- Column { children: [ids] } \u2014 vertical stack (use for root); Column and Grid may also repeat one component per entry: children {\"path\", \"componentId\"}\n- Text { text, variant?: \"h3\"|\"h4\"|\"lead\"|\"body\"|\"muted\" } \u2014 \"lead\": the one opening line in the wizard's voice\n- List { children: {\"path\": \"/rows\", \"componentId\": \"<a Row id>\"} } \u2014 one Row per array entry; inside, paths without \"/\" read the entry (\"name\")\n- Row { title, subtitle?, meta?, badge?, image? }\n- DetailGrid { rows: [{ label, value }] } \u2014 label/value facts\n- Badge { label, tone?: \"default\"|\"success\"|\"warning\"|\"accent\" }\n- Grid { children: [ids], columns?: 2|3|4, min?: rem } \u2014 tiles side by side; min: the narrowest a tile gets (14 for cards, so a phone shows one)\n- Metric { label, value, caption? } \u2014 a key figure\n- Table { rows: {\"path\": \"/rows\"}, columns?: [{ key, label }] }\n- Image { src: an asset id or {\"path\": ...}, alt? }\n- BarChart / LineChart { title?, points: [{ label, value }] or {\"path\": ...}, labelKey?, valueKey? }\n- DonutChart { title?, slices: [{ label, value }] or {\"path\": ...}, labelKey?, valueKey? }\n  (labelKey / valueKey: the columns of bound rows that hold the label and the number, e.g. \"name\", \"price\")\n- Actions { children: [Button ids] } / Button { label, action: \"regenerate\"|\"open\" }\n- Tabs { tabs: [{ label, count?, child: id }] } \u2014 two to four views of one result; count may bind a list (shows its length)\n- Card { title, eyebrow?, subtitle?, meta?: [values], image?, children?: [ids] } \u2014 one thing: a day, a recipe, an offer\n- Fold { title, open?, children: [ids] } \u2014 details that open on a tap\n- Group { children: {\"path\", \"componentId\"}, by: \"<key>\", order?: [values] } \u2014 entries under a heading per value of a key\n- Chips { items, labelKey?, flagKey?, flag? } \u2014 short things at a glance; flagKey marks some (\"bald\")\n- Checklist { items, labelKey?, detailKey?, noteKey?, noteFormat?, noteMap?, groupKey?, groupOrder?, share? } \u2014 things to get or do; ticks are kept; a yes/no note needs noteMap: {\"true\": \"da\", \"false\": \"einkaufen\"}\n- Steps { items, textKey?, minutesKey? } \u2014 ordered work, numbered, with times\n- Link { title, subtitle?, eyebrow?, meta?, look?: \"row\"|\"card\", items: {\"path\": \"/recipes\"}, key?: \"id\", value: {\"path\": \"recipe_id\"}, view: id } \u2014 opens the entry of items whose key is value in a sheet, drawn by view; title, subtitle and meta read that entry, eyebrow the row the Link sits in\n- Callout { text, title?, tone?: \"tip\"|\"note\"|\"warning\" }\nA path may put its value into words: {\"path\": \"in_fridge\", \"map\": {\"true\": \"da\", \"false\": \"einkaufen\"}}, {\"path\": \"minutes\", \"format\": \"{} Min\"}.\nDesign it like an app, not a report: lead with a headline, the key figure or the chips; one Card per thing, never a Table of things; ordered work is Steps, things to get are a Checklist, sets are grouped by their key. A Table only for figures people compare across columns.\nKeep it small: what the person needs to see first, then the details. Never invent numbers: bind them by path.";