@djangocfg/ui-tools 2.1.374 → 2.1.376

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.374",
+  "version": "2.1.376",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -156,8 +156,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.374",
-    "@djangocfg/ui-core": "^2.1.374",
+    "@djangocfg/i18n": "^2.1.376",
+    "@djangocfg/ui-core": "^2.1.376",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -211,10 +211,10 @@
     "material-file-icons": "^2.4.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.374",
+    "@djangocfg/i18n": "^2.1.376",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.374",
-    "@djangocfg/ui-core": "^2.1.374",
+    "@djangocfg/typescript-config": "^2.1.376",
+    "@djangocfg/ui-core": "^2.1.376",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",

package/src/tools/Chat/Chat.story.tsx

@@ -28,6 +28,7 @@ import { StreamingIndicator } from './components/StreamingIndicator';
 import { ChatProvider, useChatContext } from './context';
 import { useChatComposer } from './hooks/useChatComposer';
 import { useChatLightbox } from './hooks/useChatLightbox';
+import { useAutoFocusOnStreamEnd } from './hooks/useAutoFocusOnStreamEnd';
 import { createMockTransport } from './core/transport/mock';
 import { dispatchToolPayload, isLatLng, isPlainObject } from './core/payload-dispatch';
 import { collectImageAttachments } from './utils/collectImageAttachments';
@@ -1281,3 +1282,75 @@ export const WailsLikeVirtualization = () => {
     </Frame>
   );
 };
+
+// ---------------------------------------------------------------------------
+// AutoFocusOnStreamEnd — refocus composer the moment a reply lands
+// ---------------------------------------------------------------------------
+//
+// Standard chat UX: user types → sends → reads → starts typing again.
+// `useAutoFocusOnStreamEnd` watches `isStreaming` and fires `.focus()`
+// on the true → false edge. Pass any object with `.focus()` —
+// `useChatComposer`'s textareaRef, a forwarded handle, or a raw
+// HTMLTextAreaElement.
+
+export const AutoFocusOnStreamEnd = () => {
+  const [enabled] = useBoolean('autofocus', { defaultValue: true, label: 'Auto-focus composer when reply lands' });
+
+  const transport = useMemo(
+    () =>
+      createMockTransport({
+        replies: [
+          'Reply landed — composer should be focused now. Start typing without reaching for the mouse.',
+          'Toggle the knob off to see the difference: focus stays wherever it was.',
+          'The hook only fires on the streaming → idle transition, so reading mid-stream is undisturbed.',
+        ],
+        latencyMs: 25,
+      }),
+    [],
+  );
+
+  return (
+    <Frame>
+      <ChatProvider
+        transport={transport}
+        config={{
+          greeting: 'Auto-focus demo',
+          description:
+            'Send a message, wait for the reply to finish streaming, then start typing — the composer is already focused.',
+          placeholder: 'Send anything…',
+        }}
+      >
+        <AutoFocusWiring enabled={enabled} />
+        <AutoFocusShell />
+      </ChatProvider>
+    </Frame>
+  );
+};
+
+/** Story-internal wiring component — sits inside ChatProvider. The
+ *  built-in `<Composer>` registers itself with the context on mount,
+ *  so the hook needs no args at all: it reads `isStreaming` and the
+ *  composer handle from context automatically. */
+function AutoFocusWiring({ enabled }: { enabled: boolean }) {
+  useAutoFocusOnStreamEnd({ enabled });
+  return null;
+}
+
+/** Minimal shell to render the message list + composer. ChatRoot
+ *  doesn't take children so we drop a slim layout here. */
+function AutoFocusShell() {
+  const ctx = useChatContext();
+  const composer = useChatComposer({ onSubmit: (text) => ctx.sendMessage(text) });
+  return (
+    <div className="flex h-full flex-col">
+      <MessageList
+        messages={ctx.messages}
+        renderItem={(m) => (
+          <MessageBubble key={m.id} message={m} />
+        )}
+        className="flex-1"
+      />
+      <Composer composer={composer} placeholder={ctx.config.placeholder} />
+    </div>
+  );
+}

package/src/tools/Chat/README.md

@@ -290,6 +290,58 @@ ctx.audio.isUnlocked;              // boolean
 
 Or directly: `useChatAudio(config)` — returns the same surface, no provider required.
 
+## Composer focus & auto-focus on stream end
+
+The chat context exposes a small composer registry so other parts of
+the tree can drive the composer imperatively without prop-drilling a
+ref. The built-in `<Composer>` registers itself on mount; custom
+composers opt in with a one-line hook.
+
+```tsx
+import { useChatContext, useRegisterComposer } from '@djangocfg/ui-tools';
+
+// Inside any custom composer:
+function MyComposer() {
+  const focus = useCallback(() => myEditorRef.current?.commands.focus(), []);
+  useRegisterComposer(focus);
+  // ...
+}
+
+// Then anywhere inside <ChatProvider>:
+const ctx = useChatContext();
+ctx.composer?.focus();   // null until any composer has mounted
+```
+
+### `useAutoFocusOnStreamEnd` — refocus when the reply lands
+
+Standard chat UX: user types → sends → reads the reply → starts
+typing again without reaching for the mouse. The hook listens for the
+streaming → idle transition and calls `.focus()` exactly once. Reading
+mid-stream is undisturbed.
+
+Zero-config (default: focuses the registered composer):
+
+```tsx
+import { useAutoFocusOnStreamEnd } from '@djangocfg/ui-tools';
+
+function MyChatShell() {
+  useAutoFocusOnStreamEnd();      // reads isStreaming + composer from context
+  return <ChatProvider>{/* … */}</ChatProvider>;
+}
+```
+
+Options:
+
+| option        | default                | when to set                                                                 |
+|---------------|------------------------|-----------------------------------------------------------------------------|
+| `isStreaming` | `ctx.isStreaming`      | Driving stream state from your own store (e.g. an external event bus).      |
+| `targetRef`   | registered composer    | Focus something other than the composer — an "approve" button, etc.         |
+| `enabled`     | `true`                 | User preference toggle (off without unmounting the hook).                   |
+| `delayMs`     | `0` (next rAF)         | 50–150ms helps when the composer re-mounts after the final chunk.           |
+
+The hook only fires on the `true → false` edge — flipping `enabled`
+mid-stream won't steal focus.
+
 ## Attachment renderers (registry)
 
 `<Attachments>` and `<ChatRoot>` accept a per-type renderer map. Default tile is used when no renderer matches. Plug in heavy viewers (`LazyAudioPlayer`, `LazyImageViewer`, `LazyMap`) host-side without forcing `ui-tools/Chat` to depend on them.
@@ -464,7 +516,9 @@ createHttpTransport, createMockTransport, parseSSE, TransportError
 
 // Hooks
 useChat, useChatComposer, useChatScroll, useChatHistory, useChatLayout,
-useChatAudio, useChatLightbox
+useChatAudio, useChatLightbox,
+useAutoFocusOnStreamEnd, useRegisterComposer,
+type UseAutoFocusOnStreamEndOptions, type Focusable
 
 // Audio
 ChatAudioConfig, ChatAudioEvent, ChatAudioSounds, UseChatAudioReturn,
@@ -479,7 +533,8 @@ type ToolPayloadMatcher, type ToolPayloadFallback
 collectImageAttachments
 
 // Context
-ChatProvider, useChatContext, useChatContextOptional
+ChatProvider, useChatContext, useChatContextOptional,
+type ComposerHandle
 
 // Components
 ChatRoot, MessageList, MessageBubble, MessageActions, Composer,

package/src/tools/Chat/components/Composer.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { type ReactNode, forwardRef } from 'react';
+import { type ReactNode, forwardRef, useEffect } from 'react';
 import { Paperclip, Send, Square } from 'lucide-react';
 
 import { Button, Textarea } from '@djangocfg/ui-core/components';
@@ -98,6 +98,18 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
   const isDisabled = disabled ?? isStreaming;
   const sz = SIZE_CLASSES[size];
 
+  // Register the composer's focus() with the chat context so other
+  // parts of the tree (e.g. useAutoFocusOnStreamEnd) can drive it
+  // imperatively without prop-drilling a ref. No-op when used outside
+  // a ChatProvider.
+  const register = ctx?.registerComposer;
+  const composerFocus = composer.focus;
+  useEffect(() => {
+    if (!register) return;
+    register({ focus: composerFocus });
+    return () => register(null);
+  }, [register, composerFocus]);
+
   return (
     <div
       ref={ref}

package/src/tools/Chat/context/ChatProvider.tsx

@@ -8,15 +8,24 @@ import {
   useEffect,
   useMemo,
   useRef,
+  useState,
 } from 'react';
 
 import type { ChatConfig, ChatLabels, ChatTransport } from '../types';
 import { DEFAULT_LABELS } from '../types';
+
 import { useChat, type UseChatReturn } from '../hooks/useChat';
 import { useChatLayout, type UseChatLayoutReturn } from '../hooks/useChatLayout';
 import { useChatAudio } from '../hooks/useChatAudio';
 import type { ChatAudioConfig, UseChatAudioReturn } from '../core/audio/types';
 
+/** Minimal handle a composer (built-in or custom) registers so other
+ *  parts of the chat tree can drive it imperatively — `.focus()` is
+ *  enough today; expand the surface as new needs arise. */
+export interface ComposerHandle {
+  focus: () => void;
+}
+
 export interface ChatContextValue extends UseChatReturn {
   layout: UseChatLayoutReturn;
   config: ChatConfig;
@@ -26,6 +35,13 @@ export interface ChatContextValue extends UseChatReturn {
    * Components like ``AudioToggle`` use this to auto-hide when there
    * is nothing to mute. */
   hasAudio: boolean;
+  /** Composer registry. The built-in `<Composer>` calls
+   *  `registerComposer({ focus })` on mount; custom composers (e.g.
+   *  cmdop's MarkdownEditor wrapper) do the same via the
+   *  `useRegisterComposer` helper. Read it via `composer?.focus()` —
+   *  null until any composer has mounted. Plan64 follow-up. */
+  composer: ComposerHandle | null;
+  registerComposer: (handle: ComposerHandle | null) => void;
 }
 
 const Ctx = createContext<ChatContextValue | null>(null);
@@ -121,9 +137,18 @@ export function ChatProvider({
     );
   }, [audio]);
 
+  // Composer registry — kept in state (not a ref) so consumers
+  // observing `ctx.composer` re-render when a composer mounts /
+  // unmounts. The setter is the API surface; pass it to the composer
+  // on mount and call with `null` on unmount.
+  const [composer, setComposer] = useState<ComposerHandle | null>(null);
+  const registerComposer = useCallback((handle: ComposerHandle | null) => {
+    setComposer(handle);
+  }, []);
+
   const value = useMemo<ChatContextValue>(
-    () => ({ ...chat, layout, config, labels, audio: audioApi, hasAudio }),
-    [chat, layout, config, labels, audioApi, hasAudio],
+    () => ({ ...chat, layout, config, labels, audio: audioApi, hasAudio, composer, registerComposer }),
+    [chat, layout, config, labels, audioApi, hasAudio, composer, registerComposer],
   );
 
   return (

package/src/tools/Chat/context/index.ts

@@ -6,4 +6,5 @@ export {
   useChatContextOptional,
   type ChatContextValue,
   type ChatProviderProps,
+  type ComposerHandle,
 } from './ChatProvider';

package/src/tools/Chat/hooks/index.ts

@@ -24,3 +24,9 @@ export {
   type ChatLightboxState,
   type ChatLightboxScope,
 } from './useChatLightbox';
+export {
+  useAutoFocusOnStreamEnd,
+  useRegisterComposer,
+  type UseAutoFocusOnStreamEndOptions,
+  type Focusable,
+} from './useAutoFocusOnStreamEnd';

package/src/tools/Chat/hooks/useAutoFocusOnStreamEnd.ts

@@ -0,0 +1,128 @@
+'use client';
+
+import { type RefObject, useEffect, useRef } from 'react';
+
+import { useChatContextOptional, type ComposerHandle } from '../context';
+
+/** Anything with a `.focus()` method — covers HTMLElement, the
+ *  composer's textareaRef from `useChatComposer`, and any custom
+ *  imperative handle exposing the same shape. */
+export interface Focusable {
+  focus: () => void;
+}
+
+export interface UseAutoFocusOnStreamEndOptions {
+  /** True while an assistant reply is streaming. The hook fires the
+   *  focus() call on the true → false transition.
+   *
+   *  When omitted, the hook reads `isStreaming` from `useChatContext`.
+   *  Pass it explicitly only if you're driving stream state from your
+   *  own store (cmdop's Wails event bus, for example). */
+  isStreaming?: boolean;
+  /** Ref / handle to focus when the reply lands.
+   *
+   *  When omitted, the hook uses the composer handle registered in
+   *  the chat context — the built-in `<Composer>` registers itself
+   *  automatically, custom composers can opt in via
+   *  `useRegisterComposer`. Pass `targetRef` only when you need to
+   *  focus something other than the composer (e.g. an "approve"
+   *  button, a quick-reply chip). */
+  targetRef?: RefObject<Focusable | HTMLElement | null>;
+  /** Opt-out. Default true. Pass false to disable without unmounting
+   *  the hook (e.g. user preference). */
+  enabled?: boolean;
+  /** Delay the focus call by this many ms. Default 0 = next animation
+   *  frame, which lets the streaming bubble's final commit settle
+   *  before focus pulls scroll. Bump to 50-150ms for layouts that
+   *  re-mount the composer after the final chunk. */
+  delayMs?: number;
+}
+
+/**
+ * Refocus the chat composer the moment the assistant reply finishes
+ * streaming. Standard chat UX: the user types → sends → reads the
+ * reply → starts typing again without reaching for the mouse.
+ *
+ * Default (zero-config) usage — works the moment a `<Composer>` is
+ * mounted inside a `<ChatProvider>`:
+ *
+ *   useAutoFocusOnStreamEnd();
+ *
+ * Custom composer / advanced wiring:
+ *
+ *   const ref = useRef<{ focus: () => void } | null>(null);
+ *   useAutoFocusOnStreamEnd({ targetRef: ref });
+ *
+ * Driving stream state yourself:
+ *
+ *   useAutoFocusOnStreamEnd({ isStreaming: myExternalStreaming });
+ *
+ * Only the true → false transition fires focus — toggling `enabled`
+ * mid-stream won't steal focus while the user is reading.
+ */
+export function useAutoFocusOnStreamEnd(
+  options: UseAutoFocusOnStreamEndOptions = {},
+): void {
+  const { isStreaming: isStreamingProp, targetRef, enabled = true, delayMs = 0 } = options;
+  const ctx = useChatContextOptional();
+  // Prefer the prop (caller knows best), fall back to context.
+  const isStreaming = isStreamingProp ?? ctx?.isStreaming ?? false;
+
+  // Keep latest ctx-composer in a ref so the focus effect always
+  // sees the freshest registered handle without re-firing when
+  // composers re-mount.
+  const composerHandleRef = useRef<ComposerHandle | null>(null);
+  composerHandleRef.current = ctx?.composer ?? null;
+
+  const prevStreamingRef = useRef(isStreaming);
+
+  useEffect(() => {
+    const wasStreaming = prevStreamingRef.current;
+    prevStreamingRef.current = isStreaming;
+
+    if (!enabled) return;
+    if (!(wasStreaming && !isStreaming)) return;
+
+    const focusNow = () => {
+      // Resolve target in priority order: explicit ref > registered
+      // composer handle. Refs may carry an HTMLElement (raw DOM) or
+      // any object with `.focus()`; both are handled by the same
+      // call site below.
+      const explicit = targetRef?.current as Focusable | null;
+      const target: Focusable | null = explicit ?? composerHandleRef.current;
+      target?.focus();
+    };
+
+    if (delayMs > 0) {
+      const id = window.setTimeout(focusNow, delayMs);
+      return () => window.clearTimeout(id);
+    }
+    const raf = requestAnimationFrame(focusNow);
+    return () => cancelAnimationFrame(raf);
+  }, [isStreaming, enabled, delayMs, targetRef]);
+}
+
+/**
+ * Helper for custom composers (anything that's NOT the built-in
+ * `<Composer>`) to register their focus() with the chat context so
+ * `useAutoFocusOnStreamEnd()` and other consumers work without
+ * prop-drilling.
+ *
+ * Usage inside your custom composer:
+ *
+ *   const focus = useCallback(() => {
+ *     myEditorRef.current?.commands.focus();
+ *   }, []);
+ *   useRegisterComposer(focus);
+ *
+ * No-op when called outside a `<ChatProvider>`.
+ */
+export function useRegisterComposer(focus: () => void): void {
+  const ctx = useChatContextOptional();
+  const register = ctx?.registerComposer;
+  useEffect(() => {
+    if (!register) return;
+    register({ focus });
+    return () => register(null);
+  }, [register, focus]);
+}

package/src/tools/Chat/index.ts

@@ -74,6 +74,8 @@ export {
   useChatHistory,
   useChatLayout,
   useChatAudio,
+  useAutoFocusOnStreamEnd,
+  useRegisterComposer,
   type UseChatConfig,
   type UseChatReturn,
   type UseChatComposerOptions,
@@ -83,6 +85,8 @@ export {
   type UseChatHistoryOptions,
   type UseChatLayoutConfig,
   type UseChatLayoutReturn,
+  type UseAutoFocusOnStreamEndOptions,
+  type Focusable,
 } from './hooks';
 
 // Audio

package/dist/ChatRoot-3LA3DSNY.cjs

@@ -1,14 +0,0 @@
-'use strict';
-
-var chunkTAEHNX4W_cjs = require('./chunk-TAEHNX4W.cjs');
-require('./chunk-XACCHZH2.cjs');
-require('./chunk-OLISEQHS.cjs');
-
-
-
-Object.defineProperty(exports, "ChatRoot", {
-  enumerable: true,
-  get: function () { return chunkTAEHNX4W_cjs.ChatRoot; }
-});
-//# sourceMappingURL=ChatRoot-3LA3DSNY.cjs.map
-//# sourceMappingURL=ChatRoot-3LA3DSNY.cjs.map

package/dist/ChatRoot-RIETBE55.mjs

@@ -1,5 +0,0 @@
-export { ChatRoot } from './chunk-PSM3DUTC.mjs';
-import './chunk-NWUT327A.mjs';
-import './chunk-N2XQF2OL.mjs';
-//# sourceMappingURL=ChatRoot-RIETBE55.mjs.map
-//# sourceMappingURL=ChatRoot-RIETBE55.mjs.map