Ask Arbor Standalone Component

Self-contained AI chat widget and React component library. No arbor-fe ecosystem dependencies.

Published as two artefacts:

• 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

Quick start (widget dev)

yarn install
make dev

Opens http://localhost:5173/playground/widget-demo.html with hot reload. Mock API endpoints are included — no backend or build step needed.

Scripts

| Command | What it does | |---|---| | yarn dev / make dev | Hot-reload widget demo (playground/widget-demo.html) | | 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 | 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 | | yarn style-lint | Stylelint check for SCSS |

Widget integration (production)

Floating button + Slideover (ask-arbor-slideover.js)

Drop one <script> into any HTML page — no React, no CSS imports required:

<script src="ask-arbor-slideover.js"></script>
<script>
AskArborSlideover.init({
    chatUrl: 'https://your-api.example.com/chat',
    openOnStart: false,       // true → opens immediately
    position: 'bottom-right', // 'bottom-right' | 'bottom-left'
    authorizationToken: 'eyJ...',  // optional JWT — sent as Authorization: Bearer
});
</script>

Bare panel (ask-arbor-widget.js)

Embed the chat panel directly into any container element — no floating button, no Slideover chrome:

<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 the config on window before loading the script and init runs automatically:

<!-- Floating button widget -->
<script>
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

// Floating button
AskArborSlideover.init(config)
AskArborSlideover.destroy()

// Bare panel
AskArborWidget.init(container, config)
AskArborWidget.destroy()

React component (NPM package)

Installation

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:

import { AskArborWidget } from '@arbor-education/ask-arbor-chat-panel';
import '@arbor-education/ask-arbor-chat-panel/style.css';

<AskArborWidget
    connector={connector}
    onClose={() => setOpen(false)}
/>

Slideover-wrapped (AskArborSlideover) — renders inside the Arbor design system Slideover:

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:

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:

<script src="https://unpkg.com/@arbor-education/ask-arbor-chat-panel/dist-iife/ask-arbor-slideover.js"></script>

Releasing

Releases are managed via Changesets.

Creating a changeset

When your change is ready, run:

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.

API shape

POST chatUrl

Request:

{
    "chatId": "string | undefined",
    "userMessage": "string",
    "canvasMode": false
}

Response:

{
    "items": [{
        "id": "string",
        "text": "string",
        "type": "AGENT",
        "chatId": "string (optional)"
    }]
}

Authorization

Pass authorizationToken to the widget/component. Every request will include:

Authorization: Bearer <token>

Project structure

src/
  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
    getNewAgentMessage.ts
    getHistoricMessages.ts
    sendNotification.ts
    sendMessageRating.ts
playground/
  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
  AskArborSlideover.test.tsx