reifyui 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -8,38 +8,91 @@ import type { ComponentType, ReactNode } from 'react';
8
8
 
9
9
  // ── streaming ──────────────────────────────────────────────────────────────
10
10
  export interface SSEEvent { type: string; [k: string]: unknown; }
11
+
12
+ /** Semantic callbacks over the Responses SSE shape. All optional — handle only what you render. */
13
+ export interface ResponseHandlers {
14
+ /** The response id, as soon as response.created arrives. */
15
+ onCreated?(responseId: string): void;
16
+ /** The server-side session id, for continuing this conversation on the next turn. */
17
+ onSession?(sessionId: string): void;
18
+ onReasoningDelta?(text: string): void;
19
+ onTextDelta?(text: string): void;
20
+ onToolCall?(name: string, args: string, callId: string): void;
21
+ onToolResult?(callId: string, output: string): void;
22
+ onFile?(file: { container_id: string; file_id: string; filename: string }): void;
23
+ /** Terminal event. `status` distinguishes completed / incomplete / failed (incl. cancels). */
24
+ onDone?(status: string, response: unknown): void;
25
+ onError?(message: string): void;
26
+ }
27
+
28
+ export interface ResponsesDispatcher {
29
+ responseId: string | null;
30
+ dispatch(event: SSEEvent): void;
31
+ }
32
+ /** Event-shape decoding only — pair with readSSEStream when you own the read loop. */
33
+ export function createResponsesDispatcher(handlers: ResponseHandlers): ResponsesDispatcher;
34
+
35
+ /** Frame an SSE byte stream. Takes the response BODY, and hands back each frame's raw `data:`
36
+ * payload as a STRING — parsing is the caller's (see pumpResponsesStream for the parsed form). */
11
37
  export function readSSEStream(
12
- response: Response,
13
- onEvent: (event: SSEEvent) => void,
38
+ body: ReadableStream<Uint8Array>,
39
+ onData: (data: string) => void,
14
40
  ): Promise<void>;
15
- export function createResponsesDispatcher(handlers: Record<string, (event: SSEEvent) => void>):
16
- (event: SSEEvent) => void;
17
- export function pumpResponsesStream(args: {
18
- response: Response;
19
- onEvent?: (event: SSEEvent) => void;
20
- [k: string]: unknown;
21
- }): Promise<unknown>;
41
+
42
+ /** Read + decode in one call. Resolves to the response id. */
43
+ export function pumpResponsesStream(
44
+ body: ReadableStream<Uint8Array>,
45
+ handlers: ResponseHandlers,
46
+ ): Promise<string | null>;
22
47
 
23
48
  // ── block state machine ─────────────────────────────────────────────────────
24
- export type Block = Record<string, unknown>;
25
- export function withText(blocks: Block[], text: string): Block[];
26
- export function withReasoning(blocks: Block[], text: string): Block[];
27
- export function withStep(blocks: Block[], step: Record<string, unknown>): Block[];
28
- export function withResult(blocks: Block[], result: Record<string, unknown>): Block[];
29
- export function asstText(blocks: Block[]): string;
49
+ // An assistant turn is an ORDERED list of blocks appended as events arrive, so tool activity
50
+ // interleaves with prose in real time instead of every tool being hoisted above the text.
51
+ export interface ToolStep {
52
+ name: string;
53
+ args?: string;
54
+ result?: unknown;
55
+ callId?: string;
56
+ [k: string]: unknown;
57
+ }
58
+ export type Block =
59
+ | { kind: 'text'; text: string }
60
+ | { kind: 'tools'; reasoning: string; steps: ToolStep[] };
61
+
62
+ // The transforms are generic over the caller's block type: they only ever read `kind` (and, in
63
+ // withResult, a step's `callId`/`result`), and otherwise pass values through untouched. An app
64
+ // with a stricter Block/ToolStep of its own keeps it, rather than having every result widened to
65
+ // this module's shape. Block above is the DEFAULT for apps that don't declare their own.
66
+ /** Append prose, merging into a trailing text block. */
67
+ export function withText<B = Block>(blocks: B[], delta: string): B[];
68
+ /** Append reasoning, merging into a trailing tools block. */
69
+ export function withReasoning<B = Block>(blocks: B[], delta: string): B[];
70
+ /** Append a tool step, merging into a trailing tools block. */
71
+ export function withStep<B = Block, S = ToolStep>(blocks: B[], step: S): B[];
72
+ /** Attach a result to the pending step with this call id. */
73
+ export function withResult<B = Block>(blocks: B[], callId: string, output: unknown): B[];
74
+ /** All prose of an assistant MESSAGE joined — takes the message, not its blocks. */
75
+ export function asstText(message: { blocks: readonly unknown[] }): string;
30
76
 
31
77
  // ── conversation store ──────────────────────────────────────────────────────
78
+ // A tiny keyed store with a React binding: `use(key)` subscribes, `get`/`set` read and write
79
+ // outside render. Values are whatever the caller puts in, so they stay generic per key.
32
80
  export interface ConversationStore {
33
- getState: () => unknown;
34
- setState: (next: unknown) => void;
35
- subscribe: (listener: () => void) => () => void;
36
- [k: string]: unknown;
81
+ get<T = unknown>(key: string): T;
82
+ /** Shallow-merges a partial into the key's current state (or the partial a function returns). */
83
+ set<T = unknown>(key: string, patch: Partial<T> | ((prev: T) => Partial<T>)): void;
84
+ seed(key: string, value: unknown): void;
85
+ updateLastAssistant(key: string, update: (msg: unknown) => unknown): void;
86
+ use<T = unknown>(key: string): T;
37
87
  }
38
- export function createConversationStore(initial?: unknown): ConversationStore;
88
+ /** `makeInitial(key)` supplies the starting value the first time a key is read. */
89
+ export function createConversationStore(
90
+ makeInitial?: (key: string) => unknown,
91
+ ): ConversationStore;
39
92
 
40
93
  // ── icons ───────────────────────────────────────────────────────────────────
41
94
  export const Svg: ComponentType<{ s?: number; children?: ReactNode }>;
42
- export const Chevron: ComponentType<{ open?: boolean }>;
95
+ export const Chevron: ComponentType<{ dir?: 'left' | 'right' | 'down'; size?: number }>;
43
96
  export const IcTool: ComponentType;
44
97
  export const IcPlug: ComponentType;
45
98
  export const IcSkill: ComponentType;
@@ -65,7 +118,25 @@ export function summarizeSteps(steps: unknown[]): string;
65
118
  // ── components (permissive props: see README for slot contracts) ─────────────
66
119
  export const ToolGroup: ComponentType<Record<string, unknown>>;
67
120
  export const ToolRow: ComponentType<Record<string, unknown>>;
68
- export const ChatMessages: ComponentType<Record<string, unknown>>;
121
+ /** The message list. `messages` is the conversation you own — this renders it and its tool
122
+ * timeline; every render slot is optional. */
123
+ // Generic over YOUR message type: the renderer never inspects a message beyond `role` and its
124
+ // blocks, so the slots hand back whatever shape you passed in rather than widening it.
125
+ export interface ChatMessagesProps<M = any> {
126
+ messages: M[];
127
+ renderMarkdown?: (text: string) => ReactNode;
128
+ renderMessage?(message: M, index: number): ReactNode;
129
+ renderStep?(step: ToolStep, index: number): ReactNode;
130
+ userExtras?(message: M, index: number): ReactNode;
131
+ /** Rendered on the live "working" row — a node, not a slot function. */
132
+ workingExtra?: ReactNode;
133
+ assistantFooter?(message: M, index: number): ReactNode;
134
+ statusLabels?: Record<string, string>;
135
+ workingLabel?: string;
136
+ toolLabels?: Record<string, string>;
137
+ [k: string]: unknown;
138
+ }
139
+ export const ChatMessages: <M = unknown>(props: ChatMessagesProps<M>) => ReactNode;
69
140
  export const ChatMessagesSkeleton: ComponentType<Record<string, unknown>>;
70
141
  export const UserTurn: ComponentType<Record<string, unknown>>;
71
142
  export const AssistantTurn: ComponentType<Record<string, unknown>>;
@@ -99,6 +170,41 @@ export interface TaskListProps {
99
170
  export const TaskList: ComponentType<TaskListProps>;
100
171
  export function taskStatusGroup(status: string): 'working' | 'done' | 'failed' | 'idle';
101
172
 
173
+ // ── dialogs (alert / confirm / prompt, in-app) ───────────────────────────────
174
+ export type DialogVariant = 'destructive' | 'error' | 'warning' | 'success';
175
+ export interface DialogLabels {
176
+ confirm?: string; cancel?: string; ok?: string; create?: string; required?: string;
177
+ }
178
+ export interface AlertOptions {
179
+ title?: string; message?: ReactNode; variant?: DialogVariant; confirmLabel?: string;
180
+ }
181
+ export interface ConfirmOptions extends AlertOptions {
182
+ destructive?: boolean; cancelLabel?: string;
183
+ }
184
+ export interface PromptOptions extends ConfirmOptions {
185
+ label?: string; placeholder?: string; help?: ReactNode;
186
+ defaultValue?: string; inputType?: string;
187
+ multiline?: boolean; rows?: number; required?: boolean;
188
+ /** Return an error message to reject, or null/undefined to accept. */
189
+ validate?: (value: string) => string | null | undefined;
190
+ }
191
+ export interface CreateType { kind: string; label: string; color?: string; icon?: ReactNode; }
192
+ export interface CreateOptions extends PromptOptions {
193
+ types?: CreateType[]; defaultKind?: string;
194
+ }
195
+ export interface DialogApi {
196
+ alert(opts: AlertOptions): Promise<boolean>;
197
+ confirm(opts: ConfirmOptions): Promise<boolean>;
198
+ /** Resolves to the entered string, or null when cancelled. */
199
+ prompt(opts: PromptOptions): Promise<string | null>;
200
+ create(opts: CreateOptions): Promise<{ kind: string; name: string } | null>;
201
+ labels: Required<DialogLabels>;
202
+ }
203
+ export const DialogHost: ComponentType<{
204
+ children?: ReactNode; locale?: 'en' | 'zh'; labels?: DialogLabels;
205
+ }>;
206
+ export function useDialog(): DialogApi;
207
+
102
208
  // ── auth client (optional; couples to a /v1/auth-style backend) ──────────────
103
209
  export interface AuthConfig { engine: string; product: string; loginHash?: string; }
104
210
  export function configureAuth(cfg: Partial<AuthConfig> & { product: string; engine: string }): void;