@djangocfg/ui-tools 2.1.310 → 2.1.313

package/package.json

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

package/src/components/markdown/MarkdownMessage/ActionRow.tsx

@@ -0,0 +1,48 @@
+'use client';
+
+import React from 'react';
+import { CopyButton } from '@djangocfg/ui-core/components';
+
+interface ActionRowProps {
+  /** Raw text to copy — pass the same source string used for render. */
+  value: string;
+  /** Bubble side. Just controls flex alignment; nothing is mirrored. */
+  isUser: boolean;
+  /**
+   * Whether the row is currently shown. Owner-controlled (typically
+   * `<ChatMessageRow>` toggles this on hover with a small close delay).
+   * The component is intentionally dumb about visibility — owners
+   * have full control over reveal logic (hover, focus, always-on,
+   * touch behaviour, etc.).
+   */
+  visible: boolean;
+}
+
+// Action row that lives directly under a chat bubble.
+// Visibility is fully owner-controlled via `visible`.
+//
+// We render at `opacity-0` (not `display:none`) so the fade in/out
+// stays smooth across re-renders. While invisible we drop pointer
+// events so a hidden row can't intercept clicks meant for the page
+// underneath.
+export const ActionRow: React.FC<ActionRowProps> = ({ value, isUser, visible }) => {
+  return (
+    <div
+      className={`flex ${isUser ? 'justify-end' : 'justify-start'}
+        transition-opacity duration-150
+        ${visible ? 'opacity-100 pointer-events-auto' : 'opacity-0 pointer-events-none'}`}
+    >
+      <CopyButton
+        value={value}
+        size="icon"
+        variant="ghost"
+        iconClassName="h-3.5 w-3.5"
+        className="h-7 w-7 text-muted-foreground hover:text-foreground"
+        // Hidden rows must not be reachable via Tab — otherwise
+        // keyboard users land on an invisible button.
+        tabIndex={visible ? 0 : -1}
+        aria-hidden={!visible}
+      />
+    </div>
+  );
+};

package/src/components/markdown/MarkdownMessage/ChatMessageRow.tsx

@@ -0,0 +1,97 @@
+'use client';
+
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { useMediaQuery } from '@djangocfg/ui-core/hooks';
+
+interface ChatMessageRowProps {
+  /** Side of the conversation — drives flex alignment and `isUser`
+   *  passed to `actions`. */
+  isUser: boolean;
+  /** The bubble (your own JSX). Anything goes — `<MarkdownMessage>`,
+   *  custom card, multi-element composition. */
+  children: React.ReactNode;
+  /** Render-prop for the action row. Receives `visible` so the row
+   *  knows when to fade in/out. Render `null` to opt out. */
+  actions?: (visible: boolean, isUser: boolean) => React.ReactNode;
+  /** Close delay in ms after the cursor leaves the row. Long enough
+   *  to bridge cursor travel from bubble → action button without
+   *  flicker. Default 250ms (Radix Tooltip-ish). */
+  closeDelayMs?: number;
+  /** Optional class on the column container. */
+  className?: string;
+}
+
+// Owner of the bubble + action row layout.
+//
+// Why a state-based hover instead of `group-hover` CSS:
+//   - CSS-only hover bridges break when the cursor crosses gaps
+//     between the bubble and the (initially-invisible) row — the
+//     row's `pointer-events-none` lets the cursor "fall through",
+//     `group-hover` flips off, the row vanishes mid-travel.
+//   - State + a small close timeout gives Radix-Tooltip-style
+//     stability: enter shows immediately, leave waits N ms.
+//   - On touch (`@media (hover:none)`) hover doesn't exist; we
+//     always pass `visible={true}` so the affordance is reachable.
+//
+// The action row is rendered **absolutely** under the bubble so
+// hidden rows don't allocate vertical space — no dead-air gap
+// between consecutive messages.
+export const ChatMessageRow: React.FC<ChatMessageRowProps> = ({
+  isUser,
+  children,
+  actions,
+  closeDelayMs = 250,
+  className = '',
+}) => {
+  const isTouch = useMediaQuery('(hover: none), (pointer: coarse)');
+  const [hovered, setHovered] = useState(false);
+  const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const cancelClose = useCallback(() => {
+    if (closeTimer.current) {
+      clearTimeout(closeTimer.current);
+      closeTimer.current = null;
+    }
+  }, []);
+
+  const open = useCallback(() => {
+    cancelClose();
+    setHovered(true);
+  }, [cancelClose]);
+
+  const scheduleClose = useCallback(() => {
+    cancelClose();
+    closeTimer.current = setTimeout(() => setHovered(false), closeDelayMs);
+  }, [cancelClose, closeDelayMs]);
+
+  useEffect(() => () => cancelClose(), [cancelClose]);
+
+  // Touch: always-visible. Hover: state-driven.
+  const visible = isTouch || hovered;
+
+  // On touch, `static` positioning so the row claims real layout
+  // space (otherwise an absolute always-visible row would still
+  // overlap the next message). On hover devices, `absolute` so the
+  // hidden row doesn't leave dead air between bubbles.
+  const rowPositionClass = isTouch ? 'static mt-1' : 'absolute top-full';
+  const rowSideClass = isUser ? 'right-0' : 'left-0';
+
+  return (
+    <div
+      className={`relative flex flex-col ${isUser ? 'items-end' : 'items-start'} ${className}`}
+      onPointerEnter={isTouch ? undefined : open}
+      onPointerLeave={isTouch ? undefined : scheduleClose}
+      onFocusCapture={open}
+      onBlurCapture={(e) => {
+        if (!e.currentTarget.contains(e.relatedTarget as Node | null)) scheduleClose();
+      }}
+    >
+      {children}
+      {actions && (
+        <div className={`${rowPositionClass} ${rowSideClass}`}>
+          {actions(visible, isUser)}
+        </div>
+      )}
+    </div>
+  );
+};

package/src/components/markdown/MarkdownMessage/CodeBlock.tsx

@@ -19,27 +19,23 @@ interface CodeBlockProps {
  * branch below still ships its own button because the plain <pre>
  * has no toolbar of its own.
  */
-export const CodeBlock: React.FC<CodeBlockProps> = ({ code, language, isCompact = false }) => {
+export const CodeBlock: React.FC<CodeBlockProps> = ({ code, language }) => {
   const theme = useResolvedTheme();
 
-  // Hoist derived values out of JSX (COMPONENTS.md
-  // "Data Preparation Before Render"):
-  //   `textSizeClass` — chat-density font tier, so the JSX line
-  //                     stays a one-liner.
-  // The `--code` token (ui-core/styles/theme/tokens.css) handles the
-  // palette in both themes / both bubble roles; we don't branch on
-  // `isUser` here on purpose.
-  const textSizeClass = isCompact ? 'text-xs' : 'text-sm';
-
+  // Chat fences are always rendered in PrettyCode's compact mode:
+  // 12px font, tighter padding, line-height 1.4. A fenced block in
+  // a chat bubble shouldn't outweigh two paragraphs of body text —
+  // the standalone PrettyCode story keeps the larger default for
+  // docs/diff viewers.
   return (
-    <div className="my-3">
+    <div className="my-2">
       <PrettyCode
         data={code}
         language={language}
-        className={textSizeClass}
+        className="text-xs"
         customBg="bg-code"
         mode={theme}
-        isCompact={isCompact}
+        isCompact
         // Disable click-to-scroll-isolation in chat markdown: code
         // fences here are part of an assistant reply, not a docs
         // viewer. Forcing the user to click into a small block to

package/src/components/markdown/MarkdownMessage/MarkdownMessage.story.tsx

@@ -1,6 +1,8 @@
 import type React from 'react';
 import { defineStory } from '@djangocfg/playground';
 import { MarkdownMessage } from './MarkdownMessage';
+import { ActionRow } from './ActionRow';
+import { ChatMessageRow } from './ChatMessageRow';
 import type { LinkRule } from './types';
 
 export default defineStory({
@@ -329,15 +331,25 @@ function ChatBubble({
   content,
   rules,
   plainText,
+  actions,
 }: {
   role: 'user' | 'assistant';
   content: string;
   rules?: LinkRule[];
   plainText?: boolean;
+  /** Show the copy-on-hover ActionRow under the bubble. */
+  actions?: 'copy';
 }) {
   const isUser = role === 'user';
   return (
-    <div className={`flex ${isUser ? 'justify-end' : 'justify-start'}`}>
+    <ChatMessageRow
+      isUser={isUser}
+      actions={
+        actions === 'copy'
+          ? (visible) => <ActionRow value={content} isUser={isUser} visible={visible} />
+          : undefined
+      }
+    >
       <div
         className={`max-w-[85%] rounded-xl px-3 py-2 ${
           isUser
@@ -352,7 +364,7 @@ function ChatBubble({
           plainText={plainText}
         />
       </div>
-    </div>
+    </ChatMessageRow>
   );
 }
 
@@ -694,3 +706,66 @@ export const MermaidDiagrams = () => (
     </div>
   </div>
 );
+
+// CopyActions — opt-in action row under the bubble. The `<ActionRow>`
+// component lives outside the bubble (so it doesn't fight the
+// saturated `bg-primary` palette on user messages); the `group` class
+// on the parent flex container makes it appear on hover. On touch
+// devices it stays at 50% opacity so the affordance is discoverable
+// without hover.
+export const CopyActions = () => (
+  <div className="mx-auto max-w-2xl space-y-6 p-6">
+    <div>
+      <h3 className="mb-2 text-sm font-semibold">
+        Hover any message to reveal the copy button
+      </h3>
+      <p className="mb-3 text-xs text-muted-foreground">
+        <code>ActionRow</code> is exported separately from{' '}
+        <code>MarkdownMessage</code> on purpose — placement is a
+        layout concern of the bubble, not of the renderer. Wrap your
+        bubble + <code>&lt;ActionRow&gt;</code> in a{' '}
+        <code>group</code> div, and the row toggles via{' '}
+        <code>group-hover</code>. On <code>@media (hover: none)</code>{' '}
+        it stays at 50% opacity instead of hiding.
+      </p>
+      <div className="rounded-lg border border-border bg-card p-4 space-y-8">
+        <ChatBubble
+          role="user"
+          content="How do I install cmdop?"
+          plainText
+          actions="copy"
+        />
+        <ChatBubble
+          role="assistant"
+          content={`Run this from your terminal:
+
+\`\`\`bash
+curl -sSL cmdop.com/install.sh | bash
+\`\`\`
+
+It auto-detects your shell and adds \`cmdop\` to PATH.`}
+          actions="copy"
+        />
+        <ChatBubble
+          role="user"
+          content={'Multi\nline\nuser message\nto verify copy preserves all newlines'}
+          plainText
+          actions="copy"
+        />
+      </div>
+    </div>
+
+    <div>
+      <h3 className="mb-2 text-sm font-semibold">
+        Without <code>actions</code> — no extra row, no overhead
+      </h3>
+      <p className="mb-3 text-xs text-muted-foreground">
+        Default behaviour. Existing consumers see no visual change.
+      </p>
+      <div className="rounded-lg border border-border bg-card p-4 space-y-3">
+        <ChatBubble role="user" content="Plain user bubble." plainText />
+        <ChatBubble role="assistant" content="Plain assistant bubble." />
+      </div>
+    </div>
+  </div>
+);

package/src/components/markdown/MarkdownMessage/MarkdownMessage.tsx

@@ -153,7 +153,7 @@ export const MarkdownMessage: React.FC<MarkdownMessageProps> = ({
     // WhatsApp/Telegram bubble density.
     return (
       <div
-        className={`${textSizeClass} leading-snug break-words whitespace-pre-wrap ${className}`}
+        className={`${textSizeClass} font-normal antialiased leading-snug break-words whitespace-pre-wrap ${className}`}
       >
         {displayContent}
         {collapsible && shouldCollapse && (
@@ -177,14 +177,13 @@ export const MarkdownMessage: React.FC<MarkdownMessageProps> = ({
     <div className={className}>
       <div
         className={`
-          prose ${proseClass} max-w-none break-words overflow-hidden ${textSizeClass}
+          prose ${proseClass} max-w-none break-words overflow-hidden ${textSizeClass} font-normal antialiased
           ${isUser ? 'prose-invert' : 'dark:prose-invert'}
           [&>*]:leading-relaxed
           [&>*:first-child]:mt-0 [&>*:last-child]:mb-0
           [&_p]:my-2
           [&_ul]:my-2 [&_ol]:my-2 [&_ul]:pl-5 [&_ol]:pl-5
           [&_li]:my-1 [&_li>p]:my-0
-          [&_pre]:my-3
           [&_h1]:mt-4 [&_h1]:mb-2 [&_h1]:text-base [&_h1]:font-semibold
           [&_h2]:mt-3.5 [&_h2]:mb-1.5 [&_h2]:text-[15px] [&_h2]:font-semibold
           [&_h3]:mt-3 [&_h3]:mb-1 [&_h3]:text-sm [&_h3]:font-medium

package/src/components/markdown/MarkdownMessage/README.md

@@ -23,6 +23,7 @@ import { MarkdownMessage } from '@djangocfg/ui-tools';
 | Custom URL schemes via declarative `linkRules` | `./linkRules.ts` |
 | Plain-text fast path — short messages skip the markdown pipeline | `./plainText.ts` |
 | Optional collapsible "Read more" for long replies | `useCollapsibleContent` |
+| Hover-revealed copy action under the bubble (separate `<ActionRow>` export) | `<CopyButton>` (ui-core) |
 | User vs assistant palette via `isUser` flag | semantic theme tokens |
 
 ## Why these plugins
@@ -83,6 +84,74 @@ The plain `a` renderer keeps its palette and typography; `linkRules` only fires
 when both the `protocols` and the `match` predicate accept the href. See
 `linkRules.ts` for the sanitize-extension logic.
 
+## Copy action (`<ChatMessageRow>` + `<ActionRow>`)
+
+Two pieces, two responsibilities:
+
+- **`<ActionRow>`** — dumb leaf. Knows the side (`isUser`) and the
+  text to copy (`value`). Owner controls visibility via `visible`.
+- **`<ChatMessageRow>`** — opinionated wrapper. Owns the bubble +
+  action-row layout, hover state with a 250 ms close delay, touch
+  fallback, focus management, and absolute positioning for the row
+  so a hidden row never claims vertical space.
+
+The split exists because:
+
+1. `MarkdownMessage` doesn't know whether it lives in a saturated
+   `bg-primary` bubble or a neutral card — putting the copy icon
+   inside would force it to fight the bubble's palette.
+2. CSS-only `group-hover` bridges flicker when the cursor crosses
+   the gap between the bubble and the (initially-invisible) row.
+   State + a small close timeout is the same pattern Radix Tooltip
+   uses for the same reason.
+
+```tsx
+import { MarkdownMessage, ChatMessageRow, ActionRow } from '@djangocfg/ui-tools';
+
+function ChatBubble({ role, content }) {
+  const isUser = role === 'user';
+  return (
+    <ChatMessageRow
+      isUser={isUser}
+      actions={(visible) => (
+        <ActionRow value={content} isUser={isUser} visible={visible} />
+      )}
+    >
+      <div
+        className={
+          isUser
+            ? 'bg-primary text-primary-foreground rounded-xl px-3 py-2'
+            : 'bg-card border border-border rounded-xl px-3 py-2'
+        }
+      >
+        <MarkdownMessage content={content} isUser={isUser} plainText={isUser} />
+      </div>
+    </ChatMessageRow>
+  );
+}
+```
+
+Behaviour:
+
+- **Desktop:** hidden until you hover anywhere over the row (bubble
+  or its action area). 250 ms close delay so cursor travel from
+  bubble to button never flickers. Fades over 150 ms.
+- **Touch (`@media (hover: none), (pointer: coarse)`):** always
+  visible at full opacity, in-flow under the bubble (so it claims
+  honest layout space — touch users have no hover, the affordance
+  must always be reachable).
+- **Keyboard:** `focus-within` opens the row, `blur` outside the row
+  schedules the same close timeout.
+- **Side:** the row sits on the same side as the bubble (`isUser`
+  flips alignment); the icon itself is never mirrored.
+
+Pass the original `content` string to `ActionRow.value` so collapsed
+bubbles still copy the full text, not the truncated `displayContent`.
+
+The `actions` prop is a render-prop (`(visible, isUser) => ReactNode`)
+so it's already future-proof for richer rows like
+`[Copy] [Like] [Regenerate]`.
+
 ## Files
 
 | File | Purpose |
@@ -94,6 +163,8 @@ when both the `protocols` and the `match` predicate accept the href. See
 | `plainText.ts` | `looksLikePlainProse` heuristic + `extractTextFromChildren` utility |
 | `sanitize.ts` | Extended rehype-sanitize schema + `urlTransform` builder |
 | `CollapseToggle.tsx` | "Read more / Show less" affordance for long replies |
+| `ActionRow.tsx` | Dumb action row (copy button); owner toggles `visible` |
+| `ChatMessageRow.tsx` | Bubble + action-row wrapper with hover state and touch fallback |
 | `MarkdownMessage.story.tsx` | Storybook — kitchen sink, link rules, mermaid, soft breaks, plugin sampler |
 
 ## Stories
@@ -109,3 +180,4 @@ Open the storybook and look at:
 - `Markdown Message / Kitchen Sink` — every block element together, used to spot
   spacing regressions at a glance.
 - `Markdown Message / Mermaid Diagrams` — flowchart + sequence diagram in a bubble.
+- `Markdown Message / Copy Actions` — hover-revealed copy button on user and assistant bubbles.

package/src/components/markdown/MarkdownMessage/components.tsx

@@ -21,10 +21,10 @@ export function createMarkdownComponents(
 
   return {
     h1: ({ children }) => (
-      <h1 className={`${headingBase} font-bold mb-2 mt-3 first:mt-0`}>{children}</h1>
+      <h1 className={`${headingBase} font-semibold mb-2 mt-3 first:mt-0`}>{children}</h1>
     ),
     h2: ({ children }) => (
-      <h2 className={`${headingSm} font-bold mb-2 mt-3 first:mt-0`}>{children}</h2>
+      <h2 className={`${headingSm} font-semibold mb-2 mt-3 first:mt-0`}>{children}</h2>
     ),
     h3: ({ children }) => (
       <h3 className={`${headingSm} font-semibold mb-1 mt-2 first:mt-0`}>{children}</h3>
@@ -40,7 +40,7 @@ export function createMarkdownComponents(
     ),
 
     p: ({ children }) => (
-      <p className={`${textSize} mb-4 last:mb-0 leading-7 break-words font-light`}>{children}</p>
+      <p className={`${textSize} mb-4 last:mb-0 leading-relaxed break-words`}>{children}</p>
     ),
 
     ul: ({ children }) => (

package/src/components/markdown/MarkdownMessage/index.ts

@@ -7,7 +7,13 @@
  *   - `LinkRule` — the declarative link-handling primitive.
  *   - `extractTextFromChildren` — utility for callers that build their
  *     own custom `a` renderers and need a string label.
+ *   - `ActionRow` — dumb action row (copy button), takes `visible`
+ *     from its owner.
+ *   - `ChatMessageRow` — opinionated bubble + action-row wrapper
+ *     with state-driven hover, close-delay and touch handling.
  */
 export { MarkdownMessage, default } from './MarkdownMessage';
 export type { MarkdownMessageProps, LinkRule } from './types';
 export { extractTextFromChildren } from './plainText';
+export { ActionRow } from './ActionRow';
+export { ChatMessageRow } from './ChatMessageRow';

package/src/index.ts

@@ -79,17 +79,8 @@ export { LazyJsonSchemaForm } from './tools/JsonForm/lazy';
 // LottiePlayer (~200KB)
 export { LazyLottiePlayer } from './tools/LottiePlayer/lazy';
 
-// AudioPlayer (~200KB)
-export {
-  LazyHybridAudioPlayer,
-  LazyHybridSimplePlayer,
-  LazyHybridCompactPlayer,
-} from './tools/AudioPlayer/lazy';
-export type { HybridCompactPlayerProps } from './tools/AudioPlayer/lazy';
-
-// AudioBus — global audio exclusivity (one player at a time)
-export { useAudioBus, useAudioBusStore } from './tools/AudioPlayer/hooks/useAudioBus';
-export type { UseAudioBusReturn } from './tools/AudioPlayer/hooks/useAudioBus';
+// AudioPlayer v6 — under construction (see @dev/@refactoring6-audioplayer/).
+export { LazyPlayer as LazyAudioPlayer } from './tools/AudioPlayer/lazy';
 
 // VideoPlayer (~150KB)
 export { LazyVideoPlayer } from './tools/VideoPlayer/lazy';