@ahmedramez-org/nexus-chat 1.0.0-beta.5 → 1.0.0-beta.7

package/README.md

@@ -1,14 +1,31 @@
 # @incorta/nexus-chat
 
-NexusChat, the IncortaCopilot chat UI, for any app on any framework: `<NexusChat />` for React,
-`mountNexusChat()` for everything else.
+NexusChat, the IncortaCopilot chat UI, for any app on any framework: one `<script>` tag for any
+site, `<NexusChat />` for React, `mountNexusChat()` for everything else.
 
 The chat always runs as a prebuilt Module Federation bundle with its own React and isolated
 styles, never re-compiled by the app's bundler, so it never collides with the app's React, its
-dependencies or its CSS. Importing the connector and the component adds about 3 KB to an app. The
-chat build itself is not in this package: Copilot serves it, and each GitHub Release attaches it as
+dependencies or its CSS. The connector adds about 6 KB gzipped to an app (half of it the Incorta
+Intelligence mark its loading skeleton draws), and the React component about 7 KB more. The chat
+build itself is not in this package: Copilot serves it, and each GitHub Release attaches it as
 `nexus-chat-dist.tar.gz`.
 
+## Any site: one script
+
+```html
+<script src="https://<incorta>/incorta/copilot/nexus-chat/widget.js" defer></script>
+```
+
+Incorta serves this script next to `embed.html`; it is not in this package and needs no build. It
+draws the Incorta Intelligence launcher at the bottom right and opens the embedded chat (below)
+floating, docked or full screen, on the user's Incorta session, so the page holds no token. It is
+one classic script with no imports, so a page on any origin loads it without CORS.
+
+Optional `data-` attributes set it up: `data-theme="dark"`, `data-modes="floating,docked"` (the
+windows allowed, in that order; default all three), `data-default-mode="docked"` (open on load;
+default only the launcher) and `data-locale="fr"`. The page drives it afterwards through
+`window.NexusChatWidget`: `open()`, `close()`, `setMode('docked')`, `setTheme('dark')`.
+
 ## React
 
 Two ways in: **direct**, where the chat mounts into the page and shares its session (Incorta's own
@@ -24,38 +41,88 @@ import { NexusChat } from '@incorta/nexus-chat/react';
 ```
 
 It draws its own window: an Incorta Intelligence launcher at the bottom right opens the chat
-floating or docked on the right (the page makes room). The chat's own top bar takes it to full
-screen and back (Undock / Dock to the side) and closes it back to the launcher; nothing sits
-above the chat. `modes` limits the windows (default all three, in that order) and `defaultMode`
-opens one on load; dock returns to the window last shown beside the page. Below 768px wide the chat covers the page. The window takes the
-page's background colour, the chat is drawn smaller when floating or docked, and the launcher icon
-shimmers while the chat loads. `theme` is followed live; `locale` is read when the chat first opens.
+floating (a card lifted off the page, opening out of the launcher, which stays under it to hide
+it) or docked flush on the right (the page makes room). The chat's own top bar switches between
+the windows (Float, Dock to the side, Enter full screen: every allowed one but the current) and
+closes it back to the launcher; nothing sits above the chat. `modes` limits the windows (default
+all three, in that order) and `defaultMode` opens one on load. Below 768px wide the chat covers
+the page. The chat is drawn smaller in a small window, and a skeleton holds the window while the
+chat loads. `theme` is followed live; `locale` is read when the chat first opens.
 
 The Incorta cluster needs `iframe.inclusion.enabled` (and `frame-ancestors` set to the app's
-domains), and the user signed in to Incorta in that browser. The iframe reaches the Incorta
-session only where the browser allows third-party cookies: Chrome by default; Safari ("Prevent
-cross-site tracking" off), Firefox (a cookie exception for the Incorta site) and private windows
-need that setting.
+domains). Where the browser keeps the Incorta session from the iframe (Safari, Firefox, private
+windows), the chat shows Continue with Incorta: the browser asks the user to allow it once, and
+the chat starts on their Incorta session. A user not signed in to Incorta signs in through a small
+Incorta window that closes itself afterwards. No browser setting is needed.
+
+While the user clicks or types in the app, the component tells the chat at most every ten seconds,
+so Incorta's own idle timeout does not end the chat's session while the app is in use. A page that
+places the iframe itself can do the same: `iframe.contentWindow.postMessage({ nexusChat: 'active' },
+'<incorta origin>')`. If the session ends anyway, the chat shows Sign in to Incorta.
 
 ### Direct
 
+```ts
+// Copilot answers 400 without the signed-in user's token: read it from Incorta's
+// session, and read it again after a 401 or 403.
+let session;
+const incortaHeaders = () =>
+  (session ??= fetch('/incorta/service/user/isLoggedIn', { credentials: 'include' }).then(
+    async (response) => ({
+      Authorization: `Bearer ${(await response.json()).accessToken}`,
+      'X-XSRF-TOKEN': response.headers.get('X-XSRF-TOKEN') ?? '',
+    }),
+  ));
+```
+
 ```tsx
 <NexusChat
-  connection={{ client: 'general', copilotUrl: '/incorta/copilot', credentials: 'include' }}
+  connection={{
+    client: 'general',
+    copilotUrl: '/incorta/copilot',
+    credentials: 'include',
+    headers: incortaHeaders, // read before each request
+    refreshAuth: async () => ((session = undefined), true), // after a 401 or 403: read again, retry
+  }}
   theme="dark"
   user={{ id: user.sub, name: user.name }}
   onLoadError={(error) => setError(error.message)}
 />
 ```
 
-The chat fills the component's box; the app draws any frame around it. Until the chat is mounted, the Incorta Intelligence mark sits in the middle of the box (the embedded window's loading face), and it leaves when the chat mounts or `onLoadError` fires, so the app's own failure takes the box. `theme`, `locale` (default:
+The chat fills the component's box; the app draws any frame around it. Until the chat is mounted, a skeleton holds the box (the embedded window's loading face: the Incorta Intelligence mark and two lines, after 300 ms), and it fades once the chat mounts, or leaves at once when `onLoadError` fires, so the app's own failure takes the box. `theme`, `locale` (default:
 the browser's), `direction`, `tenantId`, `user` and `window` update the running chat;
 `connection`, `chat`, `actions`, `events`, `instanceId`, `assetsUrl` and `timeoutMs` are read once
 at mount. `window` (`docked`, `canDock`, `setDocked`, `close`) hands the chat's window to the app:
-the chat shows a dock toggle and a close button. An app that already builds the contract's
+the chat shows a dock toggle and a close button; with `mode`, `modes` and `setMode` (read at
+mount) it shows a button per other mode instead of the toggle. An app that already builds the contract's
 `environment` or `window` passes it as is. `onReady` receives the handle (`ask`, `attach`), and
 `null` once the chat unmounts; `loadedNexusChatVersion()` names the loaded build for error reports.
 
+### Direct, in a window
+
+```tsx
+<NexusChat
+  connection={{
+    client: 'general',
+    copilotUrl: '/incorta/copilot',
+    credentials: 'include',
+    headers: incortaHeaders, // as above
+    refreshAuth: async () => ((session = undefined), true),
+  }}
+  theme="dark"
+  modes={['floating', 'docked', 'fullscreen']}
+  defaultMode="floating"
+/>
+```
+
+`modes` or `defaultMode` instead of `window` gives the direct chat the embedded window: the
+launcher, floating, docked (the page makes room) and full-screen windows, full screen below 768px.
+The chat's own top bar switches windows and closes it to the launcher, where the conversation
+stays. `modes` limits the windows (default all three, in that order); `defaultMode` opens one on
+load, else only the launcher shows. The other props are the direct ones, and an app passing
+`window` keeps drawing its own frame.
+
 ## Any framework
 
 ```ts
@@ -73,8 +140,10 @@ chat.unmount();
 ```
 
 The options are the host contract: `connection` and `environment` are required; `chat`, `actions`,
-`events` and `window` are optional, and the chat hides what a host leaves out. Mount in the browser
-only, never during SSR.
+`events` and `window` are optional, and the chat hides what a host leaves out. The chat fills
+`element`. Until it is mounted the React component's skeleton holds the element (after 300 ms, in
+the `environment`'s theme), and it leaves at once if the chat cannot load, so the app's own failure
+takes its place. Mount in the browser only, never during SSR.
 
 `chat={{ contexts: ['business-view', 'ai-container', 'file'] }}` lets users attach contexts, in
 that menu order: `'file'` uploads, and each other built-in kind (`business-view`, `physical-table`,
@@ -84,7 +153,8 @@ that menu order: `'file'` uploads, and each other built-in kind (`business-view`
 Stores. A `ContextSource` of a kind replaces the chat's loader for it.
 
 `loadNexusChat(source)` only loads the chat and resolves to its `mount`. It loads once per source,
-retries once, and gives up after `timeoutMs` (default 20 s); a failed load is forgotten so the next
+retries once, and gives up after `timeoutMs` (default 20 s, counted while the page is visible: a
+hidden tab gets a fresh deadline once it shows); a failed load is forgotten so the next
 call tries again. Call it when the page is idle to make the first open instant.
 
 ## Where the chat comes from

package/contract/index.d.ts

@@ -383,16 +383,27 @@ export interface NexusChatOptions {
      * The host sizes the mount and owns its window (a page-covering overlay, a
      * docked side panel) and draws its frame. Present: the chat hides its own
      * fullscreen toggle and its edge border, and shows a dock toggle while
-     * `canDock`, and a close button. Absent: the chat's own fullscreen toggle,
-     * and no close button.
+     * `canDock` (or, with `mode`, `modes` and `setMode`, one button per other
+     * mode), and a close button. Absent: the chat's own fullscreen toggle, and
+     * no close button.
      */
     window?: NexusChatWindow;
 }
+/** The windows a host can show the chat in. */
+export type NexusChatWindowMode = 'floating' | 'docked' | 'fullscreen';
 export interface NexusChatWindowState {
     /** The mount is the docked side panel (the toggle shows pressed). */
     docked: boolean;
     /** The host page allows docking now; `false` hides the dock toggle. */
     canDock: boolean;
+    /**
+     * The window shown now. With `modes` and `setMode`, the header offers every
+     * mode in `modes` but this one (float, dock, full screen, in that order)
+     * instead of the dock toggle.
+     */
+    mode?: NexusChatWindowMode;
+    /** The modes the host can switch to now, the current one included. */
+    modes?: readonly NexusChatWindowMode[];
 }
 export interface NexusChatWindow {
     /** May return a fresh object on every call: the chat compares the fields. */
@@ -400,6 +411,8 @@ export interface NexusChatWindow {
     /** Call `onChange` whenever `get` may return something different. */
     subscribe(onChange: () => void): () => void;
     setDocked(docked: boolean): void;
+    /** Shows the chat in another of `modes`; the conversation and draft stay. */
+    setMode?(mode: NexusChatWindowMode): void;
     close(): void;
 }
 /** What `mount` returns: the host's handle on one running chat. */

package/index.d.ts

@@ -1,4 +1,9 @@
-import type { NexusChatHandle, NexusChatMount, NexusChatOptions } from './contract/index.js';
+import type {
+  HostTheme,
+  NexusChatHandle,
+  NexusChatMount,
+  NexusChatOptions,
+} from './contract/index.js';
 
 export type * from './contract/index.js';
 
@@ -35,3 +40,12 @@ export function mountNexusChat(
   element: HTMLElement,
   options: MountNexusChatOptions,
 ): Promise<NexusChatHandle>;
+
+/**
+ * @internal The skeleton `mountNexusChat` and `<NexusChat>` draw over a box
+ * while the chat loads. Not part of the package's API.
+ */
+export function showNexusChatSkeleton(
+  box: HTMLElement,
+  theme?: HostTheme,
+): { setTheme(theme?: HostTheme): void; done(): void; remove(): void };

package/index.js

@@ -126,6 +126,24 @@ export function loadedNexusChatVersion() {
   return loadedVersion;
 }
 
+/**
+ * Rejects after `timeoutMs`, counted while the page can be seen: a hidden tab
+ * runs its timers and requests slowly (Chrome throttles background tabs), so
+ * a chat loading there gets a fresh deadline once the tab shows. Internal to
+ * this package.
+ */
+export function loadDeadline(timeoutMs) {
+  return new Promise((_, reject) => {
+    const expire = () => {
+      if (!document.hidden) return reject(new Error('Timed out loading NexusChat.'));
+      document.addEventListener('visibilitychange', () => setTimeout(expire, timeoutMs), {
+        once: true,
+      });
+    };
+    setTimeout(expire, timeoutMs);
+  });
+}
+
 /**
  * Loads the chat once per source and resolves to its `mount` function. One
  * retry, since a single failure (a 502 during a rolling restart) is not an
@@ -143,9 +161,7 @@ export function loadNexusChat(options) {
         await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
         return importMount(entry);
       }),
-      new Promise((_, reject) =>
-        setTimeout(() => reject(new Error('Timed out loading NexusChat.')), timeoutMs),
-      ),
+      loadDeadline(timeoutMs),
     ]);
     load.catch(() => loads.delete(entry));
     loads.set(entry, load);
@@ -156,13 +172,133 @@ export function loadNexusChat(options) {
 /**
  * Loads the chat (from `assetsUrl`, else `connection.copilotUrl`) and mounts
  * it into `element` with the host contract options. The chat fills the
- * element, so the element's box decides the presentation.
+ * element, so the element's box decides the presentation. Until the chat is
+ * up the skeleton holds the element; it leaves at once if the chat cannot load.
  */
 export async function mountNexusChat(element, { assetsUrl, timeoutMs, ...options }) {
-  const mount = await loadNexusChat({
-    copilotUrl: options.connection?.copilotUrl,
-    assetsUrl,
-    timeoutMs,
-  });
-  return mount(element, { version: CONTRACT_VERSION, ...options });
+  const skeleton = showNexusChatSkeleton(element, options.environment?.get().theme);
+  let handle;
+  try {
+    const mount = await loadNexusChat({
+      copilotUrl: options.connection?.copilotUrl,
+      assetsUrl,
+      timeoutMs,
+    });
+    handle = mount(element, { version: CONTRACT_VERSION, ...options });
+  } catch (error) {
+    skeleton.remove();
+    throw error;
+  }
+  skeleton.done();
+  return {
+    ...handle,
+    unmount() {
+      skeleton.remove();
+      handle.unmount();
+    },
+  };
+}
+
+// ---- the loading face every app shows until the chat is up (<NexusChat> draws it too)
+
+/** Fast loads show no skeleton; one that shows stays long enough to read, then cross-fades. */
+const SKELETON_DELAY_MS = 300;
+const SKELETON_MIN_MS = 400;
+const SKELETON_FADE_MS = 150;
+
+/** The chat's own ground (so the swap does not flash), its line fill, its window edge. */
+export const PALETTE = {
+  light: { ground: '#fcfdfe', fill: '#efeff2', line: '#e4e4e7' },
+  dark: { ground: '#151515', fill: '#242426', line: '#2c2c2e' },
+};
+
+export const reducedMotion = () => window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+
+/** The Incorta Intelligence mark. */
+export const ICON = `data:image/svg+xml,${encodeURIComponent(
+  "<svg width='107' height='120' viewBox='0 0 107 120' fill='none' xmlns='http://www.w3.org/2000/svg'><g clip-path='url(#clip0_108_873)'><path d='M84 35.4C89.8 37.6 95.2 41.2 99.8 45.9C102.4 48.6 104.6 51.5 106.5 54.6L106.7 35.4C106.7 32 104.9 28.8 102 27L63.1 3.9C66.2 5.8 69.1 8.1 71.7 10.9C78.5 17.8 82.6 26.4 84 35.4Z' fill='url(#paint0_linear_108_873)'/><path d='M22.9 84.8C17.1 82.5 11.7 79 7.1 74.3C4.4 71.5 2.1 68.4 0.2 65.2L0 84.6C0 88.1 1.7 91.2 4.7 93L43.9 116.3C40.8 114.4 37.9 112.1 35.2 109.3C28.4 102.4 24.3 93.8 22.9 84.8Z' fill='url(#paint1_linear_108_873)'/><path d='M106.1 85.8L106.5 54.6C104.6 51.5 102.4 48.6 99.8 45.9C95.2 41.2 89.8 37.6 84 35.4C86.3 49.4 81.9 64.3 71 75C57.9 87.9 38.9 91.1 22.9 84.8C24.3 93.8 28.4 102.4 35.2 109.3C37.9 112.1 40.8 114.4 43.9 116.3L45.2 117.1L47.9 118.7C48.9 119.3 49.9 119.7 51 119.9C53.2 120.3 55.5 119.9 57.5 118.8L101.3 94.1C104.2 92.4 106.1 89.2 106.1 85.8V85.8Z' fill='url(#paint2_linear_108_873)'/><path d='M35.9 45.2C49 32.3 68 29.1 84 35.4C82.6 26.4 78.5 17.8 71.7 10.8C69.1 8.1 66.2 5.8 63.1 3.9L61.7 3.1L58.8 1.3C57.7 0.7 56.6 0.3 55.4 0.1C53.3 -0.2 51.1 0.2 49.2 1.2L5.4 26C2.4 27.6 0.6 30.8 0.6 34.2L0.2 65.2C2.1 68.4 4.4 71.5 7.1 74.3C11.7 79 17.1 82.5 22.9 84.8C20.7 70.7 25 55.9 35.9 45.2V45.2Z' fill='#00A098'/><path d='M22.9 84.8C23 85.3 23.1 85.8 23.2 86.3C23.2 86.5 23.2 86.7 23.3 86.8C23.3 87.2 23.4 87.5 23.5 87.9C23.5 88 23.6 88.2 23.6 88.4C23.7 88.8 23.8 89.1 23.9 89.4C23.9 89.6 24 89.8 24 90C24.1 90.4 24.2 90.8 24.4 91.1C24.4 91.4 24.5 91.6 24.6 91.9C24.7 92.2 24.8 92.5 24.9 92.8C25 93.1 25.1 93.3 25.2 93.6C25.3 93.8 25.4 94 25.5 94.2C25.6 94.5 25.7 94.8 25.8 95C25.9 95.2 25.9 95.4 26 95.6C26.2 95.9 26.3 96.2 26.4 96.5C26.5 96.6 26.5 96.7 26.5 96.7C26.9 97.4 27.2 98.1 27.6 98.8C27.6 98.9 27.6 98.9 27.7 99C27.9 99.3 28 99.7 28.2 100C28.3 100.1 28.4 100.2 28.4 100.3C28.6 100.7 28.8 101 29 101.3C29 101.4 29.1 101.5 29.1 101.6C29.8 102.7 30.6 103.8 31.4 104.9C31.8 104.9 92.7 102.9 96.2 42.5C96.6 36.7 96.4 30.2 95.5 23.2L63.1 3.9C66.2 5.8 69.1 8.1 71.7 10.9C78.5 17.8 82.6 26.4 84 35.4C86.3 49.4 81.9 64.3 71 75C57.9 87.9 38.9 91.1 22.9 84.8V84.8Z' fill='url(#paint3_linear_108_873)'/><path d='M84 35.4C84 34.9 83.9 34.4 83.8 33.8C83.7 33.7 83.7 33.5 83.7 33.4C83.6 33 83.5 32.7 83.4 32.3C83.4 32.1 83.3 31.9 83.3 31.7C83.2 31.4 83.1 31.1 83.1 30.8C83 30.6 83 30.4 82.9 30.2C82.8 29.8 82.7 29.4 82.6 29C82.5 28.8 82.4 28.5 82.3 28.3C82.2 28 82.1 27.7 82 27.4C81.9 27.1 81.8 26.9 81.7 26.6C81.6 26.4 81.5 26.2 81.5 25.9C81.4 25.7 81.2 25.4 81.1 25.1C81.1 24.9 81 24.7 80.9 24.6C80.8 24.3 80.6 24 80.5 23.7C80.5 23.6 80.4 23.5 80.4 23.4C80.1 22.7 79.7 22.1 79.4 21.4C79.3 21.3 79.3 21.2 79.2 21.2C79.1 20.8 78.9 20.5 78.7 20.2C78.6 20.1 78.6 20 78.5 19.9C78.3 19.5 78.1 19.2 77.9 18.9C77.9 18.8 77.8 18.7 77.8 18.6C77.1 17.5 76.3 16.4 75.5 15.3C75.1 15.3 14.2 17.3 10.7 77.6C10.4 83.5 10.6 90 11.4 97L43.8 116.2C40.7 114.3 37.8 112 35.2 109.3C28.4 102.4 24.3 93.8 22.9 84.8C20.7 70.8 25 55.9 35.9 45.2C49 32.3 68 29.1 84 35.4V35.4Z' fill='url(#paint4_linear_108_873)'/></g><defs><linearGradient id='paint0_linear_108_873' x1='104.6' y1='41.1' x2='52.2' y2='1.6' gradientUnits='userSpaceOnUse'><stop stop-color='#4854FE'/><stop offset='1' stop-color='#241C55'/></linearGradient><linearGradient id='paint1_linear_108_873' x1='0' y1='90.8' x2='43.9' y2='90.8' gradientUnits='userSpaceOnUse'><stop stop-color='#4854FE'/><stop offset='1' stop-color='#241C55'/></linearGradient><linearGradient id='paint2_linear_108_873' x1='31.5' y1='40.6' x2='92.7' y2='102.9' gradientUnits='userSpaceOnUse'><stop stop-color='white'/><stop offset='1' stop-color='#4854FE'/></linearGradient><linearGradient id='paint3_linear_108_873' x1='86.3' y1='19.1' x2='41.6' y2='98.7' gradientUnits='userSpaceOnUse'><stop stop-color='#4854FE' stop-opacity='0.93'/><stop offset='1' stop-color='#006EF0' stop-opacity='0'/></linearGradient><linearGradient id='paint4_linear_108_873' x1='19.9' y1='103.3' x2='61' y2='27.5' gradientUnits='userSpaceOnUse'><stop stop-color='#006EF0'/><stop offset='1' stop-color='#006EF0' stop-opacity='0'/></linearGradient><clipPath id='clip0_108_873'><rect width='106.7' height='120' fill='white'/></clipPath></defs></svg>",
+)}`;
+
+/**
+ * Draws the skeleton over `box`: the mark and two lines centred in it,
+ * pulsing together, revealed only once loading has taken SKELETON_DELAY_MS.
+ * It stays on top of whatever renders into `box` (the chat's React empties its
+ * element when it first paints) until `done` fades it out (after showing for
+ * SKELETON_MIN_MS) or `remove` drops it at once. Internal to this package.
+ */
+export function showNexusChatSkeleton(box, theme) {
+  const root = document.createElement('div');
+  root.setAttribute('role', 'status');
+  root.setAttribute('aria-label', 'Loading Incorta Intelligence');
+  root.style.cssText =
+    'position:absolute;inset:0;box-sizing:border-box;padding:24px;display:flex;align-items:center;justify-content:center;pointer-events:none';
+  const line = (width, height) =>
+    `<span style="display:block;width:${width};height:${height}px;border-radius:${height / 2}px"></span>`;
+  root.innerHTML = `<div style="width:100%;max-width:280px"><div style="display:flex;flex-direction:column;align-items:center;gap:20px"><img alt="" width="32" height="34"><div style="display:flex;flex-direction:column;align-items:center;gap:10px;width:100%">${line('100%', 14)}${line('64%', 10)}</div></div></div>`;
+  root.querySelector('img').src = ICON;
+  const setTheme = (next) => {
+    const palette = PALETTE[next === 'dark' ? 'dark' : 'light'];
+    root.style.background = palette.ground;
+    for (const span of root.querySelectorAll('span')) span.style.background = palette.fill;
+  };
+  setTheme(theme);
+
+  // An unpositioned box becomes the skeleton's containing block while it shows.
+  const position = box.style.position;
+  const unpositioned = getComputedStyle(box).position === 'static';
+  if (unpositioned) box.style.position = 'relative';
+  box.append(root);
+  const stay = new MutationObserver(() => root.parentNode === box || box.append(root));
+  stay.observe(box, { childList: true });
+
+  const shownAt = Date.now() + SKELETON_DELAY_MS;
+  const stack = root.firstChild;
+  const animations = [
+    stack.animate?.([{ opacity: 0 }, { opacity: 1 }], {
+      duration: SKELETON_FADE_MS,
+      delay: SKELETON_DELAY_MS,
+      fill: 'backwards',
+    }),
+    reducedMotion()
+      ? undefined
+      : stack.firstChild.animate?.([{ opacity: 1 }, { opacity: 0.45 }, { opacity: 1 }], {
+          duration: 1600,
+          easing: 'ease-in-out',
+          iterations: Infinity,
+        }),
+  ];
+  let timer;
+  let gone = false;
+  const remove = () => {
+    if (gone) return;
+    gone = true;
+    clearTimeout(timer);
+    stay.disconnect();
+    animations.forEach((animation) => animation?.cancel());
+    root.remove();
+    if (unpositioned) box.style.position = position;
+  };
+  return {
+    setTheme,
+    remove,
+    done() {
+      if (gone || timer !== undefined) return;
+      const sinceShown = Date.now() - shownAt;
+      // Never shown (a fast load): gone at once, before its reveal can start.
+      if (sinceShown < 0) return remove();
+      // Shown: for at least SKELETON_MIN_MS, then it fades.
+      timer = setTimeout(
+        () => {
+          const fade = root.animate?.([{ opacity: 1 }, { opacity: 0 }], {
+            duration: SKELETON_FADE_MS,
+            fill: 'forwards',
+          });
+          if (!fade) return remove();
+          animations.push(fade);
+          fade.onfinish = remove;
+        },
+        Math.max(0, SKELETON_MIN_MS - sinceShown),
+      );
+    },
+  };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahmedramez-org/nexus-chat",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.7",
   "description": "NexusChat for any app: a connector and React component that load the prebuilt chat from IncortaCopilot (or a pinned copy), and the host contract types and checks.",
   "license": "UNLICENSED",
   "repository": {
@@ -53,6 +53,7 @@
     "index.js",
     "index.d.ts",
     "react.js",
+    "window.js",
     "react.d.ts",
     "contract",
     "README.md"

package/react.d.ts

@@ -8,13 +8,10 @@ import type {
   NexusChatEnvironment,
   NexusChatHandle,
   NexusChatWindow,
+  NexusChatWindowMode,
 } from './index.js';
 
-/** The chat mounted into this page, sharing its session. It fills its box. */
-export interface DirectNexusChatProps extends Omit<
-  MountNexusChatOptions,
-  'environment' | 'window'
-> {
+interface DirectChatProps extends Omit<MountNexusChatOptions, 'environment' | 'window'> {
   embedUrl?: undefined;
   /** Required unless `environment` is given. */
   theme?: HostTheme;
@@ -26,28 +23,52 @@ export interface DirectNexusChatProps extends Omit<
   user?: HostUser;
   /** The app's own contract environment, used as is instead of the props above. */
   environment?: NexusChatEnvironment;
+  /** The chat is mounted (`ask` and `attach` are available); `null` once it unmounts. */
+  onReady?(chat: NexusChatHandle | null): void;
+  /** The chat could not load (after its retry and deadline). */
+  onLoadError?(error: Error): void;
+  className?: string;
+  style?: CSSProperties;
+}
+
+/** The chat mounted into this page, sharing its session. It fills its box. */
+export interface DirectNexusChatProps extends DirectChatProps {
   /**
    * The app owns the chat's window (a docked panel, an overlay): the chat
-   * shows a dock toggle while `canDock`, and a close button. A contract
-   * `NexusChatWindow` is used as is.
+   * shows a dock toggle while `canDock` (or, with `mode`, `modes` and
+   * `setMode`, a button per other mode), and a close button. `setMode` is
+   * read at mount. A contract `NexusChatWindow` is used as is.
    */
   window?:
     | {
         docked: boolean;
         canDock: boolean;
+        mode?: NexusChatMode;
+        modes?: readonly NexusChatMode[];
         setDocked(docked: boolean): void;
+        setMode?(mode: NexusChatMode): void;
         close(): void;
       }
     | NexusChatWindow;
-  /** The chat is mounted (`ask` and `attach` are available); `null` once it unmounts. */
-  onReady?(chat: NexusChatHandle | null): void;
-  /** The chat could not load (after its retry and deadline). */
-  onLoadError?(error: Error): void;
-  className?: string;
-  style?: CSSProperties;
+  modes?: undefined;
+  defaultMode?: undefined;
+}
+
+/**
+ * The chat mounted into this page, sharing its session, in a window drawn
+ * here as for `embedUrl`: a launcher icon that opens it floating, docked on
+ * the right, or fullscreen. Giving `modes` or `defaultMode` instead of a
+ * `window` opts in.
+ */
+export interface WindowedNexusChatProps extends DirectChatProps {
+  /** Where the chat may open, in launcher order. Default: all three. */
+  modes?: NexusChatMode[];
+  /** Open on load in this mode. Default: the launcher icon only. */
+  defaultMode?: NexusChatMode;
+  window?: undefined;
 }
 
-export type NexusChatMode = 'floating' | 'docked' | 'fullscreen';
+export type NexusChatMode = NexusChatWindowMode;
 
 /**
  * The chat in an <iframe> served by Incorta, on the user's own Incorta
@@ -67,12 +88,13 @@ export interface EmbeddedNexusChatProps {
   locale?: string;
 }
 
-export type NexusChatProps = DirectNexusChatProps | EmbeddedNexusChatProps;
+export type NexusChatProps = DirectNexusChatProps | WindowedNexusChatProps | EmbeddedNexusChatProps;
 
 /**
  * The chat as a React component. Direct: it fills its box; `connection`,
  * `chat`, `actions`, `events`, `instanceId`, `assetsUrl` and `timeoutMs` are
- * read once at mount, and the other props update the running chat.
- * Embedded (`embedUrl`): it draws its own window.
+ * read once at mount, and the other props update the running chat. With
+ * `modes` or `defaultMode` (and no `window`), or embedded (`embedUrl`): it
+ * draws its own window.
  */
 export function NexusChat(props: NexusChatProps): ReactElement;