@mast-ai/react-ui 0.1.1 → 0.2.0

package/dist/components/AssistantMessage.d.ts

@@ -1,6 +1,14 @@
 import type { ReactNode } from 'react';
 import type { PendingApproval } from '../approval.js';
 import type { ConversationEntry, ToolEventEntry } from '../types.js';
+import { type GetToolLabel } from './ToolLabelContext.js';
+/**
+ * Slot for replacing only the inline approval card while keeping the default
+ * `<ToolCallBlock>` rendering for non-approval tool events. Receives the
+ * matching {@link ToolEventEntry} and the live {@link PendingApproval} handle
+ * exposing `approve()`, `reject()`, and `respondWith()`.
+ */
+export type RenderApproval = (entry: ToolEventEntry, approval: PendingApproval) => ReactNode;
 /**
  * Props accepted by {@link AssistantMessage}.
  */
@@ -28,8 +36,38 @@ export interface AssistantMessageProps {
      * When this prop is omitted, the library defaults to rendering
      * `<InlineApproval>` for tool events with a pending approval handle and
      * `<ToolCallBlock>` otherwise.
+     *
+     * Takes a back seat to {@link AssistantMessageProps.renderApproval} when
+     * both are provided and the entry has a pending approval handle.
      */
     renderToolCall?: (entry: ToolEventEntry, approval?: PendingApproval) => ReactNode;
+    /**
+     * Replaces only the inline approval card. Called once per tool event whose
+     * call is awaiting an inline approval decision (i.e. has a matching
+     * {@link PendingApproval} handle); non-approval tool events fall through to
+     * `renderToolCall` or the default `<ToolCallBlock>`.
+     *
+     * Use this slot to customise the approval prompt without rebuilding the
+     * tool-call rendering for every other event. Takes precedence over
+     * `renderToolCall` for entries with a pending approval handle when both
+     * are provided.
+     */
+    renderApproval?: RenderApproval;
+    /**
+     * Resolves the header label for each {@link ToolEventEntry} rendered inside
+     * this message. Forwarded via context to every nested `<ToolCallBlock>`,
+     * including those rendered for sub-agent tool calls.
+     *
+     * Use this for the common case of relabelling delegation-style tools (e.g.
+     * `delegate_to_skill` showing the target skill's name) without needing to
+     * write a custom `renderToolCall` purely to override `entry.name`.
+     *
+     * Resolution order inside `<ToolCallBlock>`: explicit `label` prop, then this
+     * resolver, then `entry.name`. Returning `undefined` or `null` from the
+     * resolver lets the block fall back to `entry.name` for that specific entry,
+     * which is useful for selectively overriding only a subset of tool names.
+     */
+    getToolLabel?: GetToolLabel;
 }
 /**
  * Renders an assistant turn: an optional {@link ThinkingBlock}, zero or more
@@ -41,4 +79,4 @@ export interface AssistantMessageProps {
  * `renderMessage` (the entire text region) or `renderToolCall` (each tool
  * invocation) without losing the surrounding wiring.
  */
-export declare function AssistantMessage({ entry, className, renderMessage, renderToolCall, }: AssistantMessageProps): import("react/jsx-runtime").JSX.Element;
+export declare function AssistantMessage({ entry, className, renderMessage, renderToolCall, renderApproval, getToolLabel, }: AssistantMessageProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/ConversationPanel.d.ts

@@ -2,6 +2,8 @@ import type { ReactNode } from 'react';
 import type { PendingApproval } from '../approval.js';
 import type { MentionsConfig } from '../mentions/types.js';
 import type { ToolEventEntry } from '../types.js';
+import type { RenderApproval } from './AssistantMessage.js';
+import type { GetToolLabel } from './ToolLabelContext.js';
 /**
  * Props accepted by {@link ConversationPanel}.
  */
@@ -20,8 +22,25 @@ export interface ConversationPanelProps {
      * awaiting an inline approval decision.
      */
     renderToolCall?: (entry: ToolEventEntry, approval?: PendingApproval) => ReactNode;
+    /**
+     * Replaces only the inline approval card. Use this slot to customise the
+     * approval prompt without rebuilding the rest of the tool-call rendering.
+     * Takes precedence over `renderToolCall` for entries with a pending
+     * approval handle when both are provided.
+     */
+    renderApproval?: RenderApproval;
     /** Replaces the default assistant text renderer for the entire list. */
     renderMessage?: (text: string) => ReactNode;
+    /**
+     * Overrides the `<ToolCallBlock>` header label for the entire list. The
+     * resolver flows via context so it also applies to nested sub-agent tool
+     * calls. Returning `undefined` or `null` for a given entry falls back to
+     * `entry.name`.
+     *
+     * Common use case: relabelling delegation-style tools (e.g.
+     * `delegate_to_skill` showing the target skill's name).
+     */
+    getToolLabel?: GetToolLabel;
     /** Placeholder text for the {@link ChatInput} field. */
     inputPlaceholder?: string;
     /**
@@ -40,4 +59,4 @@ export interface ConversationPanelProps {
  *
  * Must be rendered inside an `<AgentProvider>`.
  */
-export declare function ConversationPanel({ theme, className, renderToolCall, renderMessage, inputPlaceholder, mentions, }: ConversationPanelProps): import("react/jsx-runtime").JSX.Element;
+export declare function ConversationPanel({ theme, className, renderToolCall, renderApproval, renderMessage, getToolLabel, inputPlaceholder, mentions, }: ConversationPanelProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/MessageItem.d.ts

@@ -1,6 +1,8 @@
 import type { ReactNode } from 'react';
 import type { PendingApproval } from '../approval.js';
 import type { ConversationEntry, ToolEventEntry } from '../types.js';
+import { type RenderApproval } from './AssistantMessage.js';
+import type { GetToolLabel } from './ToolLabelContext.js';
 /**
  * Props accepted by {@link MessageItem}.
  */
@@ -14,11 +16,21 @@ export interface MessageItemProps {
      * `'user'`.
      */
     renderToolCall?: (entry: ToolEventEntry, approval?: PendingApproval) => ReactNode;
+    /**
+     * Forwarded to {@link AssistantMessage}. Has no effect when `entry.role` is
+     * `'user'`.
+     */
+    renderApproval?: RenderApproval;
     /**
      * Forwarded to {@link AssistantMessage}. Has no effect when `entry.role` is
      * `'user'`.
      */
     renderMessage?: (text: string) => ReactNode;
+    /**
+     * Forwarded to {@link AssistantMessage}. Has no effect when `entry.role` is
+     * `'user'`.
+     */
+    getToolLabel?: GetToolLabel;
 }
 /**
  * Renders a single {@link ConversationEntry} by dispatching to
@@ -26,4 +38,4 @@ export interface MessageItemProps {
  *
  * Used by {@link MessageList} to render each virtualised row.
  */
-export declare function MessageItem({ entry, className, renderToolCall, renderMessage }: MessageItemProps): import("react/jsx-runtime").JSX.Element;
+export declare function MessageItem({ entry, className, renderToolCall, renderApproval, renderMessage, getToolLabel, }: MessageItemProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/MessageList.d.ts

@@ -1,6 +1,8 @@
 import type { ReactNode } from 'react';
 import type { PendingApproval } from '../approval.js';
 import type { ToolEventEntry } from '../types.js';
+import type { RenderApproval } from './AssistantMessage.js';
+import type { GetToolLabel } from './ToolLabelContext.js';
 /**
  * Props accepted by {@link MessageList}.
  */
@@ -14,11 +16,29 @@ export interface MessageListProps {
      * decision.
      */
     renderToolCall?: (entry: ToolEventEntry, approval?: PendingApproval) => ReactNode;
+    /**
+     * Forwarded to each {@link MessageItem} so consumers can replace only the
+     * inline approval card without overriding the rest of the tool-call
+     * rendering. Takes precedence over `renderToolCall` for entries with a
+     * pending approval handle when both are provided.
+     */
+    renderApproval?: RenderApproval;
     /**
      * Forwarded to each {@link MessageItem} so consumers can replace the default
      * assistant text renderer for the entire list.
      */
     renderMessage?: (text: string) => ReactNode;
+    /**
+     * Forwarded to each {@link MessageItem} so consumers can override the
+     * `<ToolCallBlock>` header label for the entire list. The resolver is read
+     * via context inside `<ToolCallBlock>`, so it also applies to nested
+     * sub-agent tool calls.
+     *
+     * Returning `undefined` or `null` for a given entry falls back to
+     * `entry.name`, which is useful for selectively overriding only a subset of
+     * tool names.
+     */
+    getToolLabel?: GetToolLabel;
 }
 /**
  * Scrollable list of {@link ConversationEntry} items rendered with
@@ -35,4 +55,4 @@ export interface MessageListProps {
  * Reads `messages` from `useAgent()`, so this component must be rendered
  * inside an `<AgentProvider>`.
  */
-export declare function MessageList({ className, renderToolCall, renderMessage }: MessageListProps): import("react/jsx-runtime").JSX.Element;
+export declare function MessageList({ className, renderToolCall, renderApproval, renderMessage, getToolLabel, }: MessageListProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/ToolCallBlock.d.ts

@@ -1,3 +1,4 @@
+import type { ReactNode } from 'react';
 import type { ToolEventEntry } from '../types.js';
 /**
  * Props accepted by {@link ToolCallBlock}.
@@ -7,5 +8,26 @@ export interface ToolCallBlockProps {
     entry: ToolEventEntry;
     /** Optional class added to the root element. */
     className?: string;
+    /**
+     * Controls whether the block body (sub-output, nested events, args, result)
+     * is open by default. The header (status icon + tool name) is always
+     * visible.
+     *
+     * - `'streaming'` (default): open while `entry.isStreaming` is `true`, then
+     *   collapses on completion.
+     * - `true`: open by default, regardless of streaming state.
+     * - `false`: closed by default, regardless of streaming state.
+     */
+    defaultOpen?: boolean | 'streaming';
+    /**
+     * Overrides `entry.name` in the header. Useful for delegation-style tools
+     * whose interesting label lives in the args (e.g. `delegate_to_skill` should
+     * display the target skill's name, not the wrapper tool's name).
+     *
+     * Takes precedence over the `getToolLabel` resolver supplied via
+     * `<AssistantMessage>` / `<MessageList>` / `<ConversationPanel>`. When
+     * omitted, falls back to the resolver, then to `entry.name`.
+     */
+    label?: ReactNode;
 }
-export declare function ToolCallBlock({ entry, className }: ToolCallBlockProps): import("react/jsx-runtime").JSX.Element;
+export declare function ToolCallBlock({ entry, className, defaultOpen, label, }: ToolCallBlockProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/ToolLabelContext.d.ts

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react';
+import type { ToolEventEntry } from '../types.js';
+/**
+ * Computes the header label for a {@link ToolEventEntry}. Returning `undefined`
+ * (or `null`) lets the consuming `<ToolCallBlock>` fall back to `entry.name`,
+ * which is useful for selectively overriding only a subset of tool names.
+ */
+export type GetToolLabel = (entry: ToolEventEntry) => ReactNode;
+/**
+ * Context written by `<AssistantMessage getToolLabel>` (and parents that
+ * forward the prop) and read by `<ToolCallBlock>` to resolve its header label.
+ *
+ * Resolution order inside `<ToolCallBlock>`:
+ *
+ * 1. The explicit `label` prop, if provided.
+ * 2. The value returned by this context's `getToolLabel`, if defined and the
+ *    return value is not `null`/`undefined`.
+ * 3. `entry.name`.
+ */
+export declare const ToolLabelContext: import("react").Context<GetToolLabel | undefined>;

package/dist/context.d.ts

@@ -7,8 +7,15 @@ import type { ConversationEntry, IconMap } from './types.js';
  * Props accepted by {@link AgentProvider}.
  */
 export interface AgentProviderProps {
-    /** The {@link AgentRunner} that will execute agent runs. */
-    runner: AgentRunner;
+    /**
+     * The {@link AgentRunner} that will execute agent runs. Pass `null` for the
+     * "agent not yet configured" state (e.g. before the user has supplied an
+     * API key, signed in, or selected a provider): the provider mounts cleanly,
+     * `useAgent()` returns disabled-state defaults, and `<ChatInput>` greys out
+     * automatically. Switching from `null` to a real runner does not require
+     * remounting; the conversation starts fresh on the next `sendMessage`.
+     */
+    runner: AgentRunner | null;
     /** The agent configuration used for every turn. */
     agent: AgentConfig;
     /** The subtree that should have access to {@link useAgent}. */
@@ -58,6 +65,21 @@ export interface AgentProviderProps {
      * a run is cancelled or errors before completion.
      */
     onConversationChange?: (history: Message[], entries: ConversationEntry[]) => void;
+    /**
+     * Forces a theme on the auto-rendered `[data-mast-root]` wrapper. When
+     * omitted, the panel follows the OS preference via the default stylesheet's
+     * `prefers-color-scheme` media query. Ignored when `disableRoot` is `true`.
+     */
+    theme?: 'light' | 'dark';
+    /**
+     * Disable the auto-rendered `<div data-mast-root>` wrapper around `children`.
+     * Use this when you want to place `data-mast-root` somewhere else in the
+     * tree yourself, e.g. on a chat sidebar's outer container so additional
+     * non-library UI inside also picks up the library's CSS variables.
+     *
+     * Default: `false` (the wrapper is rendered).
+     */
+    disableRoot?: boolean;
 }
 /**
  * The value exposed by {@link useAgent}.
@@ -95,6 +117,15 @@ export interface UseAgentReturn {
      * called.
      */
     pendingApprovals: PendingApproval[];
+    /**
+     * `true` when an `AgentRunner` is configured. `false` when `<AgentProvider>`
+     * was mounted with `runner={null}` (the "agent not yet configured" state).
+     * `<ChatInput>` reads this to disable its textarea and Send button; custom
+     * inputs built via `useAgent()` should do the same.
+     *
+     * When `false`, `sendMessage` is a no-op (it logs a development warning).
+     */
+    isReady: boolean;
 }
 /**
  * Wraps a subtree with agent context.
@@ -103,7 +134,7 @@ export interface UseAgentReturn {
  * and drives it with {@link useAgentStream}. Children access the resulting
  * state through {@link useAgent}.
  */
-export declare function AgentProvider({ runner, agent, children, icons, onApprovalRequired, approvalOverride, initialHistory, initialEntries, onConversationChange, }: AgentProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function AgentProvider({ runner, agent, children, icons, onApprovalRequired, approvalOverride, initialHistory, initialEntries, onConversationChange, theme, disableRoot, }: AgentProviderProps): import("react/jsx-runtime").JSX.Element;
 /**
  * Reads the current agent state from {@link AgentProvider}.
  *

package/dist/hooks/useAgentStream.d.ts

@@ -99,6 +99,12 @@ export interface UseAgentStreamReturn {
  * of the conversation. Sub-agent events are captured via `onToolEvent` and
  * routed to the matching `ToolEventEntry` by tool name.
  *
+ * Pass `null` for `conversation` to model the "agent not yet configured"
+ * state — `sendMessage` becomes a no-op (with a development warning),
+ * `history` is empty, and `isRunning` is always `false`. The hook switches
+ * back to live behaviour once a non-null `conversation` is supplied on a
+ * later render.
+ *
  * This hook is consumed by `<AgentProvider>` and is not part of the public API.
  * It is exported so that it can be used independently in advanced scenarios.
  *
@@ -128,4 +134,4 @@ export interface UseAgentStreamReturn {
  * const { entries, sendMessage, cancel, isRunning } = useAgentStream(conversation);
  * ```
  */
-export declare function useAgentStream(conversation: Conversation, options?: UseAgentStreamOptions): UseAgentStreamReturn;
+export declare function useAgentStream(conversation: Conversation | null, options?: UseAgentStreamOptions): UseAgentStreamReturn;

package/dist/index.d.ts

@@ -14,7 +14,8 @@ export type { ToolCallBlockProps } from './components/ToolCallBlock.js';
 export { UserMessage } from './components/UserMessage.js';
 export type { UserMessageProps } from './components/UserMessage.js';
 export { AssistantMessage } from './components/AssistantMessage.js';
-export type { AssistantMessageProps } from './components/AssistantMessage.js';
+export type { AssistantMessageProps, RenderApproval } from './components/AssistantMessage.js';
+export type { GetToolLabel } from './components/ToolLabelContext.js';
 export { ChatInput } from './components/ChatInput.js';
 export type { ChatInputProps } from './components/ChatInput.js';
 export { MessageItem } from './components/MessageItem.js';