@shapesos/clay 0.11.0 → 0.13.0

package/dist/types-GCkXbyFm.d.ts

@@ -0,0 +1,330 @@
+import { ComponentType } from 'react';
+import { C as ChartSeries } from './types-B2aYk82c.js';
+
+/**
+ * Shared artifact primitives — the discriminator constant and the cross-variant `ArtifactBase`
+ * shape that every concrete artifact record extends.
+ *
+ * Pulled into its own file so the per-type `types.ts` files (`table-artifact/types.ts`,
+ * `chart-artifact/types.ts`) and the union assembler (`artifacts/types.ts`) can all depend on
+ * one canonical source without creating a circular module graph between them.
+ */
+/**
+ * Artifact-type discriminator constants. Uppercase to match the server-side `artifactTypes`
+ * constant — io-server stores `artifact.type === "TABLE"` (aligned with the GraphQL enum).
+ */
+declare const artifactTypes: {
+    readonly TABLE: "TABLE";
+    readonly CHART: "CHART";
+};
+/** Discriminator for artifact types. Additive — new types extend this union. */
+type ArtifactType = (typeof artifactTypes)[keyof typeof artifactTypes];
+/** Common shape every artifact record carries. Discriminated by `type`. */
+interface ArtifactBase<TType extends ArtifactType, TConfig> {
+    /** Artifact-type discriminator. */
+    type: TType;
+    /** Human-readable label. Nullable when the artifact has no title. */
+    title: string | null;
+    /** Rendering config — shape varies per artifact type. */
+    config: TConfig;
+    /** Protected-asset metadata pointing to the underlying data payload. Null while the asset is unavailable. */
+    protectedAsset: {
+        /** Time-limited URL the renderer fetches the artifact's data from. */
+        presignedUrl: string;
+    } | null;
+}
+/**
+ * A row inside an artifact's parsed CSV. Every cell is the raw string from the CSV (or `null`
+ * for the empty string). Used by every artifact kind whose data wire is a CSV (`TABLE`, `CHART`).
+ * The renderer never coerces — type-aware formatting is a server concern (the CSV's contents
+ * are what the user sees).
+ */
+type ArtifactDataRow = Record<string, string | null>;
+
+/**
+ * Rendering config for a `BAR` chart. `xKey` selects the categorical axis; each series
+ * contributes one `<Bar>`. `stacked` collapses all series onto a single stack-id (so they sum
+ * vertically); when false / omitted bars are grouped side-by-side per x-tick.
+ */
+interface BarChartConfig extends ChartConfigBase {
+    variant: "BAR";
+    /** CSV column key used as the x-axis. */
+    xKey: string;
+    /** When true, stack all series on one stack-id. When false / omitted, group bars side-by-side. */
+    stacked?: boolean;
+}
+
+/**
+ * Rendering config for a `LINE` chart. `xKey` selects the categorical/temporal axis from the
+ * CSV; each series contributes one `<Line>` overlaid against that axis.
+ */
+interface LineChartConfig extends ChartConfigBase {
+    variant: "LINE";
+    /** CSV column key used as the x-axis. */
+    xKey: string;
+}
+
+/**
+ * Rendering config for a `PIE` chart. `categoryKey` names the slice; `valueKey` carries the
+ * slice's numeric magnitude. One row of CSV becomes one slice. The base's `series` array is
+ * always empty for pie — colors are resolved by row index from the palette.
+ */
+interface PieChartConfig extends ChartConfigBase {
+    variant: "PIE";
+    /** CSV column key used as the slice label. */
+    categoryKey: string;
+    /** CSV column key used as the slice numeric value. */
+    valueKey: string;
+}
+
+/**
+ * Discriminated union of all supported chart variant configs. Assembled here (not in the parent
+ * `types.ts`) because the union depends on each variant service file as its single source of
+ * truth for that variant's config type.
+ *
+ * Extension pattern: add a new variant by creating one `*-chart-variant-service.ts` file and
+ * extending this union + the `ChartVariantServices` map below. No edits to the dispatcher.
+ */
+type ChartConfig = LineChartConfig | BarChartConfig | PieChartConfig;
+
+/**
+ * Optional stats embedded in `ChartConfig` so clients can pre-render UI before fetching the
+ * actual CSV (e.g. a skeleton sized to the eventual row count). Mirrors `TableStats`.
+ */
+interface ChartStats {
+    /** Total number of rows in the materialised CSV. */
+    rowCount: number;
+}
+/**
+ * Cross-variant base for `ChartConfig`. Carries the fields every variant shares — series
+ * descriptors and optional stats. Per-variant config interfaces (in `chart-variant-services/`)
+ * extend this with their own required fields.
+ *
+ * Note: `series` is always present on the wire (matching the GraphQL `[ChartSeries!]!` shape)
+ * even for PIE — PIE just receives an empty array. Keeping it on the base mirrors the wire shape
+ * exactly and avoids TS object-literal freshness errors for callers that explicitly set
+ * `series: []` on a pie config.
+ */
+interface ChartConfigBase {
+    /** Series descriptors in render order. LINE/BAR consume these; PIE ignores in favour of `categoryKey`+`valueKey`. */
+    series: ChartSeries[];
+    /** Optional metadata describing the underlying data — used for loading-state UI. */
+    stats?: ChartStats;
+}
+/** Concrete chart artifact record. */
+type ChartArtifactRecord = ArtifactBase<typeof artifactTypes.CHART, ChartConfig>;
+/**
+ * Localized labels for the `CHART` artifact's user-facing strings. Covers action buttons AND
+ * status messages — see `TableArtifactLabels` for the same shape philosophy. Extends as the
+ * chart artifact grows its action set (e.g. future `copyAsPng`); optional keys document
+ * anticipated additions without forcing every consumer to provide them today.
+ */
+interface ChartArtifactLabels {
+    /** Tooltip + aria-label on the Download menu's trigger button (icon-only, opens the format
+     *  picker). The trigger is action-shaped (just "Download"); the menu items spell out the
+     *  format. */
+    download: string;
+    /** Label for the "Download CSV" item inside the Download menu. */
+    downloadCsv: string;
+    /** Label for the "Download PNG" item inside the Download menu. */
+    downloadPng: string;
+    /** Tooltip + aria-label on the "Copy Image" button in the chart artifact header (idle state).
+     * Transient working / success / error tooltips remain in English — they flash for ~1.5s and the
+     * cost of translating them is rarely worth it. */
+    copyAsImage: string;
+    /** Status message shown when no presigned URL is available or the chart config is malformed. */
+    unavailable: string;
+    /** Status message shown when the fetch / parse fails at runtime. */
+    loadError: string;
+    /** Status message shown while the CSV is being fetched. */
+    loading: string;
+    /** Status message shown when the fetched CSV has zero data rows. */
+    empty: string;
+    /**
+     * Category labels treated as the "Others" bucket in pie charts (case-insensitive). Matching
+     * slices are pinned to the end of the sweep and rendered in neutral grey. The agent writes a
+     * translated bucket name in non-English UIs (e.g. "אחרים", "Otros") — consumer passes the
+     * localized list here so clay can detect the bucket regardless of language. English fallback
+     * is `["Others", "Other"]`. Pass `[]` to disable Others detection (every slice from the palette).
+     */
+    othersCategoryLabels: readonly string[];
+}
+/** English fallback for `ChartArtifactLabels`. Used when the consumer hasn't passed `labels`. */
+declare const DEFAULT_CHART_ARTIFACT_LABELS: ChartArtifactLabels;
+/**
+ * Consumer-supplied side-effect callbacks for actions on the chart artifact. Mirrors
+ * `ChartArtifactLabels`'s shape philosophy: one entry per action this artifact exposes
+ * (download today; future "Copy as PNG" etc.). Every callback is optional — consumers wire
+ * only the actions they care about. The artifact passes its own `ChartArtifactRecord` as the
+ * only argument so consumers can derive analytics context (title, config.variant, etc.) without
+ * a per-block closure at every render site.
+ *
+ * The callback fires alongside the default browser behaviour (e.g. `onDownload` does not
+ * prevent the anchor's download navigation) — it's purely for analytics / observability hooks.
+ */
+interface ChartArtifactCallbacks {
+    /** Fires when the "Download CSV" menu item is selected. Browser-native download still happens. */
+    onDownload?: (artifact: ChartArtifactRecord) => void;
+    /** Fires when the "Download PNG" menu item is selected. Runs alongside the rasterise — fires
+     *  regardless of whether the rasterise ultimately succeeds (failures surface via console.warn). */
+    onDownloadPng?: (artifact: ChartArtifactRecord) => void;
+    /** Fires when the Copy Image button is clicked. Fires regardless of whether the copy ultimately
+     * succeeds (the result is reported via the button's own state flash) — use this only for
+     * analytics / observability, not for retrying failed copies. */
+    onCopyAsImage?: (artifact: ChartArtifactRecord) => void;
+}
+
+/**
+ * A single column descriptor for a `TableArtifact`. Carries the ORDER and LABEL for the
+ * rendered table — `key` selects a column from the CSV header; `label` overrides the rendered
+ * header text. The CSV is always the source of truth for the data shape; clay never coerces,
+ * reformats, or interprets cell values.
+ */
+interface TableColumn {
+    /** Matches a header in the CSV. Required. Used to project + order the CSV's columns. */
+    key: string;
+    /** Human-readable header text. Required. */
+    label: string;
+    /**
+     * Accepted in the wire payload but not consulted by the renderer — every cell is rendered as
+     * the raw CSV string (or empty for null). Format conversion is a server concern; if a column
+     * needs to be "Yes/No" instead of "true/false", the server should emit it that way in the CSV.
+     * Kept in the interface so callers that pass `type` (e.g. io-client) don't get a type error.
+     */
+    type?: "string" | "number" | "date" | "boolean";
+    /**
+     * Accepted in the wire payload but not consulted by the renderer — every column is left-aligned
+     * by design. Kept in the interface for forward-compat; restore per-column alignment by editing
+     * `table-artifact-content.tsx` if a future use case justifies it.
+     */
+    align?: "left" | "center" | "right";
+}
+/**
+ * Optional stats embedded in `TableConfig` so clients can pre-render UI before fetching the
+ * actual data payload (e.g. N loading shimmers sized to the eventual row count).
+ *
+ * Backward-compat: optional everywhere — older artifacts persisted before this field shipped
+ * still validate. The renderer falls back to a single status-message line when `stats` is absent.
+ */
+interface TableStats {
+    /** Total number of rows in the materialised CSV. Lets the loading branch render shimmers. */
+    rowCount: number;
+}
+/** Rendering config for a table artifact, stored at `artifact.config` (JSONB on the server). */
+interface TableConfig {
+    /** Column descriptors in render order. */
+    columns: TableColumn[];
+    /** Optional metadata describing the underlying data — used for loading-state UI. */
+    stats?: TableStats;
+}
+/** Alias retained for callers typed against the table-specific name. */
+type TableRow = ArtifactDataRow;
+/** Concrete table artifact record. */
+type TableArtifactRecord = ArtifactBase<typeof artifactTypes.TABLE, TableConfig>;
+/**
+ * Localized labels for the `TABLE` artifact's user-facing strings. Covers both action buttons
+ * (download today; future "Copy as CSV", etc.) AND status messages (loading / error / empty /
+ * unavailable). Consumer passes the bag from their i18n layer; clay falls back to English
+ * defaults when omitted (per-key Partial merge).
+ */
+interface TableArtifactLabels {
+    /** Tooltip + aria-label on the Download CSV button in the table artifact header. */
+    download: string;
+    /**
+     * Status message shown when no presigned URL is available (permanent server-side absence) or
+     * the artifact config is malformed. Both states reduce to "the underlying file isn't usable".
+     */
+    unavailable: string;
+    /** Status message shown when the fetch / parse fails at runtime (transient). */
+    loadError: string;
+    /** Status message shown while the CSV is being fetched and `stats.rowCount` is not known. */
+    loading: string;
+    /** Empty-state row inside the table body when the fetched CSV has zero data rows. */
+    empty: string;
+}
+/** English fallback for `TableArtifactLabels`. Used when the consumer hasn't passed `labels`. */
+declare const DEFAULT_TABLE_ARTIFACT_LABELS: TableArtifactLabels;
+/**
+ * Consumer-supplied side-effect callbacks for actions on the table artifact. Mirrors
+ * `ChartArtifactCallbacks` — see that interface for the shape philosophy. Every callback is
+ * optional; the artifact passes its own `TableArtifactRecord` as the only argument so consumers
+ * can derive analytics context without a per-block closure at every render site.
+ */
+interface TableArtifactCallbacks {
+    /** Fires when the Download CSV button is clicked. Browser-native download still happens. */
+    onDownload?: (artifact: TableArtifactRecord) => void;
+}
+
+/**
+ * Artifact-domain types — wire-protocol shapes shared between artifact components, block-services,
+ * and consumers. Splits responsibilities across three layers so each artifact kind owns its own
+ * `types.ts` and this file assembles the cross-type union + service contract:
+ *
+ * 1. **`artifact-base.ts`** — discriminator (`artifactTypes`), `ArtifactBase<TType, TConfig>`, and
+ *    `ArtifactDataRow`. Pulled out so each per-type `types.ts` and this assembler can depend on
+ *    one canonical base without a circular module graph.
+ * 2. **`<type>-artifact/types.ts`** — per-artifact-type records, configs, labels, and defaults.
+ *    Variant-specific types (e.g. `LineChartConfig`) live in even deeper per-variant service files.
+ * 3. **This file** — the cross-type `ArtifactRecord` union, the labels map keyed by artifact type,
+ *    and the `ArtifactService<TArtifact, TLabels>` registry contract used by the dispatcher.
+ *
+ * Mirrored from the agent / io-server contract — see the `chat-typed-content-blocks-and-artifacts`
+ * plan, §6.4 (table contract).
+ */
+
+/**
+ * Discriminated union of all supported artifacts. Extension pattern: add the new branch here AND
+ * in the `ArtifactServices` map (single source of truth for the type→component mapping). Older
+ * clay versions that don't know about a new type silently render nothing — see `ArtifactRefBlock`
+ * guard.
+ */
+type ArtifactRecord = TableArtifactRecord | ChartArtifactRecord;
+/**
+ * Type-level lookup from an `ArtifactRecord` branch to its labels / callbacks slice. The block
+ * layer already carries the discriminator on `artifact.type`, so the renderer-side `labels` and
+ * `callbacks` props expose exactly one type's slice — never a union-bag keyed by type. Consumers
+ * emit a flat object; the dispatcher narrows it implicitly via `TArtifact`.
+ */
+type ArtifactLabelsOf<TArtifact extends ArtifactRecord> = TArtifact extends ChartArtifactRecord ? ChartArtifactLabels : TArtifact extends TableArtifactRecord ? TableArtifactLabels : never;
+/** Sibling to `ArtifactLabelsOf` — callbacks slice matching the artifact branch. */
+type ArtifactCallbacksOf<TArtifact extends ArtifactRecord> = TArtifact extends ChartArtifactRecord ? ChartArtifactCallbacks : TArtifact extends TableArtifactRecord ? TableArtifactCallbacks : never;
+/**
+ * Props every concrete artifact component receives from the dispatcher.
+ *
+ * `labels` and `callbacks` are the renderer's OWN flat slice — narrowed by `TArtifact` so a
+ * `ChartArtifact` reads `ChartArtifactLabels` directly. The block layer (`ArtifactRefBlockRecord`)
+ * is a *distributed* union over `ArtifactRecord` branches, so wrong-shape labels for a given
+ * artifact.type are caught at the consumer's construction site — not silently forwarded here.
+ */
+interface ArtifactServiceProps<TArtifact extends ArtifactRecord = ArtifactRecord> {
+    /** The artifact metadata (config + presigned URL). */
+    artifact: TArtifact;
+    /**
+     * Optional localized labels for this artifact's action buttons + status messages. Per-key
+     * `Partial` merge against `DEFAULT_*_ARTIFACT_LABELS` — anything omitted falls back to English.
+     */
+    labels?: Partial<ArtifactLabelsOf<TArtifact>>;
+    /**
+     * Optional side-effect callbacks for actions on this artifact — for analytics / observability
+     * hooks (e.g. tracking a download event). Callbacks fire alongside the default browser
+     * behaviour and do not replace it.
+     */
+    callbacks?: Partial<ArtifactCallbacksOf<TArtifact>>;
+}
+/** Per-artifact-type service — registry entry that pairs a discriminator with its concrete component. */
+interface ArtifactService<TArtifact extends ArtifactRecord = ArtifactRecord> {
+    /** Discriminator value this service handles. */
+    type: (typeof artifactTypes)[keyof typeof artifactTypes];
+    /** React component that renders an artifact of this type — composes ai-elements primitives
+     * (`Artifact`, `ArtifactHeader`, `ArtifactTitle`, `ArtifactActions`, `ArtifactContent`) directly. */
+    Component: ComponentType<ArtifactServiceProps<TArtifact>>;
+    /**
+     * Returns a plain-text / markdown string suitable for clipboard copy.
+     *
+     * Called by `ArtifactRefBlockService.toClipboardText` when the user copies a message that
+     * contains this artifact. Must be pure and synchronous.
+     */
+    toClipboardText: (artifact: TArtifact) => string;
+}
+
+export { type ArtifactCallbacksOf as A, type BarChartConfig as B, type ChartArtifactLabels as C, DEFAULT_CHART_ARTIFACT_LABELS as D, type LineChartConfig as L, type PieChartConfig as P, type TableArtifactLabels as T, type ArtifactDataRow as a, type ArtifactLabelsOf as b, type ArtifactRecord as c, type ArtifactService as d, type ArtifactServiceProps as e, type ArtifactType as f, type ChartArtifactRecord as g, type ChartConfig as h, type ChartStats as i, DEFAULT_TABLE_ARTIFACT_LABELS as j, type TableArtifactRecord as k, type TableColumn as l, type TableConfig as m, type TableRow as n, type TableStats as o, artifactTypes as p };

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@shapesos/clay",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "devDependencies": {
     "@changesets/changelog-github": "^0.6.0",
     "@changesets/cli": "^2.30.0",
     "@eslint/js": "^10.0.1",
+    "@fontsource-variable/crimson-pro": "^5.2.8",
+    "@fontsource-variable/geist": "^5.2.9",
     "@playwright/test": "^1.58.2",
     "@storybook/addon-a11y": "^10.2.19",
     "@storybook/addon-docs": "^10.2.19",
@@ -33,6 +35,7 @@
     "lefthook": "^2.1.1",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
+    "recharts": "^3.8.1",
     "storybook": "^10.2.13",
     "styled-components": "^6.3.11",
     "tailwindcss": "^4",
@@ -46,8 +49,14 @@
   "peerDependencies": {
     "react": "^17 || ^18 || ^19",
     "react-dom": "^17 || ^18 || ^19",
+    "recharts": "^3",
     "styled-components": "^5 || ^6"
   },
+  "peerDependenciesMeta": {
+    "recharts": {
+      "optional": true
+    }
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -75,6 +84,11 @@
       "import": "./dist/artifacts.js",
       "require": "./dist/artifacts.cjs"
     },
+    "./chart": {
+      "types": "./dist/chart.d.ts",
+      "import": "./dist/chart.js",
+      "require": "./dist/chart.cjs"
+    },
     "./table": {
       "types": "./dist/table.d.ts",
       "import": "./dist/table.js",
@@ -105,6 +119,11 @@
       "import": "./dist/utils.js",
       "require": "./dist/utils.cjs"
     },
+    "./capture": {
+      "types": "./dist/capture.d.ts",
+      "import": "./dist/capture.js",
+      "require": "./dist/capture.cjs"
+    },
     "./button": {
       "types": "./dist/button.d.ts",
       "import": "./dist/button.js",
@@ -129,8 +148,9 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "build": "bun run gen:theme && tsup && bun run build:css",
+    "build": "bun run gen:font && bun run gen:theme && tsup && bun run build:css",
     "build:css": "tailwindcss -i src/styles/tailwind.css -o dist/blocks.css --minify",
+    "gen:font": "bun run scripts/generate-font-embed.ts",
     "gen:theme": "bun run scripts/generate-theme-tokens.ts",
     "dev": "tsup --watch",
     "storybook": "storybook dev -p 6006",
@@ -153,8 +173,10 @@
   "type": "module",
   "types": "./dist/index.d.ts",
   "dependencies": {
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-tooltip": "^1.2.8",
     "clsx": "^2.1.1",
+    "html-to-image": "^1.11.13",
     "lottie-react": "^2.4.1",
     "papaparse": "^5.5.3",
     "react-markdown": "^8.0.7",