@bloonio/chat-angular 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+## 0.2.0
+
+Backwards compatible with 0.1.x.
+
+### Added
+
+- `locale` (`'fr' | 'en' | 'zh'`, default `'en'`): built-in translations for
+  every string the widget renders itself, also sent with each new visitor
+  session. It may be a function or a signal, and `provideBloonioChat` accepts
+  a factory run in an injection context, so the widget can follow the host
+  app's language at runtime. With no `locale`, sessions are still created
+  with `fr`, as in 0.1.x.
+- Host copy: `greeting`, `launcherLabel`, `onlineStatusText`,
+  `offlineStatusText`, `quickReplies`. Each replaces the matching text of the
+  tenant's single-language relay config and may be a function or a signal.
+  The greeting is a local opening bubble, never sent or stored.
+- Unread badge on the launcher for answers received while the panel is
+  closed; the count is in its accessible name.
+- Resume after a reload: the visitor session is stored per tenant in
+  `localStorage`; on load the token is refreshed, the thread replayed and the
+  socket reopened. A session the relay refuses is replaced by a fresh one
+  without an error. Not applied when a `visitorTokenProvider` is configured.
+- The panel says so when the chat is connecting or cannot be reached, and
+  reopening it retries. The input is disabled while there is no session.
+- Accessibility: `aria-expanded` on the launcher, the floating panel is a
+  labelled dialog that takes focus on open, Escape closes it and focus
+  returns to the launcher, the message list is a `log` region, the input bar
+  shows keyboard focus.
+- `BloonioChatService.visibleMessages`.
+- Specs (`npm test`).
+
+### Fixed
+
+- Bubbles are aligned again (visitor right, answers left, notices centred):
+  the message list host no longer sits between the flex column and its
+  items.
+- The typing dots clear when the answer arrives, and after 30 seconds
+  without a new typing frame.
+- The input and the quick replies wait for the socket's welcome frame, so a
+  message can no longer be typed or tapped before it can be sent
+  (`connecting` now lasts until then).
+- Messages received while the panel was open no longer count as unread once
+  it is closed.
+- A socket the relay closes with 4401, 4403 or 4404 is no longer retried
+  forever with the same token.
+- The header initials are styled from the stylesheet, not a style attribute
+  (a strict CSP dropped it).
+
+### Changed
+
+- The ticket notice no longer carries an emoji or a dash, and the agent
+  joined / left notices lose their final period.

package/README.md

@@ -46,22 +46,135 @@ export const appConfig: ApplicationConfig = {
 ```
 
 ```ts
-// any standalone component — drop the launcher anywhere
-import { BloonioChatLauncherComponent } from '@bloonio/chat-angular';
+// any standalone component — the launcher toggles the panel next to it
+import {
+  BloonioChatLauncherComponent,
+  BloonioChatPanelComponent,
+} from '@bloonio/chat-angular';
 
 @Component({
   standalone: true,
-  imports: [BloonioChatLauncherComponent],
-  template: `<router-outlet /> <bloonio-chat-launcher />`,
+  imports: [BloonioChatLauncherComponent, BloonioChatPanelComponent],
+  template: `<router-outlet /> <bloonio-chat-launcher /> <bloonio-chat-panel />`,
 })
 export class AppComponent {}
 ```
 
+## Language
+
+`locale` picks the built-in translation of every string the widget renders
+itself (placeholder, labels, connection and error lines, agent and ticket
+notices, aria-labels). Supported: `'fr'`, `'en'`, `'zh'`. Default `'en'`; a
+region is trimmed (`'fr-FR'` is `'fr'`) and anything else falls back to
+English.
+
+The configured value is also sent, as given, with each new visitor session.
+With no `locale` configured the session is created with `fr`, as in 0.1.x.
+
+Text configured on the relay (status texts, launcher label, offline message,
+quick replies) is shown as received, unless the host supplies its own: see
+"Host copy" below.
+
+To follow the host app's language at runtime, pass a function. A signal is
+one, and `provideBloonioChat` accepts a factory that runs in an injection
+context so it can reach your own language service:
+
+```ts
+provideBloonioChat(() => ({
+  tenantId: '019e4ae7-…',
+  publicKey: 'pk_…',
+  baseUrl: 'https://chat-relay.example.com',
+  locale: inject(MyI18nService).lang, // Signal<'fr' | 'en'>
+})),
+```
+
+The widget's strings switch immediately. A conversation keeps the language
+it was opened with.
+
+## Host copy
+
+A tenant's relay config holds one language. These optional entries replace
+the matching tenant text; each takes a value or a function (a signal works),
+so it can follow the host's language. Left out, the tenant's text is used.
+
+| Entry | Replaces |
+|---|---|
+| `greeting` | Nothing on the relay: an opening bubble drawn like an assistant message at the top of a new conversation. It is local only (never sent, never stored), stays above the first messages, and is not shown above a thread replayed after a reload. When set, the tenant's offline message is not shown. |
+| `launcherLabel` | The label next to the launcher. An empty string shows no label. |
+| `onlineStatusText` | The header subtitle during opening hours. |
+| `offlineStatusText` | The header subtitle outside opening hours. |
+| `quickReplies` | The suggested replies shown until the visitor's first message. |
+
+```ts
+provideBloonioChat(() => {
+  const i18n = inject(MyI18nService);
+  return {
+    tenantId: '019e4ae7-…',
+    publicKey: 'pk_…',
+    baseUrl: 'https://chat-relay.example.com',
+    locale: i18n.lang,
+    launcherLabel: '',
+    greeting: () => i18n.t('chat.greeting'),
+    onlineStatusText: () => i18n.t('chat.online'),
+    quickReplies: () => [i18n.t('chat.reply.sales'), i18n.t('chat.reply.help')],
+  };
+}),
+```
+
+## Resume after a reload
+
+The visitor session (`session_id`, `visitor_token`, `expires_at`) is kept in
+`localStorage` under `bloonio:chat:<tenantId>:session`. On the next page
+load the widget refreshes the token (`POST /refresh/visitor-token`), replays
+the newest 50 messages (`GET /fetch/visitor-messages`) and reopens the
+socket in the background, so a visitor waiting for an agent keeps the
+thread and still receives the reply with the panel closed.
+
+When the session cannot be resumed (the relay answers 4xx, or closes the
+socket with 4401 / 4404) the stored session is dropped and a new one starts
+the next time the panel is open, with no error shown. A network failure
+keeps the stored session for the next load. Nothing is read or written on
+the server, and when storage is blocked the chat works without resume.
+
+Sessions are not stored when a `visitorTokenProvider` is configured: an
+identified visitor's thread would otherwise show to the next account on the
+same browser. An anonymous thread stays resumable on that browser for as
+long as the relay keeps the session, shared computers included.
+
+## Theming
+
+Colours, radius, shadow and font are CSS variables declared on `.bch-root`.
+Redeclare them in a rule placed after the stylesheet import:
+
+```css
+@import "@bloonio/chat-angular/styles.css";
+
+.bch-root {
+  --bch-primary: #0b5d3b;
+  --bch-bg: #ffffff;
+  --bch-font: "Inter", sans-serif;
+}
+```
+
+Variables: `--bch-primary`, `--bch-primary-contrast`, `--bch-bg`,
+`--bch-surface`, `--bch-text`, `--bch-text-muted`, `--bch-border`,
+`--bch-radius`, `--bch-shadow`, `--bch-font`. The tenant's branding colour,
+when set on the relay, is applied inline as `--bch-primary` on `.bch-root`
+and `.bch-panel`; mark your own value `!important` on both to keep it.
+
+## Accessibility
+
+The launcher is a labelled toggle (`aria-expanded`). Answers received while
+the panel is closed show as a count badge on it, and the count is part of
+its accessible name. The floating panel is a non-modal dialog: opening moves
+focus into it, Escape or its close button closes it and returns focus to the
+launcher, and new messages are announced through a `log` region.
+
 ## Three rendering modes
 
 | Mode | Component | When |
 |---|---|---|
-| **Floating** | `<bloonio-chat-launcher />` (+ the launcher renders the panel itself on toggle) | Tidio-style — a bubble in the corner that expands on click. |
+| **Floating** | `<bloonio-chat-launcher />` + `<bloonio-chat-panel />` | Tidio-style — a bubble in the corner that expands on click. |
 | **Docked panel** | `<bloonio-chat-panel mode="docked" />` | Always-on chat in a sidebar / dedicated column. No floating chrome. |
 | **Headless thread** | `<bloonio-chat-thread />` | Just messages + input, no header. Embed inside your own support pages. |
 
@@ -98,7 +211,8 @@ For tenants on `@angular/ssr`, no extra configuration is needed.
 ```bash
 npm install
 npm run build       # ng-packagr → dist/ (fesm2022 + .d.ts + Ivy partial)
-npm run typecheck   # tsc --noEmit -p tsconfig.lib.json
+npm run typecheck   # tsc --noEmit (sources + specs)
+npm test            # vitest (jsdom): locale, resume, focus handling
 ```
 
 Every component uses inline `template:` strings, so there are no separate