@shapesos/clay 0.11.0 → 0.12.0

package/README.md

@@ -33,6 +33,8 @@ Clay is tree-shakeable with multiple entry points — import only what you need.
 | `@shapesos/clay/tokens`   | Colors, typography, font families     | None (pure JS)           |
 | `@shapesos/clay/chat`     | Chat compound components + types      | React, styled-components |
 | `@shapesos/clay/blocks`   | Typed content blocks (Block, BlockServices, BlockContext) | React, styled-components |
+| `@shapesos/clay/artifacts`| Per-type artifact renderers + ArtifactServices map (TABLE, CHART) | React, styled-components, recharts (optional, only for CHART) |
+| `@shapesos/clay/chart`    | Standalone chart library (`<BarChart>`, `<LineChart>`, `<PieChart>` + composable primitives) | React, recharts |
 | `@shapesos/clay/icon`     | Icon, IconButton components + types   | React, styled-components |
 | `@shapesos/clay/lottie`   | Lottie animation component + types    | React, styled-components |
 | `@shapesos/clay`          | Everything (convenience re-export)    | React, styled-components |
@@ -176,6 +178,64 @@ The wire shape (`{ type, payload }`) matches `dreamteam-io-server` / `shapes-age
 
 ---
 
+## Artifacts
+
+Per-type renderers for the artifact union (`TABLE`, `CHART`) plus the `ArtifactServices` registry. The block layer's `ARTIFACT_REF` block consumes this map to dispatch the inlined artifact to its concrete component; non-block surfaces can render an artifact directly.
+
+```tsx
+import { TableArtifact, ChartArtifact, ArtifactServices } from "@shapesos/clay/artifacts";
+import type {
+  ArtifactCallbacksMap,
+  ArtifactLabelsMap,
+  ChartArtifactRecord,
+  TableArtifactRecord,
+} from "@shapesos/clay/artifacts";
+
+// Direct render — picks the renderer at the call site.
+<ChartArtifact
+  artifact={chartRecord}
+  labels={{ CHART: { download: "Download CSV", /* … */ } }}
+  callbacks={{ CHART: { onDownload: (artifact) => analytics.track("chart_downloaded", artifact) } }}
+/>
+
+// Registry-driven dispatch — block layer does this.
+const { Component } = ArtifactServices[artifact.type];
+<Component artifact={artifact} labels={labels} callbacks={callbacks} />
+```
+
+Every artifact reads from a CSV at `artifact.protectedAsset.presignedUrl`. Loading / error / unavailable / empty states surface as inline status messages with consumer-translated copy from the `labels` prop (`Partial<ArtifactLabelsMap>`). Action callbacks (today: `onDownload`) wire through the `callbacks` prop (`Partial<ArtifactCallbacksMap>`) — each callback receives the artifact record so you can derive analytics context. Both props get passed through the block layer via `block.payload.labels` and `block.payload.callbacks`.
+
+The `CHART` artifact requires `recharts` as a peer dep; bring your own if you import this entry. Adding a new artifact type is one `ArtifactService` registration plus a concrete component — no changes to the block dispatcher.
+
+---
+
+## Chart
+
+Standalone chart library — usable beyond the artifact path. Three pre-composed high-level components with smart defaults, plus composable primitives for custom recharts trees.
+
+```tsx
+import { BarChart, LineChart, PieChart } from "@shapesos/clay/chart";
+
+<BarChart
+  data={[{ month: "Jan", us: 120, uk: 60 }, { month: "Feb", us: 132, uk: 64 }]}
+  xKey="month"
+  series={[{ key: "us", label: "US" }, { key: "uk", label: "UK" }]}
+  stacked
+/>
+
+<PieChart
+  data={departments}
+  categoryKey="department"
+  valueKey="headcount"
+  // Localise the "Others" bucket detection in non-English UIs:
+  othersCategoryLabels={["אחרים"]}
+/>
+```
+
+Smart defaults: legend auto-hides for single-series charts; legend at top; x-axis labels truncate by category count; pie's "Others" bucket pins to the end of the sweep in neutral grey. Override any default with the named prop. Bring `recharts` as a peer dep.
+
+---
+
 ## Icon
 
 Render SVG icons with consistent sizing, and icon buttons with selection states.