@aiden-voice/widget 0.5.3 → 0.6.0

package/README.md

@@ -103,7 +103,9 @@ throws synchronously, at call time, if you pass both or neither.
 | `accentColor` | Link color in replies. Darkened automatically if needed to stay readable. Overrides the color configured in whoo-aiden; omit it to use that one. | whoo-aiden's, else `'#0000ee'` |
 | `name` | Agent name for the panel header and the dialog's screen-reader label ("Chat with {name}"). Overrides the name configured in whoo-aiden; omit it to use that one. | whoo-aiden's, else `'Aiden'` |
 | `greeting` | Welcome text shown in the panel before the first message. | none |
-| `launcherIconUrl` | Image shown on the launcher bubble instead of the default chat icon. `https:` or `data:image/` only. Until it loads, and permanently if it fails, the default icon shows. | none (default icon) |
+| `launcherIconUrl` | Image shown on the launcher bubble instead of the default chat icon. `https:` or `data:image/` only. Until it loads, and permanently if it fails, the default icon shows. Alias of `theme.launcher.iconUrl`. | none (default icon) |
+| `theme` | Colors, font and launcher icons. See [Theming](#theming). | defaults |
+| `layout` | Launcher position and size, and panel size. See [Layout](#layout). | defaults |
 | `emptyStateImageUrl` | Image (e.g. a brand lockup) shown above the greeting while the conversation is empty. `https:` or `data:image/` only. Removed if it fails to load. | none |
 | `emptyStateImageAlt` | Alt text for `emptyStateImageUrl`. Set it when the image carries meaning (e.g. your brand name); omit it for a purely decorative image. | none (decorative) |
 | `showFeedback` | Show thumbs up/down controls under each reply so visitors can rate answers (a thumbs-down opens an optional correction form). | `false` (hidden) |
@@ -114,6 +116,82 @@ throws synchronously, at call time, if you pass both or neither.
 
 Some third-party overlays (accessibility toolbars, chat or cookie widgets) sit at the maximum possible z-index, `2147483647`, in the same corner. No `zIndex` value can beat that: at an equal level, whichever element comes later in the page wins, and those overlays are usually injected after the widget. Move the widget to the other corner with `position: 'bottom-left'` instead.
 
+## Theming
+
+`color`, `inkColor` and `accentColor` set the brand colors, and the widget calculates the rest (the text on your color, the header text, and so on) so everything stays readable. When an edge case breaks that, the `theme` option overrides any individual color, the font, and the launcher icons.
+
+```js
+init({
+  publishableKey: 'pk_live_...',
+  theme: {
+    colors: {
+      // A dark theme: every surface is overridden together with the roles drawn on it.
+      primary: '#0a7d5a',
+      onPrimary: '#ffffff', // text on `primary`; calculated if you leave it out
+      panel: '#0f172a',
+      border: '#334155',
+      headerHover: '#1e293b',
+      primaryText: '#f1f5f9', // header buttons, on `panel` and `headerHover`
+      text: '#f8fafc', // inputs and feedback buttons
+      focusRing: '#f8fafc', // keyboard focus outline, on `panel`
+      assistantBubble: '#1e293b',
+      ink: '#f8fafc',
+      link: '#7dd3fc',
+      muted: '#cbd5e1',
+    },
+    fonts: { family: '"Inter", system-ui, sans-serif' },
+    launcher: { icon: 'sparkle', openIcon: 'close' },
+  },
+})
+```
+
+**Colors.** An override is used exactly as you give it: the widget does not darken it or fix its contrast, and only logs a `console.warn` when the contrast looks too low. You own the result for every role you override. An unusable value (a typo, `currentColor`, a CSS variable) is ignored with a warning and the calculated color is used instead. A role you don't set keeps the widget's calculated color. `theme.colors.primary`, `.ink` and `.link` beat `color`, `inkColor` and `accentColor`, which beat the agent's colors configured in whoo-aiden.
+
+| Role | What it colors | Default |
+| --- | --- | --- |
+| `primary` | Launcher, your visitor's bubbles, Send and Submit buttons | `#4f46e5` |
+| `onPrimary` | Text and icons on `primary` | black or white, whichever reads best |
+| `primaryText` | `primary` used as text on the panel (header controls) | `primary`, darkened until readable |
+| `ink` | Header title and replies | `#111111` |
+| `link` | Links in replies | `#0000ee` |
+| `text` | Form-control and feedback-button text | `#111111` |
+| `panel` | Panel background | `#ffffff` |
+| `border` | Dividers | `#e5e5e5` |
+| `headerHover` | Header control hover fill | `#f3f4f6` |
+| `assistantBubble` | Reply bubble background | `#f0f0f0` |
+| `muted` | Secondary text on replies | `#4b5563` |
+| `typingDots` | "Waiting for a reply" dots | `#6b7280` |
+| `errorBackground`, `errorText` | Error banner | `#fee2e2`, `#991b1b` |
+| `inputBorder` | Input and form borders | `#6b7280` |
+| `focusRing` | Dark tone of the keyboard focus outline | `#111827` |
+
+If you override a surface (`panel`, `assistantBubble`, ...), also override the roles drawn on it: the defaults are made for the default surfaces, and an override of one is never adjusted to fit another. The roles drawn on each surface are `panel`: `primaryText`, `text`, `focusRing`, `border`, `inputBorder`; `headerHover`: `primaryText`; `assistantBubble`: `ink`, `link`, `muted`, `typingDots`, `text`; `errorBackground`: `errorText`. (The example above leaves `inputBorder`, `typingDots` and the error colors at their defaults, which already read well on it.)
+
+**Fonts.** `theme.fonts.family` takes a CSS font-family stack. The widget never loads fonts, so the font must already be available: a system font, or one your page loads (a Google Fonts `<link>`, or your own `@font-face`). A stack that is over 200 characters or contains `url(`, `@`, `;`, `{`, `}` or `\` is ignored with a warning.
+
+**Launcher icons.** `theme.launcher.icon` picks a built-in icon for the closed launcher (`'chat'`, `'message'`, `'sparkle'`); `theme.launcher.openIcon` picks the open one (`'chevron-down'`, `'close'`). `theme.launcher.iconUrl` and `theme.launcher.openIconUrl` show your own image instead (`https:` or `data:image/` only; the built-in icon shows until the image loads, and for good if it fails).
+
+## Layout
+
+`position` picks the corner. `layout` fine-tunes where the launcher sits and how big the launcher and panel are. All values are in px.
+
+```js
+init({
+  publishableKey: 'pk_live_...',
+  position: 'bottom-right',
+  layout: {
+    offset: { x: 24, y: 96 }, // distance from the chosen corner (default 20, 20)
+    launcherSize: 64,         // launcher diameter, 24-120 (default 56)
+    panel: { width: 420, height: 640 }, // preferred panel size (default 360×480, minimum 280×320)
+  },
+})
+```
+
+- The launcher can't be moved off-screen, and not so far from its corner that the chat panel loses its room: an offset that doesn't leave space for the launcher and a minimum-size panel is held back (a warning is logged if that applies when the page loads). A smaller offset than the 20px default is always honored.
+- A `launcherSize` outside 24-120 is clamped (the 24px floor is WCAG 2.2's minimum target size).
+- The panel is always placed above the launcher, whatever its size or offset, and is capped to the viewport. `panel` is a preferred size: it can never run past the screen, and on very small screens (a viewport 400px wide or less, or 420px tall or less) it fills the viewport as before. A `panel.width` or `panel.height` below 280×320 is raised to that minimum, with a warning.
+- A value that isn't a non-negative number is ignored with a warning and the default is used.
+
 ## Theme helper
 
 `resolveTheme` (npm package only) returns the exact colors the widget will render for a set of brand colors, the same computation the widget runs internally. Use it to preview branding without mounting the widget:
@@ -129,6 +207,19 @@ const theme = resolveTheme({ color: '#3b82f6', inkColor: '#1f2937', accentColor:
 // opaque look over white doesn't count.
 ```
 
+`resolveTheme` also accepts `overrides`, the same per-role object as `theme.colors`, and returns three more fields:
+
+```ts
+const dark = resolveTheme({ overrides: { panel: '#0f172a', ink: '#f8fafc' } })
+// dark.roles: every color the widget renders, by role (all 16 of them).
+// dark.overridden: which roles came from `overrides`.
+// dark.contrastWarnings: overridden roles whose contrast against the surface
+// they are drawn on is below 4.5:1 (text) or 3:1 (icons, borders, focus ring),
+// each with { role, against, value, ratio, required }.
+```
+
+An override is never adjusted (an opaque one is only normalized to `#rrggbb`). In particular a *translucent* override (`rgba(…, 0.5)`, `#rrggbbaa`) is kept as given, not flattened to its look over white the way `color` is, so a translucent `primary` or `panel` is see-through over the host page, and the host owns the result. `resolveTheme` never logs; read `contrastWarnings` instead.
+
 It needs a DOM (a browser, or jsdom in tests).
 
 ## Versions

package/dist/components/Launcher.d.ts

@@ -1,7 +1,11 @@
 import { RefObject } from 'preact';
-export declare function Launcher({ isOpen, onClick, iconUrl, buttonRef, }: {
+import { LauncherIcon, LauncherOpenIcon } from '../types';
+export declare function Launcher({ isOpen, onClick, iconUrl, icon, openIconUrl, openIcon, buttonRef, }: {
     isOpen: boolean;
     onClick: () => void;
     iconUrl?: string;
+    icon?: LauncherIcon;
+    openIconUrl?: string;
+    openIcon?: LauncherOpenIcon;
     buttonRef?: RefObject<HTMLButtonElement | null>;
 }): import('preact').JSX.Element;

package/dist/components/icons.d.ts

@@ -1,6 +1,12 @@
 export declare function ChatIcon({ size }: {
     size?: number;
 }): import('preact').JSX.Element;
+export declare function MessageIcon({ size }: {
+    size?: number;
+}): import('preact').JSX.Element;
+export declare function SparkleIcon({ size }: {
+    size?: number;
+}): import('preact').JSX.Element;
 export declare function ChevronDownIcon({ size }: {
     size?: number;
 }): import('preact').JSX.Element;

package/dist/config.d.ts

@@ -1,7 +1,39 @@
-import { WidgetConfig } from './types';
+import { ThemeColorOverrides } from './themeRoles';
+import { LauncherIcon, LauncherOpenIcon, WidgetConfig } from './types';
 export declare const DEFAULT_API_BASE_URL = "https://api.aidenvoice.com";
 export declare const DEFAULT_Z_INDEX = 2147483000;
 export declare function resolveZIndex(zIndex: unknown): number;
 export declare const DEFAULT_AGENT_NAME = "Aiden";
 export declare function trimmedName(name: unknown): string;
 export declare function validateConfig(config: WidgetConfig): void;
+export declare function safeFontFamily(value: unknown): string | undefined;
+export interface NormalizedTheme {
+    colors: ThemeColorOverrides;
+    fontFamily: string | undefined;
+    launcher: {
+        icon?: LauncherIcon;
+        iconUrl?: string;
+        openIcon?: LauncherOpenIcon;
+        openIconUrl?: string;
+    };
+}
+export declare function normalizeTheme(theme: unknown): NormalizedTheme;
+export declare const LAYOUT_DEFAULTS: {
+    readonly offsetX: 20;
+    readonly offsetY: 20;
+    readonly launcherSize: 56;
+    readonly panelWidth: 360;
+    readonly panelHeight: 480;
+};
+export declare const LAUNCHER_SIZE_MIN = 24;
+export declare const LAUNCHER_SIZE_MAX = 120;
+export declare const PANEL_MIN_WIDTH = 280;
+export declare const PANEL_MIN_HEIGHT = 320;
+export interface NormalizedLayout {
+    offsetX: number;
+    offsetY: number;
+    launcherSize: number;
+    panelWidth: number;
+    panelHeight: number;
+}
+export declare function normalizeLayout(layout: unknown): NormalizedLayout;

package/dist/controller.d.ts

@@ -1,3 +1,4 @@
+import { NormalizedTheme } from './config';
 import { WidgetConfig } from './types';
 export declare const SLOW_RESPONSE_DELAY_MS = 8000;
 export declare const BRANDING_LOOKUP_WAIT_MS = 3000;
@@ -40,6 +41,7 @@ export declare class WidgetController {
     private activeRequestController;
     private slowResponseTimer;
     private readonly prefersReducedMotion;
+    readonly launcher: NormalizedTheme['launcher'];
     readonly launcherIconUrl: string | undefined;
     readonly emptyStateImageUrl: string | undefined;
     readonly emptyStateImageAlt: string;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { WidgetConfig, WidgetHandle } from './types';
+import { LauncherIcon, LauncherOpenIcon, WidgetConfig, WidgetHandle, WidgetLayout, WidgetTheme } from './types';
 export declare function init(config: WidgetConfig): WidgetHandle;
-export type { ResolvedTheme, ThemeInput } from './theme';
+export type { ContrastWarning, ResolvedTheme, ThemeInput } from './theme';
 export { resolveTheme } from './theme';
-export type { WidgetConfig, WidgetHandle };
+export type { ThemeColorOverrides, ThemeColorRole } from './themeRoles';
+export type { LauncherIcon, LauncherOpenIcon, WidgetConfig, WidgetHandle, WidgetLayout, WidgetTheme, };

package/dist/layout.d.ts

@@ -0,0 +1,2 @@
+import { WidgetConfig } from './types';
+export declare function applyLayout(root: HTMLElement, config: WidgetConfig): void;

package/dist/theme.d.ts

@@ -1,3 +1,4 @@
+import { ThemeColorOverrides, ThemeColorRole } from './themeRoles';
 import { WidgetConfig } from './types';
 export declare function pickTextColor(cssColor: string): '#000000' | '#ffffff';
 export declare function contrastRatio(cssColorA: string, cssColorB: string): number;
@@ -6,6 +7,17 @@ export interface ThemeInput {
     color?: string | null;
     inkColor?: string | null;
     accentColor?: string | null;
+    /** Per-role replacements. Used verbatim; they win over `color`/`inkColor`/`accentColor`. */
+    overrides?: ThemeColorOverrides;
+}
+export interface ContrastWarning {
+    role: ThemeColorRole;
+    /** The role whose color this one is drawn on. */
+    against: ThemeColorRole;
+    /** The overridden value. */
+    value: string;
+    ratio: number;
+    required: number;
 }
 export interface ResolvedTheme {
     /** Launcher, visitor bubbles, Send and Submit button fill. */
@@ -23,19 +35,26 @@ export interface ResolvedTheme {
      * Flattening a translucent color to its opaque look over white doesn't
      * count -- that's compositing, not a readability adjustment, and it
      * lightens rather than darkens, so a "shown a little darker" note would
-     * be wrong for it.
+     * be wrong for it. An explicit override is never adjusted.
      */
     adjusted: {
         primary: boolean;
         ink: boolean;
         link: boolean;
     };
+    /** Every color the widget renders, by role. */
+    roles: Record<ThemeColorRole, string>;
+    /** Which roles came from `overrides` (and so were used verbatim). */
+    overridden: Record<ThemeColorRole, boolean>;
+    /** Overridden roles whose contrast is below what their surface needs. */
+    contrastWarnings: ContrastWarning[];
 }
 export declare function usableHex(color: unknown): string | null;
-export declare function resolveTheme({ color, inkColor, accentColor }: ThemeInput): ResolvedTheme;
+export declare function resolveTheme({ color, inkColor, accentColor, overrides, }: ThemeInput): ResolvedTheme;
 export declare function applyThemeColor(root: HTMLElement, color: string, fallback?: string): void;
 export declare function applyPalette(root: HTMLElement, { inkColor, accentColor }: {
     inkColor?: string | null;
     accentColor?: string | null;
 }): void;
+export declare function applyColorOverrides(root: HTMLElement, overrides: ThemeColorOverrides): void;
 export declare function applyTheme(root: HTMLElement, config: WidgetConfig): void;

package/dist/themeRoles.d.ts

@@ -0,0 +1,5 @@
+export declare const THEME_COLOR_ROLES: readonly ["primary", "onPrimary", "primaryText", "ink", "link", "text", "panel", "border", "headerHover", "assistantBubble", "muted", "typingDots", "errorBackground", "errorText", "inputBorder", "focusRing"];
+export type ThemeColorRole = (typeof THEME_COLOR_ROLES)[number];
+export type ThemeColorOverrides = Partial<Record<ThemeColorRole, string>>;
+export declare const ROLE_DEFAULTS: Readonly<Record<ThemeColorRole, string>>;
+export declare const ROLE_CSS_VARS: Readonly<Record<ThemeColorRole, string>>;

package/dist/types.d.ts

@@ -1,3 +1,74 @@
+export type LauncherIcon = 'chat' | 'message' | 'sparkle';
+export type LauncherOpenIcon = 'chevron-down' | 'close';
+export interface WidgetTheme {
+    /**
+     * Replace any color the widget renders. Used exactly as given: no
+     * darkening, no contrast correction (a low-contrast value only logs a
+     * warning). Omit a role to keep the widget's calculated color.
+     */
+    colors?: {
+        /** Launcher, visitor bubbles, Send/Submit fill. Beats `color`. */
+        primary?: string;
+        /** Text and icons on `primary`. Calculated (black or white) when omitted. */
+        onPrimary?: string;
+        /** `primary` used as text on the panel (header controls). Calculated when omitted. */
+        primaryText?: string;
+        /** Header title and reply text. Beats `inkColor`. */
+        ink?: string;
+        /** Links in replies. Beats `accentColor`. */
+        link?: string;
+        /** Form-control and feedback-button text. */
+        text?: string;
+        /** Panel background (also the header and sticky action surfaces). */
+        panel?: string;
+        /** Dividers. */
+        border?: string;
+        /** Header control hover fill. */
+        headerHover?: string;
+        /** Reply bubble background. */
+        assistantBubble?: string;
+        /** Secondary text on the reply bubble. */
+        muted?: string;
+        /** Waiting-for-reply indicator. */
+        typingDots?: string;
+        errorBackground?: string;
+        errorText?: string;
+        inputBorder?: string;
+        /** The dark tone of the focus outline. */
+        focusRing?: string;
+    };
+    fonts?: {
+        /**
+         * A CSS font-family stack. The font must already be available: a system
+         * font, or one your page loaded. The widget never loads fonts.
+         */
+        family?: string;
+    };
+    launcher?: {
+        /** Built-in icon on the closed launcher. */
+        icon?: LauncherIcon;
+        /** Image on the closed launcher; wins over `icon` and over `launcherIconUrl`. */
+        iconUrl?: string;
+        /** Built-in icon on the open launcher (the minimize control). */
+        openIcon?: LauncherOpenIcon;
+        /** Image on the open launcher; wins over `openIcon`. */
+        openIconUrl?: string;
+    };
+}
+export interface WidgetLayout {
+    /** Distance in px from the corner chosen by `position`. Default `{ x: 20, y: 20 }`. */
+    offset?: {
+        x?: number;
+        y?: number;
+    };
+    /** Launcher diameter in px, 24-120. Default 56. */
+    launcherSize?: number;
+    /** Preferred panel size in px (minimum 280×320, always capped to the viewport). Default 360×480. */
+    panel?: {
+        width?: number;
+        height?: number;
+    };
+}
 export interface WidgetConfig {
     publishableKey?: string;
     sessionToken?: string;
@@ -19,7 +90,7 @@ export interface WidgetConfig {
     accentColor?: string;
     name?: string;
     greeting?: string;
-    /** Image shown on the launcher bubble instead of the default chat icon. */
+    /** Image shown on the launcher bubble instead of the default chat icon. Alias of `theme.launcher.iconUrl`, which wins if both are set. */
     launcherIconUrl?: string;
     /** Image shown above the greeting while the conversation is empty. */
     emptyStateImageUrl?: string;
@@ -33,6 +104,10 @@ export interface WidgetConfig {
      */
     zIndex?: number;
     apiBaseUrl?: string;
+    /** Colors, font and launcher icons. See `WidgetTheme`. */
+    theme?: WidgetTheme;
+    /** Launcher position/size and panel size. See `WidgetLayout`. */
+    layout?: WidgetLayout;
 }
 export interface WidgetHandle {
     unmount(): void;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const WIDGET_VERSION = "0.5.3";
+export declare const WIDGET_VERSION = "0.6.0";