@webority/chat-react 0.88.1 → 0.90.0

package/dist/types/components/ChatMessage.meta.d.ts

@@ -0,0 +1,153 @@
+export declare const meta: {
+    readonly name: "ChatMessage";
+    readonly marker: "ChatMessage";
+    readonly platforms: readonly ["web"];
+    readonly acceptsChildren: false;
+    readonly props: {
+        readonly turn: {
+            readonly type: "object";
+            readonly required: true;
+            readonly description: "The turn to show: the person's question and the assistant's answer.";
+            readonly fields: {
+                readonly id: {
+                    readonly type: "string";
+                    readonly required: true;
+                    readonly description: "Local key for the turn; for a reopened conversation, the stored message's id.";
+                };
+                readonly question: {
+                    readonly type: "string";
+                    readonly required: true;
+                    readonly description: "What the person asked. Left empty, no question bubble shows.";
+                };
+                readonly answer: {
+                    readonly type: "string";
+                    readonly required: true;
+                    readonly description: "The answer shown: the streamed text so far, then the reply of record.";
+                };
+                readonly streaming: {
+                    readonly type: "boolean";
+                    readonly required: true;
+                    readonly description: "True while the answer is still arriving.";
+                };
+                readonly step: {
+                    readonly type: "string";
+                    readonly required: false;
+                    readonly description: "The name of the tool the assistant is running. Unset when none is.";
+                };
+                readonly error: {
+                    readonly type: "object";
+                    readonly required: false;
+                    readonly description: "Set when the turn failed; its message shows in an alert.";
+                    readonly fields: {
+                        readonly code: {
+                            readonly type: "string";
+                            readonly required: true;
+                            readonly description: "A short code for the failure.";
+                        };
+                        readonly message: {
+                            readonly type: "string";
+                            readonly required: true;
+                            readonly description: "Written for the person.";
+                        };
+                        readonly resetsAtUtc: {
+                            readonly type: "string";
+                            readonly required: false;
+                            readonly description: "When a limit resets, as an ISO time.";
+                        };
+                    };
+                };
+                readonly actions: {
+                    readonly type: "array";
+                    readonly required: true;
+                    readonly description: "Support actions the assistant prepared for this turn.";
+                };
+                readonly messageId: {
+                    readonly type: "string";
+                    readonly required: false;
+                    readonly description: "The stored reply's id. The rating needs it.";
+                };
+                readonly rating: {
+                    readonly type: "enum";
+                    readonly values: readonly ["Up", "Down"];
+                    readonly required: false;
+                    readonly description: "The rating already given to the reply.";
+                };
+                readonly ratingNote: {
+                    readonly type: "string";
+                    readonly required: false;
+                    readonly description: "The note saved with the rating.";
+                };
+            };
+        };
+        readonly labels: {
+            readonly type: "object";
+            readonly required: false;
+            readonly description: "Replacements for the built-in wording, such as the labels for You, Assistant and Thinking.";
+        };
+    };
+    readonly examples: readonly [{
+        readonly id: "ChatMessage";
+        readonly title: "Default";
+        readonly props: {
+            readonly turn: {
+                readonly id: "t1";
+                readonly question: "Where is my order?";
+                readonly answer: "Your order ships today.";
+                readonly streaming: false;
+                readonly actions: readonly [];
+            };
+        };
+        readonly wrap: {
+            readonly component: "ul";
+            readonly props: {
+                readonly className: "list-unstyled mb-0";
+            };
+        };
+    }, {
+        readonly id: "ChatMessage.user";
+        readonly title: "Question only";
+        readonly props: {
+            readonly turn: {
+                readonly id: "message-user";
+                readonly question: "How do I turn on two-step sign-in?";
+                readonly answer: "";
+                readonly streaming: false;
+                readonly actions: readonly [];
+            };
+        };
+        readonly wrap: {
+            readonly component: "ul";
+            readonly props: {
+                readonly className: "list-unstyled mb-0";
+            };
+        };
+    }, {
+        readonly id: "ChatMessage.assistant";
+        readonly title: "Answer only";
+        readonly props: {
+            readonly turn: {
+                readonly id: "message-assistant";
+                readonly question: "";
+                readonly answer: "Open the security settings and choose two-step sign-in.";
+                readonly streaming: false;
+                readonly actions: readonly [];
+            };
+        };
+        readonly wrap: {
+            readonly component: "ul";
+            readonly props: {
+                readonly className: "list-unstyled mb-0";
+            };
+        };
+    }];
+    readonly usage: {
+        readonly when: readonly ["Show one question and its answer inside a chat thread.", "Draw a single stored or streaming turn on its own, such as in a history view."];
+        readonly whenNot: readonly [{
+            readonly text: "Showing the whole conversation, oldest turn first, with the newest text kept in view.";
+            readonly instead: "ChatThread";
+        }];
+        readonly do: readonly [];
+        readonly dont: readonly [];
+        readonly a11y: readonly ["The answer sits in a polite live region, so a screen reader reads it once it settles; it is marked busy while it streams.", "Visually hidden labels name who is speaking, taken from the You and Assistant labels.", "While the first text is awaited, a spinner carries the Thinking label."];
+    };
+};

package/dist/types/components/ChatPanel.d.ts

@@ -5,24 +5,23 @@
  * while it is open, Escape closes it, and the question box takes focus when it opens.
  *
  * @param {object} props
- * @param {ReturnType<typeof import('../useChat.js').useChat>} props.chat The hook's result.
+ * @param {ReturnType<typeof import('../useChat.js').useChat>} props.chat
  * @param {boolean} props.open
  * @param {() => void} props.onClose
- * @param {import('react').ReactNode} [props.title] Defaults to `labels.panelTitle`.
- * @param {string} [props.titleIcon="sparkles"] A library icon name.
- * @param {import('react').ReactNode} [props.headerActions] Extra header controls before New chat,
- *   e.g. an `AppActionIcon` that opens past chats.
- * @param {import('react').ReactNode} [props.empty] Shown before the first question.
- * @param {import('react').ReactNode} [props.disclaimer] The footnote; defaults to `labels.disclaimer`.
- * @param {number} [props.maxLength=4000] The server's message limit.
- * @param {number} [props.allowanceThreshold=10] Show the questions left once this many or fewer remain.
+ * @param {import('react').ReactNode} [props.title]
+ * @param {string} [props.titleIcon="sparkles"]
+ * @param {import('react').ReactNode} [props.headerActions]
+ * @param {import('react').ReactNode} [props.empty]
+ * @param {import('react').ReactNode} [props.disclaimer]
+ * @param {number} [props.maxLength=4000]
+ * @param {number} [props.allowanceThreshold=10]
  * @param {string} [props.width="440px"]
  * @param {(href: string) => string|null|undefined} [props.resolveLink] See `ChatMarkdown`.
  * @param {import('react').ElementType} [props.linkComponent] A router link (it receives `to`).
  * @param {(token: string) => Promise<{ id: string, number: string }>} [props.confirmAction] Shows
  *   support action cards, e.g. `supportClient.confirmAction`.
  * @param {(ticket: { id: string, number: string }) => void} [props.onViewTicket]
- * @param {boolean} [props.rating=true] Offer thumbs under stored replies.
+ * @param {boolean} [props.rating=true]
  * @param {(turn: import('../useChat.js').ChatTurn, state: { streaming: boolean }) => import('react').ReactNode} [props.renderReply]
  *   Draws each assistant answer instead of `ChatMarkdown`; see `ChatMessage`.
  * @param {Partial<typeof import('@webority/ui-elements/chat-core').DEFAULT_CHAT_LABELS>} [props.labels]

package/dist/types/components/ChatPanel.meta.d.ts

@@ -0,0 +1,208 @@
+export declare const meta: {
+    readonly name: "ChatPanel";
+    readonly marker: "ChatPanel";
+    readonly platforms: readonly ["web"];
+    readonly acceptsChildren: false;
+    readonly props: {
+        readonly chat: {
+            readonly type: "object";
+            readonly required: true;
+            readonly description: "The chat state the panel shows; the app takes it from useChat. The kit draws a stand-in with these fields.";
+            readonly fields: {
+                readonly turns: {
+                    readonly type: "array";
+                    readonly required: true;
+                    readonly description: "The conversation, oldest turn first.";
+                    readonly itemFields: {
+                        readonly id: {
+                            readonly type: "string";
+                            readonly required: true;
+                            readonly description: "Local key for the turn.";
+                        };
+                        readonly question: {
+                            readonly type: "string";
+                            readonly required: true;
+                            readonly description: "What the person asked.";
+                        };
+                        readonly answer: {
+                            readonly type: "string";
+                            readonly required: true;
+                            readonly description: "The answer shown.";
+                        };
+                        readonly streaming: {
+                            readonly type: "boolean";
+                            readonly required: true;
+                            readonly description: "True while the answer is still arriving.";
+                        };
+                        readonly step: {
+                            readonly type: "string";
+                            readonly required: false;
+                            readonly description: "The tool the assistant is running.";
+                        };
+                        readonly error: {
+                            readonly type: "object";
+                            readonly required: false;
+                            readonly description: "Set when the turn failed.";
+                            readonly fields: {
+                                readonly code: {
+                                    readonly type: "string";
+                                    readonly required: true;
+                                    readonly description: "A short code for the failure.";
+                                };
+                                readonly message: {
+                                    readonly type: "string";
+                                    readonly required: true;
+                                    readonly description: "Written for the person.";
+                                };
+                                readonly resetsAtUtc: {
+                                    readonly type: "string";
+                                    readonly required: false;
+                                    readonly description: "When a limit resets, as an ISO time.";
+                                };
+                            };
+                        };
+                        readonly actions: {
+                            readonly type: "array";
+                            readonly required: true;
+                            readonly description: "Support actions prepared for the turn.";
+                        };
+                        readonly messageId: {
+                            readonly type: "string";
+                            readonly required: false;
+                            readonly description: "The stored reply's id.";
+                        };
+                        readonly rating: {
+                            readonly type: "enum";
+                            readonly values: readonly ["Up", "Down"];
+                            readonly required: false;
+                            readonly description: "The rating given.";
+                        };
+                        readonly ratingNote: {
+                            readonly type: "string";
+                            readonly required: false;
+                            readonly description: "The note saved with the rating.";
+                        };
+                    };
+                };
+                readonly messagesLeftToday: {
+                    readonly type: "number";
+                    readonly required: false;
+                    readonly description: "Questions left today. Unset when not known.";
+                };
+                readonly loading: {
+                    readonly type: "boolean";
+                    readonly required: true;
+                    readonly description: "True while a saved conversation loads.";
+                };
+                readonly streaming: {
+                    readonly type: "boolean";
+                    readonly required: true;
+                    readonly description: "True while an answer is arriving.";
+                };
+                readonly loadError: {
+                    readonly type: "object";
+                    readonly required: false;
+                    readonly description: "Set when a saved conversation failed to load.";
+                    readonly fields: {
+                        readonly message: {
+                            readonly type: "string";
+                            readonly required: true;
+                            readonly description: "Written for the person.";
+                        };
+                    };
+                };
+            };
+        };
+        readonly open: {
+            readonly type: "boolean";
+            readonly required: true;
+            readonly description: "Whether the drawer is shown.";
+        };
+        readonly title: {
+            readonly type: "node";
+            readonly description: "The drawer title. Defaults to the panel title label.";
+        };
+        readonly titleIcon: {
+            readonly type: "string";
+            readonly default: "sparkles";
+            readonly description: "A library icon name shown before the title.";
+        };
+        readonly headerActions: {
+            readonly type: "node";
+            readonly description: "Extra header controls placed before New chat.";
+        };
+        readonly empty: {
+            readonly type: "node";
+            readonly description: "Shown before the first question.";
+        };
+        readonly disclaimer: {
+            readonly type: "node";
+            readonly description: "The footnote under the question box. Defaults to the disclaimer label.";
+        };
+        readonly maxLength: {
+            readonly type: "number";
+            readonly default: 4000;
+            readonly description: "The most characters a question may have.";
+        };
+        readonly allowanceThreshold: {
+            readonly type: "number";
+            readonly default: 10;
+            readonly description: "The questions left note shows once this many or fewer remain.";
+        };
+        readonly width: {
+            readonly type: "string";
+            readonly default: "440px";
+            readonly description: "The drawer width on wide screens.";
+        };
+        readonly rating: {
+            readonly type: "boolean";
+            readonly default: true;
+            readonly description: "Offer thumbs under stored replies.";
+        };
+        readonly labels: {
+            readonly type: "object";
+            readonly description: "Replacements for the built-in wording.";
+        };
+    };
+    readonly examples: readonly [{
+        readonly id: "ChatPanel";
+        readonly title: "Default";
+        readonly props: {
+            readonly chat: {
+                readonly turns: readonly [];
+                readonly messagesLeftToday: 8;
+                readonly loading: false;
+                readonly streaming: false;
+            };
+            readonly open: false;
+        };
+    }, {
+        readonly id: "ChatPanel.conversation";
+        readonly title: "With a conversation";
+        readonly props: {
+            readonly chat: {
+                readonly turns: readonly [{
+                    readonly id: "demo-question";
+                    readonly question: "How do I turn on two-step sign-in?";
+                    readonly answer: "Open the security settings and choose two-step sign-in.";
+                    readonly streaming: false;
+                    readonly actions: readonly [];
+                }];
+                readonly messagesLeftToday: 8;
+                readonly loading: false;
+                readonly streaming: false;
+            };
+            readonly open: false;
+        };
+    }];
+    readonly usage: {
+        readonly when: readonly ["Offer the assistant as a drawer that opens from a launcher.", "Show the conversation, the question box, the questions left today and the footnote in one place."];
+        readonly whenNot: readonly [{
+            readonly text: "Showing only the conversation inside a page.";
+            readonly instead: "ChatThread";
+        }];
+        readonly do: readonly [];
+        readonly dont: readonly [];
+        readonly a11y: readonly ["Focus stays inside the drawer while it is open, Escape closes it, and the question box takes focus when it opens.", "The drawer is named by its title.", "The questions left note is a status region."];
+    };
+};

package/dist/types/components/ChatThread.d.ts

@@ -4,7 +4,7 @@
  *
  * @param {object} props
  * @param {import('../useChat.js').ChatTurn[]} props.turns
- * @param {import('react').ReactNode} [props.empty] Shown when there are no turns.
+ * @param {import('react').ReactNode} [props.empty]
  * @param {(turnId: string, rating: "Up"|"Down", note?: string) => Promise<unknown>} [props.onRate]
  * @param {(href: string) => string|null|undefined} [props.resolveLink]
  * @param {import('react').ElementType} [props.linkComponent]

package/dist/types/components/ChatThread.meta.d.ts

@@ -0,0 +1,131 @@
+export declare const meta: {
+    readonly name: "ChatThread";
+    readonly marker: "ChatThread";
+    readonly platforms: readonly ["web"];
+    readonly acceptsChildren: false;
+    readonly props: {
+        readonly turns: {
+            readonly type: "array";
+            readonly required: true;
+            readonly description: "The conversation, oldest turn first. With none, the empty state shows.";
+            readonly itemFields: {
+                readonly id: {
+                    readonly type: "string";
+                    readonly required: true;
+                    readonly description: "Local key for the turn.";
+                };
+                readonly question: {
+                    readonly type: "string";
+                    readonly required: true;
+                    readonly description: "What the person asked.";
+                };
+                readonly answer: {
+                    readonly type: "string";
+                    readonly required: true;
+                    readonly description: "The answer shown: the streamed text so far, then the reply of record.";
+                };
+                readonly streaming: {
+                    readonly type: "boolean";
+                    readonly required: true;
+                    readonly description: "True while the answer is still arriving.";
+                };
+                readonly step: {
+                    readonly type: "string";
+                    readonly required: false;
+                    readonly description: "The name of the tool the assistant is running. Unset when none is.";
+                };
+                readonly error: {
+                    readonly type: "object";
+                    readonly required: false;
+                    readonly description: "Set when the turn failed.";
+                    readonly fields: {
+                        readonly code: {
+                            readonly type: "string";
+                            readonly required: true;
+                            readonly description: "A short code for the failure.";
+                        };
+                        readonly message: {
+                            readonly type: "string";
+                            readonly required: true;
+                            readonly description: "Written for the person.";
+                        };
+                        readonly resetsAtUtc: {
+                            readonly type: "string";
+                            readonly required: false;
+                            readonly description: "When a limit resets, as an ISO time.";
+                        };
+                    };
+                };
+                readonly actions: {
+                    readonly type: "array";
+                    readonly required: true;
+                    readonly description: "Support actions the assistant prepared for this turn.";
+                };
+                readonly messageId: {
+                    readonly type: "string";
+                    readonly required: false;
+                    readonly description: "The stored reply's id. The rating needs it.";
+                };
+                readonly rating: {
+                    readonly type: "enum";
+                    readonly values: readonly ["Up", "Down"];
+                    readonly required: false;
+                    readonly description: "The rating already given to the reply.";
+                };
+                readonly ratingNote: {
+                    readonly type: "string";
+                    readonly required: false;
+                    readonly description: "The note saved with the rating.";
+                };
+            };
+        };
+        readonly empty: {
+            readonly type: "node";
+            readonly required: false;
+            readonly description: "Shown when there are no turns; defaults to a short How can I help state.";
+        };
+        readonly labels: {
+            readonly type: "object";
+            readonly required: false;
+            readonly description: "Replacements for the built-in wording, such as the thread name and the empty-state text.";
+        };
+    };
+    readonly examples: readonly [{
+        readonly id: "ChatThread";
+        readonly title: "Default";
+        readonly props: {
+            readonly turns: readonly [{
+                readonly id: "t-1";
+                readonly question: "What is due?";
+                readonly answer: "Two invoices.";
+                readonly streaming: false;
+                readonly actions: readonly [];
+            }, {
+                readonly id: "t-2";
+                readonly question: "And next?";
+                readonly answer: "One more.";
+                readonly streaming: false;
+                readonly actions: readonly [];
+            }];
+        };
+    }, {
+        readonly id: "ChatThread.empty";
+        readonly title: "No turns yet";
+        readonly props: {
+            readonly turns: readonly [];
+        };
+    }];
+    readonly usage: {
+        readonly when: readonly ["Show a whole conversation, oldest turn first, in a panel or a page.", "Let the thread follow the newest text as an answer streams."];
+        readonly whenNot: readonly [{
+            readonly text: "Showing one turn on its own.";
+            readonly instead: "ChatMessage";
+        }, {
+            readonly text: "Showing the full assistant drawer with its header and question box.";
+            readonly instead: "ChatPanel";
+        }];
+        readonly do: readonly [];
+        readonly dont: readonly [];
+        readonly a11y: readonly ["The turns are an ordered list named by the thread label.", "Each answer is a polite live region; see ChatMessage.", "Only the nearest box that scrolls on its own follows the newest text, so the page itself never jumps."];
+    };
+};

package/dist/types/components/CitationChip.d.ts

@@ -17,8 +17,8 @@ export declare function splitCitations(text: string, isCitation: (inner: string)
  *
  * @param {object} props
  * @param {string} props.citation
- * @param {string} [props.label] Text on the chip; defaults to the citation.
- * @param {string} [props.ariaLabel] Accessible label; defaults to the citation.
+ * @param {string} [props.label]
+ * @param {string} [props.ariaLabel]
  * @param {(citation: string) => void} props.onOpen
  */
 export default function CitationChip({ citation, label, ariaLabel, onOpen }: {

package/dist/types/components/CitationChip.meta.d.ts

@@ -0,0 +1,48 @@
+export declare const meta: {
+    readonly name: "CitationChip";
+    readonly marker: any;
+    readonly platforms: readonly ["web"];
+    readonly acceptsChildren: false;
+    readonly props: {
+        readonly citation: {
+            readonly type: "string";
+            readonly required: true;
+            readonly description: "The source the assistant named in its reply, written as [inner] in the text. It is the chip's text and its accessible name unless label or ariaLabel replace them.";
+        };
+        readonly label: {
+            readonly type: "string";
+            readonly required: false;
+            readonly description: "Text on the chip. Defaults to the citation.";
+        };
+        readonly ariaLabel: {
+            readonly type: "string";
+            readonly required: false;
+            readonly description: "Accessible label for the chip. Defaults to the citation.";
+        };
+    };
+    readonly examples: readonly [{
+        readonly id: "CitationChip";
+        readonly title: "Default";
+        readonly props: {
+            readonly citation: "Clause 4.2";
+        };
+    }, {
+        readonly id: "CitationChip.label";
+        readonly title: "With a label";
+        readonly props: {
+            readonly citation: "Table 1";
+            readonly label: "Table 1, page 3";
+            readonly ariaLabel: "Open Table 1";
+        };
+    }];
+    readonly usage: {
+        readonly when: readonly ["Show a source the assistant named in a reply as a small chip the person can select to open it.", "Pair it with splitCitations to turn [source] runs in reply text into chips."];
+        readonly whenNot: readonly [{
+            readonly text: "Showing a general label or removable token that is not a source.";
+            readonly instead: "AppChip";
+        }];
+        readonly do: readonly [];
+        readonly dont: readonly [];
+        readonly a11y: readonly ["The chip is a button named by ariaLabel, or by the citation when none is given.", "Selecting it by pointer or keyboard calls onOpen with the citation."];
+    };
+};

package/dist/types/components/ConfirmCard.d.ts

@@ -6,8 +6,8 @@
  * @param {object} props
  * @param {string} props.title
  * @param {string} [props.subtitle]
- * @param {string[]} [props.lines] One paragraph per entry, shown above the note.
- * @param {string} [props.note] Replaces the default line saying nothing is sent until the person confirms.
+ * @param {string[]} [props.lines]
+ * @param {string} [props.note]
  * @param {() => Promise<{ message?: string } | void>} props.onConfirm Sends the person's yes; resolves to
  *   an optional message for the done state. A rejection's `message` is shown when present.
  * @param {Partial<typeof import('@webority/ui-elements/chat-core').DEFAULT_CHAT_LABELS>} [props.labels]

package/dist/types/components/ConfirmCard.meta.d.ts

@@ -0,0 +1,43 @@
+export declare const meta: {
+    readonly name: "ConfirmCard";
+    readonly marker: any;
+    readonly platforms: readonly ["web"];
+    readonly acceptsChildren: false;
+    readonly props: {
+        readonly title: {
+            readonly type: "string";
+            readonly required: true;
+            readonly description: "The action the assistant prepared, written as what happens when the person confirms.";
+        };
+        readonly subtitle: {
+            readonly type: "string";
+            readonly description: "A line under the title that says more about the action.";
+        };
+        readonly lines: {
+            readonly type: "array";
+            readonly description: "One paragraph per entry, shown above the note.";
+        };
+        readonly note: {
+            readonly type: "string";
+            readonly description: "Replaces the default line saying nothing is sent until the person confirms.";
+        };
+        readonly labels: {
+            readonly type: "object";
+            readonly description: "Replaces any of the chat texts the card shows, such as the confirm and not now button texts and the done message.";
+        };
+    };
+    readonly examples: readonly [{
+        readonly id: "ConfirmCard";
+        readonly title: "Default";
+        readonly props: {
+            readonly title: "Copy assessment";
+        };
+    }];
+    readonly usage: {
+        readonly when: readonly ["The assistant has prepared an action and nothing should happen until the person says yes.", "The action is one step the person can send now or decline."];
+        readonly whenNot: readonly [];
+        readonly do: readonly [];
+        readonly dont: readonly [];
+        readonly a11y: readonly ["Confirm and Not now are native buttons, and Confirm shows its loading state while the action is sent.", "The done message is a status message.", "A failed confirm shows its message in an alert above the buttons and returns the card to ready."];
+    };
+};

package/dist/types/components/ReplyRating.d.ts

@@ -3,9 +3,9 @@
  * that saves the same rating again with the note. Either choice can be changed.
  *
  * @param {object} props
- * @param {"Up"|"Down"|null} [props.rating] The rating already saved.
+ * @param {"Up"|"Down"|null} [props.rating]
  * @param {(rating: "Up"|"Down", note?: string) => Promise<unknown>} props.onRate Rejects on failure.
- * @param {number} [props.noteMaxLength=1000]
+ * @param {number} [props.noteMaxLength]
  * @param {Partial<typeof import('@webority/ui-elements/chat-core').DEFAULT_CHAT_LABELS>} [props.labels]
  */
 export default function ReplyRating({ rating, onRate, noteMaxLength, labels: labelOverrides }: {