@djangocfg/ui-tools 2.1.385 → 2.1.389

package/dist/launcher-5Y42OBSN.mjs

@@ -0,0 +1,6 @@
+export { ChatDock, ChatFAB, ChatGreeting, ChatHeader, ChatHeaderActionButton, ChatHeaderAudioToggle, ChatHeaderLanguageButton, ChatHeaderModeToggle, ChatHeaderResetButton, ChatLauncher, ChatUnreadPreview, useChatPresence } from './chunk-NTVBIIUD.mjs';
+import './chunk-DMX7W4XZ.mjs';
+import './chunk-UNCS5V5F.mjs';
+import './chunk-N2XQF2OL.mjs';
+//# sourceMappingURL=launcher-5Y42OBSN.mjs.map
+//# sourceMappingURL=launcher-5Y42OBSN.mjs.map

package/dist/launcher-5Y42OBSN.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"launcher-5Y42OBSN.mjs"}

package/dist/launcher-PMW2YB24.cjs

@@ -0,0 +1,59 @@
+'use strict';
+
+var chunkW75B7Y6C_cjs = require('./chunk-W75B7Y6C.cjs');
+require('./chunk-TBSHZO5R.cjs');
+require('./chunk-ADEN3UA4.cjs');
+require('./chunk-OLISEQHS.cjs');
+
+
+
+Object.defineProperty(exports, "ChatDock", {
+  enumerable: true,
+  get: function () { return chunkW75B7Y6C_cjs.ChatDock; }
+});
+Object.defineProperty(exports, "ChatFAB", {
+  enumerable: true,
+  get: function () { return chunkW75B7Y6C_cjs.ChatFAB; }
+});
+Object.defineProperty(exports, "ChatGreeting", {
+  enumerable: true,
+  get: function () { return chunkW75B7Y6C_cjs.ChatGreeting; }
+});
+Object.defineProperty(exports, "ChatHeader", {
+  enumerable: true,
+  get: function () { return chunkW75B7Y6C_cjs.ChatHeader; }
+});
+Object.defineProperty(exports, "ChatHeaderActionButton", {
+  enumerable: true,
+  get: function () { return chunkW75B7Y6C_cjs.ChatHeaderActionButton; }
+});
+Object.defineProperty(exports, "ChatHeaderAudioToggle", {
+  enumerable: true,
+  get: function () { return chunkW75B7Y6C_cjs.ChatHeaderAudioToggle; }
+});
+Object.defineProperty(exports, "ChatHeaderLanguageButton", {
+  enumerable: true,
+  get: function () { return chunkW75B7Y6C_cjs.ChatHeaderLanguageButton; }
+});
+Object.defineProperty(exports, "ChatHeaderModeToggle", {
+  enumerable: true,
+  get: function () { return chunkW75B7Y6C_cjs.ChatHeaderModeToggle; }
+});
+Object.defineProperty(exports, "ChatHeaderResetButton", {
+  enumerable: true,
+  get: function () { return chunkW75B7Y6C_cjs.ChatHeaderResetButton; }
+});
+Object.defineProperty(exports, "ChatLauncher", {
+  enumerable: true,
+  get: function () { return chunkW75B7Y6C_cjs.ChatLauncher; }
+});
+Object.defineProperty(exports, "ChatUnreadPreview", {
+  enumerable: true,
+  get: function () { return chunkW75B7Y6C_cjs.ChatUnreadPreview; }
+});
+Object.defineProperty(exports, "useChatPresence", {
+  enumerable: true,
+  get: function () { return chunkW75B7Y6C_cjs.useChatPresence; }
+});
+//# sourceMappingURL=launcher-PMW2YB24.cjs.map
+//# sourceMappingURL=launcher-PMW2YB24.cjs.map

package/dist/launcher-PMW2YB24.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"launcher-PMW2YB24.cjs"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.385",
+  "version": "2.1.389",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -65,9 +65,9 @@
       "require": "./src/tools/Tour/index.ts"
     },
     "./code-editor": {
-      "types": "./src/tools/CodeEditor/index.ts",
-      "import": "./src/tools/CodeEditor/index.ts",
-      "require": "./src/tools/CodeEditor/index.ts"
+      "types": "./src/tools/CodeEditor/lazy.tsx",
+      "import": "./src/tools/CodeEditor/lazy.tsx",
+      "require": "./src/tools/CodeEditor/lazy.tsx"
     },
     "./tree": {
       "types": "./dist/tree/index.d.ts",
@@ -80,14 +80,14 @@
       "require": "./dist/file-icon/index.cjs"
     },
     "./audio-player": {
-      "types": "./src/tools/AudioPlayer/index.ts",
-      "import": "./src/tools/AudioPlayer/index.ts",
-      "require": "./src/tools/AudioPlayer/index.ts"
+      "types": "./src/tools/AudioPlayer/lazy.tsx",
+      "import": "./src/tools/AudioPlayer/lazy.tsx",
+      "require": "./src/tools/AudioPlayer/lazy.tsx"
     },
     "./chat": {
-      "types": "./src/tools/Chat/index.ts",
-      "import": "./src/tools/Chat/index.ts",
-      "require": "./src/tools/Chat/index.ts"
+      "types": "./src/tools/Chat/lazy.tsx",
+      "import": "./src/tools/Chat/lazy.tsx",
+      "require": "./src/tools/Chat/lazy.tsx"
     },
     "./cron-scheduler": {
       "types": "./src/tools/CronScheduler/lazy.tsx",
@@ -115,9 +115,14 @@
       "require": "./src/tools/LottiePlayer/lazy.tsx"
     },
     "./markdown-editor": {
-      "types": "./src/tools/MarkdownEditor/index.ts",
-      "import": "./src/tools/MarkdownEditor/index.ts",
-      "require": "./src/tools/MarkdownEditor/index.ts"
+      "types": "./src/tools/MarkdownEditor/lazy.tsx",
+      "import": "./src/tools/MarkdownEditor/lazy.tsx",
+      "require": "./src/tools/MarkdownEditor/lazy.tsx"
+    },
+    "./markdown-message": {
+      "types": "./src/components/markdown/MarkdownMessage/index.ts",
+      "import": "./src/components/markdown/MarkdownMessage/index.ts",
+      "require": "./src/components/markdown/MarkdownMessage/index.ts"
     },
     "./openapi-viewer": {
       "types": "./src/tools/OpenapiViewer/lazy.tsx",
@@ -157,8 +162,8 @@
     "test:watch": "vitest"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.385",
-    "@djangocfg/ui-core": "^2.1.385",
+    "@djangocfg/i18n": "^2.1.389",
+    "@djangocfg/ui-core": "^2.1.389",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -212,9 +217,9 @@
     "material-file-icons": "^2.4.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.385",
-    "@djangocfg/typescript-config": "^2.1.385",
-    "@djangocfg/ui-core": "^2.1.385",
+    "@djangocfg/i18n": "^2.1.389",
+    "@djangocfg/typescript-config": "^2.1.389",
+    "@djangocfg/ui-core": "^2.1.389",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",

package/src/components/index.ts

@@ -13,5 +13,5 @@ export type {
   CreateLazyComponentOptions,
 } from './lazy-wrapper';
 
-// Markdown
-export * from './markdown';
+// Markdown moved to src/tools/MarkdownMessage (re-exported from the root barrel).
+// useCollapsibleContent moved to src/hooks/.

package/src/index.ts

@@ -127,10 +127,28 @@ export * from './tools/Chat';
 export * from './tools';
 
 // ============================================================================
-// Components (Markdown, etc.)
+// Markdown renderer (sits alongside MarkdownEditor under tools/)
 // ============================================================================
 
-export * from './components/markdown';
+export {
+  MarkdownMessage,
+  default as MarkdownMessageDefault,
+  ChatMessageRow,
+  ActionRow,
+  extractTextFromChildren,
+  type MarkdownMessageProps,
+  type LinkRule,
+} from './tools/MarkdownMessage';
+
+// ============================================================================
+// Shared hooks
+// ============================================================================
+
+export {
+  useCollapsibleContent,
+  type UseCollapsibleContentOptions,
+  type UseCollapsibleContentResult,
+} from './hooks/useCollapsibleContent';
 
 // ============================================================================
 // Stores

package/src/tools/AudioPlayer/lazy.tsx

@@ -1,8 +1,30 @@
 'use client';
 
+/**
+ * `@djangocfg/ui-tools/audio-player` subpath entrypoint.
+ *
+ * `LazyPlayer` is the only heavy export — it dynamically imports the full
+ * `Player` tree (PlayerShell + Layout + Cover + Waveform + Controls + audio
+ * decoding helpers). Everything else listed here is light:
+ *   - types are erased,
+ *   - the Zustand store, context hooks, and selectors carry no UI,
+ *   - the slot components (`Cover`, `Title`, `PlayButton`, `Waveform`, …)
+ *     are presentational React components that read from PlayerContext —
+ *     they only become meaningful inside a `<PlayerProvider>` (which only
+ *     exists inside `LazyPlayer` once loaded).
+ *
+ * Consumers building a fully custom layout: render `<LazyPlayer>` once to
+ * get the provider, then arrange slot components inside via render-children
+ * pattern, or use the bare `Player` re-exported from the root barrel.
+ */
+
 import { createLazyComponent } from '../../components';
 import type { PlayerProps } from './types';
 
+// ============================================================================
+// Lazy heavy component
+// ============================================================================
+
 export const LazyPlayer = createLazyComponent<PlayerProps>(
   () => import('./Player').then((mod) => ({ default: mod.Player })),
   {
@@ -14,3 +36,81 @@ export const LazyPlayer = createLazyComponent<PlayerProps>(
     ),
   },
 );
+
+// ============================================================================
+// Light surface — types, store, context, slot components, hooks
+// ============================================================================
+
+// Types
+export type {
+  PlayerProps,
+  PlayerState,
+  PlayerStateKind,
+  PlayerControls,
+  PlayerHandle,
+  WaveformConfig,
+  WaveformMode,
+  ReactiveCoverMode,
+  PlayerVariant,
+  PlayerErrorReason,
+} from './types';
+
+// Context provider + selector hooks (no UI)
+export {
+  PlayerProvider,
+  usePlayerAudio,
+  usePlayerControls,
+  usePlayerDuration,
+  usePlayerLevels,
+  usePlayerMeta,
+  usePlayerPaused,
+  usePlayerState,
+} from './context';
+
+// Cross-instance store (active player, preferences)
+export {
+  setActivePlayer,
+  getActivePlayer,
+  getLastActivePlayer,
+  subscribeActivePlayer,
+  getPreferences,
+  setStoredVolume,
+  setStoredMuted,
+  subscribePreferences,
+  type PlayerPreferences,
+} from './store';
+
+// Store-backed hooks
+export {
+  useActivePlayer,
+  useLastActivePlayer,
+  useIsActivePlayer,
+} from './hooks/useActivePlayer';
+export { usePlayerPreferences } from './hooks/usePlayerPreferences';
+
+// Peak cache helpers
+export { clearPeaksCache, setPeaks } from './audio';
+
+// Slot components — presentational, read from PlayerContext. Safe to
+// re-export synchronously: they don't import the heavy Player tree
+// (audio decoding, layouts, shell) — only context selectors and types.
+export { Cover, CoverPlaceholder, ReactivePulse } from './parts/Cover';
+export { Title, Artist, TimeDisplay } from './parts/Meta';
+export {
+  PlayButton,
+  SkipButton,
+  VolumeControl,
+  LoopButton,
+  ControlsRow,
+  IconButton,
+} from './parts/Controls';
+export {
+  Waveform,
+  PeaksWaveform,
+  LiveWaveform,
+  BarsWaveform,
+  ProgressBar,
+  WaveformSkeleton,
+} from './parts/Waveform';
+export { ErrorState } from './parts/ErrorState';
+export { DefaultLayout, CompactLayout } from './parts/Layout';

package/src/tools/Chat/README.md

@@ -165,6 +165,67 @@ const prefs = useChatDockPrefs({ storageKey: 'crm.chat.dock' });
 >{children}</ChatLauncher>
 ```
 
+#### Side-mode body reserve + the `--chat-dock-reserve` token
+
+When the dock is in `mode='side'` it pushes the rest of the page out of its way by writing two things to `<body>`:
+
+| Surface | Value | Set by |
+|---|---|---|
+| `body.style.paddingRight` (or `paddingLeft`) | dock width in `px` | `<ChatDock>` mount effect |
+| `--chat-dock-reserve` (CSS custom property) | same `px` value, as a token | same effect |
+
+That covers two layout flows automatically:
+
+- **Static content inside `<body>`** — `paddingRight` shifts it inward so the chat doesn't cover the right edge.
+- **CSS-only consumers** — read the token from anywhere:
+  ```css
+  .my-floating-thing {
+    padding-right: var(--chat-dock-reserve, 0px);
+  }
+  ```
+
+**`position: fixed` consumers (navbars, FABs, sticky banners) are NOT auto-shifted** — body padding doesn't propagate to fixed positioning. They have to opt in by reading the token themselves. Example for a fixed top navbar:
+
+```tsx
+'use client';
+
+import { useEffect, useState } from 'react';
+
+/** Mirrors `<body>` padding onto a fixed element so it leaves room for the docked chat. */
+function useChatDockReserve() {
+  const [reserve, setReserve] = useState({ left: 0, right: 0 });
+  useEffect(() => {
+    const read = () => {
+      const cs = getComputedStyle(document.body);
+      setReserve({
+        left: parseFloat(cs.paddingLeft) || 0,
+        right: parseFloat(cs.paddingRight) || 0,
+      });
+    };
+    read();
+    const mo = new MutationObserver(read);
+    mo.observe(document.body, { attributes: true, attributeFilter: ['style'] });
+    window.addEventListener('resize', read);
+    return () => { mo.disconnect(); window.removeEventListener('resize', read); };
+  }, []);
+  return reserve;
+}
+
+export function MyNavbar() {
+  const reserve = useChatDockReserve();
+  return (
+    <header
+      className="fixed top-0 z-50 transition-all"
+      style={{ left: reserve.left, right: reserve.right }}
+    >
+      …
+    </header>
+  );
+}
+```
+
+Same recipe works for any other fixed element (cookie banner, FAB, sticky toolbar). When the dock is in `popover` mode (or closed) both values are `0` and the navbar spans the full viewport.
+
 ### Greeting
 
 ```tsx
@@ -256,7 +317,7 @@ const audio = useChatAudio();
 </ChatLauncher>
 ```
 
-**Built-in sounds.** The chat tool ships its own notification pack (`messageSent`, `messageReceived`, `streamStart`, `error`, `mention`, `notification`) inlined into the lazy chunk via tsup's `dataurl` loader. ~136KB total, ~180KB after base64 — paid only by hosts that actually import Chat. No assets to copy, no CDN to host.
+**Built-in sounds.** The chat tool ships its own notification pack (`messageSent`, `messageReceived`, `streamStart`, `error`, `mention`, `notification`) inlined as `data:audio/mpeg;base64,…` URLs inside `core/audio/sounds/*.ts` modules. ~136KB total — paid only by hosts that actually import Chat. No `.mp3` loader, no `*.d.ts` shim, no CDN to host. Re-encode source mp3s via ffmpeg + `base64 -i …` and paste back into the matching `.ts` file (see `core/audio/defaults.ts` header for the recipe).
 
 Customize:
 
@@ -318,6 +379,29 @@ Calls `window.dialog.confirm` (destructive variant) from `@djangocfg/ui-core/lib
 | Reusing `dismissStorageKey` across products | Greeting won't show on the second product |
 | Calling `useChatUnread()` outside `ChatProvider` | Hook reads the messages store; throws without provider |
 | Forgetting `<DialogProvider>` for `<ChatHeaderResetButton confirm>` | Falls back to native browser confirm (ugly) |
+| Mixing **root barrel** and **subpath** imports | Loads the package twice → two React contexts → `useChatContextOptional()` returns `null` → VoiceComposerSlot silently drops transcripts. See **Import discipline** below. |
+
+#### Import discipline
+
+`@djangocfg/ui-tools` ships its root export (`.`) through a compiled bundle in `dist/`, while most subpaths (`./chat`, `./speech-recognition`, `./audio-player`, …) resolve to raw `src/`. JavaScript bundlers treat them as **two separate modules**, so each gets its own `React.createContext(...)` call.
+
+```tsx
+// ❌ DON'T: ChatRoot from `dist`, VoiceComposerSlot from `src` → two contexts
+import { ChatRoot } from '@djangocfg/ui-tools';
+import { VoiceComposerSlot } from '@djangocfg/ui-tools/speech-recognition';
+//                                                         ^^^^^^^^^^^^^^^^^^^
+// VoiceComposerSlot's internal useChatContextOptional() reads a DIFFERENT
+// React context than the one ChatProvider populated. ctx.composer is null,
+// every transcript gets a "no composer handle registered" warning.
+
+// ✅ DO: pull every Chat-side surface from the same `./chat` subpath
+import { ChatRoot, ChatLauncher, useChatContextOptional } from '@djangocfg/ui-tools/chat';
+import { VoiceComposerSlot } from '@djangocfg/ui-tools/speech-recognition';
+```
+
+The rule of thumb: **anything that talks to `ChatProvider` belongs on the `./chat` subpath**. The root barrel is for tooling glue (types, transports, generic helpers) and is safe to mix with subpaths as long as you don't import anything that uses the Chat React context from it.
+
+If two ChatProvider context instances ever end up in the same page, `ChatProvider` emits a one-time `console.warn` in development with the same fix instructions — that's the runtime guard, look for `[@djangocfg/ui-tools/chat] Two ChatProvider context instances detected …` in DevTools.
 
 ## Styling — role-aware tokens
 

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

@@ -5,7 +5,7 @@ import { memo, type ReactNode } from 'react';
 import { Avatar, AvatarFallback, AvatarImage } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
-import { MarkdownMessage } from '../../../components/markdown';
+import { MarkdownMessage } from '../../MarkdownMessage';
 import type {
   ChatAssistantContext,
   ChatAttachment,

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

@@ -64,6 +64,48 @@ export interface ChatContextValue extends UseChatReturn {
 
 const Ctx = createContext<ChatContextValue | null>(null);
 
+// ─── Dual-bundle guard ────────────────────────────────────────────────────
+//
+// `@djangocfg/ui-tools` ships its root export through `dist/` (compiled) but
+// most subpaths resolve to raw `src/`. If a consumer mixes them — e.g.
+// `ChatRoot` from the root barrel and `VoiceComposerSlot` from
+// `@djangocfg/ui-tools/speech-recognition` — `createContext(...)` runs twice
+// and produces two distinct context instances. The Composer registers its
+// handle on one; `useChatContextOptional()` in the voice slot reads from the
+// other, sees `null`, and silently drops every transcript.
+//
+// We tag the global with our module identity. When more than one tag is
+// observed the consumer is told exactly what to do.
+type GuardSlot = { stamps: Set<symbol>; warned: boolean };
+const GLOBAL_KEY = '__djangocfg_chat_ctx_stamps__';
+const stamp = Symbol('djangocfg.chat.ctx');
+function markCtxLoad(): void {
+  if (typeof globalThis === 'undefined') return;
+  const g = globalThis as unknown as Record<string, GuardSlot | undefined>;
+  let slot = g[GLOBAL_KEY];
+  if (!slot) {
+    slot = { stamps: new Set(), warned: false };
+    g[GLOBAL_KEY] = slot;
+  }
+  slot.stamps.add(stamp);
+  if (slot.stamps.size > 1 && !slot.warned && process.env.NODE_ENV !== 'production') {
+    slot.warned = true;
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[@djangocfg/ui-tools/chat] Two ChatProvider context instances detected — ' +
+        'this means `@djangocfg/ui-tools` was loaded twice (one bundle via the root ' +
+        '`.` export → `dist/`, another via a `./chat` / `./speech-recognition` subpath → `src/`). ' +
+        'Symptom: `useChatContextOptional()` returns `null` for descendants of `<ChatProvider>`, ' +
+        'so VoiceComposerSlot drops transcripts, useChatReset silently no-ops, etc. ' +
+        '\n\nFix: import every Chat surface from the SAME subpath. Recommended:\n' +
+        "  import { ChatRoot, ChatLauncher, useChatContextOptional, … } from '@djangocfg/ui-tools/chat';\n" +
+        "  import { VoiceComposerSlot } from '@djangocfg/ui-tools/speech-recognition';\n" +
+        '\n(See packages/ui-tools/src/tools/Chat/README.md → "Anti-patterns".)',
+    );
+  }
+}
+markCtxLoad();
+
 export interface ChatProviderProps {
   transport: ChatTransport;
   config?: ChatConfig;

package/src/tools/Chat/index.ts

@@ -253,4 +253,4 @@ export {
   extractTextFromChildren,
   type MarkdownMessageProps,
   type LinkRule,
-} from '../../components/markdown';
+} from '../MarkdownMessage';