guideai-app 0.5.4-2 → 0.5.4-8

package/README.md

@@ -37,19 +37,83 @@ function App() {
 | Prop                              | Type       | Required             | Description                                                                                                                                                                         |
 | --------------------------------- | ---------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `authKey`                         | `string`   | Yes (customer embed) | Widget access key; **not** persisted by the package. Exchanged once for a JWT via `POST /widget/session`. **Do not use React’s reserved `key` attribute** — use this prop name.     |
-| `workspace`                       | `string`   | No                   | Workspace slug to use for the realtime session. Forwarded on the `/initialize` body so the server can pick a non-default workspace per request. Omit to use the customer default.   |
+| `workspace`                       | `string`   | No                   | Default workspace **slug** for the first realtime session (single value). Forwarded on `/initialize`. Omit to use the customer default. When used with `workspaces`, pick a slug from that allowlist. |
+| `workspaces`                      | `string` or `string[]` | No | Catalog allowlist: limits which workspaces (and their workflows) end users can access. Omit for all customer workspaces. Comma-separated string (`"sales,support"`) or array. Invalid/empty allowlist removes the widget and logs `console.error`. |
 | `getUserInfo`                     | `function` | No                   | Lets Guide AI know who is signed in on your app (see **Signed-in users** below). |
 | `initializeUserId`               | `string`   | No                   | Advanced: optional fixed user id when you manage identity yourself. |
 | `adminConversationPersistenceKey` | `string`   | No                   | Optional stable key for transcript `localStorage` isolation. Omit to use a non-secret default from the page **origin** (same across SPA routes). Never use the raw access key here. |
 | `React`                           | `React`    | Yes                  | React instance from your application                                                                                                                                                |
 | `ReactDOM`                        | `ReactDOM` | Yes                  | ReactDOM instance from your application                                                                                                                                             |
 | `position`                        | `object`   | No                   | CSS positioning for the component (see below)                                                                                                                                       |
+| `launcher`                        | `object`   | No                   | Launcher presentation: floating mic circle (default) or a draggable side tab (see below)                                                                                            |
 | `environment`                     | `string`   | No                   | API environment: `'production'` (default), `'development'`, or `'local'`                                                                                                            |
 | `transcript`                      | `object`   | No                   | Transcript panel configuration (see below)                                                                                                                                          |
 | `input`                           | `object`   | No                   | Text/voice input configuration (see below)                                                                                                                                          |
+| `theme`                           | `string`   | No                   | Built-in color theme preset id (see **Themes** below). Omit for the package default palette.                                                                                        |
 
 You must pass **`authKey`** (customer integration). For authentication details, see **`AUTHENTICATION.md`** in this package.
 
+## Themes
+
+Set the widget color palette with the `theme` prop. All presets are bundled in `guideai-app`; no extra scripts or CDN files are required.
+
+```jsx
+<GuideAI
+	authKey="your-access-key"
+	workspace="your-workspace"
+	React={React}
+	ReactDOM={ReactDOM}
+	theme="dark"
+/>
+```
+
+Role-based catalog example:
+
+```jsx
+<GuideAI
+	authKey={accessKey}
+	workspace="support"
+	workspaces={user.role === 'admin' ? 'admin,support' : 'support'}
+	React={React}
+	ReactDOM={ReactDOM}
+/>
+```
+
+Omit `theme` (or pass `null`) to use the default package palette (**Studio blue**).
+
+### Light themes
+
+| `theme` id     | Name  |
+| -------------- | ----- |
+| `light-ivory`  | Ivory |
+| `light-snow`   | Snow  |
+| `light-sand`   | Sand  |
+| `light-mist`   | Mist  |
+| `light-mint`   | Mint  |
+| `light-sky`    | Sky   |
+| `light-coral`  | Coral |
+| `light-rose`   | Rose  |
+| `light-plum`   | Plum  |
+| `light-slate`  | Slate |
+
+### Dark themes
+
+| `theme` id        | Name         |
+| ----------------- | ------------ |
+| `dark`            | Studio blue  |
+| `dark-muted-gray` | Muted gray   |
+| `dark-midnight`   | Midnight     |
+| `dark-ocean`      | Ocean        |
+| `dark-forest`     | Forest       |
+| `dark-teal`       | Teal         |
+| `dark-violet`     | Violet       |
+| `dark-ember`      | Ember        |
+| `dark-carbon`     | Carbon       |
+| `dark-ruby`       | Ruby         |
+| `dark-graphite`   | Graphite     |
+
+TypeScript hosts can import `GuideAIThemeId` or `GUIDEAI_THEME_IDS` from `guideai-app`. Labels are also available on `GUIDEAI_PRESET_THEMES`.
+
 ## Position Object
 
 The `position` prop accepts an object with CSS positioning properties to control where the Guide AI button appears on your page, as well as z-index configuration for all Guide AI components:
@@ -124,6 +188,46 @@ position?: {
 />
 ```
 
+## Launcher Object
+
+The `launcher` prop selects how the idle Guide AI control is presented:
+
+```typescript
+launcher?: {
+  variant?: 'mic' | 'tab'; // 'mic' (default): floating circle. 'tab': edge-docked side tab.
+  side?: 'left' | 'right'; // Tab variant only — screen edge to dock to (default: 'right')
+}
+```
+
+The tab behaves exactly like the mic circle (click to start/end a conversation, same status
+colors and idle prompt animations), but it sits flush against the screen edge and can be
+**dragged up and down** that edge. The dragged offset is persisted in `localStorage` per
+conversation key, so the tab stays where the user left it. With `variant: 'tab'`, the CSS
+placement properties of `position` are ignored (`position.zIndex` still applies), and the
+transcript defaults to opening on the same side as the tab.
+
+**Right-edge tab:**
+
+```jsx
+<GuideAI
+	authKey="your-access-key"
+	React={React}
+	ReactDOM={ReactDOM}
+	launcher={{ variant: 'tab' }}
+/>
+```
+
+**Left-edge tab:**
+
+```jsx
+<GuideAI
+	authKey="your-access-key"
+	React={React}
+	ReactDOM={ReactDOM}
+	launcher={{ variant: 'tab', side: 'left' }}
+/>
+```
+
 ## Transcript Object
 
 The `transcript` prop controls the conversation transcript panel:

package/dist/GuideAI.d.ts

@@ -1,6 +1,3 @@
 import { GuideAIProps } from './types/GuideAI.types';
-/**
- * Default export is the GuideAI React component.
- */
-declare const GuideAI: (props: GuideAIProps) => import("react").JSX.Element | null;
-export default GuideAI;
+declare const GuideAIComponent: (props: GuideAIProps) => import("react").JSX.Element | null;
+export default GuideAIComponent;