@shapesos/clay 0.12.0 → 0.13.1

package/dist/artifacts.d.cts

@@ -1,6 +1,6 @@
-import { e as ArtifactType, c as ArtifactService, b as ArtifactRecord, d as ArtifactServiceProps, j as TableArtifactRecord, f as ChartArtifactRecord } from './types-C0BvwliI.cjs';
-export { A as ArtifactDataRow, a as ArtifactLabelsMap, B as BarChartConfig, C as ChartArtifactLabels, g as ChartConfig, h as ChartStats, D as DEFAULT_CHART_ARTIFACT_LABELS, i as DEFAULT_TABLE_ARTIFACT_LABELS, L as LineChartConfig, P as PieChartConfig, T as TableArtifactLabels, k as TableColumn, l as TableConfig, m as TableRow, n as TableStats, o as artifactTypes } from './types-C0BvwliI.cjs';
-import { ReactNode } from 'react';
+import { f as ArtifactType, d as ArtifactService, c as ArtifactRecord, e as ArtifactServiceProps, k as TableArtifactRecord, g as ChartArtifactRecord } from './types-BzXPBy6s.cjs';
+export { A as ArtifactCallbacksOf, a as ArtifactDataRow, b as ArtifactLabelsOf, B as BarChartConfig, C as ChartArtifactLabels, h as ChartConfig, i as ChartStats, D as DEFAULT_CHART_ARTIFACT_LABELS, j as DEFAULT_TABLE_ARTIFACT_LABELS, L as LineChartConfig, P as PieChartConfig, T as TableArtifactLabels, l as TableColumn, m as TableConfig, n as TableRow, o as TableStats, p as artifactTypes } from './types-BzXPBy6s.cjs';
+import { ReactNode, RefObject } from 'react';
 export { C as ChartSeries, a as ChartVariant } from './types-B2aYk82c.cjs';
 
 /**
@@ -57,6 +57,129 @@ declare function ArtifactDownloadButton({ href, label, onClick, }: ArtifactDownl
  */
 declare function isSafeDownloadUrl(url: string): boolean;
 
+/** Props for `ArtifactCopyAsImageButton`. */
+interface ArtifactCopyAsImageButtonProps {
+    /**
+     * Ref to the DOM node to capture as an image. Typically the artifact card root. The capture
+     * walks the subtree and includes everything except elements marked with
+     * `data-clay-capture-exclude` (the action toolbar should carry that marker so it doesn't
+     * capture itself).
+     */
+    targetRef: RefObject<HTMLElement | null>;
+    /**
+     * Tooltip text + `aria-label` for the idle state. Defaults to `"Copy Image"`. Per-type
+     * artifact orchestrators pass a translated value via their own `labels` prop so the button
+     * reads in the user's language. The transient working / success / error tooltips remain
+     * English-hardcoded — they flash for ~1.5s and the cost of translating them is rarely worth it.
+     */
+    label?: string;
+    /** Disable the button (e.g. while artifact data is still loading and the captured image would
+     * be empty / partial). */
+    disabled?: boolean;
+    /**
+     * Optional callback fired on click — runs alongside the copy attempt itself. Used for analytics
+     * / observability hooks; per-type artifact orchestrators wire this from their `callbacks` prop.
+     * Fires regardless of whether the copy ultimately succeeds (the result is reported via the
+     * button's own state flash).
+     */
+    onClick?: () => void;
+}
+
+/**
+ * Reusable "copy artifact as image" button for artifact headers. Drop it inside
+ * `<ArtifactActions>` alongside `ArtifactDownloadButton`.
+ *
+ * Captures the DOM node referenced by `targetRef`, rasterises it to PNG, and writes the result
+ * to the system clipboard. Must be invoked from a user gesture (the button click is enough).
+ *
+ * The button flashes a check icon on success and an alert icon on failure, reverting to its
+ * idle photo icon after ~1.5s. While capturing, it disables itself and shows a spinner.
+ *
+ * On failure, the rejection is logged via `console.warn` so production errors are visible in
+ * observability tooling (any consumer wiring a global console transport — Sentry, Datadog,
+ * Logfire — picks them up). The user-visible affordance is the error-state flash + tooltip.
+ */
+declare function ArtifactCopyAsImageButton({ targetRef, label, disabled, onClick, }: ArtifactCopyAsImageButtonProps): ReactNode;
+
+/**
+ * Per-format props for the CSV menu item. Pass within `actions.csv` to expose the item;
+ * omit the slot entirely to hide it. The item is also auto-hidden if `href` doesn't satisfy
+ * the `http(s):` safety guard — mirrors `ArtifactDownloadButton`'s defense against
+ * `javascript:` / `data:` URIs smuggled into a presigned URL field.
+ */
+interface ArtifactDownloadMenuCsvAction {
+    /** Presigned URL backing the CSV download. The browser uses whatever filename the server
+     *  supplies via `Content-Disposition`. */
+    href: string;
+    /** Label for the menu item. Defaults to `"Download CSV"`. */
+    label?: string;
+    /** Optional analytics callback. Fires alongside the browser-native download navigation. */
+    onSelect?: () => void;
+}
+/**
+ * Per-format props for the PNG menu item. Pass within `actions.png` to expose the item; omit
+ * the slot entirely to hide it. PNG capture rasterises `targetRef.current` via
+ * `@shapesos/clay/capture`'s `downloadNodeAsPng`.
+ */
+interface ArtifactDownloadMenuPngAction {
+    /** Ref to the DOM node to rasterise. Typically the artifact card root. The capture walks the
+     *  subtree and excludes anything marked with `data-clay-capture-exclude`. */
+    targetRef: RefObject<HTMLElement | null>;
+    /** Suggested filename for the saved file (without extension — the menu appends `.png`).
+     *  Defaults to `"artifact"`. Pass artifact-title-derived names for recognisable downloads. */
+    filename?: string;
+    /** Label for the menu item. Defaults to `"Download PNG"`. */
+    label?: string;
+    /** Disable the menu item (e.g. while artifact data is still loading). Default: `false`. */
+    disabled?: boolean;
+    /** Optional analytics callback. Fires alongside the rasterise + download — regardless of
+     *  whether the download ultimately succeeds. */
+    onSelect?: () => void;
+}
+/** Props for `ArtifactDownloadMenu`. */
+interface ArtifactDownloadMenuProps {
+    /**
+     * Format-keyed bag of action descriptors. Each entry exposes one menu item; omit the slot
+     * to hide it. Grouping per-format props this way (rather than spreading flat
+     * `csvHref` / `pngFilename` / `pngLabel` props at the top level) keeps the consumer's call
+     * site readable as more formats land — a future `actions.svg` or `actions.xlsx` follows the
+     * same shape without growing the prop list at the call site.
+     *
+     * Caller responsibility: include at least one action. An empty `{}` renders a menu with no
+     * items, which has no UX value — orchestrators should gate the entire `<ArtifactDownloadMenu>`
+     * mount on "at least one format reachable" before passing this prop.
+     *
+     * **Future generalisation** — if more action shapes land (SVG, XLSX, share-link, …), consider
+     * lifting these into a shared `ArtifactAction` discriminated union that both this menu and
+     * a future `<ArtifactActions>` toolbar can render generically. Postponed until a second
+     * non-Download action type appears — premature abstraction with two flavours.
+     */
+    actions: {
+        /** CSV download via presigned URL. Browser-native navigation; consumer i18n + analytics. */
+        csv?: ArtifactDownloadMenuCsvAction;
+        /** PNG download via DOM-to-image rasterise. Browser-only (capture entry). */
+        png?: ArtifactDownloadMenuPngAction;
+    };
+    /** Tooltip + `aria-label` for the trigger button. Defaults to `"Download"`. */
+    triggerLabel?: string;
+}
+
+/**
+ * Reusable "Download" affordance for artifact headers. Renders as a single icon-button trigger;
+ * clicking it opens a menu with one item per format the caller passes via `actions`. Today's
+ * formats: CSV (presigned URL) + PNG (DOM-to-image rasterise). Future formats (SVG, XLSX, …)
+ * slot into the same `actions` bag without touching the call-site prop list.
+ *
+ * Drop this inside `<ArtifactActions>` in any per-type artifact orchestrator that supports
+ * multiple download formats. For single-format artifacts (e.g. a future table artifact that
+ * only ships CSV), prefer the simpler `ArtifactDownloadButton` instead.
+ *
+ * The menu uses Radix's `DropdownMenu` primitive (vendored in `src/components/ui/dropdown-menu.tsx`)
+ * with `asChild` on the trigger so clay's `IconButton` is the real button — preserves the
+ * design-system look across all action affordances.
+ */
+declare function ArtifactDownloadMenu({ actions, triggerLabel, }: ArtifactDownloadMenuProps): ReactNode;
+
 /**
  * Orchestrator for the `table`-typed artifact.
  *
@@ -80,10 +203,15 @@ declare function TableArtifact({ artifact, labels, callbacks }: ArtifactServiceP
  * Variant dispatch lives inside `ChartArtifactContent` so the orchestrator can focus on the
  * data lifecycle and the chrome.
  *
- * Labels for action buttons (download, future copy-as-PNG) are pulled from the optional `labels`
+ * Labels for action buttons (download, copy-as-image) are pulled from the optional `labels`
  * prop with per-key fallback to `DEFAULT_CHART_ARTIFACT_LABELS`. Consumers translate via their
  * own i18n layer and pass the bag; non-i18n consumers omit it and get English defaults.
+ *
+ * `ArtifactCopyAsImageButton` snapshots the card root to PNG. The ref attaches directly to the
+ * `<Artifact>` primitive (which forwards refs as of this PR), so the captured DOM contains the
+ * artifact chrome exactly — no extra wrapper div, no layout-contract drift. The action toolbar
+ * carries `data-clay-capture-exclude` so its own buttons don't end up in the captured image.
  */
 declare function ChartArtifact({ artifact, labels, callbacks }: ArtifactServiceProps<ChartArtifactRecord>): ReactNode;
 
-export { ArtifactDownloadButton, type ArtifactDownloadButtonProps, ArtifactRecord, ArtifactService, ArtifactServiceProps, ArtifactServices, ArtifactType, ChartArtifact, ChartArtifactRecord, TableArtifact, TableArtifactRecord, artifactToClipboardText, isSafeDownloadUrl };
+export { ArtifactCopyAsImageButton, type ArtifactCopyAsImageButtonProps, ArtifactDownloadButton, type ArtifactDownloadButtonProps, ArtifactDownloadMenu, type ArtifactDownloadMenuCsvAction, type ArtifactDownloadMenuPngAction, type ArtifactDownloadMenuProps, ArtifactRecord, ArtifactService, ArtifactServiceProps, ArtifactServices, ArtifactType, ChartArtifact, ChartArtifactRecord, TableArtifact, TableArtifactRecord, artifactToClipboardText, isSafeDownloadUrl };

package/dist/artifacts.d.ts

@@ -1,6 +1,6 @@
-import { e as ArtifactType, c as ArtifactService, b as ArtifactRecord, d as ArtifactServiceProps, j as TableArtifactRecord, f as ChartArtifactRecord } from './types-C5bFH4v3.js';
-export { A as ArtifactDataRow, a as ArtifactLabelsMap, B as BarChartConfig, C as ChartArtifactLabels, g as ChartConfig, h as ChartStats, D as DEFAULT_CHART_ARTIFACT_LABELS, i as DEFAULT_TABLE_ARTIFACT_LABELS, L as LineChartConfig, P as PieChartConfig, T as TableArtifactLabels, k as TableColumn, l as TableConfig, m as TableRow, n as TableStats, o as artifactTypes } from './types-C5bFH4v3.js';
-import { ReactNode } from 'react';
+import { f as ArtifactType, d as ArtifactService, c as ArtifactRecord, e as ArtifactServiceProps, k as TableArtifactRecord, g as ChartArtifactRecord } from './types-GCkXbyFm.js';
+export { A as ArtifactCallbacksOf, a as ArtifactDataRow, b as ArtifactLabelsOf, B as BarChartConfig, C as ChartArtifactLabels, h as ChartConfig, i as ChartStats, D as DEFAULT_CHART_ARTIFACT_LABELS, j as DEFAULT_TABLE_ARTIFACT_LABELS, L as LineChartConfig, P as PieChartConfig, T as TableArtifactLabels, l as TableColumn, m as TableConfig, n as TableRow, o as TableStats, p as artifactTypes } from './types-GCkXbyFm.js';
+import { ReactNode, RefObject } from 'react';
 export { C as ChartSeries, a as ChartVariant } from './types-B2aYk82c.js';
 
 /**
@@ -57,6 +57,129 @@ declare function ArtifactDownloadButton({ href, label, onClick, }: ArtifactDownl
  */
 declare function isSafeDownloadUrl(url: string): boolean;
 
+/** Props for `ArtifactCopyAsImageButton`. */
+interface ArtifactCopyAsImageButtonProps {
+    /**
+     * Ref to the DOM node to capture as an image. Typically the artifact card root. The capture
+     * walks the subtree and includes everything except elements marked with
+     * `data-clay-capture-exclude` (the action toolbar should carry that marker so it doesn't
+     * capture itself).
+     */
+    targetRef: RefObject<HTMLElement | null>;
+    /**
+     * Tooltip text + `aria-label` for the idle state. Defaults to `"Copy Image"`. Per-type
+     * artifact orchestrators pass a translated value via their own `labels` prop so the button
+     * reads in the user's language. The transient working / success / error tooltips remain
+     * English-hardcoded — they flash for ~1.5s and the cost of translating them is rarely worth it.
+     */
+    label?: string;
+    /** Disable the button (e.g. while artifact data is still loading and the captured image would
+     * be empty / partial). */
+    disabled?: boolean;
+    /**
+     * Optional callback fired on click — runs alongside the copy attempt itself. Used for analytics
+     * / observability hooks; per-type artifact orchestrators wire this from their `callbacks` prop.
+     * Fires regardless of whether the copy ultimately succeeds (the result is reported via the
+     * button's own state flash).
+     */
+    onClick?: () => void;
+}
+
+/**
+ * Reusable "copy artifact as image" button for artifact headers. Drop it inside
+ * `<ArtifactActions>` alongside `ArtifactDownloadButton`.
+ *
+ * Captures the DOM node referenced by `targetRef`, rasterises it to PNG, and writes the result
+ * to the system clipboard. Must be invoked from a user gesture (the button click is enough).
+ *
+ * The button flashes a check icon on success and an alert icon on failure, reverting to its
+ * idle photo icon after ~1.5s. While capturing, it disables itself and shows a spinner.
+ *
+ * On failure, the rejection is logged via `console.warn` so production errors are visible in
+ * observability tooling (any consumer wiring a global console transport — Sentry, Datadog,
+ * Logfire — picks them up). The user-visible affordance is the error-state flash + tooltip.
+ */
+declare function ArtifactCopyAsImageButton({ targetRef, label, disabled, onClick, }: ArtifactCopyAsImageButtonProps): ReactNode;
+
+/**
+ * Per-format props for the CSV menu item. Pass within `actions.csv` to expose the item;
+ * omit the slot entirely to hide it. The item is also auto-hidden if `href` doesn't satisfy
+ * the `http(s):` safety guard — mirrors `ArtifactDownloadButton`'s defense against
+ * `javascript:` / `data:` URIs smuggled into a presigned URL field.
+ */
+interface ArtifactDownloadMenuCsvAction {
+    /** Presigned URL backing the CSV download. The browser uses whatever filename the server
+     *  supplies via `Content-Disposition`. */
+    href: string;
+    /** Label for the menu item. Defaults to `"Download CSV"`. */
+    label?: string;
+    /** Optional analytics callback. Fires alongside the browser-native download navigation. */
+    onSelect?: () => void;
+}
+/**
+ * Per-format props for the PNG menu item. Pass within `actions.png` to expose the item; omit
+ * the slot entirely to hide it. PNG capture rasterises `targetRef.current` via
+ * `@shapesos/clay/capture`'s `downloadNodeAsPng`.
+ */
+interface ArtifactDownloadMenuPngAction {
+    /** Ref to the DOM node to rasterise. Typically the artifact card root. The capture walks the
+     *  subtree and excludes anything marked with `data-clay-capture-exclude`. */
+    targetRef: RefObject<HTMLElement | null>;
+    /** Suggested filename for the saved file (without extension — the menu appends `.png`).
+     *  Defaults to `"artifact"`. Pass artifact-title-derived names for recognisable downloads. */
+    filename?: string;
+    /** Label for the menu item. Defaults to `"Download PNG"`. */
+    label?: string;
+    /** Disable the menu item (e.g. while artifact data is still loading). Default: `false`. */
+    disabled?: boolean;
+    /** Optional analytics callback. Fires alongside the rasterise + download — regardless of
+     *  whether the download ultimately succeeds. */
+    onSelect?: () => void;
+}
+/** Props for `ArtifactDownloadMenu`. */
+interface ArtifactDownloadMenuProps {
+    /**
+     * Format-keyed bag of action descriptors. Each entry exposes one menu item; omit the slot
+     * to hide it. Grouping per-format props this way (rather than spreading flat
+     * `csvHref` / `pngFilename` / `pngLabel` props at the top level) keeps the consumer's call
+     * site readable as more formats land — a future `actions.svg` or `actions.xlsx` follows the
+     * same shape without growing the prop list at the call site.
+     *
+     * Caller responsibility: include at least one action. An empty `{}` renders a menu with no
+     * items, which has no UX value — orchestrators should gate the entire `<ArtifactDownloadMenu>`
+     * mount on "at least one format reachable" before passing this prop.
+     *
+     * **Future generalisation** — if more action shapes land (SVG, XLSX, share-link, …), consider
+     * lifting these into a shared `ArtifactAction` discriminated union that both this menu and
+     * a future `<ArtifactActions>` toolbar can render generically. Postponed until a second
+     * non-Download action type appears — premature abstraction with two flavours.
+     */
+    actions: {
+        /** CSV download via presigned URL. Browser-native navigation; consumer i18n + analytics. */
+        csv?: ArtifactDownloadMenuCsvAction;
+        /** PNG download via DOM-to-image rasterise. Browser-only (capture entry). */
+        png?: ArtifactDownloadMenuPngAction;
+    };
+    /** Tooltip + `aria-label` for the trigger button. Defaults to `"Download"`. */
+    triggerLabel?: string;
+}
+
+/**
+ * Reusable "Download" affordance for artifact headers. Renders as a single icon-button trigger;
+ * clicking it opens a menu with one item per format the caller passes via `actions`. Today's
+ * formats: CSV (presigned URL) + PNG (DOM-to-image rasterise). Future formats (SVG, XLSX, …)
+ * slot into the same `actions` bag without touching the call-site prop list.
+ *
+ * Drop this inside `<ArtifactActions>` in any per-type artifact orchestrator that supports
+ * multiple download formats. For single-format artifacts (e.g. a future table artifact that
+ * only ships CSV), prefer the simpler `ArtifactDownloadButton` instead.
+ *
+ * The menu uses Radix's `DropdownMenu` primitive (vendored in `src/components/ui/dropdown-menu.tsx`)
+ * with `asChild` on the trigger so clay's `IconButton` is the real button — preserves the
+ * design-system look across all action affordances.
+ */
+declare function ArtifactDownloadMenu({ actions, triggerLabel, }: ArtifactDownloadMenuProps): ReactNode;
+
 /**
  * Orchestrator for the `table`-typed artifact.
  *
@@ -80,10 +203,15 @@ declare function TableArtifact({ artifact, labels, callbacks }: ArtifactServiceP
  * Variant dispatch lives inside `ChartArtifactContent` so the orchestrator can focus on the
  * data lifecycle and the chrome.
  *
- * Labels for action buttons (download, future copy-as-PNG) are pulled from the optional `labels`
+ * Labels for action buttons (download, copy-as-image) are pulled from the optional `labels`
  * prop with per-key fallback to `DEFAULT_CHART_ARTIFACT_LABELS`. Consumers translate via their
  * own i18n layer and pass the bag; non-i18n consumers omit it and get English defaults.
+ *
+ * `ArtifactCopyAsImageButton` snapshots the card root to PNG. The ref attaches directly to the
+ * `<Artifact>` primitive (which forwards refs as of this PR), so the captured DOM contains the
+ * artifact chrome exactly — no extra wrapper div, no layout-contract drift. The action toolbar
+ * carries `data-clay-capture-exclude` so its own buttons don't end up in the captured image.
  */
 declare function ChartArtifact({ artifact, labels, callbacks }: ArtifactServiceProps<ChartArtifactRecord>): ReactNode;
 
-export { ArtifactDownloadButton, type ArtifactDownloadButtonProps, ArtifactRecord, ArtifactService, ArtifactServiceProps, ArtifactServices, ArtifactType, ChartArtifact, ChartArtifactRecord, TableArtifact, TableArtifactRecord, artifactToClipboardText, isSafeDownloadUrl };
+export { ArtifactCopyAsImageButton, type ArtifactCopyAsImageButtonProps, ArtifactDownloadButton, type ArtifactDownloadButtonProps, ArtifactDownloadMenu, type ArtifactDownloadMenuCsvAction, type ArtifactDownloadMenuPngAction, type ArtifactDownloadMenuProps, ArtifactRecord, ArtifactService, ArtifactServiceProps, ArtifactServices, ArtifactType, ChartArtifact, ChartArtifactRecord, TableArtifact, TableArtifactRecord, artifactToClipboardText, isSafeDownloadUrl };

package/dist/artifacts.js

@@ -1,6 +1,8 @@
-import "./chunk-AQEJRMRN.js";
+import "./chunk-RSRNSWJN.js";
 import {
+  ArtifactCopyAsImageButton,
   ArtifactDownloadButton,
+  ArtifactDownloadMenu,
   ArtifactServices,
   ChartArtifact,
   DEFAULT_CHART_ARTIFACT_LABELS,
@@ -9,7 +11,8 @@ import {
   artifactToClipboardText,
   artifactTypes,
   isSafeDownloadUrl
-} from "./chunk-Z5JWF24N.js";
+} from "./chunk-DT44KNCV.js";
+import "./chunk-LXYCT4YO.js";
 import "./chunk-QXGYMDIA.js";
 import "./chunk-C77QMQNT.js";
 import "./chunk-SV24ONND.js";
@@ -20,7 +23,9 @@ import "./chunk-OLJIJYB5.js";
 import "./chunk-JF3P66JF.js";
 import "./chunk-5WRI5ZAA.js";
 export {
+  ArtifactCopyAsImageButton,
   ArtifactDownloadButton,
+  ArtifactDownloadMenu,
   ArtifactServices,
   ChartArtifact,
   DEFAULT_CHART_ARTIFACT_LABELS,