@agentforge-io/chat-sdk 2.4.0-dev.5 → 2.4.0-dev.7

package/dist/ChatDrawer.d.ts

@@ -1,24 +1,61 @@
 /**
- * `<ChatDrawer>` — fullscreen mobile chat shell.
+ * `<ChatDrawer>` — standard bottom-sheet wrapper around `<ChatWidget>`.
  *
- * Plain `position: fixed` modal. No Vaul, no Radix Dialog, no focus
- * trap. Those libraries fought us repeatedly: Radix's `onPointerDownOutside`
- * mis-classified the Send tap as "interact outside" and closed the
- * drawer; Radix's focus trap moved focus to the wrapper when the send
- * button disabled, collapsing the mobile keyboard.
+ * The host gives us:
+ *   - `open` / `onOpenChange`: controlled visibility (host owns the route /
+ *     URL sync, the SDK doesn't touch the URL).
+ *   - All the `<ChatWidget>` props (token, apiBaseUrl, etc.): forwarded
+ *     verbatim. The widget mounts INSIDE the drawer.
  *
- * What this gives us:
- *   - 100dvh (dynamic viewport height): the surface shrinks automatically
- *     when the on-screen keyboard appears, so the composer stays above
- *     the keys without any visualViewport bookkeeping.
- *   - No focus interception: the textarea owns its own focus. As long
- *     as the host's Send button uses `onPointerDown preventDefault`,
- *     focus never leaves the textarea and the keyboard never collapses.
- *   - No drag-to-dismiss, no click-outside, no ESC handling. The host
- *     closes via the back chevron in its header.
+ * What the drawer adds on top:
+ *   - Mounts via React portal (`document.body`) so it overlays the page
+ *     regardless of the host's stacking context. Lazy-mounted: the portal
+ *     target is computed at first open so SSR stays clean.
+ *   - Visually pinned to the bottom of the *visual viewport* (not the
+ *     layout viewport). On iOS Safari and Android Chrome the on-screen
+ *     keyboard shrinks `window.visualViewport.height`; we listen to
+ *     `resize` / `scroll` on visualViewport and reflow the drawer's
+ *     `height` + `bottom` so the composer never gets clipped by the
+ *     keyboard.
+ *   - Opens at a configurable snap fraction (default 0.98 = 98% of the
+ *     visible viewport). The visitor sees a thin sliver of the page
+ *     underneath, which keeps context and lets a tap-outside dismiss.
+ *   - Drag-to-dismiss with vanilla touch events: drag the handle down
+ *     past 30% of the panel height and the drawer closes. No external
+ *     deps — the SDK stays portable.
+ *   - Survives close+reopen: the widget inside is rendered once and kept
+ *     alive (CSS `display:none` toggle when closed, NOT unmounted), so
+ *     the chat session, transcript, and any in-flight tool calls stay
+ *     intact when the visitor closes and reopens the drawer.
+ *
+ * What the drawer does NOT do (deliberately):
+ *   - It doesn't sync with the URL. The host decides whether `?view=chat`,
+ *     `/chat`, or any other route shape opens it.
+ *   - It doesn't manage the chat session lifecycle. That's `<ChatWidget>`'s
+ *     job. We just provide presentation.
+ *   - It doesn't render a "fake composer" to trigger opening. The host
+ *     decides what trigger UX makes sense (button, input pill, FAB, etc.)
+ *     and calls `onOpenChange(true)`.
  */
 import { type CSSProperties, type ReactNode } from 'react';
 import { type ChatWidgetProps } from './react';
+/**
+ * Drawer accepts the chat surface in two shapes:
+ *
+ *   - `widgetProps`: pass the ChatWidget configuration and the drawer
+ *     creates the widget internally. The standard / forward-looking
+ *     API — most consumers should use this.
+ *
+ *   - `chatSlot`: pass a pre-rendered React node (typically a
+ *     `<ChatWidget>` instance the host wired up itself). Useful when
+ *     the host already orchestrates the widget (multiple chat slots,
+ *     custom decorators, legacy code) and just wants the drawer's
+ *     positioning + drag UX on top.
+ *
+ * Exactly one of the two MUST be passed. Mutual exclusivity isn't
+ * encoded at the type level (TS unions with optional props get noisy)
+ * — the runtime asserts gracefully if neither is present.
+ */
 type ChatSurface = {
     widgetProps: ChatWidgetProps;
     chatSlot?: never;
@@ -27,23 +64,39 @@ type ChatSurface = {
     widgetProps?: never;
 };
 export type ChatDrawerProps = ChatSurface & {
-    /** Controlled visibility. */
+    /** Whether the drawer is visible. Controlled. */
     open: boolean;
-    /** Fired when the drawer wants to close. Today only the host's back
-     *  chevron emits this — no auto-dismiss paths exist. Kept in the
-     *  shape so the host doesn't have to change call sites. */
+    /** Fired when the drawer wants to close (drag-to-dismiss, tap on the
+     *  backdrop, close button). Host is responsible for setting `open=false`. */
     onOpenChange: (open: boolean) => void;
-    /** Sticky header above the chat panel. */
+    /** Snap fraction of the visible viewport, 0–1. Defaults to 0.98 (98% =
+     *  the standard "near-fullscreen drawer that still hints at the page
+     *  below" pattern). Lower numbers leave more of the page visible. */
+    snap?: number;
+    /** Display in the drawer header above the chat. Templates pass the
+     *  agent / team identity here. When omitted, the drawer renders a
+     *  bare drag handle only — useful for hosts that want a borderless
+     *  panel. */
     header?: ReactNode;
-    /** Custom close button rendered ABOVE `header`. Default is the SDK's
-     *  chevron-left. Pass `null` to opt out (when the host renders its
-     *  own close affordance inline within `header`). */
-    closeButton?: ReactNode;
-    /** Extra class on the drawer surface. */
+    /** Backdrop click closes the drawer. Default true — set false if the
+     *  host wants a "modal" feel where the only escape is the close button
+     *  or the drag-down gesture. */
+    closeOnBackdropClick?: boolean;
+    /** Extra class on the drawer's root surface (the white card). Use it to
+     *  add a custom shadow / border colour. The CSS vars on `--af-*` already
+     *  let you re-theme the chat widget itself; this is for the SURROUND. */
     drawerClassName?: string;
-    /** CSS vars (`--af-bg`, `--af-fg`, `--af-bubble-*`, …) for the
-     *  surface. The drawer renders into a portal, so the host's
-     *  page-wrapper vars don't cascade in — re-declare them here. */
+    /** Inline style applied to the drawer surface — typically the host's
+     *  bundle of `--af-bg`, `--af-fg`, `--af-bubble-*`, etc. CSS vars.
+     *  Because the drawer renders into a portal (`document.body`), any
+     *  vars declared on the host's page wrapper DON'T cascade in. The
+     *  host re-declares them here so the chat surface inside the portal
+     *  picks up the same theme.
+     *
+     *  We default the SURFACE BG to `var(--af-bg, …)` so passing
+     *  `--af-bg` in `surfaceStyle` themes the drawer's background.
+     *  When omitted the drawer falls back to white in light mode and
+     *  the system default elsewhere — passable but not theme-perfect. */
     surfaceStyle?: CSSProperties & Record<string, string>;
 };
 export declare function ChatDrawer(props: ChatDrawerProps): JSX.Element | null;

package/dist/ChatDrawer.js

@@ -3,36 +3,143 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChatDrawer = ChatDrawer;
 const jsx_runtime_1 = require("react/jsx-runtime");
 /**
- * `<ChatDrawer>` — fullscreen mobile chat shell.
+ * `<ChatDrawer>` — standard bottom-sheet wrapper around `<ChatWidget>`.
  *
- * Plain `position: fixed` modal. No Vaul, no Radix Dialog, no focus
- * trap. Those libraries fought us repeatedly: Radix's `onPointerDownOutside`
- * mis-classified the Send tap as "interact outside" and closed the
- * drawer; Radix's focus trap moved focus to the wrapper when the send
- * button disabled, collapsing the mobile keyboard.
+ * The host gives us:
+ *   - `open` / `onOpenChange`: controlled visibility (host owns the route /
+ *     URL sync, the SDK doesn't touch the URL).
+ *   - All the `<ChatWidget>` props (token, apiBaseUrl, etc.): forwarded
+ *     verbatim. The widget mounts INSIDE the drawer.
  *
- * What this gives us:
- *   - 100dvh (dynamic viewport height): the surface shrinks automatically
- *     when the on-screen keyboard appears, so the composer stays above
- *     the keys without any visualViewport bookkeeping.
- *   - No focus interception: the textarea owns its own focus. As long
- *     as the host's Send button uses `onPointerDown preventDefault`,
- *     focus never leaves the textarea and the keyboard never collapses.
- *   - No drag-to-dismiss, no click-outside, no ESC handling. The host
- *     closes via the back chevron in its header.
+ * What the drawer adds on top:
+ *   - Mounts via React portal (`document.body`) so it overlays the page
+ *     regardless of the host's stacking context. Lazy-mounted: the portal
+ *     target is computed at first open so SSR stays clean.
+ *   - Visually pinned to the bottom of the *visual viewport* (not the
+ *     layout viewport). On iOS Safari and Android Chrome the on-screen
+ *     keyboard shrinks `window.visualViewport.height`; we listen to
+ *     `resize` / `scroll` on visualViewport and reflow the drawer's
+ *     `height` + `bottom` so the composer never gets clipped by the
+ *     keyboard.
+ *   - Opens at a configurable snap fraction (default 0.98 = 98% of the
+ *     visible viewport). The visitor sees a thin sliver of the page
+ *     underneath, which keeps context and lets a tap-outside dismiss.
+ *   - Drag-to-dismiss with vanilla touch events: drag the handle down
+ *     past 30% of the panel height and the drawer closes. No external
+ *     deps — the SDK stays portable.
+ *   - Survives close+reopen: the widget inside is rendered once and kept
+ *     alive (CSS `display:none` toggle when closed, NOT unmounted), so
+ *     the chat session, transcript, and any in-flight tool calls stay
+ *     intact when the visitor closes and reopens the drawer.
+ *
+ * What the drawer does NOT do (deliberately):
+ *   - It doesn't sync with the URL. The host decides whether `?view=chat`,
+ *     `/chat`, or any other route shape opens it.
+ *   - It doesn't manage the chat session lifecycle. That's `<ChatWidget>`'s
+ *     job. We just provide presentation.
+ *   - It doesn't render a "fake composer" to trigger opening. The host
+ *     decides what trigger UX makes sense (button, input pill, FAB, etc.)
+ *     and calls `onOpenChange(true)`.
  */
 const react_1 = require("react");
+const react_dom_1 = require("react-dom");
 const react_2 = require("./react");
 function ChatDrawer(props) {
-    const { open, onOpenChange, header, closeButton, drawerClassName, surfaceStyle, widgetProps, chatSlot, } = props;
-    // Defer the first paint until after mount so SSR doesn't try to
-    // render a portal target that doesn't exist yet.
-    const [mounted, setMounted] = (0, react_1.useState)(false);
+    const { open, onOpenChange, snap = 1, header, closeOnBackdropClick = true, drawerClassName, surfaceStyle: surfaceStyleProp, widgetProps, chatSlot, } = props;
+    // `fullscreen` mode: snap=1 (the default). The drawer occupies the
+    // entire visible viewport. We disable drag-to-dismiss, the backdrop,
+    // the rounded top corners, and the drag handle in this mode — they
+    // exist purely for the bottom-sheet form factor (snap<1) where the
+    // page peeks behind the surface. With snap=1 there's nothing behind
+    // and no affordance to drag against.
+    const fullscreen = snap >= 1;
+    // We mount once and keep alive across close→reopen so the chat session
+    // doesn't get destroyed. After the FIRST open the panel stays in the
+    // DOM forever (toggled by `display:none`) — `hasOpened` gates the
+    // initial mount so SSR doesn't render an empty portal.
+    const [hasOpened, setHasOpened] = (0, react_1.useState)(open);
+    (0, react_1.useEffect)(() => {
+        if (open)
+            setHasOpened(true);
+    }, [open]);
+    // Visible viewport tracking. iOS Safari + Android Chrome shrink
+    // `visualViewport.height` when the on-screen keyboard pops up; the
+    // layout viewport stays the same. We pin the drawer's height + bottom
+    // to the visual viewport so the composer is always above the keyboard.
+    const [vv, setVv] = (0, react_1.useState)(() => ({
+        h: typeof window === 'undefined' ? 0 : window.innerHeight,
+        offsetTop: 0,
+    }));
     (0, react_1.useEffect)(() => {
-        setMounted(true);
+        if (typeof window === 'undefined')
+            return;
+        const view = window.visualViewport;
+        if (!view)
+            return;
+        const update = () => setVv({ h: view.height, offsetTop: view.offsetTop });
+        update();
+        view.addEventListener('resize', update);
+        view.addEventListener('scroll', update);
+        return () => {
+            view.removeEventListener('resize', update);
+            view.removeEventListener('scroll', update);
+        };
+    }, []);
+    // Snap-point height: % of the visible viewport. Recomputed when vv
+    // changes so a keyboard popup keeps the drawer aligned.
+    const drawerHeight = Math.max(0, Math.round(vv.h * Math.min(Math.max(snap, 0.1), 1)));
+    // Drag-to-dismiss. Vanilla touch handlers — no library. We track
+    // pointerdown on the handle, follow movement on pointermove, and
+    // decide on pointerup whether the drag crossed the "dismiss" threshold
+    // (30% of the panel height).
+    const surfaceRef = (0, react_1.useRef)(null);
+    const dragStateRef = (0, react_1.useRef)(null);
+    const [dragOffset, setDragOffset] = (0, react_1.useState)(0);
+    const onHandlePointerDown = (0, react_1.useCallback)((e) => {
+        if (e.button !== 0 && e.pointerType !== 'touch')
+            return;
+        e.currentTarget.setPointerCapture?.(e.pointerId);
+        dragStateRef.current = {
+            startY: e.clientY,
+            startTime: Date.now(),
+            dragging: true,
+        };
+    }, []);
+    const onHandlePointerMove = (0, react_1.useCallback)((e) => {
+        const s = dragStateRef.current;
+        if (!s?.dragging)
+            return;
+        const delta = Math.max(0, e.clientY - s.startY);
+        setDragOffset(delta);
     }, []);
-    // Lock body scroll while the drawer is open. Standard pattern: save
-    // the previous overflow, set hidden, restore on close/unmount.
+    const onHandlePointerUp = (0, react_1.useCallback)((e) => {
+        const s = dragStateRef.current;
+        if (!s?.dragging)
+            return;
+        dragStateRef.current = null;
+        try {
+            e.currentTarget.releasePointerCapture?.(e.pointerId);
+        }
+        catch {
+            // Pointer was already released by some other code path; nothing
+            // to do here. Releasing a non-captured pointer throws — swallow.
+        }
+        const delta = Math.max(0, e.clientY - s.startY);
+        const dismissThreshold = drawerHeight * 0.3;
+        const elapsed = Date.now() - s.startTime;
+        // Dismiss on EITHER a long-drag (past the threshold) or a quick
+        // flick (small distance but high velocity). Velocity unit is
+        // px/ms; >0.5 is roughly the threshold iOS sheets use.
+        const velocity = elapsed > 0 ? delta / elapsed : 0;
+        if (delta > dismissThreshold || velocity > 0.5) {
+            onOpenChange(false);
+        }
+        setDragOffset(0);
+    }, [drawerHeight, onOpenChange]);
+    // Lock body scroll while the drawer is open so the page underneath
+    // doesn't move when the visitor scrolls inside the chat. Restored on
+    // close. Necessary on iOS Safari where the rubber-band scroll bleeds
+    // through to the body even with overflow:hidden on a child.
     (0, react_1.useEffect)(() => {
         if (typeof document === 'undefined')
             return;
@@ -44,48 +151,102 @@ function ChatDrawer(props) {
             document.body.style.overflow = prev;
         };
     }, [open]);
-    if (!mounted || !open)
+    // Escape closes the drawer. Keyboard-friendly even when focus is in
+    // the textarea — preventDefault on the input itself swallows Escape
+    // before it bubbles, so we use capture phase.
+    (0, react_1.useEffect)(() => {
+        if (!open)
+            return;
+        if (typeof window === 'undefined')
+            return;
+        const onKey = (e) => {
+            if (e.key === 'Escape')
+                onOpenChange(false);
+        };
+        window.addEventListener('keydown', onKey, true);
+        return () => window.removeEventListener('keydown', onKey, true);
+    }, [open, onOpenChange]);
+    // Lazy portal target. We render to `document.body` so the drawer
+    // overlays everything regardless of the consumer's stacking context.
+    const [portalEl, setPortalEl] = (0, react_1.useState)(null);
+    (0, react_1.useLayoutEffect)(() => {
+        if (typeof document === 'undefined')
+            return;
+        setPortalEl(document.body);
+    }, []);
+    // Stable id so the drag handle's `aria-controls` can point at the
+    // panel. Required for screen readers to announce the relationship.
+    const panelId = (0, react_1.useId)();
+    if (!portalEl)
         return null;
-    const chatNode = chatSlot ?? (widgetProps ? ((0, jsx_runtime_1.jsx)(react_2.ChatWidget, { ...widgetProps, inline: true, variant: widgetProps.variant ?? 'bare' })) : null);
-    return ((0, jsx_runtime_1.jsxs)("div", { role: "dialog", "aria-modal": "true", "aria-label": "Chat", className: `af-drawer-surface ${drawerClassName ?? ''}`, style: {
-            // 100dvh shrinks when the on-screen keyboard appears.
-            // `inset: 0` + `position: fixed` covers the viewport.
+    if (!hasOpened)
+        return null;
+    // The translate3d ensures the drawer animates from below on first
+    // open (initial transform = 100%, becomes 0% after the open prop
+    // flips). When dragging we add the manual drag offset on top.
+    const translateY = open ? `${dragOffset}px` : `${drawerHeight}px`;
+    // Transition disabled WHILE dragging so the surface follows the
+    // finger 1:1. Re-enabled at the end of the drag (delta back to 0
+    // smoothly when below threshold).
+    const isDragging = dragStateRef.current?.dragging === true;
+    // Motion / sizing portion of the surface style, kept separate from
+    // the host-supplied theming so a re-render driven by drag offset
+    // doesn't smash the host's CSS vars.
+    const surfaceMotionStyle = {
+        height: `${drawerHeight}px`,
+        transform: `translate3d(0, ${translateY}, 0)`,
+        bottom: `${vv.offsetTop}px`,
+        transition: isDragging ? 'none' : 'transform 240ms cubic-bezier(.32,.72,0,1)',
+        willChange: 'transform',
+    };
+    return (0, react_dom_1.createPortal)((0, jsx_runtime_1.jsxs)("div", { className: "af-drawer-root", "data-state": open ? 'open' : 'closed', style: {
             position: 'fixed',
             inset: 0,
-            height: '100dvh',
             zIndex: 2147483600,
-            display: 'flex',
-            flexDirection: 'column',
-            backgroundColor: 'var(--af-bg, #ffffff)',
-            color: 'var(--af-fg, inherit)',
-            ...surfaceStyle,
-        }, children: [(0, jsx_runtime_1.jsxs)("div", { style: {
-                    flexShrink: 0,
+            pointerEvents: open ? 'auto' : 'none',
+        }, children: [!fullscreen && ((0, jsx_runtime_1.jsx)("div", { className: "af-drawer-backdrop", onClick: closeOnBackdropClick ? () => onOpenChange(false) : undefined, style: {
+                    position: 'absolute',
+                    inset: 0,
+                    backgroundColor: 'rgba(0, 0, 0, 0.4)',
+                    opacity: open ? 1 : 0,
+                    transition: 'opacity 200ms ease-out',
+                }, "aria-hidden": true })), (0, jsx_runtime_1.jsxs)("div", { ref: surfaceRef, id: panelId, role: "dialog", "aria-modal": "true", className: `af-drawer-surface ${drawerClassName ?? ''}`, style: {
+                    position: 'absolute',
+                    left: 0,
+                    right: 0,
+                    width: '100%',
+                    // Host supplies the CSS vars via `surfaceStyle`; the
+                    // backgroundColor resolves from `--af-bg` (which the host
+                    // declares in that same prop). When `surfaceStyle` is
+                    // omitted we fall back to white — passable for an unthemed
+                    // demo, wrong for a themed embed; passing surfaceStyle is
+                    // the correct path.
                     backgroundColor: 'var(--af-bg, #ffffff)',
-                    borderBottom: '1px solid var(--af-border, rgba(15, 23, 42, 0.08))',
-                }, children: [closeButton === undefined ? ((0, jsx_runtime_1.jsx)(DefaultCloseButton, { onClose: () => onOpenChange(false) })) : (closeButton), header] }), (0, jsx_runtime_1.jsx)("div", { style: {
-                    flex: 1,
-                    minHeight: 0,
+                    color: 'var(--af-fg, inherit)',
+                    // Bottom-sheet visuals only — fullscreen mode is flat.
+                    borderTopLeftRadius: fullscreen ? 0 : '16px',
+                    borderTopRightRadius: fullscreen ? 0 : '16px',
+                    boxShadow: fullscreen ? 'none' : '0 -8px 24px rgba(15, 23, 42, 0.25)',
                     display: 'flex',
                     flexDirection: 'column',
-                }, "data-af-drawer-body": true, children: chatNode })] }));
-}
-function DefaultCloseButton({ onClose }) {
-    return ((0, jsx_runtime_1.jsx)("div", { style: {
-            display: 'flex',
-            alignItems: 'center',
-            padding: '8px 12px',
-        }, children: (0, jsx_runtime_1.jsx)("button", { type: "button", onClick: onClose, "aria-label": "Close chat", style: {
-                appearance: 'none',
-                background: 'transparent',
-                border: 'none',
-                padding: '8px',
-                margin: 0,
-                cursor: 'pointer',
-                color: 'var(--af-fg, inherit)',
-                display: 'inline-flex',
-                alignItems: 'center',
-                justifyContent: 'center',
-                borderRadius: '8px',
-            }, children: (0, jsx_runtime_1.jsx)("svg", { width: "20", height: "20", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": true, children: (0, jsx_runtime_1.jsx)("polyline", { points: "15 18 9 12 15 6" }) }) }) }));
+                    overflow: 'hidden',
+                    // Host-supplied theme vars come FIRST so the motion
+                    // properties below override any conflicting `transform` /
+                    // `height` declarations a careless host might pass.
+                    ...surfaceStyleProp,
+                    ...surfaceMotionStyle,
+                }, children: [!fullscreen && ((0, jsx_runtime_1.jsx)("div", { onPointerDown: onHandlePointerDown, onPointerMove: onHandlePointerMove, onPointerUp: onHandlePointerUp, onPointerCancel: onHandlePointerUp, style: {
+                            padding: '10px 0',
+                            cursor: 'grab',
+                            touchAction: 'none',
+                            display: 'flex',
+                            justifyContent: 'center',
+                            flexShrink: 0,
+                        }, "aria-label": "Drag to close", children: (0, jsx_runtime_1.jsx)("span", { style: {
+                                width: '40px',
+                                height: '4px',
+                                borderRadius: '999px',
+                                backgroundColor: 'var(--af-muted, rgba(100, 116, 139, 0.45))',
+                                display: 'block',
+                            } }) })), header, (0, jsx_runtime_1.jsx)("div", { style: { flex: 1, minHeight: 0, display: 'flex', flexDirection: 'column' }, children: chatSlot ?? (widgetProps ? ((0, jsx_runtime_1.jsx)(react_2.ChatWidget, { ...widgetProps, inline: true, variant: widgetProps.variant ?? 'bare' })) : null) })] })] }), portalEl);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge-io/chat-sdk",
-  "version": "2.4.0-dev.5",
+  "version": "2.4.0-dev.7",
   "description": "Framework-free chat session SDK for AgentForge public chat tokens. Headless — no DOM. Drop into any frontend (React, Vue, Svelte, vanilla) and listen for events.",
   "license": "MIT",
   "main": "dist/index.js",
@@ -35,7 +35,6 @@
     "@types/node": "^20.0.0",
     "@types/react": "^18.3.28",
     "react": "^18.3.1",
-    "react-dom": "^18.3.1",
     "typescript": "^5.0.0"
   }
 }