@djangocfg/ui-tools 2.1.415 → 2.1.417

package/src/tools/forms/MarkdownEditor/slash/SlashCommandNode.ts

@@ -0,0 +1,162 @@
+/**
+ * `SlashCommandNode` — TipTap inline atom that renders a chosen slash
+ * verb as a styled chip inside the editor, analogous to how
+ * `@tiptap/extension-mention` renders an `@user` pill.
+ *
+ * Why a node (and not a mark / decoration):
+ *
+ * - The chip must read as one indivisible unit — pressing Backspace
+ *   removes the whole `/verb`, not the trailing letter. That's
+ *   exactly what `atom: true` + `inline: true` give us.
+ * - The chip's text content (`/verb`) participates in `editor.getText()`
+ *   and the markdown serializer's text output so the host's
+ *   `composer.value` round-trips to the same plain string the plain
+ *   `<SlashHighlightTextarea>` produces. The slash hook (which lives on
+ *   the string buffer) stays oblivious to the node form.
+ *
+ * Render parity with the plain mirror:
+ *
+ * The chip class `markdown-slash-command` mirrors the plain textarea's
+ * `bg-primary/15 text-primary` look (see `SlashHighlightTextarea.tsx`).
+ * Styles live in `../styles.css`. The TipTap chip can carry a touch of
+ * horizontal padding without breaking the caret — the node is atomic
+ * so the caret never lands inside it — which the plain mirror cannot.
+ */
+import { Node, mergeAttributes } from '@tiptap/core';
+
+declare module '@tiptap/core' {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface Commands<ReturnType> {
+    slashCommand: {
+      /**
+       * Insert a slash-command atom at the given absolute document
+       * position. The host normally calls this once per `pick()`
+       * after the slash hook has produced the new string buffer.
+       */
+      insertSlashCommandAt: (
+        pos: number,
+        from: number,
+        to: number,
+        attrs: { id: string; token: string },
+      ) => ReturnType;
+    };
+  }
+}
+
+export interface SlashCommandNodeOptions {
+  /** Extra HTML attrs spread onto the rendered `<span>`. */
+  HTMLAttributes: Record<string, unknown>;
+}
+
+/**
+ * Inline atom node that paints a `/verb` chip inside the TipTap editor.
+ *
+ * - `inline: true` — lives next to text in a paragraph.
+ * - `atom: true`   — caret cannot land inside it; Backspace removes it
+ *   wholesale, matching the plain mirror's "the verb is one token"
+ *   feel.
+ * - `selectable: false` — clicking the chip does not stick a node
+ *   selection on it (mention does the same).
+ *
+ * `renderText` returns the bare `/verb` so `editor.getText()` (and
+ * therefore the host `composer.value`) reads the same string the plain
+ * mirror produces. This is what keeps the slash hook — which only
+ * understands strings — driving the menu correctly when the editor is
+ * TipTap-backed.
+ */
+export const SlashCommandNode = Node.create<SlashCommandNodeOptions>({
+  name: 'slashCommand',
+  group: 'inline',
+  inline: true,
+  atom: true,
+  selectable: false,
+  // Higher than StarterKit text so paste rules etc. don't try to
+  // re-parse our chip text as plain.
+  priority: 101,
+
+  addOptions() {
+    return {
+      HTMLAttributes: {},
+    };
+  },
+
+  addAttributes() {
+    return {
+      id: {
+        default: null,
+        parseHTML: (element) => element.getAttribute('data-id'),
+        renderHTML: (attrs) =>
+          attrs.id ? { 'data-id': attrs.id as string } : {},
+      },
+      token: {
+        default: null,
+        parseHTML: (element) => element.getAttribute('data-token'),
+        renderHTML: (attrs) =>
+          attrs.token ? { 'data-token': attrs.token as string } : {},
+      },
+    };
+  },
+
+  parseHTML() {
+    return [{ tag: `span[data-type="${this.name}"]` }];
+  },
+
+  renderHTML({ node, HTMLAttributes }) {
+    const token =
+      (node.attrs.token as string | null) ??
+      (node.attrs.id ? `/${node.attrs.id as string}` : '/');
+    return [
+      'span',
+      mergeAttributes(
+        { 'data-type': this.name, class: 'markdown-slash-command' },
+        this.options.HTMLAttributes,
+        HTMLAttributes,
+      ),
+      token,
+    ];
+  },
+
+  // `editor.getText()` and the markdown text-serializer fallback read
+  // this — the chip flattens to its raw `/verb` glyph so consumers
+  // (slash hook, transport, backends) see plain text.
+  renderText({ node }) {
+    const token =
+      (node.attrs.token as string | null) ??
+      (node.attrs.id ? `/${node.attrs.id as string}` : '/');
+    return token;
+  },
+
+  // `@tiptap/markdown` reads `renderMarkdown` off the extension at
+  // registration time. We emit the bare token, NOT the default
+  // shortcode `[slashCommand id="..."]`, so a round-trip through
+  // `getMarkdown()` yields the same `/verb argument` string the plain
+  // mirror produces. Slash commands never need re-parsed back from
+  // markdown — fresh value sync handles that via
+  // `syncLeadingSlashNode` after each `setContent`.
+  renderMarkdown(node) {
+    const attrs = node.attrs as { token?: string | null; id?: string | null };
+    const token = attrs.token ?? (attrs.id ? `/${attrs.id}` : '');
+    return token;
+  },
+
+  addCommands() {
+    return {
+      insertSlashCommandAt:
+        (pos, from, to, attrs) =>
+        ({ chain }) => {
+          // Replace the [from, to) range (typically the leading `/verb`
+          // text the user just had the menu narrow down) with the atom
+          // node. `pos` is unused here but kept in the signature for
+          // future use (e.g. cursor-driven insertion not anchored at
+          // the start of the doc).
+          void pos;
+          return chain()
+            .insertContentAt(
+              { from, to },
+              { type: 'slashCommand', attrs },
+            )
+            .run();
+        },
+    };
+  },
+});

package/src/tools/forms/MarkdownEditor/slash/index.ts

@@ -0,0 +1,4 @@
+export { SlashCommandNode } from './SlashCommandNode';
+export type { SlashCommandNodeOptions } from './SlashCommandNode';
+export { syncLeadingSlashNode } from './syncSlashNode';
+export type { SlashCommandInfo } from './types';

package/src/tools/forms/MarkdownEditor/slash/syncSlashNode.ts

@@ -0,0 +1,97 @@
+/**
+ * `syncSlashNode` — bridge between the slash hook's string buffer and
+ * the TipTap document's node form.
+ *
+ * The slash hook lives entirely on the editor value string — it has no
+ * concept of nodes. When the host wires a TipTap-backed
+ * `<ComposerRichTextarea>` with `slashCommands`, the document needs to
+ * pick up two things on its own:
+ *
+ *   1. After `setContent(newValue)` runs (e.g. the user picked `/verb`
+ *      from the menu so `composer.value` became `"/verb "`), the
+ *      leading `/verb` text must turn into a `SlashCommandNode` atom
+ *      so the chip shows up.
+ *   2. If the user backspaces past the chip or types non-slash text,
+ *      the buffer is no longer a slash command — there's nothing to
+ *      do because the atom would have been removed wholesale by the
+ *      backspace.
+ *
+ * This module owns the post-`setContent` "absorb the leading slash"
+ * pass. It is the only piece of TipTap-aware code the slash node needs
+ * beyond the node definition itself.
+ */
+import type { Editor } from '@tiptap/react';
+
+import type {
+  SlashCommandInfo,
+} from './types';
+
+/**
+ * Find the leading `/verb` in the document — if and only if it appears
+ * as the very first inline text of the first paragraph. Returns
+ * `{ verb, from, to }` (`from` / `to` are absolute document positions
+ * usable with `insertContentAt`) or `null` when no leading slash is
+ * present.
+ */
+function findLeadingSlashText(
+  editor: Editor,
+  commands: readonly SlashCommandInfo[],
+): { verb: SlashCommandInfo; from: number; to: number } | null {
+  const doc = editor.state.doc;
+  if (doc.childCount === 0) return null;
+  // Walk the document's first inline block. The buffer must START with
+  // the slash — verbs in the middle of the message are not slash
+  // commands (matches `parseSlashState` semantics).
+  const firstBlock = doc.firstChild;
+  if (!firstBlock || firstBlock.childCount === 0) return null;
+  const firstInline = firstBlock.firstChild;
+  if (!firstInline) return null;
+  // If the first inline is already a slash atom we're done.
+  if (firstInline.type.name === 'slashCommand') return null;
+  if (!firstInline.isText) return null;
+  const text = firstInline.text ?? '';
+  // Mirrors SLASH_RE from ../../../chat/composer/slash/state.ts. Kept
+  // inline to avoid pulling the chat package into the editor module.
+  const m = /^\/([a-zA-Z][\w-]*)(?:[ \n]|$)/.exec(text);
+  if (!m) return null;
+  const verb = m[1]?.toLowerCase() ?? '';
+  const cmd = commands.find((c) => c.id === verb);
+  if (!cmd) return null;
+  const slashLen = 1 + (m[1]?.length ?? 0); // `/verb` length, no trailing
+  // First text child of the first block starts at position 1 in the
+  // document (the block boundary takes position 0).
+  const from = 1;
+  const to = from + slashLen;
+  return { verb: cmd, from, to };
+}
+
+/**
+ * If the document starts with a `/verb` text node whose verb is in
+ * `commands`, replace that text with a `SlashCommandNode` atom. No-op
+ * otherwise. Idempotent — calling it on a document that already starts
+ * with the atom does nothing.
+ *
+ * Returns `true` when a replacement happened (so callers can suppress
+ * a feedback `onUpdate` if needed).
+ */
+export function syncLeadingSlashNode(
+  editor: Editor,
+  commands: readonly SlashCommandInfo[],
+): boolean {
+  if (!editor || editor.isDestroyed) return false;
+  if (commands.length === 0) return false;
+  const found = findLeadingSlashText(editor, commands);
+  if (!found) return false;
+  const { verb, from, to } = found;
+  editor
+    .chain()
+    .insertContentAt(
+      { from, to },
+      {
+        type: 'slashCommand',
+        attrs: { id: verb.id, token: verb.token },
+      },
+    )
+    .run();
+  return true;
+}

package/src/tools/forms/MarkdownEditor/slash/types.ts

@@ -0,0 +1,13 @@
+/**
+ * Editor-side slash command info — a deliberately tiny subset of the
+ * chat package's `SlashCommand` so the editor module does not depend
+ * on `@djangocfg/ui-tools/chat`. Hosts pass either the chat package's
+ * `SlashCommand[]` directly (structural compatibility) or this minimal
+ * shape.
+ */
+export interface SlashCommandInfo {
+  /** Verb without the leading slash (e.g. `"clear"`). */
+  id: string;
+  /** Display token with the slash (e.g. `"/clear"`). */
+  token: string;
+}

package/src/tools/forms/MarkdownEditor/styles.css

@@ -116,6 +116,24 @@
   box-shadow: none;
 }
 
+/* Slash-command inline chip — TipTap atom analogue of the plain
+   `<SlashHighlightTextarea>` mirror. Mirrors `bg-primary/15 text-primary`
+   so the two paths look identical. Atom nodes don't admit a caret, so
+   light horizontal padding is safe here (unlike the plain mirror,
+   which has to be padding-less to keep caret alignment). */
+.markdown-slash-command {
+  background: color-mix(in oklab, var(--color-primary, var(--primary)) 15%, transparent);
+  color: var(--color-primary, var(--primary));
+  padding: 0 2px;
+  border-radius: 3px;
+  font-weight: 500;
+  /* Atom nodes can't be entered; reflect that visually so the user does
+     not try to click into the chip to edit it. */
+  cursor: default;
+  user-select: none;
+  display: inline;
+}
+
 /* Mention inline chip */
 .markdown-mention {
   background: var(--color-primary, var(--primary));

package/src/tools/input/SpeechRecognition/widgets/VoiceComposerSlot.tsx

@@ -6,8 +6,7 @@ import { AlertCircle, Loader2, Mic } from 'lucide-react';
 
 import { useCountdownFromSeconds, useNotificationSounds } from '@djangocfg/ui-core/hooks';
 import { cn } from '@djangocfg/ui-core/lib';
-
-import { useChatContextOptional } from '../../../chat/context';
+import { useActiveComposer } from '@djangocfg/ui-tools/composer-registry';
 import { useSpeechRecognition } from '../hooks/useSpeechRecognition';
 import { useVoiceSupport } from '../hooks/useVoiceSupport';
 import { getSpeechLogger } from '../core/logger';
@@ -105,24 +104,24 @@ export function VoiceComposerSlot({
 }: VoiceComposerSlotProps): React.ReactElement | null {
   const support = useVoiceSupport(engine);
 
-  // Read the composer handle from chat context — works transparently
-  // for the built-in `<Composer>` (registers itself) and for TipTap
-  // hosts that call `useRegisterComposer({ getValue, setValue, focus,
-  // moveCursorToEnd })`. Falls back to a no-op when mounted outside of
-  // a chat.
-  const chatCtx = useChatContextOptional();
-  const composerHandleRef = useRef(chatCtx?.composer ?? null);
-  composerHandleRef.current = chatCtx?.composer ?? null;
+  // Read the active composer handle from the cross-tool registry
+  // (`@djangocfg/ui-tools/composer-registry`). The built-in
+  // `<Composer>` (and TipTap hosts via `useRegisterComposer`) publish
+  // their handle to this registry on mount. Falls back to a no-op
+  // when nothing is registered (no composer in the tree).
+  const activeComposer = useActiveComposer();
+  const composerHandleRef = useRef(activeComposer);
+  composerHandleRef.current = activeComposer;
 
   useEffect(() => {
     log.slot.debug('mount', {
       supported: support.supported,
       reason: support.reason,
-      hasComposerHandle: !!chatCtx?.composer,
+      hasComposerHandle: !!activeComposer,
       hasExplicitValue: value !== undefined,
       hasOnChange: !!onChange,
     });
-  }, [support.supported, support.reason, chatCtx?.composer, value, onChange]);
+  }, [support.supported, support.reason, activeComposer, value, onChange]);
 
   // Resolve value/onChange: prop wins; otherwise pull from the
   // registered composer handle. The slot can therefore be dropped into

package/src/tools/integration/ComposerRegistry/index.ts

@@ -0,0 +1,105 @@
+'use client';
+
+import { useCallback, useSyncExternalStore } from 'react';
+
+/**
+ * Minimal imperative handle every text-editor surface implements so
+ * an external tool (voice dictation, command palette, AI suggestion)
+ * can read/write its text content without traversing React.
+ *
+ * Methods are optional so a host can register a partial handle
+ * (e.g. only `getValue` + `setValue`), and the caller checks before use.
+ */
+export interface ComposerHandle {
+  /** Move keyboard focus into the composer's editable surface. */
+  focus: () => void;
+  /** Move the caret to the very end of the input. */
+  moveCursorToEnd?: () => void;
+  /** Read the current draft text. Voice dictation anchors partial
+   *  transcripts onto the user's already-typed prefix via this. */
+  getValue?: () => string;
+  /** Replace the current draft text. Voice dictation pushes interim
+   *  and final transcripts through this without owning a controlled
+   *  binding. */
+  setValue?: (value: string) => void;
+}
+
+/**
+ * `@djangocfg/ui-tools/composer-registry`
+ *
+ * Cross-tool bridge: the currently-active text composer's handle.
+ *
+ * Producer side (`@djangocfg/ui-tools/chat` and TipTap hosts):
+ *   register their composer's imperative handle via `attachComposer`.
+ *
+ * Consumer side (`@djangocfg/ui-tools/speech-recognition`):
+ *   reads the active handle via `useActiveComposer`/`getActiveComposer`
+ *   and pipes voice transcripts into it.
+ *
+ * Why this lives in its own subpath (not inside `chat`)
+ * ----------------------------------------------------
+ * `chat` and `speech-recognition` are sibling subpath exports. If the
+ * registry lived inside `chat`, then `speech-recognition` would have
+ * to reach into it via a cross-tool relative import — and under Vite
+ * dev's dependency optimizer that file ends up loaded TWICE (once via
+ * the `./chat` URL, once via the `./speech-recognition` relative-up
+ * URL), giving the producer and the consumer two separate `let active`
+ * slots. The active handle registered by chat would be invisible to
+ * speech-recognition (and vice versa).
+ *
+ * Putting the registry in its own dedicated subpath (a single tool
+ * that NEITHER chat nor speech-recognition cross-import — they both
+ * import this one as their dependency) means Vite resolves it from a
+ * single URL across the whole graph. One module instance, one shared
+ * `active` slot.
+ *
+ * Semantics: one active composer per realm. The most recent
+ * `registerComposer(handle)` wins; `registerComposer(null)` clears it.
+ */
+
+type Listener = (handle: ComposerHandle | null) => void;
+
+let active: ComposerHandle | null = null;
+const listeners = new Set<Listener>();
+
+/** Set or replace the active composer handle. Pass `null` to clear. */
+export function registerComposer(handle: ComposerHandle | null): void {
+  active = handle;
+  for (const fn of listeners) fn(active);
+}
+
+/**
+ * Convenience for components: register on mount, unregister on
+ * unmount. Returns a cleanup function suitable for `useEffect`.
+ */
+export function attachComposer(handle: ComposerHandle): () => void {
+  registerComposer(handle);
+  return () => {
+    if (active === handle) registerComposer(null);
+  };
+}
+
+/** Read the current active handle (no subscription). */
+export function getActiveComposer(): ComposerHandle | null {
+  return active;
+}
+
+/** Subscribe to handle changes; returns an unsubscribe fn. */
+export function subscribeComposer(listener: Listener): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/**
+ * React hook: re-renders the caller whenever the active composer
+ * changes. Built on `useSyncExternalStore` so concurrent rendering,
+ * SSR, and dev-mode strict-effects all behave correctly.
+ */
+export function useActiveComposer(): ComposerHandle | null {
+  const subscribe = useCallback((onChange: () => void) => {
+    return subscribeComposer(onChange);
+  }, []);
+  return useSyncExternalStore(subscribe, getActiveComposer, () => null);
+}

package/src/tools/media/AudioPlayer/Player.tsx

@@ -34,6 +34,7 @@ export const Player = forwardRef<PlayerHandle, PlayerProps>(function Player(prop
     ariaLabel,
     enableKeyboardShortcuts,
     seekStartsPlayback,
+    autoFocus,
   } = props;
 
   // onTimeUpdate is intentionally not wired in the provider — we expose it via
@@ -71,6 +72,7 @@ export const Player = forwardRef<PlayerHandle, PlayerProps>(function Player(prop
         enableKeyboardShortcuts={enableKeyboardShortcuts}
         ariaLabel={ariaLabel}
         seekStartsPlayback={seekStartsPlayback}
+        autoFocus={autoFocus}
         handleRef={ref}
       />
     </PlayerProvider>

package/src/tools/media/AudioPlayer/PlayerShell.tsx

@@ -4,7 +4,6 @@
 // keyboard shortcuts and MediaSession wiring; renders the picked layout.
 
 import { useCallback, useEffect, useImperativeHandle, useState } from 'react';
-import { TooltipProvider } from '@djangocfg/ui-core/components';
 import { useIsPhone } from '@djangocfg/ui-core/hooks';
 import { usePlayerAudio, usePlayerControls, usePlayerMeta } from './context/selectors';
 import { useElementWidth } from './hooks/useResizeObserver';
@@ -26,6 +25,7 @@ type Props = Pick<
   | 'enableKeyboardShortcuts'
   | 'ariaLabel'
   | 'seekStartsPlayback'
+  | 'autoFocus'
 > & {
   handleRef?: React.Ref<PlayerHandle>;
 };
@@ -40,6 +40,7 @@ export function PlayerShell({
   enableKeyboardShortcuts = true,
   ariaLabel,
   seekStartsPlayback = true,
+  autoFocus = false,
   handleRef,
 }: Props) {
   const [container, setContainer] = useState<HTMLDivElement | null>(null);
@@ -87,8 +88,9 @@ export function PlayerShell({
       seek: (s: number) => controls.seek(s),
       getCurrentTime: () => audio.currentTime,
       getDuration: () => (Number.isFinite(audio.duration) ? audio.duration : 0),
+      focus: () => container?.focus(),
     }),
-    [audio, controls],
+    [audio, controls, container],
   );
 
   // Keyboard shortcuts work only when the container can take focus.
@@ -97,26 +99,39 @@ export function PlayerShell({
     container.setAttribute('tabindex', '0');
   }, [container]);
 
+  // `autoFocus` opts the player into pulling keyboard focus on mount
+  // (and whenever the container ref is established). Once focused,
+  // the hotkey scope (Space=play/pause, ←→=seek, ↑↓=volume, M=mute)
+  // is immediately live.
+  //
+  // Deferred via a 0-timeout so the tree row's native focus event
+  // (fired by the click that triggered the mount) lands first; we
+  // then steal focus here. rAF was racy — the row's focus event can
+  // fire AFTER the next animation frame.
+  useEffect(() => {
+    if (!autoFocus || !container) return;
+    const id = setTimeout(() => container.focus(), 0);
+    return () => clearTimeout(id);
+  }, [autoFocus, container]);
+
   return (
-    <TooltipProvider delayDuration={400}>
-      <div
-        ref={setRootRef}
-        role="group"
-        aria-label={ariaLabel ?? 'Audio player'}
-        className={`audioplayer @container/player rounded-lg border border-border/60 bg-card text-foreground shadow-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50 ${className}`}
-      >
-        {resolvedVariant === 'compact' ? (
-          <CompactLayout waveform={waveform} seekStartsPlayback={seekStartsPlayback} />
-        ) : (
-          <DefaultLayout
-            waveform={waveform}
-            reactiveCover={reactiveCover}
-            onPrev={onPrev}
-            onNext={onNext}
-            seekStartsPlayback={seekStartsPlayback}
-          />
-        )}
-      </div>
-    </TooltipProvider>
+    <div
+      ref={setRootRef}
+      role="group"
+      aria-label={ariaLabel ?? 'Audio player'}
+      className={`audioplayer @container/player rounded-lg border border-border/60 bg-card text-foreground shadow-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50 ${className}`}
+    >
+      {resolvedVariant === 'compact' ? (
+        <CompactLayout waveform={waveform} seekStartsPlayback={seekStartsPlayback} />
+      ) : (
+        <DefaultLayout
+          waveform={waveform}
+          reactiveCover={reactiveCover}
+          onPrev={onPrev}
+          onNext={onNext}
+          seekStartsPlayback={seekStartsPlayback}
+        />
+      )}
+    </div>
   );
 }