@shapesos/clay 0.9.0 → 0.10.0

package/README.md

@@ -32,6 +32,7 @@ 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/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 |
@@ -122,11 +123,55 @@ type MessageRole = "user" | "assistant";
 interface ChatMessage {
   id: string;
   role: MessageRole;
-  content: string;            // Markdown supported
+  blocks: BlockData[];        // ordered, type-discriminated content blocks (defined by @shapesos/clay/blocks)
+  fallbackText: string;       // server-supplied plain-text version of the blocks; used for clipboard/accessibility
   isHelpful?: boolean | null;
 }
 ```
 
+`BlockData`, `BlockType`, and `TextBlockData` live in [`@shapesos/clay/blocks`](#blocks). Chat doesn't own block rendering — it composes the `Block` component from the blocks package and bridges chat-specific concerns (like passing the message's `id` into `TableActions` callbacks). This means the same block infrastructure renders chat messages, vibe-view embeds, marketing-site responses, or any other surface that wants typed content blocks — without coupling to chat.
+
+</details>
+
+---
+
+## Blocks
+
+Typed content-block infrastructure: a `Block` dispatcher, a `BlockServices` registry of concrete renderers (currently `TextBlockService`), and a `BlockContext` for renderer-level concerns like table actions. Chat consumes this internally — non-chat surfaces import directly.
+
+```tsx
+import { Block, BlockContext, type BlockData } from "@shapesos/clay/blocks";
+
+const blocks: BlockData[] = [{ type: "TEXT", payload: { text: "**hello world**" } }];
+
+function MyContent() {
+  return (
+    <BlockContext.Provider value={{ TableActions: ({ tableIndex }) => <ExportButton index={tableIndex} /> }}>
+      {blocks.map((block, i) => <Block key={i} block={block} />)}
+    </BlockContext.Provider>
+  );
+}
+```
+
+The wire shape (`{ type, payload }`) matches `dreamteam-io-server` / `shapes-agent` 1:1, so blocks fetched from the API can be passed straight to `Block` with no translation. Unknown block types render as no-ops (forward-compat). Adding a new block type is a registration in `BlockServices` plus a concrete component — no changes to the dispatcher.
+
+<details>
+<summary><strong>Public API</strong></summary>
+
+| Export                | Kind      | Description                                                                                  |
+| --------------------- | --------- | -------------------------------------------------------------------------------------------- |
+| `Block`               | Component | Single-block dispatcher. Looks up the concrete renderer in `BlockServices` by `block.type`.  |
+| `BlockContext`        | Context   | Renderer-level concerns (today: `TableActions`). Optional — `Block` works without it.        |
+| `useBlockContext`     | Hook      | Reads the ambient `BlockContextValue`. Returns `{}` outside a provider.                      |
+| `BlockServices`       | Registry  | `{ TEXT: TextBlockService }` today; additive over time.                                      |
+| `TextBlockService`    | Service   | Concrete renderer entry for `TEXT` blocks.                                                   |
+| `BlockData`           | Type      | Discriminated union of all block shapes.                                                     |
+| `TextBlockData`       | Type      | `{ type: "TEXT"; payload: { text: string } }`.                                               |
+| `BlockType`           | Type      | `"TEXT"` (literal union; widens as new types are added).                                     |
+| `BlockComponentProps` | Type      | Props every concrete block component receives — `{ block }`.                                 |
+| `BlockService`        | Type      | Service registry entry contract — `{ type, Component }`.                                     |
+| `BlockContextValue`   | Type      | `{ TableActions?: ComponentType<{ tableIndex: number }> }`.                                  |
+
 </details>
 
 ---