@djangocfg/widget-assistant 0.2.4 → 0.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/widget-assistant",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "A site assistant on top of @djangocfg/widget-chat: the SSE wire and session layer, a persistent host, docked column, floating button and sheet, dictation, Help and 17 built-in locales",
   "keywords": [
     "chat",
@@ -48,15 +48,15 @@
     "zustand": "^5.0.16"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.613",
-    "@djangocfg/ui-core": "^2.1.613",
+    "@djangocfg/i18n": "^2.1.616",
+    "@djangocfg/ui-core": "^2.1.616",
     "lucide-react": "^1.68.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.613",
-    "@djangocfg/typescript-config": "^2.1.613",
-    "@djangocfg/ui-core": "^2.1.613",
+    "@djangocfg/i18n": "^2.1.616",
+    "@djangocfg/typescript-config": "^2.1.616",
+    "@djangocfg/ui-core": "^2.1.616",
     "@storybook/react-vite": "^10.6.5",
     "@types/node": "^25.9.5",
     "@types/react": "19.3.0",

package/src/shell/AssistantFrame.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { useCallback, type CSSProperties, type KeyboardEvent, type PointerEvent, type ReactNode } from 'react';
+import { useCallback, useEffect, useRef, useState, type CSSProperties, type KeyboardEvent, type PointerEvent, type ReactNode } from 'react';
 
 import { X } from 'lucide-react';
 
@@ -34,21 +34,68 @@ interface Props {
   children: ReactNode;
 }
 
+/** How long the column takes to open or close; the same number is in `layout.css`. */
+const MOTION_MS = 380;
+/** A column restored at page load is already there: only a change after this long is animated. */
+const RESTORE_GRACE_MS = 800;
+
 /**
  * The page with the assistant column beside it. While `docked`, the page narrows and the column stands at the right edge, full height. Its width is published as the CSS
  * variable `--assistant-w` (`0px` when closed) so fixed elements of the host keep clear of it. Page scroll stays the window's: the column is `sticky`, not a scroll container.
+ *
+ * Opening and closing move that variable, not the column: the page eases to its new width and the column is revealed from the right edge at its full width (nothing inside
+ * reflows), with a short fade. `--assistant-w` is a registered length (`layout.css`), so fixed host elements follow the same curve. The column stays mounted until the
+ * close finishes. Resizing by hand and the first paint after a page load are not animated.
  */
 export function AssistantFrame({ docked, width, minWidth, maxWidth, defaultWidth, onWidthChange, onClose, labels, content, children }: Props) {
-  const style = { '--assistant-w': docked ? `${width}px` : '0px' } as CSSProperties;
+  const born = useRef(0);
+  const [mounted, setMounted] = useState(false);
+  const [shown, setShown] = useState(false);
+  const [moving, setMoving] = useState(false);
+
+  useEffect(() => {
+    if (!born.current) born.current = performance.now();
+    const timers: number[] = [];
+    let frame = 0;
+    if (docked) {
+      setMounted(true);
+      if (performance.now() - born.current < RESTORE_GRACE_MS) {
+        setMoving(false);
+        setShown(true);
+      } else {
+        // Mount at zero width, then (two frames on, so the browser has laid out the start) move to the real one.
+        setMoving(true);
+        frame = requestAnimationFrame(() => {
+          frame = requestAnimationFrame(() => setShown(true));
+        });
+        timers.push(window.setTimeout(() => setMoving(false), MOTION_MS + 40));
+      }
+    } else {
+      setMoving(true);
+      setShown(false);
+      timers.push(
+        window.setTimeout(() => {
+          setMounted(false);
+          setMoving(false);
+        }, MOTION_MS + 40),
+      );
+    }
+    return () => {
+      cancelAnimationFrame(frame);
+      timers.forEach(window.clearTimeout);
+    };
+  }, [docked]);
+
+  const style = { '--assistant-w': shown ? `${width}px` : '0px' } as CSSProperties;
   return (
-    <div className="flex" style={style}>
+    <div className="assistant-frame flex" data-moving={moving ? 'true' : 'false'} style={style}>
       <div className="min-w-0 flex-1">{children}</div>
-      {docked ? <Column {...{ width, minWidth, maxWidth, defaultWidth, onWidthChange, onClose, labels, content }} /> : null}
+      {mounted ? <Column {...{ width, shown, minWidth, maxWidth, defaultWidth, onWidthChange, onClose, labels, content }} /> : null}
     </div>
   );
 }
 
-function Column({ width, minWidth, maxWidth, defaultWidth, onWidthChange, onClose, labels, content }: Omit<Props, 'docked' | 'children'>) {
+function Column({ width, shown, minWidth, maxWidth, defaultWidth, onWidthChange, onClose, labels, content }: Omit<Props, 'docked' | 'children'> & { shown: boolean }) {
   const copy = useAssistantCopy();
   // The handle sits on the column's left edge: the pointer's distance from the window's right edge is the new width.
   const drag = useCallback(
@@ -77,7 +124,9 @@ function Column({ width, minWidth, maxWidth, defaultWidth, onWidthChange, onClos
   };
 
   return (
-    <aside aria-label={labels.title} style={{ width }} className="sticky top-0 flex h-dvh shrink-0 flex-col self-start border-l bg-background">
+    // The clip: as wide as the page has given so far, the column inside keeps its full width and is anchored right, so it slides in instead of squeezing.
+    <div className="assistant-clip sticky top-0 flex h-dvh shrink-0 justify-end self-start overflow-hidden" data-shown={shown ? 'true' : 'false'}>
+    <aside aria-label={labels.title} style={{ width }} className="assistant-column relative flex h-full shrink-0 flex-col border-l bg-background">
       <div
         role="separator"
         aria-orientation="vertical"
@@ -99,5 +148,6 @@ function Column({ width, minWidth, maxWidth, defaultWidth, onWidthChange, onClos
       </header>
       {content ? <div className="flex min-h-0 flex-1 flex-col">{content}</div> : <AssistantSlot className="min-h-0 flex-1" />}
     </aside>
+    </div>
   );
 }

package/src/styles/layout.css

@@ -13,3 +13,48 @@
 .assistant-chat > .chat-surface {
   flex: 1 1 0;
 }
+
+/*
+ * Opening and closing the docked column (AssistantFrame). `--assistant-w` is a registered length so it can be transitioned: the page, the clip and the fixed elements of the
+ * host that read it all follow one curve. The curve is the iOS sheet spring's settle (fast start, long soft landing); keep the duration in step with MOTION_MS in AssistantFrame.
+ * Without @property support the width simply jumps, as before.
+ */
+@property --assistant-w {
+  syntax: "<length>";
+  inherits: true;
+  initial-value: 0px;
+}
+
+.assistant-frame {
+  --assistant-ease: cubic-bezier(0.32, 0.72, 0, 1);
+  --assistant-ms: 380ms;
+}
+
+.assistant-frame[data-moving="true"] {
+  transition: --assistant-w var(--assistant-ms) var(--assistant-ease);
+}
+
+.assistant-clip {
+  width: var(--assistant-w);
+  opacity: 0;
+}
+
+.assistant-clip[data-shown="true"] {
+  opacity: 1;
+}
+
+.assistant-frame[data-moving="true"] .assistant-clip {
+  transition: opacity calc(var(--assistant-ms) * 0.7) ease-out;
+}
+
+/* Closing: the fade finishes early so the column does not look like it is dragged off. */
+.assistant-frame[data-moving="true"] .assistant-clip[data-shown="false"] {
+  transition-duration: calc(var(--assistant-ms) * 0.45);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .assistant-frame[data-moving="true"],
+  .assistant-frame[data-moving="true"] .assistant-clip {
+    transition: none;
+  }
+}