@webority/chat-react 0.127.0 → 0.133.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.
Files changed (89) hide show
  1. package/dist/chat-react.js +14 -11
  2. package/dist/types/ChatAgentTyping.d.ts +4 -0
  3. package/dist/types/ChatAuthorBadge.d.ts +4 -0
  4. package/dist/types/ChatComposer.d.ts +10 -0
  5. package/dist/types/ChatConversationActions.d.ts +7 -0
  6. package/dist/types/ChatEmbed.d.ts +5 -0
  7. package/dist/types/ChatExplain.d.ts +16 -0
  8. package/dist/types/ChatFooter.d.ts +8 -0
  9. package/dist/types/ChatFrame.d.ts +26 -0
  10. package/dist/types/ChatHistory.d.ts +9 -0
  11. package/dist/types/ChatLauncher.d.ts +5 -0
  12. package/dist/types/ChatLiveStatus.d.ts +4 -0
  13. package/dist/types/ChatMessageActions.d.ts +10 -0
  14. package/dist/types/ChatNudge.d.ts +10 -0
  15. package/dist/types/ChatOpenTickets.d.ts +9 -0
  16. package/dist/types/ChatPage.d.ts +49 -0
  17. package/dist/types/ChatPanel.d.ts +9 -0
  18. package/dist/types/ChatPastChats.d.ts +9 -0
  19. package/dist/types/ChatReadAloudButton.d.ts +8 -0
  20. package/dist/types/ChatShell.d.ts +32 -0
  21. package/dist/types/ChatStarters.d.ts +8 -0
  22. package/dist/types/ChatThread.d.ts +15 -0
  23. package/dist/types/chatLive.d.ts +5 -0
  24. package/dist/types/chatPrint.d.ts +5 -0
  25. package/dist/types/chatShared.d.ts +10 -0
  26. package/dist/types/dictationText.d.ts +31 -0
  27. package/dist/types/index.d.ts +20 -14
  28. package/dist/types/loaders/ChatLoader.d.ts +21 -0
  29. package/dist/types/loaders/OrbLoader.d.ts +11 -0
  30. package/dist/types/loaders/PhrasesLoader.d.ts +14 -0
  31. package/dist/types/loaders/SkeletonLoader.d.ts +11 -0
  32. package/dist/types/loaders/StepsLoader.d.ts +12 -0
  33. package/dist/types/loaders/TypingPill.d.ts +12 -0
  34. package/dist/types/renderers/ActionPart.d.ts +4 -0
  35. package/dist/types/renderers/ChartPart.d.ts +4 -0
  36. package/dist/types/renderers/ChatLinkContext.d.ts +8 -0
  37. package/dist/types/renderers/FigureText.d.ts +5 -0
  38. package/dist/types/renderers/FiguresPart.d.ts +4 -0
  39. package/dist/types/renderers/FilePart.d.ts +4 -0
  40. package/dist/types/renderers/HandoffPart.d.ts +4 -0
  41. package/dist/types/renderers/ImagePart.d.ts +4 -0
  42. package/dist/types/renderers/InputRequestPart.d.ts +5 -0
  43. package/dist/types/renderers/NoticePart.d.ts +3 -0
  44. package/dist/types/renderers/QuickRepliesPart.d.ts +4 -0
  45. package/dist/types/renderers/RecordCardPart.d.ts +4 -0
  46. package/dist/types/renderers/SourcesPart.d.ts +4 -0
  47. package/dist/types/renderers/TablePart.d.ts +4 -0
  48. package/dist/types/renderers/TextPart.d.ts +5 -0
  49. package/dist/types/renderers/TicketPart.d.ts +4 -0
  50. package/dist/types/renderers/VoiceClipPart.d.ts +7 -0
  51. package/dist/types/renderers/index.d.ts +32 -0
  52. package/dist/types/useAutoOpen.d.ts +11 -0
  53. package/dist/types/useChat.d.ts +34 -76
  54. package/dist/types/useChatDictation.d.ts +24 -0
  55. package/dist/types/useChatExplain.d.ts +57 -0
  56. package/dist/types/useChatHandoff.d.ts +19 -0
  57. package/dist/types/useChatReadAloud.d.ts +16 -0
  58. package/dist/types/useChatSound.d.ts +5 -0
  59. package/dist/types/useChatSpeech.d.ts +7 -0
  60. package/dist/types/useLauncherAvoid.d.ts +1 -0
  61. package/dist/types/useReducedMotion.d.ts +1 -0
  62. package/dist/types/useTranscriptActions.d.ts +12 -0
  63. package/package.json +18 -20
  64. package/README.md +0 -320
  65. package/dist/guidance.json +0 -216
  66. package/dist/types/ChatMarkdown.meta.d.ts +0 -31
  67. package/dist/types/components/ActionCard.d.ts +0 -27
  68. package/dist/types/components/ActionCard.meta.d.ts +0 -89
  69. package/dist/types/components/ChatComposer.d.ts +0 -38
  70. package/dist/types/components/ChatComposer.meta.d.ts +0 -56
  71. package/dist/types/components/ChatConversationList.d.ts +0 -20
  72. package/dist/types/components/ChatConversationList.meta.d.ts +0 -37
  73. package/dist/types/components/ChatLauncher.d.ts +0 -31
  74. package/dist/types/components/ChatLauncher.meta.d.ts +0 -50
  75. package/dist/types/components/ChatMessage.d.ts +0 -61
  76. package/dist/types/components/ChatMessage.meta.d.ts +0 -173
  77. package/dist/types/components/ChatPanel.d.ts +0 -74
  78. package/dist/types/components/ChatPanel.meta.d.ts +0 -228
  79. package/dist/types/components/ChatThread.d.ts +0 -54
  80. package/dist/types/components/ChatThread.meta.d.ts +0 -151
  81. package/dist/types/components/CitationChip.d.ts +0 -15
  82. package/dist/types/components/CitationChip.meta.d.ts +0 -48
  83. package/dist/types/components/ComposerAttachments.d.ts +0 -14
  84. package/dist/types/components/ConfirmCard.d.ts +0 -24
  85. package/dist/types/components/ConfirmCard.meta.d.ts +0 -43
  86. package/dist/types/components/ReplyRating.d.ts +0 -16
  87. package/dist/types/components/ReplyRating.meta.d.ts +0 -34
  88. package/dist/types/markdown.d.ts +0 -22
  89. /package/{LICENSE → LICENSE.txt} +0 -0
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Plays the open, sent and reply cues from the session's state transitions, and vibrates on a reply.
3
+ * Restored and greeting messages never pass through a streaming transition, so they stay silent.
4
+ */
5
+ export default function useChatSound(chat: any): void;
@@ -0,0 +1,7 @@
1
+ /**
2
+ * The speech adapter for this chat, or null when the profile has no speech package or neither dictation nor read-aloud is on.
3
+ *
4
+ * @param {object} chat The chat state from useChat.
5
+ * @returns {import('@webority/chat-core').ChatSpeechAdapter | null}
6
+ */
7
+ export default function useChatSpeech(chat: object): import('@webority/chat-core').ChatSpeechAdapter | null;
@@ -0,0 +1 @@
1
+ export default function useLauncherAvoid(ref: any, avoid: any, launcher: any, enabled: any): void;
@@ -0,0 +1 @@
1
+ export default function useReducedMotion(look: any, experience: any): boolean;
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Share and print for one reply or the whole conversation, built from the same transcript model.
3
+ */
4
+ export default function useTranscriptActions(chat: any, labels: any): {
5
+ canShare: any;
6
+ canPrint: any;
7
+ notice: null;
8
+ shareReply: (message: any) => Promise<void>;
9
+ printReply: (message: any) => void;
10
+ shareConversation: () => Promise<void>;
11
+ printConversation: () => void;
12
+ };
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@webority/chat-react",
3
- "version": "0.127.0",
4
- "description": "Webority AI assistant for React portals: a streaming chat client, a store-agnostic chat hook, and the launcher, panel, thread, rating and support action card, built on @webority/ui-react.",
5
- "license": "SEE LICENSE IN LICENSE",
3
+ "version": "0.133.0",
4
+ "description": "The Webority Chat React screens: launcher, docked, full-page and embedded shells, thread, composer, one renderer per message part kind and the useChat hook, built on @webority/chat-core and @webority/ui-react.",
5
+ "license": "SEE LICENSE IN LICENSE.txt",
6
6
  "type": "module",
7
7
  "publishConfig": {
8
8
  "access": "public",
@@ -22,19 +22,15 @@
22
22
  "types": "./dist/types/index.d.ts",
23
23
  "default": "./dist/chat-react.js"
24
24
  },
25
- "./package.json": "./package.json",
26
- "./guidance.json": "./dist/guidance.json"
25
+ "./package.json": "./package.json"
27
26
  },
28
27
  "sideEffects": false,
29
- "dependencies": {
30
- "@webority/markdown-core": "0.127.0"
31
- },
32
28
  "peerDependencies": {
33
- "@webority/ui-elements": "0.127.0",
34
- "@webority/ui-react": "0.127.0",
35
- "bootstrap": "5.3.3",
29
+ "@webority/chat-core": "0.133.0",
30
+ "@webority/chat-elements": "0.133.0",
31
+ "@webority/markdown-core": "^0.130.0",
32
+ "@webority/ui-react": "^0.130.0",
36
33
  "react": "^19.0.0",
37
- "react-bootstrap": "^2.10.0",
38
34
  "react-dom": "^19.0.0"
39
35
  },
40
36
  "devDependencies": {
@@ -45,22 +41,24 @@
45
41
  "@types/react": "^19.2.17",
46
42
  "@vitejs/plugin-react": "^6.0.1",
47
43
  "@vitest/coverage-v8": "5.0.1",
48
- "@webority/canvas-kit": "0.127.0",
49
- "@webority/ui-elements": "0.127.0",
50
- "@webority/ui-react": "0.127.0",
44
+ "@webority/analytics": "0.34.0",
45
+ "@webority/chat-core": "0.133.0",
46
+ "@webority/chat-elements": "0.133.0",
47
+ "@webority/markdown-core": "0.130.2",
48
+ "@webority/ui-elements": "0.130.2",
49
+ "@webority/ui-react": "0.130.2",
51
50
  "bootstrap": "5.3.3",
52
51
  "jsdom": "30.1.1",
53
- "react": "^19.2.6",
52
+ "react": "19.2.8",
54
53
  "react-bootstrap": "^2.10.6",
55
- "react-dom": "^19.2.6",
54
+ "react-dom": "19.2.8",
56
55
  "typescript": "^7.0.2",
57
56
  "vite": "^8.0.12",
58
57
  "vitest": "5.0.1"
59
58
  },
60
59
  "scripts": {
61
- "build": "vite build && tsc -p tsconfig.json && node ../canvas-kit/dist/cli.js guidance --config canvas-kit.json --out dist/guidance.json",
60
+ "build": "vite build && tsc -p tsconfig.json",
62
61
  "test": "vitest run",
63
- "test:watch": "vitest",
64
- "test:coverage": "vitest run --coverage"
62
+ "test:watch": "vitest"
65
63
  }
66
64
  }
package/README.md DELETED
@@ -1,320 +0,0 @@
1
- # @webority/chat-react
2
-
3
- An AI assistant for a React portal: a client that streams the assistant's reply, a chat hook with
4
- no store of its own, and the pieces of the assistant's UI (a floating launcher, a side panel, the
5
- conversation, reply ratings, a past-chats list and support action cards). It talks to the chat
6
- endpoint the product's backend hosts with `Webority.Ai.Chat.AspNetCore`, and it is built on
7
- `@webority/ui-react` and `@webority/theme`, so it looks like the rest of the portal with no extra
8
- CSS.
9
-
10
- ## Install
11
-
12
- ```bash
13
- npm install @webority/chat-react @webority/ui-react react-bootstrap bootstrap@5.3.3
14
- ```
15
-
16
- `@webority/ui-react`, `react`, `react-dom`, `react-bootstrap` and `bootstrap` are peer
17
- dependencies: the portal already has them. Pin `@webority/chat-react` to the same exact version as
18
- `@webority/ui-react`.
19
-
20
- ## Wire it up
21
-
22
- Give the client the portal's own axios instance. That instance already carries the bearer token,
23
- the tenant headers and the refresh on 401, so the chat calls sign in the same way as every other
24
- call. The package never handles auth.
25
-
26
- ```jsx
27
- import { ChatLauncher, ChatPanel, createChatClient, useChat } from "@webority/chat-react";
28
- import { createSupportClient } from "@webority/support-react";
29
- import { useState } from "react";
30
- import { Link, useLocation, useNavigate } from "react-router-dom";
31
- import { userClient } from "./services/api/clients";
32
-
33
- const chatClient = createChatClient(userClient, { base: "/api/assistant" });
34
- const supportClient = createSupportClient(userClient, "/api/support");
35
-
36
- // Reply links look like [label](scheme:kind/id); map the ones the product knows to a route.
37
- const resolveLink = (href) => {
38
- const [scheme, rest] = href.split(":");
39
- if (scheme === "ticket") return `/support?ticket=${rest.split("/")[1]}`;
40
- return null;
41
- };
42
-
43
- export function Assistant() {
44
- const [open, setOpen] = useState(false);
45
- const navigate = useNavigate();
46
- const { pathname } = useLocation();
47
- const chat = useChat({ client: chatClient, pageContext: { path: pathname } });
48
-
49
- return (
50
- <>
51
- <ChatLauncher open={open} onClick={() => setOpen(true)} style={{ bottom: "5rem" }} />
52
- <ChatPanel
53
- chat={chat}
54
- open={open}
55
- onClose={() => setOpen(false)}
56
- resolveLink={resolveLink}
57
- linkComponent={Link}
58
- confirmAction={supportClient.confirmAction}
59
- onViewTicket={(ticket) => navigate(`/support?ticket=${ticket.id}`)}
60
- />
61
- </>
62
- );
63
- }
64
- ```
65
-
66
- Call `chat.reset()` when the person signs out or switches account, so nothing of one person's chat
67
- shows to the next. The hook keeps its state in the component that calls it; mount it once, above
68
- the routes, so the conversation survives navigation.
69
-
70
- The streamed reply is read through axios's XHR adapter, the browser default. An instance forced
71
- onto the fetch adapter still works, but the reply then appears whole at the end.
72
-
73
- ## The engine and the contract
74
-
75
- The client, the stream reader, the conversation rules and the server contract (the routes, the
76
- request bodies, the events and the error codes) live in
77
- [`@webority/markdown-core/chat`](https://www.npmjs.com/package/@webority/markdown-core/chat). This package draws the
78
- assistant on top of it and re-exports its names, so a product imports every chat name from
79
- `@webority/chat-react`. That includes `CHAT_CONTRACT_VERSION`, `createChatClient`,
80
- `createConversationList`, `DEFAULT_CHAT_LABELS` and `mergeLabels` from the engine, and
81
- `splitCitations` from `@webority/markdown-core`.
82
-
83
- ## Server contract
84
-
85
- The client sends contract number 2 (`CHAT_CONTRACT_VERSION`). A server that reports a lower number, or a 404 on the settings route, makes the client answer `assistant_outdated`, whose message is "The assistant needs an update before it can answer. Please try again later." The panel shows that message in place of the answer.
86
-
87
- ## Settings
88
-
89
- The chat needs the server side of `Webority.Ai.Chat`, served by `Webority.Ai.Chat.AspNetCore`, with
90
- `GET {base}/settings` mapped. The panel reads that route once and keeps the answer. It carries the
91
- attachment limits: the panel refuses a file over them before upload, and the Attach button appears
92
- once they have loaded. A 404 on that route means the server is too old, and the panel shows the
93
- assistant as outdated. A server without the attachment routes gives no limits, so no Attach button.
94
-
95
- ## Panel behaviour
96
-
97
- - Stop cancels the answer arriving. The question and its files stay in the turn.
98
- - Retry sends again the last turn that failed or was stopped, with its files.
99
- - Regenerate asks for a new answer to the last answered turn, replacing it.
100
- - Edit puts a question and its files back in the box. Sending replaces that question and every later turn.
101
- - Attach uploads files in parallel, each with its progress. An upload still running blocks sending; a failed upload is skipped.
102
-
103
- ## Support actions
104
-
105
-
106
- A support card's Confirm calls the `confirmAction(token)` it is given. With
107
- `@webority/support-react` that is `supportClient.confirmAction`, which sends
108
- `POST {supportBase}/actions/confirm` with `{ token }` and resolves to the ticket it acted on. Nothing
109
- reaches support until the person confirms.
110
-
111
- ## On a Razor site
112
-
113
- A server-rendered Razor site uses `<app-chat base="/api/assistant" />` from `Webority.Ui.Razor`
114
- instead. It wraps the `<wui-chat>` element from `@webority/ui-elements/chat`, which reads the same
115
- routes with this package's client, labels and reply parser, and shows the launcher, the panel and
116
- the conversation. Its attributes are this package's props in kebab case: `base`, `position`,
117
- `icon`, `compact`, `panel-title`, `disclaimer`, `max-length`, `allowance-threshold`, `rating`,
118
- `labels` (JSON) and `page-context` (JSON). `title` is `panel-title` there, because `title` is a
119
- global HTML attribute. The `conversations` attribute offers the past-chats list. Support action cards, the rating note, `linkComponent`
120
- and `renderReply` are not in the element.
121
-
122
- ## The hook
123
-
124
- `useChat({ client, pageContext })` returns:
125
-
126
- | Field | What it is |
127
- |---|---|
128
- | `turns` | `[{ id, questionId, question, attachments, answer, streaming, stopped, step, error, actions, messageId, rating, ratingNote }]`, oldest first. `questionId` is the stored question's id (null until the server answers; Edit needs it). `attachments` are the files sent with the question. `stopped` is true when the person stopped the answer. `step` is the name of the tool the assistant is running, or null (set by a `tool` event, cleared when text arrives, on a reset and when the turn ends), for the product to map to its own sentence. `suggestions` are the follow-up questions offered under a settled answer, `[]` when none |
129
- | `client` | The chat client the session talks to; pass it to `ChatConversationList` for the past-chats list |
130
- | `conversationId` | The conversation being continued, or null |
131
- | `messagesLeftToday` | From the last answer or `refreshAllowance()`; null with no daily limit |
132
- | `streaming` | An answer is arriving |
133
- | `loading`, `loadError` | `openConversation` is loading, or failed |
134
- | `settings` | `{ contractVersion, titleMaxLength, attachments }` from `GET {base}/settings`, where `titleMaxLength` caps a chat's renamed title and `attachments` is `{ maxFiles, maxFileBytes, contentTypes }` or null when attachments are off; null until loaded |
135
- | `settingsError` | The settings read failed; the error shows until reset |
136
- | `editing` | `{ turnId, text }` while a question is being edited, or null |
137
- | `attachments` | The files in the question being written: `{ key, fileName, contentType, length, status, progress, error }`, status `Uploading`, `Ready` or `Failed` |
138
- | `submit(message)` | Asks a question. Ignored while an answer is still arriving. |
139
- | `stop()` | Cancels the answer arriving; the question and its files stay in the turn |
140
- | `retry(turnId)` | Sends the last turn again when it failed or was stopped, with its files |
141
- | `regenerate(turnId)` | Asks for a new answer to the last answered turn, replacing it |
142
- | `startEdit(turnId)` | Puts that question and its files back in the box for editing; sending replaces it and every later turn |
143
- | `cancelEdit()` | Leaves editing without sending |
144
- | `attach(files)` | Uploads picked files, each with its progress; a failed upload stays listed with its error |
145
- | `removeAttachment(key)` | Removes a file from the question being written |
146
- | `openConversation(id)` | Replaces the thread with a stored conversation |
147
- | `newConversation()` | Clears the thread; the next question starts a conversation |
148
- | `rate(turnId, rating, note?)` | Saves a rating, shown at once; a failed save puts the old one back and rejects |
149
- | `refreshAllowance()` | Reads the questions left today |
150
- | `reset()` | Clears everything, for sign-out or an account switch |
151
-
152
- An answer still arriving is cancelled on `reset`, `newConversation`, `openConversation` and
153
- unmount. A failed turn keeps the question, drops the half-streamed text and carries `error`
154
- (`{ code, message, resetsAtUtc }`). After `daily_limit`, `messagesLeftToday` becomes 0; after
155
- `conversation_not_found`, the next question starts a new conversation.
156
-
157
- ## Components
158
-
159
- Every component takes `labels`, any subset of `DEFAULT_CHAT_LABELS`, to change its wording. The keys
160
- added for copy, suggestions, citations, past chats and renaming are `copy`, `copied`, `toolStep`,
161
- `suggestions`, `openCitation`, `renameConversation`, `conversationTitle`, `renameSave`,
162
- `renameFailed` and `backToChat`.
163
-
164
- ### `<ChatLauncher />`
165
-
166
- The floating pill that opens the panel. `onClick`, `open` (announced on the button), `position`
167
- (`end` or `start`, the bottom corner), `icon`, `compact`, and `className` and `style` on the
168
- floating wrapper to move it clear of other fixed controls, such as `ReportIssue`. The launcher is
169
- left out of `ReportIssue`'s page capture.
170
-
171
- `compact` makes it a 48px icon-only circle with the label as its tooltip and accessible name. It
172
- joins the shared floating stack (`useFloatingStack` from `@webority/ui-react`), one fixed container
173
- per corner that the compact `ReportIssue` from `@webority/support-react` also uses: the launcher
174
- sits in the corner and the report button stacks above it with a gap, so neither needs an offset.
175
- `className` and `style` then land on the item inside the stack, which is not itself fixed.
176
-
177
- ```jsx
178
- <ChatLauncher compact open={open} onClick={() => setOpen(true)} />
179
- <ReportIssue floating compact />
180
- ```
181
-
182
- ### `<ChatPanel />`
183
-
184
- The drawer: 440px from the right (`width`), the full screen on a phone. Focus stays inside it,
185
- Escape closes it, and the question box takes focus when it opens.
186
-
187
- | Prop | What it does |
188
- |---|---|
189
- | `chat` | The `useChat` result. |
190
- | `open`, `onClose` | Open state and close handler. |
191
- | `title`, `titleIcon` | Header title (default "Assistant") and its library icon. |
192
- | `headerActions` | Extra header controls before New chat, e.g. a past-chats button. |
193
- | `empty` | Shown before the first question. |
194
- | `disclaimer` | The footnote under the question box. |
195
- | `maxLength` | The server's message limit. Default 4000. |
196
- | `allowanceThreshold` | Show the questions left once this many or fewer remain. Default 10. |
197
- | `resolveLink`, `linkComponent` | Reply links; see Replies below. |
198
- | `confirmAction`, `onViewTicket` | Support action cards; see `ActionCard`. |
199
- | `rating` | Offer ratings under stored replies. Default true. |
200
- | `renderReply` | Draws each assistant reply your way; see Custom reply rendering below. |
201
- | `openAttachment` | Opens a file attached to a question, called with `{ publicId, fileName, contentType, length }`. The session has no open action, so the app supplies one, for example with `client.getAttachment(publicId)` (the bytes) and a blob URL: `(file) => client.getAttachment(file.publicId).then((bytes) => window.open(URL.createObjectURL(new Blob([bytes], { type: file.contentType }))))`. Without it the attachment chips on a question are not buttons. |
202
- | `conversations` | Off by default. When true, a history icon in the header (labelled `labels.conversations`) shows the person's past chats in place of the conversation; opening one loads it. A back icon (labelled `labels.backToChat`) returns to the chat. |
203
- | `isCitation`, `onOpenCitation` | Draw a run of the reply as a citation chip and handle its press; see Citation chips. |
204
- | `labels` | Replacements for any subset of `DEFAULT_CHAT_LABELS`. |
205
-
206
- ### `<ChatThread />`, `<ChatMessage />`, `<ChatComposer />`
207
-
208
- The panel's parts, for a product that lays out its own assistant page. `ChatThread` takes
209
- `turns`, `empty`, `onRate`, `resolveLink`, `linkComponent`, `confirmAction`, `onViewTicket`,
210
- `renderReply`, `onRetry`, `onRegenerate`, `onEdit`, `onOpenAttachment`, `onAskSuggestion`, `isCitation` and `onOpenCitation`. `onRetry` is offered on the
211
- last turn only, `onRegenerate` (New answer) on the last answered turn only, `onEdit` beside each
212
- question that has a `questionId`, and `onOpenAttachment` makes each attachment chip a button.
213
- Each answer is a polite live region, marked busy while it streams. `ChatMessage` draws one turn with the same reply props. Under a settled answer, `onAskSuggestion(text)` offers the suggested follow-up questions; `ChatPanel` wires it to send the chosen question through `submit`.
214
-
215
- `ChatComposer` takes `onSubmit`, `busy`, `disabled`, `maxLength` and `inputRef`; Enter sends, Shift
216
- and Enter starts a new line. With `onStop` it shows Stop in place of Send while `busy`. With
217
- `onAttach` it shows the attach button, and `accept` sets the file types the picker offers; the picked
218
- files come to `onAttach(files)`, and `attachments` (each with `key`, `fileName`, `status`, `progress`
219
- and `error`) show as chips that `onRemoveAttachment(key)` removes. `editing` (`{ text }`) fills the
220
- box and shows the editing notice, whose Cancel calls `onCancelEdit`.
221
-
222
- ### `<ReplyRating />`
223
-
224
- Helpful and Not helpful under a reply. Either saves at once; Not helpful then offers an optional
225
- note, saved with the same rating. Takes `rating` and `onRate(rating, note?)`.
226
-
227
- ### `<ChatConversationList />`
228
-
229
- Past chats, newest first, for a page or a panel: `client`, `onOpen(conversation)`,
230
- `onDeleted(id)` and `pageSize` (default 20). It pages with Show more, opens one through `onOpen`,
231
- renames one in place and deletes one after a confirm. The rename form caps the title at the
232
- server's `titleMaxLength`. If the settings read fails, its message shows in the rename form and Save
233
- stays enabled, because the server enforces the limit. The component calls `client.getSettings()`
234
- only when the client has that method.
235
-
236
- ### The paged past-chats list
237
-
238
- `createConversationList({ client, pageSize })` (exported from `@webority/chat-react`) builds the
239
- state the component draws. It returns `getState()`, `subscribe(listener)`, `load()` (reads the first
240
- page and replaces the list), `loadMore()` (reads the next page), `rename(id, title)`, `remove(id)`
241
- and `dispose()`. `getState()` returns `{ items, totalCount, loading, error, hasMore }`, where
242
- `error` is `{ code, message, resetsAtUtc }` and its message is written for the person.
243
-
244
- The client it reads from provides `listConversations({ page, pageSize })`, which resolves to a
245
- `PagedDataObject` `{ items, page, pageSize, totalCount, totalPages }`, plus `renameConversation(id,
246
- title)`, `deleteConversation(id)` and `getSettings()`.
247
-
248
- ### `<ActionCard />`
249
-
250
- One support action under a reply: what will be sent, then Confirm or Not now. It moves through
251
- sending to done (with View ticket when `onViewTicket` is given), and an expired action shows
252
- without a button. Takes `action`, `confirmAction(token)` and `onViewTicket(ticket)`.
253
-
254
- ### `<ConfirmCard />`
255
-
256
- One general card for an action the assistant prepared. Nothing happens until the person presses
257
- Confirm. It moves through sending to done, showing the message `onConfirm` resolves to (or Done.),
258
- and a failed confirm shows its message and stays ready to try again. Not now dismisses it without
259
- sending. Takes `title`, `subtitle`, `lines` (strings, one paragraph each), `note` (replaces the
260
- default "Nothing is sent until you confirm."), `onConfirm()` and `labels`.
261
-
262
- ```jsx
263
- <ConfirmCard
264
- title="Archive project"
265
- subtitle="Planning"
266
- lines={["Moves the project to the archive."]}
267
- onConfirm={() => archiveProject(projectId)}
268
- />
269
- ```
270
-
271
- ### Citation chips
272
-
273
- A reply can cite its sources as `[Clause 4.2]`. `splitCitations(text, isCitation)` splits the reply into text parts and citation parts. The function lives in `@webority/markdown-core`; `@webority/chat-react` re-exports it, so the import stays the same. `CitationChip` draws each citation as a chip that opens its source. Only the runs that `isCitation` accepts become chips: a markdown link such as `[text](url)` and an empty `[]` stay text. `CitationChip` takes `citation`, `onOpen(citation)`, and optionally `label` (the chip text, defaulting to the citation) and `ariaLabel`. `ChatMarkdown`, `ChatMessage`, `ChatThread` and `ChatPanel` take `isCitation` and `onOpenCitation`: a run that `isCitation` accepts draws as a chip, and pressing it calls `onOpenCitation(citation)` with the citation text.
274
-
275
- ```jsx
276
- const parts = splitCitations(reply.text, (inner) => sources.has(inner));
277
-
278
- {parts.map((part, i) =>
279
- "citation" in part ? (
280
- <CitationChip key={i} citation={part.citation} onOpen={openSource} />
281
- ) : (
282
- <span key={i}>{part.text}</span>
283
- ),
284
- )}
285
- ```
286
-
287
- ## Replies
288
-
289
- `<ChatMarkdown text resolveLink linkComponent />` draws a reply through `AppMarkdown` from
290
- `@webority/ui-react`, with the chat link and heading rules: paragraphs, bold, italics, inline code,
291
- bullet and numbered lists, tables, headings (as bold lines) and code blocks. It never renders HTML:
292
- every character reaches the page as text. Text still arriving updates the last block in place, and an unclosed `**` shows as typed
293
- until its partner arrives.
294
-
295
- A link shows only when its href has the form `scheme:kind/id` (for example `ticket:support/3f2a`)
296
- and `resolveLink(href)` returns an in-app route starting with `/`. Any other link, including every
297
- web address, shows its label as plain text. Pass the router's `Link` as `linkComponent` so a link
298
- navigates inside the portal.
299
-
300
- Each settled answer has a Copy button that copies the answer as plain text, without the markdown marks.
301
-
302
- While a tool runs, the waiting line reads `labels.toolStep(name)`. It receives the server's tool name and defaults to "Looking this up", so the name never shows unless the product maps it to the person's words.
303
-
304
- ### Custom reply rendering
305
-
306
- A product that draws replies its own way (charts, maths) passes `renderReply` to `ChatPanel`,
307
- `ChatThread` or `ChatMessage`. It is called as `renderReply(turn, { streaming })` for each
308
- assistant reply that has text, and what it returns replaces `ChatMarkdown`. `turn.answer` is the
309
- text so far, and `streaming` is true while it is still arriving. The person's question, the
310
- "thinking" state, errors, action cards, the rating and the layout stay the library's. With no
311
- `renderReply`, replies render as above.
312
-
313
- ```jsx
314
- <ChatPanel
315
- chat={chat}
316
- open={open}
317
- onClose={() => setOpen(false)}
318
- renderReply={(turn, { streaming }) => <RichReply text={turn.answer} live={streaming} />}
319
- />
320
- ```
@@ -1,216 +0,0 @@
1
- {
2
- "format": "webority-guidance/1",
3
- "package": {
4
- "name": "@webority/chat-react",
5
- "version": "0.127.0"
6
- },
7
- "components": [
8
- {
9
- "name": "ActionCard",
10
- "usage": {
11
- "when": [
12
- "One support action the assistant prepared, shown under its reply for the person to confirm before anything reaches support."
13
- ],
14
- "whenNot": [],
15
- "do": [],
16
- "dont": [],
17
- "a11y": [
18
- "The done message is an alert with role status, so it is announced when the ticket is raised.",
19
- "Confirm and Not now are native buttons with text labels, and Not now is disabled while the request is sending.",
20
- "A failed confirm shows its message in a danger alert and puts the card back to ready so the person can try again."
21
- ]
22
- }
23
- },
24
- {
25
- "name": "ChatComposer",
26
- "usage": {
27
- "when": [
28
- "The question box where the person types a question for the assistant: Enter sends it and Shift and Enter starts a new line."
29
- ],
30
- "whenNot": [],
31
- "do": [],
32
- "dont": [],
33
- "a11y": [
34
- "The form and its text box are both named by the composer label.",
35
- "The text box is described by a visually hidden hint, so the Enter and Shift and Enter keys are announced.",
36
- "Send is a submit button whose only text is the visually hidden send label next to a send icon, and it is disabled while busy, disabled or empty."
37
- ]
38
- }
39
- },
40
- {
41
- "name": "ChatConversationList",
42
- "usage": {
43
- "when": [
44
- "The person's past chats, newest first, for a past-chats page or a panel."
45
- ],
46
- "whenNot": [],
47
- "do": [],
48
- "dont": [],
49
- "a11y": [
50
- "The chats are a list named by the conversations label.",
51
- "Each chat is a button showing its title and a time element that carries the date, and the delete icon button is named by the delete label.",
52
- "Deleting asks for confirmation in a dialog first, and the loading skeleton is hidden from assistive technology.",
53
- "Renaming turns the row into a labelled text field: Enter saves, Escape cancels, and only one row edits at a time."
54
- ]
55
- }
56
- },
57
- {
58
- "name": "ChatLauncher",
59
- "usage": {
60
- "when": [
61
- "The floating pill that opens the assistant, pinned to a bottom corner."
62
- ],
63
- "whenNot": [],
64
- "do": [],
65
- "dont": [],
66
- "a11y": [
67
- "The button announces that it opens a dialog (aria-haspopup) and whether it is open (aria-expanded).",
68
- "The default pill shows the launcher label as its button text.",
69
- "The compact circle takes the launcher label as its accessible name and as its tooltip."
70
- ]
71
- }
72
- },
73
- {
74
- "name": "ChatMarkdown",
75
- "usage": {
76
- "when": [
77
- "A chat reply is written in Markdown and must render as text, never as HTML.",
78
- "A reply may point at in-app records, and the host decides which links become routes."
79
- ],
80
- "whenNot": [],
81
- "do": [],
82
- "dont": [],
83
- "a11y": [
84
- "Lists render as real ordered and unordered lists, and tables render as the markdown table, with a header row.",
85
- "Code blocks have a Copy button.",
86
- "A link renders only when the host maps it to a route; any other link shows its label as plain text.",
87
- "Headings render as bold lines, not heading elements, so a reply does not change the page outline."
88
- ]
89
- }
90
- },
91
- {
92
- "name": "ChatMessage",
93
- "usage": {
94
- "when": [
95
- "Show one question and its answer inside a chat thread.",
96
- "Draw a single stored or streaming turn on its own, such as in a history view."
97
- ],
98
- "whenNot": [
99
- {
100
- "text": "Showing the whole conversation, oldest turn first, with the newest text kept in view.",
101
- "instead": "ChatThread"
102
- }
103
- ],
104
- "do": [],
105
- "dont": [],
106
- "a11y": [
107
- "The answer sits in a polite live region, so a screen reader reads it once it settles; it is marked busy while it streams.",
108
- "Visually hidden labels name who is speaking, taken from the You and Assistant labels.",
109
- "While the first text is awaited, a spinner carries the Thinking label."
110
- ]
111
- }
112
- },
113
- {
114
- "name": "ChatPanel",
115
- "usage": {
116
- "when": [
117
- "Offer the assistant as a drawer that opens from a launcher.",
118
- "Show the conversation, the question box, the questions left today and the footnote in one place."
119
- ],
120
- "whenNot": [
121
- {
122
- "text": "Showing only the conversation inside a page.",
123
- "instead": "ChatThread"
124
- }
125
- ],
126
- "do": [],
127
- "dont": [],
128
- "a11y": [
129
- "Focus stays inside the drawer while it is open, Escape closes it, and the question box takes focus when it opens.",
130
- "The drawer is named by its title.",
131
- "The questions left note is a status region."
132
- ]
133
- }
134
- },
135
- {
136
- "name": "ChatThread",
137
- "usage": {
138
- "when": [
139
- "Show a whole conversation, oldest turn first, in a panel or a page.",
140
- "Let the thread follow the newest text as an answer streams."
141
- ],
142
- "whenNot": [
143
- {
144
- "text": "Showing one turn on its own.",
145
- "instead": "ChatMessage"
146
- },
147
- {
148
- "text": "Showing the full assistant drawer with its header and question box.",
149
- "instead": "ChatPanel"
150
- }
151
- ],
152
- "do": [],
153
- "dont": [],
154
- "a11y": [
155
- "The turns are an ordered list named by the thread label.",
156
- "Each answer is a polite live region; see ChatMessage.",
157
- "Only the nearest box that scrolls on its own follows the newest text, so the page itself never jumps."
158
- ]
159
- }
160
- },
161
- {
162
- "name": "CitationChip",
163
- "usage": {
164
- "when": [
165
- "Show a source the assistant named in a reply as a small chip the person can select to open it.",
166
- "Pair it with splitCitations from @webority/markdown-core (re-exported by @webority/chat-react) to turn [source] runs in reply text into chips."
167
- ],
168
- "whenNot": [
169
- {
170
- "text": "Showing a general label or removable token that is not a source.",
171
- "instead": "AppChip"
172
- }
173
- ],
174
- "do": [],
175
- "dont": [],
176
- "a11y": [
177
- "The chip is a button named by ariaLabel, or by the citation when none is given.",
178
- "Selecting it by pointer or keyboard calls onOpen with the citation."
179
- ]
180
- }
181
- },
182
- {
183
- "name": "ConfirmCard",
184
- "usage": {
185
- "when": [
186
- "The assistant has prepared an action and nothing should happen until the person says yes.",
187
- "The action is one step the person can send now or decline."
188
- ],
189
- "whenNot": [],
190
- "do": [],
191
- "dont": [],
192
- "a11y": [
193
- "Confirm and Not now are native buttons, and Confirm shows its loading state while the action is sent.",
194
- "The done message is a status message.",
195
- "A failed confirm shows its message in an alert above the buttons and returns the card to ready."
196
- ]
197
- }
198
- },
199
- {
200
- "name": "ReplyRating",
201
- "usage": {
202
- "when": [
203
- "A reply can be rated helpful or not helpful, with an optional note after a not helpful rating."
204
- ],
205
- "whenNot": [],
206
- "do": [],
207
- "dont": [],
208
- "a11y": [
209
- "Both rating buttons are native buttons that expose their state through aria-pressed.",
210
- "The thank you line is a status message.",
211
- "The note field has a visible label and a hint, and the person can send the note or skip it."
212
- ]
213
- }
214
- }
215
- ]
216
- }