@k8ordo/ui 1.0.0 → 2.1.0

package/docs/references/ai-chat.md

@@ -1,67 +1,68 @@
-# k8ordo UI AI チャットコンポーネント
+# @k8ordo/ui AI chat components
 
-AI チャット UI（会話ログ・メッセージ・入力欄・推論表示・ツール実行表示）を構築するコンポーネント群。ルートではなく専用サブパスからインポートする。
+Components for building an AI chat UI: the conversation log, messages and their actions, the input box with attachments, reasoning display, tool-invocation display with approval, attachments, and sources. Import them from their dedicated subpaths rather than from the root.
 
-## インポート方法
+## Importing
 
 ```tsx
-// 基本コンポーネント（追加の依存なし）
+// Core components (no extra dependencies)
 import {
+  Attachment,
   Conversation,
   Message,
   PromptInput,
   Reasoning,
+  Source,
   Suggestion,
   ToolInvocation,
 } from '@k8ordo/ui/ai';
-
-// ストリーミング対応 Markdown 描画（optional peer: streamdown）
-import { Response } from '@k8ordo/ui/ai/response';
-
-// AI SDK 連携（optional peer: ai）
+// AI SDK integration (optional peer: ai)
 import { mapMessageParts } from '@k8ordo/ui/ai-sdk';
+// Streaming-aware Markdown rendering (optional peer: streamdown)
+import { Response } from '@k8ordo/ui/ai/response';
 ```
 
-型も `@k8ordo/ui/ai` から export される：
+The types are exported from `@k8ordo/ui/ai` too:
 
-- `ChatStatus`: `'ready' | 'submitted' | 'streaming' | 'error'`（AI SDK の `status` と互換）
-- `ToolState`: `'input-streaming' | 'input-available' | 'approval-requested' | 'approval-responded' | 'output-available' | 'output-error' | 'output-denied'`（AI SDK v7 のツール状態と 1:1）
+- `ChatStatus`: `'ready' | 'submitted' | 'streaming' | 'error'` (compatible with the AI SDK's `status`)
+- `ToolState`: `'input-streaming' | 'input-available' | 'approval-requested' | 'approval-responded' | 'output-available' | 'output-error' | 'output-denied'` (1:1 with the AI SDK v7 tool states)
+- `ToolApproval`: `{ id: string; approved?: boolean; reason?: string; requestReason?: string; isAutomatic?: boolean }` (the shape of the AI SDK's `part.approval`, so the part's own object can be passed as is)
+- `ToolApprovalResponse`: `{ id: string; approved: boolean }` (what `ToolInvocation` answers with)
+- `MessageFeedback`: `'positive' | 'negative'`
 
-### optional peer のセットアップ
+### Setting up the optional peers
 
-使うサブパスの分だけインストールする。`@k8ordo/ui/ai` 本体はどちらも不要。
+Install only what the subpaths you use require. `@k8ordo/ui/ai` itself needs neither.
 
 ```bash
-# @k8ordo/ui/ai/response（Response）を使う場合
+# If you use @k8ordo/ui/ai/response (Response)
 pnpm add streamdown
-# @k8ordo/ui/ai-sdk（mapMessageParts）を使う場合
+# If you use @k8ordo/ui/ai-sdk (mapMessageParts)
 pnpm add ai
 ```
 
-`Response` を使う場合は streamdown のスタイルシートの読み込みと、Tailwind の `@source` 設定も必要。streamdown のスタイルはビルド済み `styles.css` には含まれないため、`Response` だけは Tailwind CSS 4 のビルド（`@k8ordo/ui/tailwind.css` エントリ）が前提になる：
+`Response` styles what streamdown renders itself, through the
+`data-streamdown` attribute streamdown puts on every element, so it needs no
+Tailwind. Load streamdown's own stylesheet only when you turn on its `animated`
+option, which keeps its keyframes there:
 
 ```tsx
 import 'streamdown/styles.css';
 ```
 
-```css
-/* アプリの CSS エントリに追加（パスは CSS ファイルから node_modules への相対） */
-@source '../node_modules/streamdown/dist/*.js';
-```
-
-なお本リファレンスの例で使う `useChat` は AI SDK の React バインディング（`pnpm add @ai-sdk/react`）から import する。
+The `useChat` used in the examples below comes from the AI SDK's React bindings (`pnpm add @ai-sdk/react`).
 
-以下に出てくる `label` / `sendLabel` などの「デフォルト」は文言辞書の既定値（日本語）。`<UIProvider messages={en}>` で辞書ごと切り替えられる（[i18n](components.md)）。個別の prop を渡した場合はそちらが辞書より優先される。
+The "default" shown for `label`, `sendLabel`, and similar props below is the built-in Japanese dictionary's. The text actually used follows `@k8ordo/i18n`'s current locale (see [i18n](components.md)). Passing the prop directly wins over the dictionary.
 
-## 全体像
+## The whole picture
 
-`Conversation`（会話ログ）+ `Message`（吹き出し）+ `PromptInput`（入力欄）が骨組み。`Response` / `Reasoning` / `ToolInvocation` は後から足せる。
+`Conversation` (the log), `Message` (a bubble), and `PromptInput` (the input box) form the skeleton. `Response`, `Reasoning`, `ToolInvocation`, `Attachment`, `Source`, and the message actions can be added later — [AI SDK integration](#ai-sdk-integration-mapmessageparts) shows all of them together.
 
 ```tsx
 'use client';
+import { useChat } from '@ai-sdk/react';
 import { Avatar, AssistantIcon } from '@k8ordo/ui';
 import { Conversation, Message, PromptInput } from '@k8ordo/ui/ai';
-import { useChat } from '@ai-sdk/react';
 import type { UIMessage } from 'ai';
 
 const textOf = (m: UIMessage) =>
@@ -71,22 +72,31 @@ export function Chat() {
   const { messages, sendMessage, status, stop } = useChat();
 
   return (
-    <div className="flex h-full flex-col gap-3">
+    <div
+      style={{
+        display: 'flex',
+        height: '100%',
+        flexDirection: 'column',
+        gap: 'calc(var(--spacing) * 3)',
+      }}
+    >
       <Conversation.Root>
         <Conversation.Messages isStreaming={status === 'streaming'}>
           {messages.map((m) => (
             <Message.Root
+              avatar={
+                m.role === 'user' ? undefined : (
+                  <Avatar
+                    color="primary"
+                    icon={<AssistantIcon />}
+                    name="AI"
+                    size="sm"
+                  />
+                )
+              }
               from={m.role === 'user' ? 'user' : 'assistant'}
               key={m.id}
             >
-              {m.role !== 'user' && (
-                <Avatar
-                  color="primary"
-                  icon={<AssistantIcon />}
-                  name="AI"
-                  size="sm"
-                />
-              )}
               <Message.Content>{textOf(m)}</Message.Content>
             </Message.Root>
           ))}
@@ -99,7 +109,7 @@ export function Chat() {
         onSubmit={(text) => sendMessage({ text })}
         status={status}
       >
-        <PromptInput.Textarea placeholder="メッセージを入力" />
+        <PromptInput.Textarea placeholder="Type a message" />
         <PromptInput.Submit />
       </PromptInput.Root>
     </div>
@@ -109,7 +119,7 @@ export function Chat() {
 
 ## Conversation
 
-会話ログのスクロール領域。Compound component パターン。最下部に張り付き、新しいメッセージで自動スクロールする。最下部から離れると `ScrollButton` が現れる。
+The scrolling region for the conversation log, as a compound component. It sticks to the bottom and auto-scrolls on a new message. Once you scroll away from the bottom, a `ScrollButton` appears.
 
 ```tsx
 import { Conversation } from '@k8ordo/ui/ai';
@@ -124,40 +134,94 @@ import { Conversation } from '@k8ordo/ui/ai';
 
 Props (Conversation.Messages):
 
-- `label`: string（デフォルト: `'チャット'`、aria-label として使用）
-- `isStreaming`: boolean（`aria-busy` に反映）
+- `label`: string (default: `'チャット'`, used as the aria-label)
+- `isStreaming`: boolean (reflected in `aria-busy`)
 
 Props (Conversation.ScrollButton):
 
-- `label`: string（デフォルト: `'最新のメッセージへ移動'`）
+- `label`: string (default: `'最新のメッセージへ移動'`)
 
 ## Message
 
-メッセージ 1 件。`from="user"` は右寄せの吹き出し、`from="assistant"` は地の文として描画される。アバターなどは `Message.Root` の子として自由に並べられる。
+A single message. `from="user"` renders as a right-aligned bubble; `from="assistant"` renders as running text. `avatar` sits beside the message, and the children stack in a column next to it — attachments, the content, sources, and the actions each get their own row.
 
 ```tsx
 import { Message } from '@k8ordo/ui/ai';
 
 <Message.Root from="user">
-  <Message.Content>こんにちは</Message.Content>
+  <Message.Content>Hello</Message.Content>
 </Message.Root>
 
-<Message.Root from="assistant">
-  <Message.Content isStreaming>生成中の本文…</Message.Content>
+<Message.Root avatar={<Avatar icon={<AssistantIcon />} name="AI" size="sm" />} from="assistant">
+  <Message.Content isStreaming>Text still streaming…</Message.Content>
 </Message.Root>
 ```
 
 Props (Message.Root):
 
-- `from`: `'user'` | `'assistant'`（必須）
+- `from`: `'user'` | `'assistant'` (required)
+- `avatar`: ReactNode (shown beside the message: left for the assistant, right for the user)
+- plus the other `div` attributes (`className` and `style` excluded)
 
 Props (Message.Content):
 
-- `isStreaming`: boolean（true でストリーミングカーソルを表示）
+- `isStreaming`: boolean (shows the streaming cursor when true)
+- plus the other `div` attributes (`className` and `style` excluded)
+
+### Message actions
+
+`Message.Actions` is the row of icon buttons under a message. `Copy`, `Regenerate`, and `Feedback` carry their own icons and dictionary labels; `Action` is the generic one for anything else. Each shows its label as a tooltip.
+
+```tsx
+<Message.Root avatar={avatar} from="assistant">
+  <Message.Content>{text}</Message.Content>
+  <Message.Actions>
+    <Message.Copy value={text} />
+    <Message.Regenerate
+      disabled={status === 'submitted' || status === 'streaming'}
+      onAction={() => regenerate({ messageId: message.id })}
+    />
+    <Message.Feedback onChange={(value) => saveFeedback(message.id, value)} />
+    <Message.Action label="Share" onAction={() => share(message.id)}>
+      <LinkIcon size="sm" />
+    </Message.Action>
+  </Message.Actions>
+</Message.Root>
+```
+
+- `Copy` is an icon-only, `sm` [`CopyButton`](components.md#copybutton): it writes `value` to the clipboard, shows a check icon — or an error icon when the clipboard refuses — for two seconds, and announces 「コピーしました」 or 「コピーできませんでした」 through a `status` region. Nothing is thrown either way.
+- `Regenerate` and `Action` take `onAction`; a returned promise keeps the button busy (`aria-busy`, `aria-disabled`, presses ignored) until it settles, so `() => regenerate(...)` does not need its own pending state. The button keeps focus meanwhile.
+- `Feedback` is a pair of toggle buttons (`aria-pressed`). Pressing the pressed one again clears it, so `onChange` receives `null`.
+
+Props (Message.Actions):
+
+- `label`: string (default: `'メッセージの操作'`, used as the group's aria-label)
+
+Props (Message.Action):
+
+- `label`: string (required; the accessible name and the tooltip)
+- `onAction`: `() => void | Promise<void>`
+- `disabled`: boolean
+- `children`: ReactNode (the icon, `size="sm"`)
+
+Props (Message.Copy):
+
+- `value`: string (required; the text to copy)
+- `label`: string (default: `'コピー'`)
+
+Props (Message.Regenerate):
+
+- `onAction`: `() => void | Promise<void>` (required)
+- `label`: string (default: `'再生成'`)
+- `disabled`: boolean
+
+Props (Message.Feedback):
+
+- `value` / `defaultValue` / `onChange`: `MessageFeedback | null`, controlled or uncontrolled (`onChange` is `(value: MessageFeedback | null) => void`; `null` is no feedback)
 
 ## PromptInput
 
-送信フォーム。Enter で送信、Shift+Enter で改行。IME 変換確定の Enter では送信しない。`status` が `'submitted'` / `'streaming'` の間は `Submit` が停止ボタンに切り替わる。本文は trim され、空文字は送信されない。
+The submit form. Enter sends; Shift+Enter inserts a newline; the Enter that commits an IME conversion does not send. While `status` is `'submitted'` or `'streaming'`, `Submit` turns into a stop button. The body is trimmed, and a message with neither text nor attachments is never sent.
 
 ```tsx
 import { PromptInput } from '@k8ordo/ui/ai';
@@ -167,30 +231,121 @@ import { PromptInput } from '@k8ordo/ui/ai';
   onSubmit={(message) => send(message)}
   onStop={stop}
 >
-  <PromptInput.Textarea placeholder="メッセージを入力" />
+  <PromptInput.Textarea placeholder="Type a message" />
   <PromptInput.Submit />
 </PromptInput.Root>;
 ```
 
+### Attachments
+
+Pass `accept` to take files. It turns on all three ways in — the `Attach` button's file picker, dropping files onto the input, and pasting them into the textarea — and filters every one of them by the same rule as `<input accept>` (the browser applies it only to the picker). A dropped folder is skipped, as on `FileField.Dropzone`. Without `accept` the input takes text only: `Attach` renders nothing, a pasted file is not taken, and a file dragged over the input shows the not-allowed cursor — the drop is still cancelled, so the browser never opens the file and leaves the chat.
+
+`PromptInput.Attachments` lists the files waiting to be sent, image thumbnails included, each with a remove button. `onSubmit` receives them as a `FileList` in its second argument, which the AI SDK's `sendMessage` takes as is. The list empties after each submit, and a message with attachments but no text can be sent — pass `{ files }` alone then, since `sendMessage` turns `text: ''` into an empty text part that some providers reject.
+
+```tsx
+<PromptInput.Root
+  accept="image/*,application/pdf"
+  maxFiles={4}
+  onStop={stop}
+  onSubmit={(text, files) =>
+    sendMessage(text === '' ? { files } : { text, files })
+  }
+  status={status}
+>
+  <PromptInput.Attachments />
+  <PromptInput.Attach />
+  <PromptInput.Textarea placeholder="Type a message" />
+  <PromptInput.Submit />
+</PromptInput.Root>
+```
+
+Put `Attachments` first: it takes a row of its own above the textarea. Choose `accept` from what your model reads — the AI SDK turns `image/*` and `text/*` into model input by itself, and other types need handling on your server.
+
 Props (PromptInput.Root):
 
-- `status`: ChatStatus（デフォルト: `'ready'`）
-- `value` / `defaultValue` / `onChange`: controlled / uncontrolled 両対応（`onChange` は `(value: string) => void`）
-- `onSubmit`: `(message: string) => void`（trim 済みの本文）
-- `onStop`: `() => void`（送信中に停止ボタンを押したとき）
+- `status`: ChatStatus (default: `'ready'`)
+- `value` / `defaultValue` / `onChange`: supports both controlled and uncontrolled use (`onChange` is `(value: string) => void`)
+- `onSubmit`: `(message: string, files: FileList) => void` (the trimmed body, and the attachments — an empty `FileList` when there are none)
+- `onStop`: `() => void` (when the stop button is pressed mid-send)
+- `accept`: string (the file types to take, in `<input accept>` syntax; omit to take no files)
+- `maxFiles`: number (files beyond it are dropped, first come first kept; `1` also makes the picker single-select)
+
+Props (PromptInput.Attachments):
+
+- `label`: string (default: `'添付ファイル'`, used as the list's aria-label)
+
+Props (PromptInput.Attach):
+
+- `label`: string (default: `'ファイルを添付'`)
 
 Props (PromptInput.Textarea):
 
-- `placeholder`: string ほか textarea 属性
+- `placeholder`: string, plus the other textarea attributes
 
 Props (PromptInput.Submit):
 
-- `sendLabel`: string（デフォルト: `'送信'`）
-- `stopLabel`: string（デフォルト: `'停止'`）
+- `sendLabel`: string (default: `'送信'`)
+- `stopLabel`: string (default: `'停止'`)
+
+## Attachment
+
+Files attached to a sent message. An image (`image/*`, or the bare `image` the AI SDK allows) shows as a thumbnail with `filename` as its alt text; anything else shows as a chip with its name and media type.
+
+```tsx
+import { Attachment } from '@k8ordo/ui/ai';
+
+<Message.Root from="user">
+  <Attachment.List>
+    {files.map((file) => (
+      <Attachment.Item
+        filename={file.filename}
+        key={file.url}
+        mediaType={file.mediaType}
+        url={file.url}
+      />
+    ))}
+  </Attachment.List>
+  <Message.Content>{text}</Message.Content>
+</Message.Root>;
+```
+
+Props (Attachment.List):
+
+- `label`: string (default: `'添付ファイル'`, used as the list's aria-label)
+
+Props (Attachment.Item):
+
+- `url`: string (required; a hosted URL or a data URL)
+- `mediaType`: string (required)
+- `filename`: string (without it an image's alt text is 「添付画像」 and a file chip shows the media type)
+
+An image `url` is loaded as soon as the item renders, with no click in between. Pass URLs your own server produced or vouches for — a data URL, or your storage — rather than an arbitrary URL a model or tool wrote, which could point anywhere (a tracking pixel, an internal address). The AI SDK already turns files a provider generates into data URLs.
+
+## Source
+
+The sources a response cites. An item with an `http(s)` `href` is a link that opens in a new tab, labelled by `title` or else the host name; anything else — a document source, or a URL with another scheme — is plain text. The URL comes from the model, so a `javascript:` URL never becomes a link.
+
+```tsx
+import { Source } from '@k8ordo/ui/ai';
+
+<Source.List>
+  <Source.Item href="https://ordo.k8o.me/ui/ai/chat" title="AI chat" />
+  <Source.Item title="Internal design doc v3" />
+</Source.List>;
+```
+
+Props (Source.List):
+
+- `label`: string (default: `'出典'`, used as the list's aria-label)
+
+Props (Source.Item):
+
+- `href`: string (the source's URL)
+- `title`: string (the source's title; falls back to the host name)
 
 ## Reasoning
 
-推論（思考過程）の折りたたみ表示。ストリーミング中はラベルが「思考中…」になる。
+A collapsible view of the model's reasoning. While streaming, the label reads 「思考中…」.
 
 ```tsx
 import { Reasoning } from '@k8ordo/ui/ai';
@@ -201,15 +356,14 @@ import { Reasoning } from '@k8ordo/ui/ai';
 Props:
 
 - `isStreaming`: boolean
-- `isOpen` / `defaultOpen` / `onChange`: 開閉の controlled / uncontrolled 両対応（`onChange` は `(isOpen: boolean) => void`）
+- `isOpen` / `defaultOpen` / `onChange`: open state, controlled or uncontrolled (`onChange` is `(isOpen: boolean) => void`)
 
 ## Response
 
-ストリーミング対応の Markdown レンダラ。未クローズのコードブロックなど途中の Markdown も破綻なく描画する。optional peer の `streamdown` が必要（[セットアップ](#optional-peer-のセットアップ)参照）。
+A streaming-aware Markdown renderer. It renders half-finished Markdown — an unclosed code block, say — without breaking. Requires the optional peer `streamdown` (see [setup](#setting-up-the-optional-peers)).
 
 ```tsx
 import { Response } from '@k8ordo/ui/ai/response';
-import 'streamdown/styles.css';
 
 <Message.Content>
   <Response isStreaming={isStreaming}>{markdown}</Response>
@@ -218,47 +372,47 @@ import 'streamdown/styles.css';
 
 Props:
 
-- `children`: string（Markdown 文字列、必須）
+- `children`: string (the Markdown, required)
 - `isStreaming`: boolean
-- 上記以外の streamdown の props（`translations` / `controls` / `linkSafety` / `plugins` / `components` / `urlTransform` / `dir` など）はそのまま透過する。`className` と `mode` はライブラリが握る（`mode` は `isStreaming` から決まる）
+- Every other streamdown prop (`translations`, `controls`, `linkSafety`, `plugins`, `components`, `urlTransform`, `dir`, …) passes straight through. The library owns `className`, `mode` (`mode` is derived from `isStreaming`) and `portal`: the confirmation dialog and a table's full screen open inside the `Response`, where its styles reach them
 
-文言は i18n 辞書から引くので、既定では「コードをコピー」「表をダウンロード」などが日本語で出る。個別に変えたいときは `translations` を渡す（prop > 辞書 > streamdown 既定）。
+The wording comes from the i18n dictionary of the current locale, so strings such as `responseCopyCode` and `responseDownloadTable` follow the rest of the components. Pass `translations` to change individual strings (prop > dictionary > streamdown's own default).
 
-`linkSafety` はライブラリ側で**無効を既定にしている**。streamdown の既定（有効）ではリンクが `<a>` ではなく `<button>` で描画され、⌘クリック・中クリック・リンクアドレスのコピー・支援技術の link ロールが失われるため。確認ダイアログを挟みたい場合は明示的に有効化する:
+The library **defaults `linkSafety` to off**. With streamdown's own default (on), links render as `<button>` rather than `<a>`, which loses ⌘-click, middle-click, copying the link address, and the link role for assistive technology. Turn it on explicitly if you want the confirmation dialog:
 
 ```tsx
 <Response linkSafety={{ enabled: true }}>{markdown}</Response>
 ```
 
-なお `javascript:` のような危険なスキームは `linkSafety` とは無関係に rehype-harden が無効化するので、既定のままでも生きたリンクにはならない。
+Dangerous schemes such as `javascript:` are neutralized by rehype-harden regardless of `linkSafety`, so they never become live links even with the default.
 
 ## Suggestion
 
-候補プロンプトのチップ表示。クリックで `onSelect` に `value` が渡る。
+Suggested prompts shown as chips. Clicking one passes its `value` to `onSelect`.
 
 ```tsx
 import { Suggestion } from '@k8ordo/ui/ai';
 
 <Suggestion.List>
-  <Suggestion.Item onSelect={send} value="IME 対応について教えて" />
+  <Suggestion.Item onSelect={send} value="Tell me about IME support" />
   <Suggestion.Item onSelect={send} value="streaming">
-    ストリーミング表示は？
+    How does streaming display work?
   </Suggestion.Item>
 </Suggestion.List>;
 ```
 
 Props (Suggestion.List):
 
-- `label`: string（デフォルト: `'候補'`、aria-label として使用）
+- `label`: string (default: `'候補'`, used as the aria-label)
 
 Props (Suggestion.Item):
 
-- `value`: string（必須。children 省略時は表示テキストも兼ねる）
+- `value`: string (required; also serves as the visible text when children is omitted)
 - `onSelect`: `(value: string) => void`
 
 ## ToolInvocation
 
-ツール呼び出しの折りたたみ表示。`state` に応じてスピナー / 成功 / エラー / 拒否のアイコンが切り替わる（承認待ち・承認応答・入力中は進行中としてスピナー）。
+A collapsible view of a tool call. The icon switches between spinner, success, error, and denied according to `state` (approval responded and input streaming count as in-progress and show the spinner).
 
 ```tsx
 import { ToolInvocation } from '@k8ordo/ui/ai';
@@ -267,23 +421,45 @@ import { ToolInvocation } from '@k8ordo/ui/ai';
   name="search_web"
   state="output-available"
   input={{ query: 'k8ordo UI' }}
-  output="検索結果…"
+  output="Search results…"
 />;
 ```
 
+### Approval
+
+When `state` is `'approval-requested'`, the tool is waiting for the user. Pass the part's `approval` and an `onApprovalResponse`, and a question with Deny / Allow buttons appears below the header — outside the collapsible panel, so it is visible without expanding the call; the input stays one click away in the panel. Pressing one calls `onApprovalResponse({ id: approval.id, approved })`, which is exactly what the AI SDK's `addToolApprovalResponse` takes. Until a returned promise settles, both buttons are `aria-disabled` and ignore presses; they are not natively `disabled`, so the pressed one keeps focus while the answer is sent. Once the state moves on, the question disappears; if it held focus, focus moves to the tool's header instead of falling to `body`.
+
+```tsx
+<ToolInvocation
+  name={part.name}
+  state={part.state}
+  input={part.input}
+  approval={part.approval}
+  onApprovalResponse={addToolApprovalResponse}
+/>
+```
+
+- The question is `approval.requestReason` when the server gave one, 「このツールの実行を許可しますか？」 otherwise.
+- An automatic decision (`approval.isAutomatic`) shows no question and no buttons; there is nothing for the user to answer.
+- Without `onApprovalResponse`, the question shows but the buttons do not.
+- In `'output-denied'`, the panel explains the denial with `approval.reason`, falling back to the default wording.
+
+With the AI SDK, send the answer back automatically with `sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses` on `useChat`; otherwise nothing happens after the user answers.
+
 Props:
 
-- `name`: string（必須、ツール名）
-- `state`: ToolState（必須）
-- `input`: unknown（文字列以外は JSON 表示）
-- `output`: ReactNode（文字列は `pre` 表示、要素はそのまま描画）
-- `errorText`: string（`state="output-error"` 時の表示。省略時は既定文言）
-- `deniedReason`: string（`state="output-denied"` 時の表示。省略時は既定文言）
-- `isOpen` / `defaultOpen` / `onChange`: 開閉の controlled / uncontrolled 両対応
+- `name`: string (required, the tool name)
+- `state`: ToolState (required)
+- `input`: unknown (anything other than a string is shown as JSON)
+- `output`: ReactNode (a string is shown in a `pre`; an element renders as-is)
+- `errorText`: string (shown when `state="output-error"`; falls back to the default wording)
+- `approval`: ToolApproval (the approval being asked for or answered; its `reason` explains an `output-denied` call)
+- `onApprovalResponse`: `(response: ToolApprovalResponse) => void | PromiseLike<void>` (called with the approval `id` and the user's answer)
+- `isOpen` / `defaultOpen` / `onChange`: open state, controlled or uncontrolled
 
-## AI SDK 連携（mapMessageParts）
+## AI SDK integration (mapMessageParts)
 
-`@k8ordo/ui/ai-sdk` の `mapMessageParts` は、AI SDK の `UIMessage.parts` を描画しやすい `MappedPart[]` に変換する。React 非依存で、optional peer の `ai`（v7）が必要。
+`mapMessageParts` from `@k8ordo/ui/ai-sdk` converts the AI SDK's `UIMessage.parts` into a `MappedPart[]` that is easy to render. It has no React dependency and requires the optional peer `ai` (v7).
 
 ```ts
 type MappedPart =
@@ -297,49 +473,156 @@ type MappedPart =
       input?: unknown;
       output?: unknown;
       errorText?: string;
-      deniedReason?: string;
-    };
+      approval?: ToolApproval; // the part's own approval object, id included
+    }
+  | { kind: 'file'; url: string; mediaType: string; filename?: string }
+  | {
+      kind: 'source'; // both source-url and source-document
+      id: string;
+      url?: string; // source-url only
+      title?: string;
+      mediaType?: string; // source-document only
+      filename?: string; // source-document only
+    }
+  | { kind: 'data'; name: string; id?: string; data: unknown }; // `data-weather` → name 'weather'
 ```
 
-利用側が `kind` で分岐して `Response` / `Reasoning` / `ToolInvocation` を描画する：
+Order is preserved. `step-start`, `custom`, and `reasoning-file` parts are skipped.
+
+Render each part as its own row under `Message.Root` — the children stack in a column. Files and sources read better as one list each, so pull them out with `filter` and skip them in the loop. A `data` part is yours: pick the ones you know by `name`, and validate what the model put in them before drawing it.
 
 ```tsx
+'use client';
+import { useChat } from '@ai-sdk/react';
+import { Avatar, AssistantIcon } from '@k8ordo/ui';
+import {
+  Attachment,
+  Message,
+  Reasoning,
+  Source,
+  ToolInvocation,
+} from '@k8ordo/ui/ai';
 import { mapMessageParts } from '@k8ordo/ui/ai-sdk';
-import { Reasoning, ToolInvocation } from '@k8ordo/ui/ai';
 import { Response } from '@k8ordo/ui/ai/response';
+import { validateGeneratedSpec } from '@k8ordo/ui/json-render';
+import { JsonRenderUI } from '@k8ordo/ui/json-render/registry';
+import { lastAssistantMessageIsCompleteWithApprovalResponses } from 'ai';
+import type { UIMessage } from 'ai';
 
-<Message.Content>
-  {mapMessageParts(message).map((part, i) => {
-    if (part.kind === 'reasoning')
-      return <Reasoning key={i}>{part.text}</Reasoning>;
-    if (part.kind === 'tool') {
-      // output は unknown なので、ReactNode に変換してから渡す
-      return (
-        <ToolInvocation
-          key={part.toolCallId}
-          name={part.name}
-          state={part.state}
-          input={part.input}
-          output={
-            typeof part.output === 'string'
-              ? part.output
-              : JSON.stringify(part.output, null, 2)
-          }
-          errorText={part.errorText}
-          deniedReason={part.deniedReason}
-        />
-      );
-    }
-    return <Response key={i}>{part.text}</Response>;
-  })}
-</Message.Content>;
+type Chat = ReturnType<typeof useChat>;
+
+function ChatMessage({ message, chat }: { message: UIMessage; chat: Chat }) {
+  const parts = mapMessageParts(message);
+  const files = parts.filter((part) => part.kind === 'file');
+  const sources = parts.filter((part) => part.kind === 'source');
+  const text = parts
+    .map((part) => (part.kind === 'text' ? part.text : ''))
+    .join('');
+  const isUser = message.role === 'user';
+
+  return (
+    <Message.Root
+      avatar={
+        isUser ? undefined : (
+          <Avatar icon={<AssistantIcon />} name="AI" size="sm" />
+        )
+      }
+      from={isUser ? 'user' : 'assistant'}
+    >
+      {files.length > 0 && (
+        <Attachment.List>
+          {files.map((file) => (
+            <Attachment.Item
+              filename={file.filename}
+              key={file.url}
+              mediaType={file.mediaType}
+              url={file.url}
+            />
+          ))}
+        </Attachment.List>
+      )}
+      {parts.map((part, i) => {
+        const key = `${message.id}-${i}`;
+        if (part.kind === 'text') {
+          return (
+            <Message.Content key={key}>
+              <Response>{part.text}</Response>
+            </Message.Content>
+          );
+        }
+        if (part.kind === 'reasoning') {
+          return <Reasoning key={key}>{part.text}</Reasoning>;
+        }
+        if (part.kind === 'tool') {
+          return (
+            <ToolInvocation
+              approval={part.approval}
+              errorText={part.errorText}
+              input={part.input}
+              key={part.toolCallId}
+              name={part.name}
+              onApprovalResponse={chat.addToolApprovalResponse}
+              // output is unknown, so convert it to a ReactNode first
+              output={
+                part.output === undefined
+                  ? undefined
+                  : JSON.stringify(part.output, null, 2)
+              }
+              state={part.state}
+            />
+          );
+        }
+        if (part.kind === 'data' && part.name === 'ui') {
+          const result = validateGeneratedSpec(part.data);
+          return result.ok ? (
+            <JsonRenderUI key={key} spec={result.spec} />
+          ) : null;
+        }
+        return null;
+      })}
+      {sources.length > 0 && (
+        <Source.List>
+          {sources.map((source) => (
+            <Source.Item
+              href={source.url}
+              key={source.id}
+              title={source.title}
+            />
+          ))}
+        </Source.List>
+      )}
+      {!isUser && text !== '' && (
+        <Message.Actions>
+          <Message.Copy value={text} />
+          <Message.Regenerate
+            disabled={
+              chat.status === 'submitted' || chat.status === 'streaming'
+            }
+            onAction={() => chat.regenerate({ messageId: message.id })}
+          />
+          <Message.Feedback />
+        </Message.Actions>
+      )}
+    </Message.Root>
+  );
+}
+
+export function Chat() {
+  const chat = useChat({
+    // sends the answers back as soon as every pending approval has one
+    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
+  });
+  // … Conversation.Root / chat.messages.map((message) => <ChatMessage … />) / PromptInput
+}
 ```
 
-`ChatStatus` / `ToolState` 型は `@k8ordo/ui/ai-sdk` からも re-export される。
+`examples/ui-integrations` in the repository runs this against the real `useChat`, with a scripted transport in place of a model.
+
+`@k8ordo/ui/ai-sdk` exports the `MappedPart` type, and re-exports the `ChatStatus`, `ToolState`, `ToolApproval`, and `ToolApprovalResponse` types as well.
 
-## 生成 UI との組み合わせ
+## Combining with generative UI
 
-LLM がツール結果として返した UI spec を、チャットの吹き出し内で描画できる。詳細は [生成 UI リファレンス](generative-ui.md) を参照。
+A UI spec returned by an LLM as a tool result can be rendered inside a chat bubble. See the [generative UI reference](generative-ui.md) for details.
 
 ```tsx
 'use client';