@clubmed/usg-chat-ui 1.2.6 → 1.3.0

package/README.md

@@ -63,6 +63,42 @@ export function ChatPanel() {
 
 If you need to customize HTTP transport or headers, provide a `fetcher` override or extend the HTTP client directly—`ChatProvider` keeps the config surface minimal (`apiUrl`, `fetcher`, `accessToken`, `user`).
 
+## Labels & Accessibility
+
+The chat UI exposes a `labels` prop on `<Chat />` so hosts can override empty‑state copy, greeting templates, and every aria-label used throughout the experience without editing component logic.
+
+```tsx
+<Chat
+  labels={{
+    greetingTemplate: "Hola {{firstName}} 👋",
+    emptyStateTitle: "¡Bienvenido a tu copiloto!",
+    chatSettingsButtonAriaLabel: "Preferencias",
+  }}
+/>
+```
+
+Under the hood, the `ChatLabelsProvider` and `useChatLabels()` hook distribute these strings to all molecules. The hook exposes two helpers:
+
+- `get(key, fallback)` → returns a plain string, falling back to the provided default when the host didn’t override it.
+- `p(key, fallback, values)` → interpolates templates (e.g. `{{firstName}}`) and trims whitespace. Returns `undefined` when the final string is empty.
+
+### Available label keys
+
+| Key                                                                                                | Purpose / Example                                                     |
+|----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
+| `greetingTemplate`                                                                                 | Template for the empty-state greeting (`"Bonjour {{firstName}} 👋"`). |
+| `emptyStateTitle` / `emptyStateDescription`                                                        | Marketing copy for the empty state.                                   |
+| `assistantThinkingIndicator`                                                                       | Pulsing text while the assistant is streaming.                        |
+| `chatSettingsButtonAriaLabel`                                                                      | Settings button aria label.                                           |
+| `sidebarOpenHistoryAriaLabel`, `conversationRefreshAriaLabel`, `conversationCloseHistoryAriaLabel` | Sidebar toggle & controls.                                            |
+| `messageCopyAriaLabel`, `messageRegenerateAriaLabel`, `messageOpenCanvasAriaLabel`                 | Message action buttons.                                               |
+| `messageThumbsUpAriaLabel`, `messageThumbsDownAriaLabel`, `messageCloseFeedbackAriaLabel`          | Feedback modal controls.                                              |
+| `canvasReduceAriaLabel`, `canvasExpandAriaLabel`, `canvasCloseAriaLabel`                           | Canvas panel controls.                                                |
+| `branchPreviousAriaLabel`, `branchNextAriaLabel`                                                   | Multi-branch navigation buttons.                                      |
+| `promptSubmitAriaLabel`                                                                            | Submit icon on the prompt composer.                                   |
+
+> **Implementation convention:** All new user-facing strings or aria labels **must** use `useChatLabels()` (`const {get, p} = useChatLabels();`) instead of hard-coded literals. Declare the key inside `ChatLabelsConfig` with a short JSDoc example, then consume it via `get/p` with a sensible fallback so the UI remains resilient when a host doesn’t override that value yet.
+
 ## Storybook
 
 Storybook v10 is configured at the workspace root (`usg-ui/.storybook`). Run `yarn storybook` from `usg-ui/` to browse molecules and verify appearance tokens in isolation. The build output (`storybook-static`) can be published alongside the npm package for visual regression if desired.