@djangocfg/ui-tools 2.1.381 → 2.1.382

package/src/tools/Chat/stories/03-tool-calls.story.tsx

@@ -0,0 +1,59 @@
+import { useMemo } from 'react';
+
+import { defineStory } from '@djangocfg/playground';
+
+import { LazyJsonTree } from '../../JsonTree/lazy';
+import { ChatRoot } from '../components/ChatRoot';
+import { ToolCalls } from '../components/ToolCalls';
+import { createMockTransport } from '../core/transport/mock';
+import {
+  Frame,
+  SEED_JSON_PAYLOAD,
+  SEED_TOOL_CALLS,
+  makeToolCallsTransport,
+} from './shared';
+
+export default defineStory({
+  title: 'Tools/Chat/ToolCalls',
+  component: ToolCalls,
+  description:
+    'Streaming tool-call panels (auto-open while running, auto-close on success) and the `renderInput`/`renderOutput` payload dispatcher.',
+});
+
+export const Default = () => {
+  const transport = useMemo(() => makeToolCallsTransport(SEED_TOOL_CALLS), []);
+  return (
+    <Frame h={620}>
+      <ChatRoot
+        transport={transport}
+        config={{ greeting: 'Tool-call panel — try sending a message to trigger another search.' }}
+      />
+    </Frame>
+  );
+};
+
+export const WithJsonTreePayload = () => {
+  const transport = useMemo(
+    () =>
+      createMockTransport({
+        initialMessages: SEED_JSON_PAYLOAD,
+        replies: ['Open the tool panel above to inspect the payload.'],
+        latencyMs: 40,
+      }),
+    [],
+  );
+
+  return (
+    <Frame h={620}>
+      <ChatRoot
+        transport={transport}
+        config={{ greeting: 'JsonTree payload demo' }}
+        toolCallsProps={{
+          defaultExpanded: true,
+          renderInput: (input) => <LazyJsonTree data={input} mode="compact" />,
+          renderOutput: (output) => <LazyJsonTree data={output} mode="compact" />,
+        }}
+      />
+    </Frame>
+  );
+};

package/src/tools/Chat/stories/04-personas.story.tsx

@@ -0,0 +1,78 @@
+import { useMemo } from 'react';
+
+import { defineStory } from '@djangocfg/playground';
+
+import { MessageBubble } from '../components/MessageBubble';
+import { ChatRoot } from '../components/ChatRoot';
+import type { ChatMessage } from '../types';
+import {
+  ASSISTANT_AURA,
+  Frame,
+  SEED_BASIC,
+  USER_ANNA,
+  makeBasicTransport,
+} from './shared';
+
+export default defineStory({
+  title: 'Tools/Chat/Personas',
+  component: ChatRoot,
+  description:
+    'Default user/assistant identities via `config.user` / `config.assistant`, and per-message overrides via `message.sender` (multi-user / multi-bot).',
+});
+
+export const Default = () => {
+  const transport = useMemo(() => makeBasicTransport(SEED_BASIC), []);
+  return (
+    <Frame>
+      <ChatRoot
+        transport={transport}
+        config={{
+          greeting: `Hi ${USER_ANNA.name} 👋`,
+          user: USER_ANNA,
+          assistant: ASSISTANT_AURA,
+        }}
+      />
+    </Frame>
+  );
+};
+
+const MULTI_USER: ChatMessage[] = [
+  {
+    id: 'm1',
+    role: 'user',
+    content: '@aura can you summarise the spec?',
+    createdAt: Date.now() - 90_000,
+    sender: USER_ANNA,
+  },
+  {
+    id: 'm2',
+    role: 'assistant',
+    content: 'Pulling the latest version from the docs index now.',
+    createdAt: Date.now() - 80_000,
+    sender: ASSISTANT_AURA,
+  },
+  {
+    id: 'm3',
+    role: 'user',
+    content: 'Make sure to flag the auth migration section.',
+    createdAt: Date.now() - 60_000,
+    sender: { name: 'Mark', initials: 'MK' },
+  },
+  {
+    id: 'm4',
+    role: 'assistant',
+    content: '👍 Flagged section 4.2 — needs DBA review.',
+    createdAt: Date.now() - 30_000,
+    sender: ASSISTANT_AURA,
+  },
+];
+
+export const MultiUser = () => (
+  <Frame h={520}>
+    <div className="h-full overflow-y-auto py-2">
+      {MULTI_USER.map((m) => (
+        <MessageBubble key={m.id} message={m} showActions={false} showTimestamp />
+      ))}
+    </div>
+  </Frame>
+);

package/src/tools/Chat/stories/05-launcher.story.tsx

@@ -0,0 +1,321 @@
+import { useEffect, useMemo, useState } from 'react';
+import { Bot, MessageCircle, Sparkles, Zap } from 'lucide-react';
+
+import { defineStory, useBoolean, useNumber, useSelect } from '@djangocfg/playground';
+import { Avatar, AvatarFallback, AvatarImage } from '@djangocfg/ui-core/components';
+
+import { ChatRoot } from '../components/ChatRoot';
+import { Composer } from '../components/Composer';
+import { EmptyState } from '../components/EmptyState';
+import { MessageList } from '../components/MessageList';
+import { ChatProvider, useChatContext } from '../context';
+import { useChatComposer } from '../hooks/useChatComposer';
+import { useChatUnread } from '../hooks/useChatUnread';
+import {
+  ChatFAB,
+  type ChatFABPosition,
+  type ChatFABSize,
+  type ChatFABVariant,
+} from '../launcher/ChatFAB';
+import { ChatHeaderLanguageButton } from '../launcher/ChatHeaderLanguageButton';
+import { ChatLauncher } from '../launcher/ChatLauncher';
+import { VoiceComposerSlot } from '../../SpeechRecognition/widgets/VoiceComposerSlot';
+import type { ChatMessage } from '../types';
+import { SEED_BASIC, makeBasicTransport } from './shared';
+
+export default defineStory({
+  title: 'Tools/Chat/Launcher',
+  component: ChatLauncher,
+  description:
+    'Floating chat launcher (FAB + Dock + Greeting + hotkey). Production-realistic stories pin the FAB to the viewport corner like any chat widget; isolated previews use `inline` mode for the FAB primitive.',
+});
+
+function DemoChat() {
+  const transport = useMemo(() => makeBasicTransport(SEED_BASIC), []);
+  // Drop the voice slot into the composer toolbar. No props needed —
+  // it pulls value/setValue from the registered ComposerHandle and
+  // auto-hides on browsers that can't dictate.
+  return (
+    <ChatRoot
+      transport={transport}
+      config={{ greeting: 'How can I help?' }}
+      composerToolbarEnd={<VoiceComposerSlot />}
+    />
+  );
+}
+
+export const Default = () => (
+  <ChatLauncher
+    hotkey={{ key: '/', meta: true }}
+    fab={{ ariaLabel: 'Open chat', tooltip: 'Open chat (⌘/)' }}
+    dock={{
+      title: 'Assistant',
+      height: 600,
+      // Kebab settings menu in the dock header — language picker
+      // persists into `useSpeechPrefs` so dictation honours the
+      // choice across reloads. Composable: pass children to override.
+      headerActions: <ChatHeaderLanguageButton />,
+    }}
+  >
+    <DemoChat />
+  </ChatLauncher>
+);
+
+export const Playground = () => {
+  const [variant] = useSelect('variant', {
+    options: ['simple', 'animated', 'glass'] as const,
+    defaultValue: 'simple',
+    label: 'FAB variant',
+  });
+  const [size] = useSelect('size', {
+    options: ['sm', 'md', 'lg'] as const,
+    defaultValue: 'md',
+    label: 'FAB size',
+  });
+  const [position] = useSelect('position', {
+    options: ['bottom-right', 'bottom-left', 'top-right', 'top-left'] as const,
+    defaultValue: 'bottom-right',
+    label: 'Position',
+  });
+  const [pulse] = useBoolean('pulse', { defaultValue: false });
+  const [withBadge] = useBoolean('badge', { defaultValue: false });
+  const [badgeCount] = useNumber('badge count', { defaultValue: 3, min: 1, max: 99 });
+  const [withTooltip] = useBoolean('tooltip', { defaultValue: true });
+  const [withGreeting] = useBoolean('greeting', { defaultValue: false });
+
+  return (
+    <ChatLauncher
+      fab={{
+        variant: variant as ChatFABVariant,
+        size: size as ChatFABSize,
+        position: position as ChatFABPosition,
+        pulse,
+        badge: withBadge ? badgeCount : undefined,
+        tooltip: withTooltip ? 'Open chat (⌘/)' : undefined,
+        icon: <MessageCircle className="h-6 w-6" />,
+        ariaLabel: 'Open chat',
+      }}
+      dock={{
+        title: 'Support',
+        icon: <MessageCircle className="text-primary h-4 w-4" />,
+        position: position as ChatFABPosition,
+        height: 600,
+        headerActions: <ChatHeaderLanguageButton />,
+      }}
+      greeting={
+        withGreeting
+          ? {
+              content: 'Hey 👋 Got a question? Happy to help.',
+              senderName: 'Anna · Support',
+              avatar: (
+                <Avatar className="h-8 w-8">
+                  <AvatarImage src="https://i.pravatar.cc/64?img=47" />
+                  <AvatarFallback>A</AvatarFallback>
+                </Avatar>
+              ),
+              delayMs: 600,
+              dismissStorageKey: null,
+            }
+          : undefined
+      }
+      hotkey={{ key: '/', meta: true }}
+    >
+      <DemoChat />
+    </ChatLauncher>
+  );
+};
+
+export const MobileFullscreen = () => (
+  <ChatLauncher
+    fab={{ icon: <MessageCircle className="h-6 w-6" />, tooltip: 'Open chat' }}
+    dock={{ title: 'Mobile-friendly', width: 480, height: 600 }}
+  >
+    <DemoChat />
+  </ChatLauncher>
+);
+
+/**
+ * LiveChat / Intercom-style proactive invite: animated FAB + greeting
+ * bubble with avatar, sender name, and a friendly nudge. The greeting
+ * fades in after a short delay; click the bubble or the FAB to open
+ * the chat. Composer auto-focuses on open.
+ */
+export const LiveChatStyle = () => (
+  <ChatLauncher
+    fab={{
+      variant: 'animated',
+      icon: <Bot className="h-6 w-6" />,
+      ariaLabel: 'Chat with us',
+      tooltip: 'Chat with us',
+    }}
+    dock={{
+      title: 'Anna · Sales',
+      icon: (
+        <Avatar className="h-5 w-5">
+          <AvatarImage src="https://i.pravatar.cc/64?img=47" />
+          <AvatarFallback>A</AvatarFallback>
+        </Avatar>
+      ),
+      height: 620,
+    }}
+    greeting={{
+      content: (
+        <>
+          Hi 👋 Looking for something? I&apos;m around — we usually reply{' '}
+          <strong>within a minute</strong>.
+        </>
+      ),
+      senderName: 'Anna · Sales',
+      avatar: (
+        <Avatar className="h-9 w-9">
+          <AvatarImage src="https://i.pravatar.cc/64?img=47" />
+          <AvatarFallback>A</AvatarFallback>
+        </Avatar>
+      ),
+      delayMs: 1200,
+      dismissStorageKey: null,
+    }}
+    hotkey={{ key: '/', meta: true }}
+  >
+    <DemoChat />
+  </ChatLauncher>
+);
+
+// ── Live push demo ─────────────────────────────────────────────────────────
+//
+// Hosts wire push notifications via:
+//   1. `useChatUnread({ open })` inside the `<ChatProvider>` for state.
+//   2. `chat.injectMessage(...)` to feed inbound messages from Centrifugo / WS.
+//   3. `<ChatLauncher unreadMessage onMarkRead>` to surface the preview bubble.
+
+function PushInjector({ enabled, intervalMs }: { enabled: boolean; intervalMs: number }) {
+  const chat = useChatContext();
+  useEffect(() => {
+    if (!enabled) return;
+    let i = 0;
+    const samples = [
+      'Hey 👋 just checking in — anything I can help with?',
+      'Heads up: your order #1042 just shipped 🚀',
+      'New: try the redesigned dashboard — feedback welcome.',
+    ];
+    const id = setInterval(() => {
+      chat.injectMessage({
+        id: `push-${Date.now()}-${i}`,
+        role: 'assistant',
+        content: samples[i % samples.length]!,
+        createdAt: Date.now(),
+        sender: { name: 'Anna · Sales', avatarUrl: 'https://i.pravatar.cc/64?img=47' },
+      });
+      i++;
+    }, intervalMs);
+    return () => clearInterval(id);
+  }, [chat, enabled, intervalMs]);
+  return null;
+}
+
+function InlineChatUI() {
+  // Lightweight chat shell rendered inside an existing ChatProvider — used
+  // so we don't double-mount provider state in the push demo.
+  const chat = useChatContext();
+  const composer = useChatComposer({
+    onSubmit: (content, attachments) => chat.sendMessage(content, attachments),
+    disabled: chat.isStreaming,
+  });
+  return (
+    <div className="flex h-full flex-col">
+      <MessageList
+        className="flex-1"
+        renderEmpty={() => <EmptyState greeting="Anna · Sales" />}
+      />
+      <Composer composer={composer} />
+    </div>
+  );
+}
+
+function LivePushShell({ intervalMs, autoPush }: { intervalMs: number; autoPush: boolean }) {
+  const [open, setOpen] = useState(false);
+  const { unread, markRead } = useChatUnread({ open });
+  return (
+    <>
+      <PushInjector enabled={autoPush} intervalMs={intervalMs} />
+      <ChatLauncher
+        open={open}
+        onOpenChange={setOpen}
+        fab={{ ariaLabel: 'Open chat', tooltip: 'Open chat' }}
+        dock={{ title: 'Sales · Anna', height: 580 }}
+        unreadMessage={unread}
+        onMarkRead={markRead}
+      >
+        <InlineChatUI />
+      </ChatLauncher>
+    </>
+  );
+}
+
+/**
+ * Simulates server-pushed messages every N seconds. While the dock is
+ * closed, the FAB badge shows the unread indicator and a notification
+ * bubble appears next to the FAB with sender + message preview. Open the
+ * chat (FAB / preview / ⌘/) and unread resets to zero.
+ */
+export const WithLivePush = () => {
+  const [autoPush] = useBoolean('auto-push', { defaultValue: true });
+  const [intervalSec] = useNumber('interval (s)', {
+    defaultValue: 6,
+    min: 2,
+    max: 30,
+  });
+
+  const transport = useMemo(() => makeBasicTransport(SEED_BASIC), []);
+
+  return (
+    <ChatProvider transport={transport} config={{ greeting: 'Sales chat — push demo' }}>
+      <LivePushShell intervalMs={intervalSec * 1000} autoPush={autoPush} />
+    </ChatProvider>
+  );
+};
+
+export const VariantsAndSizes = () => (
+  <div className="p-6 space-y-6">
+    <div>
+      <p className="text-sm font-medium">Variants (inline)</p>
+      <p className="text-muted-foreground text-xs mb-3">
+        Inline preview only — production usage drops <code className="text-xs">inline</code> and pins to the viewport corner.
+      </p>
+      <div className="grid grid-cols-1 sm:grid-cols-3 gap-4">
+        {(['simple', 'animated', 'glass'] as const).map((variant) => (
+          <div key={variant} className="flex flex-col items-center gap-3 rounded-lg border bg-card p-6">
+            <div className="text-xs font-medium text-muted-foreground">{variant}</div>
+            <ChatFAB
+              inline
+              variant={variant}
+              size="lg"
+              onClick={() => {}}
+              ariaLabel={`${variant} FAB`}
+              tooltip={variant === 'simple' ? 'Open chat' : undefined}
+              badge={variant === 'glass' ? 5 : undefined}
+              pulse={variant === 'simple'}
+              icon={
+                variant === 'animated' ? <Zap size={26} /> :
+                variant === 'glass'    ? <Sparkles className="h-6 w-6" /> :
+                <Bot size={26} />
+              }
+            />
+          </div>
+        ))}
+      </div>
+    </div>
+
+    <div>
+      <p className="text-sm font-medium">Sizes (inline)</p>
+      <div className="mt-3 grid grid-cols-3 gap-4">
+        {(['sm', 'md', 'lg'] as const).map((s) => (
+          <div key={s} className="flex flex-col items-center gap-2 rounded-lg border bg-card p-4">
+            <div className="text-xs text-muted-foreground">size={s}</div>
+            <ChatFAB inline size={s} onClick={() => {}} ariaLabel={`${s} FAB`} />
+          </div>
+        ))}
+      </div>
+    </div>
+  </div>
+);

package/src/tools/Chat/stories/06-header.story.tsx

@@ -0,0 +1,147 @@
+import { useMemo, useState } from 'react';
+import { RotateCcw, Settings } from 'lucide-react';
+
+import { defineStory } from '@djangocfg/playground';
+import { Button } from '@djangocfg/ui-core/components';
+
+import { ChatRoot } from '../components/ChatRoot';
+import { ChatDock } from '../launcher/ChatDock';
+import { ChatHeader } from '../launcher/ChatHeader';
+import { ChatHeaderActionButton } from '../launcher/ChatHeaderActionButton';
+import { ChatHeaderModeToggle } from '../launcher/ChatHeaderModeToggle';
+import { useChatDockPrefs } from '../hooks/useChatDockPrefs';
+import { useChatReset } from '../hooks/useChatReset';
+import { SEED_BASIC, makeBasicTransport } from './shared';
+
+export default defineStory({
+  title: 'Tools/Chat/Header',
+  component: ChatHeader,
+  description:
+    '`<ChatHeader>` + `headerActions` slot + helpers: `ChatHeaderActionButton`, `ChatHeaderModeToggle`. State persisted via `useChatDockPrefs` (ui-core localStorage).',
+});
+
+function ResetButton() {
+  const { reset, isResetting } = useChatReset({
+    onReset: async () => {
+      await new Promise((r) => setTimeout(r, 800));
+      return true;
+    },
+    onSuccess: () => alert('Context cleared.'),
+  });
+  return (
+    <ChatHeaderActionButton
+      icon={<RotateCcw className="h-3.5 w-3.5" />}
+      ariaLabel="Clear conversation context"
+      onClick={() => reset()}
+      loading={isResetting}
+    />
+  );
+}
+
+/** Standalone `<ChatHeader>` — title + actions + close. No surrounding chrome. */
+export const HeaderOnly = () => (
+  <div className="p-6">
+    <div className="overflow-hidden rounded-lg border border-border bg-popover">
+      <ChatHeader
+        title="Assistant"
+        onClose={() => alert('close')}
+        actions={
+          <>
+            <ResetButton />
+            <ChatHeaderActionButton
+              icon={<Settings className="h-3.5 w-3.5" />}
+              ariaLabel="Settings"
+              onClick={() => alert('settings')}
+              badge={2}
+            />
+          </>
+        }
+      />
+    </div>
+  </div>
+);
+
+/**
+ * Production-like dock with persistent prefs + mode toggle.
+ * Reload the story — `mode` and `side` survive via localStorage.
+ */
+export const WithPersistentPrefs = () => {
+  const [open, setOpen] = useState(true);
+  const prefs = useChatDockPrefs({ storageKey: 'story.chat.dock.prefs' });
+  const transport = useMemo(() => makeBasicTransport(SEED_BASIC), []);
+
+  return (
+    <>
+      <div className="p-6">
+        <h2 className="text-foreground text-lg font-semibold">Page content</h2>
+        <p className="text-muted-foreground mt-2 max-w-md text-sm">
+          The header toggle switches between popover and side-docked layouts.
+          When the side dock is active in production, ChatDock auto-reserves
+          <code className="text-xs"> padding-{prefs.side}</code> on the body so this content
+          shifts away from the dock. Current prefs: <code className="text-xs">mode={prefs.mode}</code> ·{' '}
+          <code className="text-xs">side={prefs.side}</code>.
+        </p>
+        {!open && (
+          <Button className="mt-4" onClick={() => setOpen(true)}>
+            Open chat
+          </Button>
+        )}
+      </div>
+      <ChatDock
+        open={open}
+        onClose={() => setOpen(false)}
+        mode={prefs.mode}
+        side={prefs.side}
+        width={prefs.mode === 'side' ? prefs.sideWidth : 440}
+        height={600}
+        title="CRM Assistant"
+        headerActions={
+          <>
+            <ResetButton />
+            <ChatHeaderModeToggle mode={prefs.mode} onToggle={prefs.toggleMode} />
+          </>
+        }
+      >
+        <ChatRoot transport={transport} config={{ greeting: 'How can I help?' }} />
+      </ChatDock>
+    </>
+  );
+};
+
+/**
+ * `mode='side'` pinned to the viewport edge, reserves body padding so page
+ * content stays visible. This is the production behaviour — no `inline`.
+ */
+export const SideMode = () => {
+  const [open, setOpen] = useState(true);
+  const transport = useMemo(() => makeBasicTransport(SEED_BASIC), []);
+
+  return (
+    <>
+      <div className="p-6">
+        <h2 className="text-foreground text-lg font-semibold">Page content</h2>
+        <p className="text-muted-foreground mt-2 max-w-md text-sm">
+          The dock is pinned full-height to the right edge. The browser body
+          gets <code className="text-xs">padding-right</code> equal to the dock width while
+          it&apos;s open, so this column stays visible.
+        </p>
+        {!open && (
+          <Button className="mt-4" onClick={() => setOpen(true)}>
+            Open side dock
+          </Button>
+        )}
+      </div>
+      <ChatDock
+        open={open}
+        onClose={() => setOpen(false)}
+        mode="side"
+        side="right"
+        width={400}
+        title="Workspace Chat"
+        headerActions={<ResetButton />}
+      >
+        <ChatRoot transport={transport} config={{ greeting: 'Side-docked chat.' }} />
+      </ChatDock>
+    </>
+  );
+};