@djangocfg/widget-assistant 0.3.7 → 0.3.9

package/README.md

@@ -7,6 +7,10 @@ It knows nothing about one site (`src/boundary.test.ts` enforces it), so what a
 <AssistantChat adapter={adapter} suggestions={suggestions} dataRenderers={renderers} />
 ```
 
+## Docs
+
+Longer pages live in [`@docs/`](./@docs/README.md) (repository only, not in the npm package): architecture, the wire contract, the Python server half, connecting a new project, customization, troubleshooting. The server half is not in django-cfg's config: each product writes its own on the agent plane (`@docs/server.md`).
+
 ## Folders (one job each)
 
 | Folder | Job |
@@ -69,7 +73,7 @@ Dictation start/stop tones are bundled (Web Audio, no files). `sounds={false}` s
 ## Asking from outside, the dock and the locked room
 
 *   `askAssistant(text)` puts a prompt typed elsewhere on the page (a hero search, a "discuss this" button) into the composer and sends it once the composer is mounted and sending is allowed. One slot: asking twice before the composer exists keeps the last.
-*   `AssistantFrame` and `ChatDock` take `actions` (header controls such as `SessionsMenu`): they sit next to Close in the one panel header (`ChatPanelHeader` from `widget-chat`, drawn identically by the wide column, the tablet side panel and the phone sheet), set apart by a thin divider; each button has a ui-core tooltip. `ChatDock` is a side panel on tablets, the base package's `ChatSheet` on phones. The keys list (`ComposerHelp`) is hidden on touch devices.
+*   `<AssistantHeaderActions><SessionsMenu session={session} /></AssistantHeaderActions>`, rendered beside `AssistantPortal`, publishes the header controls; `AssistantFrame` and `ChatDock` show them with no wiring between the files (an explicit `actions` prop wins). `AssistantFrame` and `ChatDock` take `actions` (header controls such as `SessionsMenu`): they sit next to Close in the one panel header (`ChatPanelHeader` from `widget-chat`, drawn identically by the wide column, the tablet side panel and the phone sheet), set apart by a thin divider; each button has a ui-core tooltip. `ChatDock` is a side panel on tablets, the base package's `ChatSheet` on phones. The keys list (`ComposerHelp`) is hidden on touch devices.
 *   `AssistantLocked` takes `onComposerClick`: the inert composer becomes a button for the way out (sign in).
 
 ## Tests

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/widget-assistant",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "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",
@@ -44,19 +44,19 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@djangocfg/widget-chat": "^0.1.23",
+    "@djangocfg/widget-chat": "^0.1.25",
     "zustand": "^5.0.16"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.622",
-    "@djangocfg/ui-core": "^2.1.622",
+    "@djangocfg/i18n": "^2.1.624",
+    "@djangocfg/ui-core": "^2.1.624",
     "lucide-react": "^1.68.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.622",
-    "@djangocfg/typescript-config": "^2.1.622",
-    "@djangocfg/ui-core": "^2.1.622",
+    "@djangocfg/i18n": "^2.1.624",
+    "@djangocfg/typescript-config": "^2.1.624",
+    "@djangocfg/ui-core": "^2.1.624",
     "@storybook/react-vite": "^10.6.5",
     "@types/node": "^25.9.5",
     "@types/react": "19.3.0",

package/src/Host.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { createContext, useContext, useEffect, useLayoutEffect, useMemo, useRef, type ReactNode } from 'react';
+import { createContext, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react';
 import { createPortal } from 'react-dom';
 
 /**
@@ -13,6 +13,9 @@ interface HostValue {
   park: HTMLElement;
 }
 const HostContext = createContext<HostValue | null>(null);
+/** The header controls the conversation publishes (`AssistantHeaderActions`), and the stable setter it publishes them with. Two contexts: the publisher must not re-render when they change. */
+const ActionsContext = createContext<ReactNode>(null);
+const SetActionsContext = createContext<((actions: ReactNode) => void) | null>(null);
 
 export function AssistantHostProvider({ children }: { children: ReactNode }) {
   // Browser only: on the server there is no element, and slots render empty.
@@ -32,7 +35,14 @@ export function AssistantHostProvider({ children }: { children: ReactNode }) {
     return () => value.park.remove();
   }, [value]);
 
-  return <HostContext.Provider value={value}>{children}</HostContext.Provider>;
+  const [actions, setActions] = useState<ReactNode>(null);
+  return (
+    <HostContext.Provider value={value}>
+      <SetActionsContext.Provider value={setActions}>
+        <ActionsContext.Provider value={actions}>{children}</ActionsContext.Provider>
+      </SetActionsContext.Provider>
+    </HostContext.Provider>
+  );
 }
 
 /** Renders the chat (`children`) into the host element. Mount it once, for a signed-in viewer, inside the provider. */
@@ -55,3 +65,22 @@ export function AssistantSlot({ className }: { className?: string }) {
   }, [host]);
   return <div ref={box} className={className} />;
 }
+
+/**
+ * Publishes the header controls (`<SessionsMenu session={session} />`) from wherever the conversation is mounted. `AssistantFrame` and `ChatDock` show them next to Close
+ * without the host passing them through its component tree: the column, the dock and the conversation are usually three different files. Render it beside `AssistantPortal`.
+ * An explicit `actions` prop on the frame or the dock still wins.
+ */
+export function AssistantHeaderActions({ children }: { children: ReactNode }) {
+  const set = useContext(SetActionsContext);
+  useEffect(() => {
+    set?.(children);
+  }, [set, children]);
+  useEffect(() => () => set?.(null), [set]);
+  return null;
+}
+
+/** The controls published by `AssistantHeaderActions`, or null. */
+export function useHeaderActions(): ReactNode {
+  return useContext(ActionsContext);
+}

package/src/index.ts

@@ -7,7 +7,7 @@ export { AssistantFrame, type FrameLabels } from './shell/AssistantFrame';
 export { AssistantFab, type FabHint } from './shell/AssistantFab';
 export { AssistantLocked } from './shell/AssistantLocked';
 export { createAssistantUi, useMediaQuery, type UiOptions, type UiState, type UiStorage } from './shell/panelState';
-export { AssistantHostProvider, AssistantPortal, AssistantSlot } from './Host';
+export { AssistantHostProvider, AssistantPortal, AssistantSlot, AssistantHeaderActions } from './Host';
 export { useSession, type Session, type SessionCopy, type SessionDeps, type SessionNotice, type ThreadState } from './stream/useSession';
 export { relativeTime, restoreSession, type SessionStorage, type ThreadApi } from './stream/sessions';
 export { SessionsMenu } from './sessions/SessionsMenu';

package/src/shell/AssistantFrame.tsx

@@ -4,7 +4,7 @@ import { useCallback, useEffect, useRef, useState, type CSSProperties, type Keyb
 
 import { ChatPanelHeader, PANEL_TITLE_CLASS, PanelCloseButton } from '@djangocfg/widget-chat';
 
-import { AssistantSlot } from '../Host';
+import { AssistantSlot, useHeaderActions } from '../Host';
 import { useAssistantCopy } from '../i18n';
 
 export interface FrameLabels {
@@ -97,6 +97,7 @@ export function AssistantFrame({ docked, width, minWidth, maxWidth, defaultWidth
 
 function Column({ width, shown, minWidth, maxWidth, defaultWidth, onWidthChange, onClose, labels, content, actions }: Omit<Props, 'docked' | 'children'> & { shown: boolean }) {
   const copy = useAssistantCopy();
+  const published = useHeaderActions();
   // 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(
     (event: PointerEvent<HTMLDivElement>) => {
@@ -142,7 +143,7 @@ function Column({ width, shown, minWidth, maxWidth, defaultWidth, onWidthChange,
       />
       <ChatPanelHeader
         heading={<h2 className={PANEL_TITLE_CLASS}>{labels.title}</h2>}
-        actions={actions}
+        actions={actions ?? published}
         close={<PanelCloseButton label={labels.close ?? copy.close} onClick={onClose} />}
       />
       {content ? <div className="flex min-h-0 flex-1 flex-col">{content}</div> : <AssistantSlot className="min-h-0 flex-1" />}

package/src/shell/ChatDock.tsx

@@ -6,6 +6,7 @@ import { SidePanel } from '@djangocfg/ui-core/components';
 import { useIsMobile } from '@djangocfg/ui-core/hooks';
 import { ChatPanelHeader, ChatSheet, PANEL_TITLE_CLASS, PanelCloseButton } from '@djangocfg/widget-chat';
 
+import { useHeaderActions } from '../Host';
 import { useAssistantCopy } from '../i18n';
 
 interface Props {
@@ -26,10 +27,12 @@ interface Props {
 export function ChatDock({ open, onOpenChange, children: chat, title, contextLine, closeLabel, actions }: Props) {
   const isMobile = useIsMobile();
   const copy = useAssistantCopy();
+  const published = useHeaderActions();
+  const shown = actions ?? published;
 
   if (isMobile) {
     return (
-      <ChatSheet open={open} onOpenChange={onOpenChange} title={title} description={contextLine} closeLabel={closeLabel ?? copy.close} actions={actions}>
+      <ChatSheet open={open} onOpenChange={onOpenChange} title={title} description={contextLine} closeLabel={closeLabel ?? copy.close} actions={shown}>
         {chat}
       </ChatSheet>
     );
@@ -41,7 +44,7 @@ export function ChatDock({ open, onOpenChange, children: chat, title, contextLin
         <ChatPanelHeader
           heading={<SidePanel.Title className={PANEL_TITLE_CLASS}>{title}</SidePanel.Title>}
           description={contextLine ? <SidePanel.Description>{contextLine}</SidePanel.Description> : undefined}
-          actions={actions}
+          actions={shown}
           close={<PanelCloseButton label={closeLabel ?? copy.close} onClick={() => onOpenChange(false)} />}
         />
         <SidePanel.Body>{chat}</SidePanel.Body>

package/src/styles/widget.css

@@ -1,7 +1,16 @@
 /* The widget's own stylesheet carries the visual rules (composer, transcript, markdown); it must join the Tailwind pipeline by @import, not by a JS import in a component. */
 @import "@djangocfg/widget-chat/styles";
 
-/* Tailwind must see the widgets' classes: without these sources it purges them silently (the root node_modules holds them; the package has none of its own). */
-@source "../../../../node_modules/@djangocfg/widget-chat/src/**/*.{ts,tsx}";
-@source "../../../../node_modules/@djangocfg/widget-kit/src/**/*.{ts,tsx}";
-@source "../../../../node_modules/@djangocfg/widget-media/src/**/*.{ts,tsx}";
+/* Tailwind must see the widgets' classes: without these sources it purges them silently.
+   An @source path is relative to THIS file, and the file sits at <pkg>/src/styles, so "../../../" is the folder that holds the package:
+   - installed (npm, or pnpm with hoisting): node_modules/@djangocfg/, where the packages are named widget-chat, widget-kit, widget-media;
+   - the django-cfg monorepo: frontend/widgets/, where the same packages are the folders chat, kit, media.
+   A path that matches nothing in one layout is harmless, so both are listed. Checked with Tailwind 4.3 against a flat install, a pnpm
+   install and the monorepo (see @docs/troubleshooting.md). A strict pnpm install without hoisting cannot reach widget-kit and widget-media
+   from here: list them as direct dependencies of the app, or name them in the app's own @source (see @docs/connect.md). */
+@source "../../../widget-chat/src/**/*.{ts,tsx}";
+@source "../../../widget-kit/src/**/*.{ts,tsx}";
+@source "../../../widget-media/src/**/*.{ts,tsx}";
+@source "../../../chat/src/**/*.{ts,tsx}";
+@source "../../../kit/src/**/*.{ts,tsx}";
+@source "../../../media/src/**/*.{ts,tsx}";

package/src/wire/fixtures/events.json

@@ -1,5 +1,5 @@
 {
-  "_note": "One of each frame the server speaks. The Python side (django_cfg agent bus events) commits the same file in its own tests; a drift fails a test on either side.",
+  "_note": "One of each frame the server speaks. Canonical copy: this file. The Python copy is django_cfg/modules/django_llm/agent/bus/tests/fixtures/events.json; bus/tests/test_wire_contract.py fails when the two differ or when a bus event no longer encodes to a frame here, and wire.test.ts decodes every frame here. Change both files in one commit.",
   "frames": [
     { "type": "run", "version": 1, "thread_id": "5f0c8a52-7f0e-4c43-9a43-0e3b5a0d2f11", "message_id": "9b1e2c7a-4a0f-4d52-8d0d-3f1f6c9a7e22", "client_id": "c0a8e1d2-8f2e-4b7e-a1c4-6f5d8c1b2a33", "seq": 2 },
     { "type": "status", "phase": "thinking" },