@djangocfg/ui-tools 2.1.443 → 2.1.444

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.443",
+  "version": "2.1.444",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -334,8 +334,8 @@
     "test:watch": "vitest"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.443",
-    "@djangocfg/ui-core": "^2.1.443",
+    "@djangocfg/i18n": "^2.1.444",
+    "@djangocfg/ui-core": "^2.1.444",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -418,9 +418,9 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.443",
-    "@djangocfg/typescript-config": "^2.1.443",
-    "@djangocfg/ui-core": "^2.1.443",
+    "@djangocfg/i18n": "^2.1.444",
+    "@djangocfg/typescript-config": "^2.1.444",
+    "@djangocfg/ui-core": "^2.1.444",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^25.2.3",

package/src/tools/chat/composer/Composer.tsx

@@ -1,10 +1,10 @@
 'use client';
 
-import { forwardRef, useEffect, useMemo, useRef, useState } from 'react';
+import { forwardRef, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
 import { Textarea } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
-import { attachComposer } from '@djangocfg/ui-tools/composer-registry';
+import { attachComposer, getActiveComposer } from '@djangocfg/ui-tools/composer-registry';
 
 import { useChatContextOptional } from '../context';
 import type { UseChatComposerReturn } from '../hooks/useChatComposer';
@@ -181,6 +181,15 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
   const ctx = useChatContextOptional();
   const isStreaming = isStreamingProp ?? ctx?.isStreaming ?? false;
   const onCancel = onCancelProp ?? ctx?.cancelStream;
+  // Two distinct gates, deliberately split:
+  //   • isInputDisabled — can the user TYPE / focus / edit the buffer? Only the
+  //     explicit `disabled` prop closes this. Streaming does NOT, so the user can
+  //     compose the next message while the agent is still answering.
+  //   • isDisabled — is SUBMIT blocked (Enter no-ops, Send is a Stop)? Closed by
+  //     `disabled` OR streaming, so a streamed turn can't be double-sent. The
+  //     send-while-streaming guard lives in `gatedComposer` (Enter is swallowed).
+  // Attach / drag-drop follow isDisabled (no file ops mid-stream).
+  const isInputDisabled = disabled ?? false;
   const isDisabled = disabled ?? isStreaming;
   const sz = SIZE_CLASSES[size];
   // `appearance` is orthogonal to `size` — `full` layers extra
@@ -245,23 +254,31 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
   // surface (built-in Send, custom SendSlot, TipTap `ComposerRichTextarea`,
   // plain `<Textarea>`) shares the same gate without each having to
   // know about slash state.
+  // Submit is gated when the slash menu blocks it OR while the agent is
+  // streaming. Streaming keeps the textarea EDITABLE (isInputDisabled is false)
+  // so the user can pre-compose the next message, but Enter/Send must not fire a
+  // second turn — the gate swallows the submit and the Enter key, exactly like
+  // the slash gate. (The chosen behavior: "type ahead, Enter doesn't send until
+  // the answer lands"; `useAutoFocusOnStreamEnd` returns focus afterward.)
   const slashAllowsSubmit = slashEnabled ? slash.canSubmit : true;
+  const submitGated = !slashAllowsSubmit || isStreaming;
   const gatedComposer = useMemo<UseChatComposerReturn>(() => {
-    if (slashAllowsSubmit) return composer;
+    if (!submitGated) return composer;
     const baseOnKeyDown = composer.textareaProps.onKeyDown;
     return {
       ...composer,
       canSubmit: false,
       submit: async () => {
-        // Slash gate refuses — swallow programmatic submit attempts.
+        // Gate refuses (slash incomplete or streaming) — swallow programmatic
+        // submit attempts so a streamed turn can't be double-sent.
       },
       textareaProps: {
         ...composer.textareaProps,
         onKeyDown: (e) => {
-          // Block Enter (without Shift) so the textarea's own submit
-          // binding cannot fire while the slash gate is closed. Cmd /
-          // Ctrl + Enter is treated the same. Other keys (history,
-          // arrows, etc.) pass through to the original handler.
+          // Block Enter (without Shift) so the textarea's own submit binding
+          // cannot fire while the gate is closed. Cmd / Ctrl + Enter is treated
+          // the same. Other keys (typing, history, arrows) pass through — the
+          // buffer stays editable so the user can compose ahead while streaming.
           if (e.key === 'Enter' && !e.shiftKey) {
             e.preventDefault();
             return;
@@ -270,7 +287,7 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
         },
       },
     };
-  }, [composer, slashAllowsSubmit]);
+  }, [composer, submitGated]);
   // Capture-phase handler — runs before the textarea / TipTap own
   // submit binding, so Enter / Tab pick a verb instead of sending.
   const handleSlashKeyDownCapture = !slashEnabled
@@ -287,7 +304,9 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
   // depend on which textarea variant is mounted.
   const surfaceRef = useRef<HTMLDivElement>(null);
   const handleSurfaceMouseDown = (e: React.MouseEvent<HTMLDivElement>) => {
-    if (isDisabled) return;
+    // Use isInputDisabled — clicking the surface should focus the editor even
+    // while streaming (the buffer is editable; only submit is gated).
+    if (isInputDisabled) return;
     const target = e.target as HTMLElement;
     // A real interactive element (or the editor itself) handles its own
     // focus — only act on clicks that land on the bare surface padding.
@@ -357,6 +376,20 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
     if (dropped.length > 0) attachHandle.attachFiles(dropped);
   };
 
+  // Send, then return focus to the composer. Clicking the Send button
+  // moves focus to that button; after the message goes the caret should
+  // be back in the input so the user can keep typing without reaching for
+  // the mouse (the same UX the stream-end refocus gives on Enter-send —
+  // this covers the button-click and instant/non-streaming paths too).
+  // Resolve the live handle from the registry so it works for both the
+  // built-in <textarea> and the custom TipTap composer. No-op while the
+  // gate is closed (gatedComposer.submit swallows it).
+  const handleSend = useCallback(() => {
+    void Promise.resolve(gatedComposer.submit()).finally(() => {
+      requestAnimationFrame(() => getActiveComposer()?.focus?.());
+    });
+  }, [gatedComposer]);
+
   // Merge built-in send/stop/attach descriptors with host arrays.
   const { actionsStart, actionsEnd } = useComposerActions({
     composer: gatedComposer,
@@ -366,7 +399,7 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
     onPickFiles: pickFiles,
     actionsStart: composerSlots?.actionsStart,
     actionsEnd: composerSlots?.actionsEnd,
-    onSend: () => void gatedComposer.submit(),
+    onSend: handleSend,
     onCancel,
     micSendSwap,
   });
@@ -390,11 +423,14 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
     slotProps?.textarea?.className,
     textareaClassName,
   );
+  // The textarea uses isInputDisabled (NOT isDisabled): it stays editable while
+  // streaming so the user can compose ahead. Submit is still blocked — the
+  // gatedComposer swallows Enter and the Send button shows Stop (isDisabled).
   const textareaNode = TextareaSlot ? (
     <TextareaSlot
       composer={gatedComposer}
       placeholder={placeholder}
-      disabled={isDisabled}
+      disabled={isInputDisabled}
       size={size}
       className={slotProps?.textarea?.className ?? textareaClassName}
     />
@@ -402,7 +438,7 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
     <SlashHighlightTextarea
       composer={gatedComposer}
       placeholder={placeholder}
-      disabled={isDisabled}
+      disabled={isInputDisabled}
       size={size}
       textareaClassName={sharedTextareaClass}
     />
@@ -414,7 +450,7 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
       aria-label={placeholder}
       aria-multiline="true"
       aria-keyshortcuts="Enter"
-      disabled={isDisabled}
+      disabled={isInputDisabled}
       className={sharedTextareaClass}
     />
   );
@@ -450,7 +486,7 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
       streaming={isStreaming}
       disabled={!gatedComposer.canSubmit}
       size={size}
-      onSend={() => void gatedComposer.submit()}
+      onSend={handleSend}
       onCancel={onCancel}
       {...slotProps?.send}
     />

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

@@ -21,6 +21,7 @@ import { useChat, type UseChatReturn } from '../hooks/useChat';
 import { useChatLayout, type UseChatLayoutReturn } from '../hooks/useChatLayout';
 import { useChatAudio } from '../hooks/useChatAudio';
 import { useStreamEndFocus } from '../hooks/useStreamEndFocus';
+import { useAutoFocusOnMount } from '../hooks/useAutoFocusOnStreamEnd';
 import type { ChatAudioConfig, UseChatAudioReturn } from '../core/audio/types';
 
 /** Imperative handle a composer (built-in or custom) registers so
@@ -93,6 +94,15 @@ export interface ChatProviderProps {
    * long as a composer is registered. Set `false` to opt out.
    */
   autoFocusOnStreamEnd?: boolean;
+  /**
+   * Focus the registered composer when the chat mounts — caret already in
+   * the input the instant the chat appears. With the standard
+   * `key={conversationId}` engine remount, this also focuses on every
+   * chat-switch (the tree remounts → mount focus re-fires) without any
+   * id-tracking effect. Default `true`. Set `false` to opt out (e.g. an
+   * embedded widget that shouldn't steal focus on load).
+   */
+  autoFocusOnMount?: boolean;
   children?: ReactNode;
 }
 
@@ -108,6 +118,7 @@ export function ChatProvider({
   onBeforeSend,
   getDynamicMetadata,
   autoFocusOnStreamEnd = true,
+  autoFocusOnMount = true,
   children,
 }: ChatProviderProps) {
   const audioApi = useChatAudio(audio ?? {});
@@ -199,6 +210,11 @@ export function ChatProvider({
     resolveTarget: () => getActiveComposer(),
   });
 
+  // Focus the composer on mount (and, via the host's `key={id}` engine
+  // remount, on every chat-switch) so the caret is ready the moment the
+  // chat appears. Pairs with the stream-end focus above.
+  useAutoFocusOnMount({ enabled: autoFocusOnMount });
+
   const value = useMemo<ChatContextValue>(
     () => ({
       ...chat,

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

@@ -21,8 +21,10 @@ export {
 } from './useChatLightbox';
 export {
   useAutoFocusOnStreamEnd,
+  useAutoFocusOnMount,
   useRegisterComposer,
   type UseAutoFocusOnStreamEndOptions,
+  type UseAutoFocusOnMountOptions,
   type Focusable,
 } from './useAutoFocusOnStreamEnd';
 export {

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

@@ -79,6 +79,75 @@ export function useAutoFocusOnStreamEnd(
   });
 }
 
+export interface UseAutoFocusOnMountOptions {
+  /** Opt-out. Default true. */
+  enabled?: boolean;
+  /** Ref / handle to focus. Defaults to the registered composer handle. */
+  targetRef?: RefObject<Focusable | HTMLElement | null>;
+}
+
+/**
+ * Focus the chat composer once, when the chat tree mounts.
+ *
+ * The companion to `useStreamEndFocus`: that one fires on the streaming
+ * true→false edge so the user can keep typing after a reply; this one
+ * fires on mount so the caret is already in the composer the instant the
+ * chat appears — and, because a host that keys the chat engine on the
+ * active conversation (`key={machineId}`) remounts the whole tree on every
+ * switch, it doubles as "focus the input when you switch chats" with no
+ * id-tracking effect. Pure Google-style: open a chat, just start typing.
+ *
+ * Runs on the next animation frame so a custom composer's
+ * `useRegisterComposer` effect has run and the handle is live before we
+ * resolve it (mount focus would otherwise race an empty registry). No-op
+ * when nothing is registered yet.
+ *
+ * `<ChatProvider autoFocusOnMount>` runs this for free; call it directly
+ * only to focus something other than the composer.
+ */
+export function useAutoFocusOnMount(
+  options: UseAutoFocusOnMountOptions = {},
+): void {
+  const { enabled = true, targetRef } = options;
+  useEffect(() => {
+    if (!enabled) return;
+    // Retry across a few frames, not a single rAF. On a `key`-remount
+    // (chat-switch) two things race our focus: (1) a custom composer's
+    // `useRegisterComposer` effect must run before `getActiveComposer()`
+    // returns the NEW handle, and (2) the click that triggered the switch
+    // leaves focus on the machine button — a one-frame focus() can fire
+    // before the editor is mounted, or get immediately clobbered. We poll
+    // a handful of frames and stop as soon as the editor actually holds
+    // focus, so the caret reliably lands in the composer without a
+    // guessed fixed delay.
+    let raf = 0;
+    let tries = 0;
+    const MAX_TRIES = 8; // ~8 frames ≈ 130ms @60fps — enough post-remount.
+    const tick = () => {
+      const target =
+        (targetRef?.current as Focusable | null) ?? getActiveComposer();
+      target?.focus?.();
+      tries += 1;
+      // Stop once the composer owns focus, or we run out of tries. The
+      // active-element check keeps us from stealing focus the user just
+      // moved elsewhere (e.g. opened the slash menu) after the first frame.
+      const editor = document.querySelector<HTMLElement>(
+        '.ProseMirror, textarea',
+      );
+      const settled = !!editor && document.activeElement === editor;
+      if (!settled && tries < MAX_TRIES) {
+        raf = requestAnimationFrame(tick);
+      }
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+    // Mount-only by design: the empty dep array means a host that wants
+    // re-focus on chat-switch must remount the tree (the `key={id}`
+    // pattern), which is exactly how the chat engine is already keyed.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+}
+
 /**
  * Helper for custom composers (anything that's NOT the built-in
  * `<Composer>`) to register their focus() with the chat context so

package/src/tools/chat/public.ts

@@ -114,6 +114,7 @@ export {
   useChatLayout,
   useChatAudio,
   useAutoFocusOnStreamEnd,
+  useAutoFocusOnMount,
   useRegisterComposer,
   useChatReset,
   useVisitorFingerprint,
@@ -134,6 +135,7 @@ export {
   type UseChatLayoutConfig,
   type UseChatLayoutReturn,
   type UseAutoFocusOnStreamEndOptions,
+  type UseAutoFocusOnMountOptions,
   type Focusable,
   type UseChatResetOptions,
   type UseChatResetReturn,