@arbor-education/ask-arbor-chat-panel 1.0.0 → 1.1.0

package/README.md

@@ -3,8 +3,8 @@
 Self-contained AI chat widget and React component library. No arbor-fe ecosystem dependencies.
 
 Published as two artefacts:
-- **NPM package** — `ChatPanel` React component for host apps that already use React
-- **IIFE widget** — `ask-arbor-widget.js` drop-in script for any HTML page (Zendesk-style floating button)
+- **NPM package** — `AskArborWidget` (bare panel) and `AskArborSlideover` (panel in Arbor Slideover) React components for host apps that already use React
+- **IIFE widget** — `ask-arbor-slideover.js` (floating button + Slideover) and `ask-arbor-widget.js` (bare panel, embed in any container) for vanilla JS pages
 
 ---
 
@@ -24,10 +24,11 @@ Opens `http://localhost:5173/playground/widget-demo.html` with hot reload. Mock
 | Command | What it does |
 |---|---|
 | `yarn dev` / `make dev` | Hot-reload widget demo (`playground/widget-demo.html`) |
-| `yarn build:widget` | Production IIFE bundle → `dist-widget/ask-arbor-widget.js` |
+| `yarn build:slideover` | Production IIFE bundle → `dist-iife/ask-arbor-slideover.js` |
+| `yarn build:widget` | Production bare panel IIFE → `dist-iife/ask-arbor-widget.js` |
 | `yarn build` | NPM package build → `dist/` |
-| `yarn build:all` | Both builds in sequence |
-| `yarn test` | Run Vitest test suite (87 tests) |
+| `yarn build:all` | All three builds in sequence |
+| `yarn test` | Run Vitest test suite (135 tests) |
 | `yarn test:watch` | Vitest in watch mode |
 | `yarn check-types` | TypeScript type-check with no emit |
 | `yarn eslint` | ESLint check |
@@ -37,12 +38,14 @@ Opens `http://localhost:5173/playground/widget-demo.html` with hot reload. Mock
 
 ## Widget integration (production)
 
+### Floating button + Slideover (`ask-arbor-slideover.js`)
+
 Drop one `<script>` into any HTML page — no React, no CSS imports required:
 
 ```html
-<script src="ask-arbor-widget.js"></script>
+<script src="ask-arbor-slideover.js"></script>
 <script>
-AskArbor.init({
+AskArborSlideover.init({
     chatUrl: 'https://your-api.example.com/chat',
     openOnStart: false,       // true → opens immediately
     position: 'bottom-right', // 'bottom-right' | 'bottom-left'
@@ -51,44 +54,158 @@ AskArbor.init({
 </script>
 ```
 
+### Bare panel (`ask-arbor-widget.js`)
+
+Embed the chat panel directly into any container element — no floating button, no Slideover chrome:
+
+```html
+<div id="my-panel" style="height: 600px;"></div>
+<script src="ask-arbor-widget.js"></script>
+<script>
+AskArborWidget.init(document.getElementById('my-panel'), {
+    chatUrl: 'https://your-api.example.com/chat',
+    authorizationToken: 'eyJ...',
+    onClose: () => { /* handle close button */ },
+});
+</script>
+```
+
 ### Auto-init
 
-Set `window.AskArborConfig` before loading the script and init runs automatically:
+Set the config on `window` before loading the script and init runs automatically:
 
 ```html
+<!-- Floating button widget -->
 <script>
-window.AskArborConfig = {
+window.AskArborSlideoverConfig = {
     chatUrl: 'https://your-api.example.com/chat',
     platform: 'SAM_PEOPLE',
     openOnStart: true,
 };
 </script>
+<script src="ask-arbor-slideover.js"></script>
+
+<!-- Bare panel -->
+<script>
+window.AskArborWidgetConfig = {
+    chatUrl: 'https://your-api.example.com/chat',
+    containerId: 'my-panel',
+};
+</script>
 <script src="ask-arbor-widget.js"></script>
 ```
 
 ### Global API
 
 ```js
-AskArbor.init(config)    // mount the widget
-AskArbor.destroy()       // unmount and clean up
+// Floating button
+AskArborSlideover.init(config)
+AskArborSlideover.destroy()
+
+// Bare panel
+AskArborWidget.init(container, config)
+AskArborWidget.destroy()
 ```
 
 ---
 
 ## React component (NPM package)
 
+### Installation
+
+```bash
+yarn add @arbor-education/ask-arbor-chat-panel
+# or
+npm install @arbor-education/ask-arbor-chat-panel
+```
+
+Peer dependencies: `react ≥18`, `react-dom ≥18`, `@arbor-education/design-system.components ≥0.21`.
+
+### Usage
+
+**Bare panel** (`AskArborWidget`) — embed in your own container or drawer:
+
 ```tsx
-import {ChatPanel} from 'ask-arbor-chat-panel';
-import 'ask-arbor-chat-panel/style.css';
+import { AskArborWidget } from '@arbor-education/ask-arbor-chat-panel';
+import '@arbor-education/ask-arbor-chat-panel/style.css';
 
-<ChatPanel
-    chatUrl="https://your-api.example.com/chat"
-    authorizationToken={jwt}
+<AskArborWidget
+    connector={connector}
     onClose={() => setOpen(false)}
 />
 ```
 
-Peer dependencies: `react ≥18`, `react-dom ≥18`, `@arbor-education/design-system.components ≥0.21`.
+**Slideover-wrapped** (`AskArborSlideover`) — renders inside the Arbor design system Slideover:
+
+```tsx
+import { AskArborSlideover } from '@arbor-education/ask-arbor-chat-panel';
+import '@arbor-education/ask-arbor-chat-panel/style.css';
+
+<AskArborSlideover
+    connector={connector}
+    isOpen={isOpen}
+    onClose={() => setIsOpen(false)}
+/>
+```
+
+Both components require an `IAIServiceConnector` instance. Use `AIServiceConnectorFactory.create(config)` to build one from a config object:
+
+```tsx
+import { AIServiceConnectorFactory, AskArborWidget } from '@arbor-education/ask-arbor-chat-panel';
+
+const connector = AIServiceConnectorFactory.create({
+    chatUrl: 'https://your-api.example.com/chat',
+    authorizationToken: jwt,
+});
+```
+
+`ChatPanel` is also still exported for backwards compatibility.
+
+### Published package contents
+
+```
+dist/
+  index.js          # ESM bundle
+  index.cjs         # CommonJS bundle
+  index.d.ts        # TypeScript declarations
+  style.css         # Component styles (must be imported separately)
+dist-iife/
+  ask-arbor-slideover.js  # IIFE — floating button + Slideover (self-contained)
+  ask-arbor-widget.js     # IIFE — bare embed panel (self-contained)
+```
+
+The IIFE files are self-contained (CSS injected, no dependencies). Reference them via unpkg or jsdelivr:
+
+```html
+<script src="https://unpkg.com/@arbor-education/ask-arbor-chat-panel/dist-iife/ask-arbor-slideover.js"></script>
+```
+
+---
+
+## Releasing
+
+Releases are managed via [Changesets](https://github.com/changesets/changesets).
+
+### Creating a changeset
+
+When your change is ready, run:
+
+```bash
+yarn changeset
+```
+
+Select the bump type (patch / minor / major) and write a short summary. This creates a file in `.changeset/` - commit it with your branch.
+
+### Automated publishing
+
+`.github/workflows/release.yml` runs at 07:00 UTC Monday-Friday. It:
+
+1. Runs `npx changeset version` to apply any pending changesets and bump the package version
+2. Publishes the updated package to npm (only if the version changed)
+3. Creates a GitHub release with a `.tgz` tarball attached
+4. Posts a success/failure notification to Slack
+
+Both `dist/` (React components) and `dist-iife/` (IIFE bundles) are included in the published npm package.
 
 ---
 
@@ -130,21 +247,26 @@ Authorization: Bearer <token>
 
 ```
 src/
-  widget.tsx          # IIFE entry — AskArborWidget + init/destroy
-  ChatPanel.tsx       # Core React component (also the NPM export)
-  platformConfig.ts   # Platform → colour/logo mapping
+  widget.tsx              # IIFE entry — floating button + Slideover (AskArborSlideover)
+  widget-embed.tsx        # IIFE entry — embed panel (AskArborWidget)
+  ChatPanel.tsx           # Core React component
+  AskArborSlideover.tsx   # React component — ChatPanel wrapped in Slideover
   utils/
-    http.ts           # fetch wrapper with Authorization header support
+    http.ts               # fetch wrapper with Authorization header support
     getNewAgentMessage.ts
     getHistoricMessages.ts
     sendNotification.ts
     sendMessageRating.ts
 playground/
-  widget-demo.html    # Widget demo (served by dev:widget)
-  index.html          # React component playground (served by dev)
-  widget-dev-shim.ts  # Dev-only: exposes window.AskArbor from source
-dist-widget/
-  ask-arbor-widget.js # Production IIFE bundle (run build:widget)
+  widget-demo.html        # Floating button widget demo (yarn dev)
+  panel-demo.html         # Bare panel demo (yarn dev → /playground/panel-demo.html)
+  index.html              # React component playground (yarn dev → /playground/)
+  widget-dev-shim.ts      # Dev-only: exposes window.AskArborSlideover from source
+  panel-dev-shim.ts       # Dev-only: exposes window.AskArborWidget from source
+dist-iife/
+  ask-arbor-slideover.js  # Production IIFE — floating button + Slideover (build:slideover)
+  ask-arbor-widget.js     # Production IIFE — bare panel (build:widget)
 tests/
-  ChatPanel.test.tsx  # 87 Vitest tests
+  ChatPanel.test.tsx
+  AskArborSlideover.test.tsx
 ```