@djangocfg/ui-tools 2.1.415 → 2.1.416

package/src/tools/chat/composer/slash/README.md

@@ -0,0 +1,187 @@
+# Slash commands
+
+A small, generic `/verb` surface for the chat composer — analogous to
+the `@`-mention system, but layered outside the editor (so it works
+with both the plain `<Textarea>` and the TipTap-based
+`<ComposerRichTextarea>`).
+
+## Files
+
+| File | Layer |
+|---|---|
+| `types.ts` | Public types — `SlashCommand`, `SlashState`, `SlashConfig`. No React. |
+| `state.ts` | Pure state machine — `parseSlashState`, `filterCommands`, `applyCommand`, `resolveCommandAction`, `extractSlashToken`. No React. |
+| `labels.ts` | Localisable empty-state strings. |
+| `useSlashCommands.ts` | React hook — owns highlight + keyboard, returns `pick` / `clear` / `onKeyDown` / `query`. |
+| `SlashMenu.tsx` | Dropdown — rows and empty-state line. |
+| `SlashHighlightTextarea.tsx` | Overlay-mirror textarea that paints `/verb` as a chip in-place. |
+| `SlashToken.tsx` | Chip for a resolved verb (host-rendered, optional). |
+| `index.ts` | Barrel — public API. |
+
+## Behaviour
+
+The machine has three states:
+
+- `none` — buffer does not start with `/`.
+- `composing` — buffer starts with `/` followed by an optional partial
+  verb (`/`, `/cl`, `/clear`). The menu is open; `filter` narrows the
+  verb list.
+- `command` — buffer is `/verb<space>...`. The verb resolves and the
+  rest is treated as `argument`.
+
+Trigger fires only at buffer start. Mentions (which match `@` anywhere
+in the editor) coexist without conflict.
+
+## Usage
+
+```tsx
+import {
+  Composer,
+  type SlashConfig,
+} from '@djangocfg/ui-tools/chat';
+import { Sparkles, Trash2 } from 'lucide-react';
+
+const slash: SlashConfig = {
+  commands: [
+    {
+      id: 'clear',
+      token: '/clear',
+      label: 'Clear conversation',
+      description: 'Discard the current session and start fresh.',
+      icon: <Trash2 className="h-3.5 w-3.5" />,
+    },
+    {
+      id: 'help',
+      token: '/help',
+      label: 'Show help',
+      description: 'List available commands.',
+      icon: <Sparkles className="h-3.5 w-3.5" />,
+    },
+  ],
+};
+
+<Composer composer={composer} composerSlots={{ slashCommands: slash }} />;
+```
+
+The host owns the icon nodes — this module ships zero icon dependencies.
+
+## Selection behaviour
+
+When the user picks a verb, the hook branches on
+`resolveCommandAction(value, command)`:
+
+- **Insert** (default) — the leading `/partial` is replaced with
+  `"<token> "` and the caret lands on the argument. The verb stays
+  visible in the buffer (highlighted as a chip) and the user submits
+  with Send / Enter as a normal chat message. The host reads
+  `composer.value` on submit to grab the args, then dispatches
+  `command.onExecute?.(args)` itself.
+- **Auto-execute** — opt in with `autoExecute: true`. The hook invokes
+  `command.onExecute?.('')` and clears the editor buffer; no message
+  is produced. Use this for action commands that should not turn into
+  a chat message (e.g. `/clear`, `/settings`, `/help`).
+
+`argHint` is a display hint (shown next to the label in the menu,
+e.g. `<text>`, `<host>`). It does not affect selection behavior — use
+`autoExecute` to control that.
+
+The hook never invokes `submit()` — the host stays in control of when
+the chat transport actually fires.
+
+## Submit gate
+
+Commands with `argHint` block submit until an argument is provided. The
+Send button is disabled and Enter is a no-op while the trimmed argument
+after the verb is empty (`/note `, `/summon`). Once the user adds text
+(`/note hello`), Send activates and Enter sends as usual.
+
+Commands marked `autoExecute: true` block submit unconditionally — they
+are picked from the menu (which fires `onExecute`), never dispatched
+as a text message via Enter.
+
+The gate is a pure helper, `isSubmittableSlash(value, commands)`, and
+is surfaced through the hook as `useSlashCommands().canSubmit`. The
+composer ANDs it with `composer.canSubmit` so every Send surface
+(built-in send action, `slots.SendButton`, TipTap-backed
+`<ComposerRichTextarea>`, plain `<Textarea>`) shares the same gate.
+
+## In-input highlight
+
+`<SlashHighlightTextarea>` is mounted automatically whenever
+`composerSlots.slashCommands` is set and no `slots.Textarea` is
+overridden. It uses an overlay-mirror technique: a hidden
+`<div>` underneath the textarea renders the same text with
+the `/verb` slice wrapped in a styled span, and the real textarea
+runs with `color: transparent` + `caret-color: currentColor` so the
+native caret + selection stay alive.
+
+## TipTap-backed composer
+
+The in-editor `/verb` chip works in both composer paths:
+
+- **Plain** — `<SlashHighlightTextarea>` (overlay-mirror, mounted
+  automatically when `composerSlots.slashCommands` is set and no
+  custom `slots.Textarea` is provided).
+- **TipTap** — `<ComposerRichTextarea>` with `slashCommands` set
+  uses a `SlashCommandNode` atom extension (lives in
+  `@djangocfg/ui-tools/markdown-editor`). The atom flattens to the
+  bare `/verb` token in `editor.getText()` and
+  `editor.getMarkdown()`, so `composer.value` round-trips to the
+  same string the plain mirror produces — the slash hook keeps
+  driving the menu off pure strings, oblivious to the node form.
+
+Pattern with both `@`-mention and slash chips:
+
+```tsx
+function RichTextarea(props: ComposerTextareaProps) {
+  return (
+    <ComposerRichTextarea
+      {...props}
+      mentions={mentionConfig}
+      slashCommands={commands}
+    />
+  );
+}
+
+<Composer
+  composer={composer}
+  composerSlots={{ slashCommands: { commands } }}
+  slots={{ Textarea: RichTextarea }}
+/>
+```
+
+The TipTap extension is registered once on first render (gated on
+`slashCommands !== undefined`). Pass `[]` from mount if you may
+register verbs later — the conversion effect reads the current list
+through a ref so runtime additions still light up the chip.
+
+## Direct hook usage
+
+Hosts that drive their own editor (without `<Composer>`) can wire the
+hook up by hand:
+
+```tsx
+const slash = useSlashCommands({
+  value,
+  commands,
+  onApply: setValue,
+});
+
+return (
+  <div>
+    <textarea
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
+      onKeyDown={slash.onKeyDown}
+    />
+    {slash.isOpen ? (
+      <SlashMenu
+        matches={slash.matches}
+        highlight={slash.highlight}
+        onPick={slash.pick}
+        onHighlight={slash.setHighlight}
+      />
+    ) : null}
+  </div>
+);
+```

package/src/tools/chat/composer/slash/SlashHighlightTextarea.tsx

@@ -0,0 +1,144 @@
+'use client';
+
+/**
+ * `<SlashHighlightTextarea>` — drop-in replacement for the composer's
+ * default plain `<Textarea>` that visually highlights a leading
+ * `/verb` token while preserving the native textarea editing model.
+ *
+ * Technique: overlay-mirror.
+ *
+ * - A hidden `<div role="presentation">` is rendered behind the
+ *   `<textarea>` with identical typography + padding. The leading
+ *   `/verb` slice is wrapped in `<span class="slash-token-highlight">`;
+ *   the rest of the buffer is plain text.
+ * - The real `<textarea>` sits on top with `color: transparent` and a
+ *   visible `caret-color` so the caret + selection still feel native.
+ * - Scroll position is mirrored on `onScroll` so the highlight
+ *   tracks long drafts.
+ *
+ * This module is mounted by `Composer.tsx` whenever the host wires
+ * `composerSlots.slashCommands` and has not overridden `slots.Textarea`.
+ * Hosts that swap in `ComposerRichTextarea` keep the slash menu but lose
+ * the in-input highlight for now (TipTap node is a future iteration).
+ */
+import { useLayoutEffect, useRef } from 'react';
+
+import { Textarea } from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { extractSlashToken } from './state';
+import type { ComposerTextareaProps } from '../types';
+
+export interface SlashHighlightTextareaProps extends ComposerTextareaProps {
+  /**
+   * Visual classes applied to the real textarea — passed through from
+   * the composer's per-size class table so the mirror can copy them.
+   */
+  textareaClassName?: string;
+}
+
+/**
+ * Tailwind classes the textarea, mirror, and overlay share so their
+ * box geometry stays pixel-aligned. Border / shadow / focus rings live
+ * on the surface wrapper, not here.
+ */
+const SHARED_TYPO = cn(
+  'block w-full resize-none whitespace-pre-wrap break-words',
+  'font-sans',
+);
+
+export function SlashHighlightTextarea({
+  composer,
+  placeholder,
+  disabled,
+  size: _size,
+  className,
+  textareaClassName,
+}: SlashHighlightTextareaProps) {
+  const mirrorRef = useRef<HTMLDivElement>(null);
+  const taRef = composer.textareaRef;
+
+  // Keep the mirror's scroll synced with the textarea's. The mirror is
+  // already `overflow: hidden` but on tall drafts the textarea scrolls
+  // internally — we translate the highlight slice up by the same delta
+  // so it visually tracks. Cheap; ~one ref read per scroll event.
+  useLayoutEffect(() => {
+    const ta = taRef.current;
+    const mirror = mirrorRef.current;
+    if (!ta || !mirror) return;
+    const sync = () => {
+      mirror.scrollTop = ta.scrollTop;
+      mirror.scrollLeft = ta.scrollLeft;
+    };
+    ta.addEventListener('scroll', sync, { passive: true });
+    // Also resync on value change (caller of useLayoutEffect rerun
+    // covers this) so the initial frame is aligned too.
+    sync();
+    return () => ta.removeEventListener('scroll', sync);
+  }, [taRef, composer.value]);
+
+  const value = composer.value;
+  const slice = extractSlashToken(value);
+  const token = slice?.token ?? '';
+  const rest = slice ? value.slice(slice.end) : value;
+
+  return (
+    <div className={cn('relative min-w-0 flex-1', className)}>
+      {/* Mirror — sits *under* the textarea (z-0) and renders the same
+          text with the slash token wrapped in a highlight span. */}
+      {slice ? (
+        <div
+          ref={mirrorRef}
+          aria-hidden
+          className={cn(
+            'pointer-events-none absolute inset-0 z-0 overflow-hidden',
+            'text-foreground',
+            SHARED_TYPO,
+            textareaClassName,
+            // Wipe out any focus-ring / border classes the textarea
+            // chain might have carried in — the mirror is decoration.
+            'border-0 bg-transparent shadow-none ring-0',
+          )}
+        >
+          {/* No padding, no font-family change — the mirror must occupy
+              exactly the same pixel width as the underlying textarea so
+              the caret position lines up with the visible characters.
+              Decoration via color + subtle radius only. */}
+          <span
+            className={cn(
+              'rounded-sm',
+              'bg-primary/15 text-primary',
+            )}
+          >
+            {token}
+          </span>
+          {/* Use a zero-width space when `rest` is empty so the mirror
+              keeps a baseline row — otherwise an empty `/` row collapses
+              and the highlight box loses its line height. */}
+          <span>{rest.length > 0 ? rest : '​'}</span>
+        </div>
+      ) : null}
+
+      <Textarea
+        {...composer.textareaProps}
+        rows={1}
+        placeholder={placeholder}
+        aria-label={placeholder}
+        aria-multiline="true"
+        aria-keyshortcuts="Enter"
+        disabled={disabled}
+        className={cn(
+          'relative z-10',
+          // The textarea text itself is invisible; the caret stays
+          // visible via `caret-color`. The mirror behind it paints
+          // the actual glyphs.
+          slice ? '!text-transparent caret-foreground' : 'text-foreground',
+          'flex-1 resize-none border-0 bg-transparent shadow-none',
+          'focus-visible:ring-0 focus-visible:outline-none',
+          SHARED_TYPO,
+          textareaClassName,
+        )}
+      />
+    </div>
+  );
+}

package/src/tools/chat/composer/slash/SlashMenu.tsx

@@ -0,0 +1,142 @@
+'use client';
+
+/**
+ * `<SlashMenu>` — the filtered command list shown above the composer
+ * while the slash machine is in `composing` state.
+ *
+ * Keyboard navigation (↑/↓/Enter/Tab/Esc) is owned by
+ * `useSlashCommands` — this component is a pure render of the
+ * `matches` + `highlight` it produces, plus click/hover handlers.
+ *
+ * Empty matches still render (showing a muted "No commands match" line)
+ * — keeps the dropdown anchored while the user fixes a typo instead of
+ * silently disappearing on them.
+ */
+import { forwardRef } from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import {
+  DEFAULT_SLASH_LABELS,
+  formatEmptyState,
+  type SlashMenuLabels,
+} from './labels';
+import type { SlashCommand } from './types';
+
+export interface SlashMenuProps {
+  /** Filtered verbs to show (from `useSlashCommands.matches`). */
+  matches: readonly SlashCommand[];
+  /** Index of the highlighted row. */
+  highlight: number;
+  /** Current filter query — only used for the empty-state line. */
+  query?: string;
+  /** Called when a row is clicked. */
+  onPick: (command: SlashCommand) => void;
+  /** Optional pointer-move highlight sync. */
+  onHighlight?: (index: number) => void;
+  /** Localised label overrides for the empty state. */
+  labels?: Partial<SlashMenuLabels>;
+  className?: string;
+}
+
+export const SlashMenu = forwardRef<HTMLDivElement, SlashMenuProps>(
+  function SlashMenu(
+    {
+      matches,
+      highlight,
+      query = '',
+      onPick,
+      onHighlight,
+      labels,
+      className,
+    },
+    ref,
+  ) {
+    const L = { ...DEFAULT_SLASH_LABELS, ...labels };
+    const isEmpty = matches.length === 0;
+
+    return (
+      <div
+        ref={ref}
+        role="listbox"
+        aria-label="Slash commands"
+        className={cn(
+          'overflow-hidden rounded-xl bg-popover text-popover-foreground',
+          'ring-1 ring-border shadow-lg shadow-black/10',
+          className,
+        )}
+      >
+        <div className="p-1">
+          {isEmpty ? (
+            <div
+              role="option"
+              aria-disabled
+              aria-selected={false}
+              className="px-2 py-1.5 text-[12px] text-muted-foreground"
+            >
+              {formatEmptyState(L.emptyState, query)}
+            </div>
+          ) : (
+            matches.map((cmd, i) => {
+              const isActive = i === highlight;
+              return (
+                <button
+                  key={cmd.id}
+                  type="button"
+                  role="option"
+                  aria-selected={isActive}
+                  onMouseDown={(e) => {
+                    // Keep focus in the editor — submit/blur must not fire.
+                    e.preventDefault();
+                    onPick(cmd);
+                  }}
+                  onMouseEnter={() => onHighlight?.(i)}
+                  onMouseMove={() => onHighlight?.(i)}
+                  className={cn(
+                    'flex w-full items-center gap-2.5 rounded-lg px-2 py-1.5 text-left transition-colors',
+                    isActive ? 'bg-accent' : 'hover:bg-accent/60',
+                  )}
+                >
+                  {cmd.icon ? (
+                    <span
+                      className={cn(
+                        'flex h-6 w-6 shrink-0 items-center justify-center rounded-md',
+                        'bg-muted/40 text-primary',
+                      )}
+                    >
+                      {cmd.icon}
+                    </span>
+                  ) : null}
+                  {/* Header + description form one tight group; the icon
+                      is the visual anchor, the token is a structural
+                      label. Column auto-sizes — no dead air between
+                      `/clear` and "Clear conversation". */}
+                  <span className="flex min-w-0 flex-col gap-0.5">
+                    <span className="flex items-baseline gap-2">
+                      <span className="text-[12px] font-semibold text-foreground">
+                        {cmd.token}
+                      </span>
+                      {cmd.argHint ? (
+                        <span className="text-[11px] text-muted-foreground/60">
+                          {cmd.argHint}
+                        </span>
+                      ) : null}
+                      <span className="truncate text-[12px] text-muted-foreground">
+                        {cmd.label}
+                      </span>
+                    </span>
+                    {cmd.description ? (
+                      <span className="truncate text-[11px] text-muted-foreground/70">
+                        {cmd.description}
+                      </span>
+                    ) : null}
+                  </span>
+                </button>
+              );
+            })
+          )}
+        </div>
+      </div>
+    );
+  },
+);

package/src/tools/chat/composer/slash/SlashToken.tsx

@@ -0,0 +1,57 @@
+'use client';
+
+/**
+ * `<SlashToken>` — the styled chip a resolved slash verb renders as
+ * once the machine reaches `command` state. Intended for `blockStart`
+ * or `inlineStart` composer slots so the editor reads `[/clear] args`
+ * — the verb is a token, the rest is free-text argument.
+ */
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { SlashCommand } from './types';
+
+export interface SlashTokenProps {
+  command: SlashCommand;
+  /** Called to clear the verb (drop it back to plain text). */
+  onClear?: () => void;
+  /** Optional close-icon node. Default: a small `×` glyph. */
+  clearIcon?: React.ReactNode;
+  className?: string;
+}
+
+export function SlashToken({
+  command,
+  onClear,
+  clearIcon,
+  className,
+}: SlashTokenProps) {
+  return (
+    <span
+      className={cn(
+        'inline-flex h-6 items-center gap-1 rounded-md px-1.5',
+        'bg-primary/10 text-primary',
+        className,
+      )}
+    >
+      {command.icon ? (
+        <span className="flex h-3 w-3 shrink-0 items-center justify-center">
+          {command.icon}
+        </span>
+      ) : null}
+      <span className="text-[12px] font-semibold">{command.token}</span>
+      {onClear ? (
+        <button
+          type="button"
+          onMouseDown={(e) => {
+            e.preventDefault();
+            onClear();
+          }}
+          aria-label={`Clear ${command.token}`}
+          className="ml-0.5 rounded-sm text-primary/60 transition-colors hover:text-primary"
+        >
+          {clearIcon ?? <span aria-hidden>×</span>}
+        </button>
+      ) : null}
+    </span>
+  );
+}

package/src/tools/chat/composer/slash/index.ts

@@ -0,0 +1,44 @@
+'use client';
+
+/**
+ * Slash commands — the `/verb` surface for the chat composer.
+ *
+ * Public exports:
+ * - Types (`SlashCommand`, `SlashState`, `SlashConfig`, `SlashCommandAction`)
+ * - Pure helpers (`parseSlashState`, `filterCommands`, `applyCommand`,
+ *   `resolveCommandAction`, `extractSlashToken`)
+ * - React hook (`useSlashCommands`)
+ * - UI primitives (`SlashMenu`, `SlashToken`, `SlashHighlightTextarea`)
+ * - Labels (`DEFAULT_SLASH_LABELS`, `SlashMenuLabels`)
+ *
+ * Integration: when the host passes `composerSlots.slashCommands` to
+ * `<Composer>`, the composer mounts an internal `<SlashMenu>` as a
+ * floating popover anchored over the input surface, and (when no
+ * custom `slots.Textarea` is provided) swaps the plain textarea for
+ * `<SlashHighlightTextarea>` so the `/verb` chip is visible in-flow.
+ */
+export type { SlashCommand, SlashState, SlashConfig } from './types';
+export {
+  parseSlashState,
+  filterCommands,
+  applyCommand,
+  resolveCommandAction,
+  extractSlashToken,
+  isSubmittableSlash,
+  type SlashCommandAction,
+} from './state';
+export {
+  useSlashCommands,
+  type UseSlashCommandsOptions,
+  type UseSlashCommandsReturn,
+} from './useSlashCommands';
+export { SlashMenu, type SlashMenuProps } from './SlashMenu';
+export { SlashToken, type SlashTokenProps } from './SlashToken';
+export {
+  SlashHighlightTextarea,
+  type SlashHighlightTextareaProps,
+} from './SlashHighlightTextarea';
+export {
+  DEFAULT_SLASH_LABELS,
+  type SlashMenuLabels,
+} from './labels';

package/src/tools/chat/composer/slash/labels.ts

@@ -0,0 +1,19 @@
+/**
+ * Slash-menu UI labels — i18n is the host's job. Pass overrides via
+ * the `<SlashMenu labels={...}>` prop. Strings are kept short so the
+ * empty-state line stays on one row in narrow composers.
+ */
+
+export interface SlashMenuLabels {
+  /** Empty-state line. `{query}` is replaced with the user's filter. */
+  emptyState: string;
+}
+
+export const DEFAULT_SLASH_LABELS: SlashMenuLabels = {
+  emptyState: 'No commands match "{query}"',
+};
+
+/** Substitute `{query}` placeholders in a label template. */
+export function formatEmptyState(template: string, query: string): string {
+  return template.replace('{query}', query);
+}