@object-ui/plugin-chatbot 17.6.0 → 18.0.0

package/README.md

@@ -21,11 +21,17 @@ npm install @object-ui/plugin-chatbot
 
 ### Basic (Local/Demo Mode)
 
+`ChatbotEnhancedMessage` is this package's runtime message contract, and `role` on it is
+the closed union `'user' | 'assistant' | 'system'`. Annotate the state with it:
+an unannotated array literal widens `role` to `string`, which `<Chatbot>` then
+refuses.
+
 ```tsx
-import { Chatbot } from '@object-ui/plugin-chatbot';
+import { useState } from 'react';
+import { Chatbot, type ChatbotEnhancedMessage } from '@object-ui/plugin-chatbot';
 
 function App() {
-  const [messages, setMessages] = useState([
+  const [messages, setMessages] = useState<ChatbotEnhancedMessage[]>([
     {
       id: '1',
       role: 'assistant',
@@ -34,7 +40,7 @@ function App() {
   ]);
 
   const handleSend = (content: string) => {
-    const newMessage = {
+    const newMessage: ChatbotEnhancedMessage = {
       id: Date.now().toString(),
       role: 'user',
       content
@@ -114,7 +120,7 @@ function MyChat() {
 
 `messages` — and the `onSend(content, messages)` callback fed from it — is
 typed `ObjectChatMessage[]`, exported from this package. It is deliberately
-neither of the two `ChatMessage` types nearby, because neither is true of both
+neither of the two message contracts nearby, because neither is true of both
 modes (objectui#4424):
 
 - **Not `@object-ui/types`' authoring `ChatMessage`.** In API mode the values
@@ -124,15 +130,20 @@ modes (objectui#4424):
   card, the "Review N changes" affordance, the plan card, the build panel and
   the inline charts. The authoring contract declares none of them, so rebuilding
   a message field-by-field from it deletes all of them, and the compiler agrees.
-- **Not this package's runtime `ChatMessage` either.** In local mode an authored
+  API mode also produces the AI SDK's three approval states
+  (`'approval-requested'` / `'approval-responded'` / `'output-denied'`), which
+  the authoring contract refuses — they are runtime-only (objectui#10018).
+- **Not this package's runtime `ChatbotEnhancedMessage` either.** In local mode an authored
   `'tool'` role and the legacy `'partial-call'` / `'call'` / `'result'` tool
   states pass through untouched; they are folded only at the render seam
   (`toRuntimeMessages`, `chatMessageAdapter.ts`).
 
-`ObjectChatMessage` is a subtype of the authoring `ChatMessage`, so anything
-already typed against that keeps compiling — naming `ObjectChatMessage` is what
-lets you *read* the keys above. `timestamp` is always a `string` here: both
-modes absorb an authored `Date` before emitting.
+`ObjectChatMessage` is **not** a subtype of the authoring `ChatMessage`
+(objectui#10018): its tool invocations can carry those three runtime-only
+approval states. So an `onSend` callback that declares its parameter as the
+authoring `ChatMessage[]` does not type-check — declare `ObjectChatMessage[]`,
+which is also what lets you *read* the keys above. `timestamp` is always a
+`string` here: both modes absorb an authored `Date` before emitting.
 
 ## Schema-Driven Usage
 
@@ -191,6 +202,14 @@ safe side gutters, stays above the mobile bottom navigation area, and hides the
 FAB while open so the close button in the panel header is the only active
 dismiss control.
 
+A host that wants to signal a waiting approval outside the chat can pass
+`ChatbotEnhanced` the optional `onPlanApprovalPendingChange` callback. It is
+called with `true` while the thread's newest proposed plan still offers
+"Build it", and with `false` otherwise: no plan, the user approved it, or its
+build ran. It fires once on mount and again on every change. The console uses
+it to put a marker on its chat launchers while the chat is closed
+(objectui#11666).
+
 During a conversation, the chat surface renders an inline assistant responding
 indicator while the backend is streaming, keeps message actions quiet until
 hover/focus, and summarizes backend failures into a compact retryable notice
@@ -280,9 +299,9 @@ import { AIElements } from '@object-ui/plugin-chatbot';
 </AIElements.Conversation>;
 ```
 
-### The `ChatMessage` type
+### The `ChatbotEnhancedMessage` type
 
-`ChatMessage` is this package's one message contract — the shape
+`ChatbotEnhancedMessage` is this package's one message contract — the shape
 `<ChatbotEnhanced>` renders and the mappers below produce. On top of the core
 `id` / `role` / `content` / `timestamp` / `avatar` / `avatarFallback` fields it
 carries the streaming and agent-process keys (`streaming`, `toolInvocations`,
@@ -290,21 +309,24 @@ carries the streaming and agent-process keys (`streaming`, `toolInvocations`,
 `charts`), all optional.
 
 ```tsx
-import type { ChatMessage } from '@object-ui/plugin-chatbot';
+import type { ChatbotEnhancedMessage } from '@object-ui/plugin-chatbot';
 ```
 
-> This barrel used to export **two** different `ChatMessage` types: a minimal
-> one declared here, plus the enhanced shape aliased as
-> `ChatbotEnhancedMessage`. Reaching for the natural name got you the narrow
-> contract with no compiler complaint (objectui#4383). The minimal shape is
-> retired; `ChatbotEnhancedMessage` is now a **deprecated alias of the same
-> type**, kept only so existing importers keep compiling.
+Its tool invocations are `ChatbotEnhancedToolInvocation`, also exported here.
+
+`ChatMessage` is **not** exported from this package. That name belongs to
+`@object-ui/types`, where it is the **JSON/SDUI schema** type
+(`ChatbotSchema['messages']`, `role` includes `'tool'`, `timestamp` may be a
+`Date`) — the authoring contract, not the React runtime one. Import the schema
+type from `@object-ui/types` and the runtime type from this package.
 
-Note that `@object-ui/types` also exports a `ChatMessage`. That one is the
-**JSON/SDUI schema** type (`ChatbotSchema['messages']`, `role` includes
-`'tool'`, `timestamp` may be a `Date`) — the authoring contract, not the React
-runtime one. Import the schema type from `@object-ui/types` and the runtime
-type from this package.
+> Migrating: this package used to publish the runtime shape as `ChatMessage`
+> too, with `ChatbotEnhancedMessage` a deprecated alias of it (objectui#4383).
+> One name for two contracts across the two packages let an auto-import pick
+> the wrong one, so the runtime name is now `ChatbotEnhancedMessage` alone
+> (objectui#6349). Replace `import { type ChatMessage } from
+> '@object-ui/plugin-chatbot'` with `ChatbotEnhancedMessage` — the shape is
+> unchanged.
 
 ### Authoring → runtime: `toRuntimeMessages`
 
@@ -326,7 +348,7 @@ function MyAuthoredChat({ messages }: { messages: AuthoredChatMessage[] }) {
 |---|---|---|---|
 | `role` | `'user' \| 'assistant' \| 'system' \| 'tool'` | `'user' \| 'assistant' \| 'system'` | a `'tool'` message **is an assistant message**: it renders as an assistant bubble with its content shown. `'system'` keeps its own role (`<Chatbot>` renders it as a centred pill). |
 | `timestamp` | `string \| Date` | `string` | a `Date` becomes its ISO 8601 string. The runtime renders the timestamp straight into a React child, where an object throws. |
-| `toolInvocations[].state` | AI SDK v6 states **+ legacy** `'partial-call' \| 'call' \| 'result'` | v6 states only | the legacy spellings map to `'input-streaming'` / `'input-available'` / `'output-available'` — the mapping the authoring type's own docs declare. |
+| `toolInvocations[].state` | AI SDK v6 states **except** the three approval states, **+ legacy** `'partial-call' \| 'call' \| 'result'` | v6 states only | the legacy spellings map to `'input-streaming'` / `'input-available'` / `'output-available'` — the mapping the authoring type's own docs declare. `'approval-requested'` / `'approval-responded'` / `'output-denied'` are runtime-only and not authorable (objectui#10018); the adapter's input still admits them, because API-mode values carry them. |
 | everything else | — | — | passed through untouched, including keys the runtime contract does not declare. |
 
 The three registered SDUI renderers (`chatbot`, `chatbot-enhanced`,
@@ -346,18 +368,24 @@ of writing your own — they handle `parts: [{ type: 'text' | 'reasoning'
 
 ```tsx
 import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
 import {
   ChatbotEnhanced,
   uiMessagesToChatMessages,
+  type ChatbotEnhancedProps,
 } from '@object-ui/plugin-chatbot';
 
+declare const handleSend: ChatbotEnhancedProps['onSendMessage'];
+
 function MyChat() {
-  const { messages, status } = useChat({ api: '/api/chat' });
+  const { messages, status } = useChat({
+    transport: new DefaultChatTransport({ api: '/api/chat' }),
+  });
   const isStreaming = status === 'streaming' || status === 'submitted';
   return (
     <ChatbotEnhanced
       messages={uiMessagesToChatMessages(messages, { isStreaming })}
-      onSend={/* … */}
+      onSendMessage={handleSend}
     />
   );
 }
@@ -375,11 +403,35 @@ chat routes can use `surface="plain"` to remove the outer panel border and let
 messages, controls, and the prompt input sit in a continuous workspace:
 
 ```tsx
+import { ChatbotEnhanced, type ChatbotEnhancedMessage } from '@object-ui/plugin-chatbot';
+
+declare const messages: ChatbotEnhancedMessage[];
+
 <ChatbotEnhanced
   messages={messages}
   surface="plain"
   hideClearBar
-/>
+/>;
+```
+
+A host can add its own row to the prompt area with `promptHeaderSlot`. The row
+is laid out in flow directly above the prompt input (and outside its form), so
+the conversation gives up the room and the row never covers the input or the
+last message. Content that renders nothing takes no space. Use it for standing
+affordances such as an "unpublished changes" bar; `promptOverlaySlot` stays the
+absolute-positioned overlay for slash-command palettes.
+
+```tsx
+import { ChatbotEnhanced, type ChatbotEnhancedMessage } from '@object-ui/plugin-chatbot';
+
+declare const messages: ChatbotEnhancedMessage[];
+declare const pendingChanges: number;
+
+<ChatbotEnhanced
+  messages={messages}
+  surface="plain"
+  promptHeaderSlot={pendingChanges > 0 ? <div>{pendingChanges} changes are not published yet</div> : null}
+/>;
 ```
 
 ### Agent process visibility
@@ -394,10 +446,14 @@ Use `processVisibility="debug"` for developer or admin trace surfaces that need
 the full reasoning panel, raw tool names, tool parameters, and tool results:
 
 ```tsx
+import { ChatbotEnhanced, type ChatbotEnhancedMessage } from '@object-ui/plugin-chatbot';
+
+declare const messages: ChatbotEnhancedMessage[];
+
 <ChatbotEnhanced
   messages={messages}
   processVisibility="debug"
-/>
+/>;
 ```
 
 Use `processVisibility="hidden"` when a host wants to suppress non-interactive

package/dist/AiPendingActionsInbox.d.ts

@@ -38,9 +38,15 @@ export interface AiPendingActionsInboxProps {
     conversationId?: string;
     /** Visual style. `card` (default) wraps in a Card; `bare` renders without. */
     variant?: 'card' | 'bare';
-    /** Optional title shown in the card header. */
+    /**
+     * Optional title shown in the card header. Defaults to the locale pack's
+     * `aiApprovals.title` — a lookup, so it cannot be a default parameter value.
+     */
     title?: string;
-    /** Optional description shown in the card header. */
+    /**
+     * Optional description shown in the card header. Defaults to the locale
+     * pack's `aiApprovals.description`; pass `''` to hide it.
+     */
     description?: string;
     /** Class name applied to the outer wrapper. */
     className?: string;

package/dist/AiPendingActionsInbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AiPendingActionsInbox.d.ts","sourceRoot":"","sources":["../src/AiPendingActionsInbox.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAoD/B,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAyDD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,OAAO,EACP,OAAO,EACP,YAAmB,EACnB,cAAc,EACd,OAAgB,EAChB,KAAsB,EACtB,WAAuF,EACvF,SAAS,GACV,EAAE,0BAA0B,qBAmW5B"}
+{"version":3,"file":"AiPendingActionsInbox.d.ts","sourceRoot":"","sources":["../src/AiPendingActionsInbox.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AA0D/B,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAuGD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,OAAO,EACP,OAAO,EACP,YAAmB,EACnB,cAAc,EACd,OAAgB,EAChB,KAAK,EACL,WAAW,EACX,SAAS,GACV,EAAE,0BAA0B,qBA2Y5B"}