@hachther/akilio-widget 0.5.0 → 0.6.2

package/README.md

@@ -1,5 +1,110 @@
 # Akilio Widget
 
+## Style isolation
+
+The widget renders in a Shadow DOM by default. Host-site resets and framework
+styles cannot override its buttons, text areas, images, or layout, and widget
+styles do not leak into the surrounding page.
+
+```tsx
+<AkilioWidget
+  apiBaseUrl="https://app.akilio-ai.com"
+  projectKey="your-project-key"
+  styleIsolation="shadow"
+/>
+```
+
+Use `styleIsolation="scoped"` for a normal-DOM integration with Akilio-prefixed
+CSS, or `styleIsolation="none"` when loading `@hachther/akilio-widget/style.css`
+yourself. Standalone scripts accept `data-style-isolation="shadow"`; Shadow DOM
+is also their default.
+
+## Streaming responses
+
+The widget uses the authenticated SSE endpoint by default. It displays retrieval
+and answer-preparation status, appends `answer.delta` content as it arrives, and
+then replaces the transient answer with the canonical `final` payload (including
+citations, products, and suggestions).
+
+```tsx
+<AkilioWidget
+  apiBaseUrl="https://app.akilio-ai.com"
+  projectKey="your-project-key"
+  streaming
+/>
+```
+
+Use `streaming={false}` or `data-streaming="false"` to use `POST /api/v1/chat/`
+for compatibility with an older backend or proxy.
+
+## Server widget policy
+
+The public project configuration may include an authoritative `widget_policy`.
+The widget applies it automatically:
+
+- `available` disables questions while the project is unavailable.
+- `assistant_mode` is sent to chat instead of a client routing hint.
+- `commerce_enabled` controls product rendering and commerce event tracking.
+- `branding` enforces required, removable, or white-label presentation.
+
+For projects with `branding: "removable"`, the host can hide Akilio branding:
+
+```tsx
+<AkilioWidget showAkilioBranding={false} />
+```
+
+The standalone equivalent is `data-show-akilio-branding="false"`. A policy of
+`akilio_required` always shows Akilio branding, while `white_label` always hides
+it regardless of the client option. Older API responses without
+`widget_policy` retain the previous widget behavior.
+
+The message composer automatically expands for multiline text up to its bounded
+maximum height, after which it scrolls internally.
+
+When branding is required, a compact “Powered by Akilio” notice is displayed
+below the composer at the bottom of the widget. It is omitted for removable and
+white-label policies.
+
+The default widget primary color follows the Akilio palette (`#0F766E`) with
+`#115E59` for hover and pressed states. Project configuration and the `theme`
+prop continue to override these defaults; `theme.primaryDark` can customize the
+interactive hover color.
+
+Floating, drawer, side-panel, and hybrid Shadow DOM widgets use the browser top
+layer when supported. This keeps the widget above host-site chat, search, cookie,
+and navigation overlays—even when those elements activate after the composer
+receives focus. Older browsers use a fixed, isolated host at the maximum safe
+z-index. Inline widgets remain in the normal document layout.
+
+## Browser control API
+
+After the widget fires `akilio:ready`, integrations can control the real widget
+without querying its DOM. The frozen API works with normal DOM and Shadow DOM:
+
+```js
+await window.AkilioWidget.open();
+await window.AkilioWidget.typeDraft('How can I request a quote?', {
+  interval: 35,
+  focus: true,
+  clearExisting: true,
+});
+
+// Let the visitor click Send, or submit through the same SSE workflow:
+const response = await window.AkilioWidget.submit();
+```
+
+Available methods are `open`, `close`, `setDraft`, `typeDraft`, `clearDraft`,
+`cancelTyping`, `submit`, `ask`, `reset`, and `getState`. Rejected operations
+include a stable `code` such as `EMPTY_DRAFT`, `BUSY`, `TYPING_CANCELLED`, or
+`STREAM_FAILED`. `getState()` returns only safe UI and conversation state and
+never exposes authentication data.
+
+Lifecycle events are dispatched on `window`: `akilio:ready`, `akilio:open`,
+`akilio:close`, `akilio:draft-change`, `akilio:typing-start`,
+`akilio:typing-complete`, `akilio:typing-cancel`, `akilio:question`,
+`akilio:answer-start`, `akilio:answer-delta`, `akilio:answer-complete`,
+`akilio:error`, and `akilio:reset`.
+
 Production React and standalone JavaScript widget for the Akilio backend.
 
 ## Included modes

package/dist/AkilioWidget.d.ts

@@ -1,4 +1,7 @@
-import 'driver.js/dist/driver.css';
-import './styles.css';
 import type { AkilioWidgetProps } from './types';
-export declare function AkilioWidget({ apiBaseUrl, projectKey, locale, mode, colorMode, allowColorModeToggle, defaultOpen, open: controlledOpen, launcher, persistOpenState, enableTour, enableLocalHistory, enableServerHistorySync, anonymousId, externalUserId, channel, audience, productArea, assistantMode, pageContext, auth, accessToken, privacyNotice, privacyNoticeUrl, requireConsent, consentNoticeVersion, initialConsent, onConsentChange, copy: copyOverrides, theme, className, onOpenChange, onMessage, onProductClick, onError, }: AkilioWidgetProps): import("react").JSX.Element;
+/**
+ * Public widget boundary. By default the application and its stylesheet are
+ * rendered into a ShadowRoot, preventing CSS resets and component rules from
+ * crossing in either direction.
+ */
+export declare function AkilioWidget(props: AkilioWidgetProps): import("react").JSX.Element;