@djangocfg/ui-tools 2.1.413 → 2.1.416

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.413",
+  "version": "2.1.416",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -254,8 +254,8 @@
     "test:watch": "vitest"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.413",
-    "@djangocfg/ui-core": "^2.1.413",
+    "@djangocfg/i18n": "^2.1.416",
+    "@djangocfg/ui-core": "^2.1.416",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -265,6 +265,10 @@
     "zustand": "^5.0.0"
   },
   "dependencies": {
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/modifiers": "^9.0.0",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
     "@floating-ui/dom": "^1.7.4",
     "@rjsf/core": "^6.1.2",
     "@rjsf/utils": "^6.1.2",
@@ -315,9 +319,9 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.413",
-    "@djangocfg/typescript-config": "^2.1.413",
-    "@djangocfg/ui-core": "^2.1.413",
+    "@djangocfg/i18n": "^2.1.416",
+    "@djangocfg/typescript-config": "^2.1.416",
+    "@djangocfg/ui-core": "^2.1.416",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^25.2.3",

package/src/tools/chat/README.md

@@ -762,7 +762,7 @@ inherit the composer `size` via context, no prop needed).
 | `<ComposerToolPill icon label active onRemove>` | `inlineStart` | Gemini-style capsule for a selected tool/mode with an optional `×` to clear it. |
 | `<ComposerModelPicker value options onChange>` | `inlineEnd` | "Flash-Lite ▾" pill — opens a radio-group model picker. |
 | `<ComposerBanner variant title description actions onDismiss>` | `blockStart` | Standalone notice bubble above the composer (upsell / quota / info). |
-| `<ComposerRichTextarea mentions>` | `slots.Textarea` (Tier B) | Ready-made TipTap chat editor — unstyled, no toolbar, size-matched height, Enter-to-send, `@`-mention support. |
+| `<ComposerRichTextarea mentions slashCommands>` | `slots.Textarea` (Tier B) | Ready-made TipTap chat editor — unstyled, no toolbar, size-matched height, Enter-to-send, `@`-mention + `/slash`-chip support. |
 
 ```tsx
 <Composer
@@ -790,6 +790,82 @@ editor shows a text caret and a `mousedown` on the bare surface (not a
 button) focuses the editor. Works for both the plain `<textarea>` and the
 TipTap (`contenteditable`) backend.
 
+### Slash commands
+
+A `/verb` palette layered on top of the composer — same idea as
+mentions, but triggered only when the buffer **starts** with `/` (so it
+never conflicts with `@`-mention matching, which runs anywhere in the
+editor). Works with both the plain `<textarea>` and the TipTap-backed
+`<ComposerRichTextarea>`; in-editor chip highlighting ships for both
+paths.
+
+```tsx
+import { Composer, type SlashCommand } from '@djangocfg/ui-tools/chat';
+import { RefreshCw } from 'lucide-react';
+
+const commands: SlashCommand[] = [
+  {
+    id: 'clear',
+    token: '/clear',
+    label: 'Clear conversation',
+    description: 'Discard the current session.',
+    icon: <RefreshCw className="h-3.5 w-3.5" />,
+    autoExecute: true,
+    onExecute: () => chatActions.clearSession(),
+  },
+  {
+    id: 'connect',
+    token: '/connect',
+    label: 'Connect to machine',
+    argHint: '<hostname>',
+    // default insert behavior — user types argument and submits as normal message
+  },
+];
+
+<Composer
+  composer={composer}
+  composerSlots={{ slashCommands: { commands } }}
+/>;
+```
+
+**Behavior matrix:**
+
+- Default (insert) — Pick → inserts `/verb ` into the buffer with a
+  subtle highlight. Cursor sits ready for argument entry. User submits
+  as a normal chat message; the host reads `composer.value` to grab the
+  args and dispatches `onExecute` itself.
+- `autoExecute: true` — Pick → `onExecute()` fires immediately and the
+  buffer clears. For action commands (`/clear`, `/settings`) that don't
+  produce a chat message.
+
+**Visual highlight:**
+
+- In the plain textarea — an overlay-mirror paints `/verb` with a
+  primary tint while preserving the native caret + selection.
+- In `<ComposerRichTextarea>` (TipTap) — pass the same verb list as
+  `slashCommands` to the editor and a `SlashCommandNode` atom
+  extension paints the chip in-flow. Same primary-tinted styling as
+  the plain mirror; the atom flattens to the bare `/verb` token in
+  `getText()` / `getMarkdown()` so `composer.value` stays in plain
+  string form and the slash hook keeps driving the menu unchanged.
+
+**Keyboard:** `/` opens the menu when at buffer start. ↑/↓ navigate.
+Enter or Tab pick. Esc closes. Click outside dismisses.
+
+**Empty state:** typing `/xyzz` keeps the menu open with a "No commands
+match" row instead of disappearing — discoverability over jank.
+
+**Submit gate:** commands with `argHint` block submit until the user
+types something after the verb (`/note ` → Send disabled, Enter no-op;
+`/note hello` → Send active). `autoExecute` commands block submit
+unconditionally — they are run from the menu, not dispatched as text.
+The gate works for the plain `<Textarea>`, `<SlashHighlightTextarea>`,
+the TipTap `<ComposerRichTextarea>`, and any `slots.SendButton`.
+
+See [`composer/slash/README.md`](./composer/slash/README.md) for the
+full API reference (types, hook contract, mirror internals, direct
+`useSlashCommands` usage, mentions coexistence).
+
 ## Three usage patterns
 
 ### 1. One-line preset
@@ -808,6 +884,39 @@ TipTap (`contenteditable`) backend.
 </ChatProvider>
 ```
 
+### Suggested prompts — `<SuggestedPrompts>`
+
+Starter-prompt surface every chat host wants (ChatGPT / Claude / cmdop
+all ship a flavour of it). Drop into `slots.empty` to seed the
+composer from a click. Two layouts: `chips` (flat rounded buttons,
+default) and `grid` (2-col cards with `description`).
+
+```tsx
+import { SuggestedPrompts, type SuggestedPromptItem } from '@djangocfg/ui-tools/chat';
+import { HeartPulse, Server, Sparkles } from 'lucide-react';
+
+const PROMPTS: readonly SuggestedPromptItem[] = [
+  { id: 'machines', label: 'List my machines', prompt: 'List my connected machines', icon: <Server className="size-3.5" /> },
+  { id: 'health',   label: 'Run a health check', prompt: 'Run a health check and report issues', icon: <HeartPulse className="size-3.5" /> },
+];
+
+<ChatRoot
+  slots={{
+    empty: ({ setValue, focus }) => (
+      <SuggestedPrompts
+        items={PROMPTS}
+        onPick={(item) => { setValue(item.prompt); focus(); }}
+        hero={<Sparkles className="size-6 text-primary" />}
+        title="How can I help?"
+        description="Pick a starter, or just start typing."
+      />
+    ),
+  }}
+/>
+```
+
+`renderItem` is an escape hatch for one-off chip styling without forking the component.
+
 ### 3. Headless
 
 ```tsx
@@ -952,6 +1061,7 @@ plus `Overview` (MDX) and `Showcase` (a one-screen living demo):
 | `slots.jumpToLatest` | Sticky overlay | `ReactNode` |
 | `composer.slots.actionsStart` / `actionsEnd` | Composer action clusters | `ComposerAction[]` |
 | `composer.slots.blockStart` | Above composer textarea | `ReactNode` |
+| `composer.slots.slashCommands` | `/verb` palette (buffer-start trigger) | `SlashConfig` (`{ commands: SlashCommand[] }`) |
 | `composer.footer` | Below composer | `ComposerFooterProps \| false` |
 | `composer.render` | Replace `<Composer>` | `({ composer, config }) => ReactNode` |
 | `messages.render` | Replace each bubble | `(m, i) => ReactNode` |

package/src/tools/chat/composer/Composer.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { forwardRef, useEffect, useRef, useState } from 'react';
+import { forwardRef, useEffect, useMemo, useRef, useState } from 'react';
 
 import { Textarea } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
@@ -13,6 +13,9 @@ import { ComposerActionBar } from './ComposerActionBar';
 import { ComposerButton } from './ComposerButton';
 import { ComposerFooter } from './ComposerFooter';
 import { ComposerSizeProvider } from './size-context';
+import { SlashHighlightTextarea } from './slash/SlashHighlightTextarea';
+import { SlashMenu } from './slash/SlashMenu';
+import { useSlashCommands } from './slash/useSlashCommands';
 import { useComposerActions } from './useComposerActions';
 import { useComposerAttach } from './useComposerAttach';
 import type {
@@ -205,6 +208,63 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
   const inlineEnd = composerSlots?.inlineEnd;
   const blockStart = composerSlots?.blockStart;
 
+  // ── Slash commands ─────────────────────────────────────────────────────
+  // When the host wires `composerSlots.slashCommands`, an internal
+  // `<SlashMenu>` is rendered as a floating popover above the input
+  // surface and ↑/↓/Enter/Tab/Esc are routed to the slash hook while
+  // the menu is open. The hook is always called (React rules) — it
+  // is a no-op when `commands` is the empty array.
+  const slashCommands = composerSlots?.slashCommands?.commands;
+  const slashEnabled = !!slashCommands && slashCommands.length > 0;
+  const slash = useSlashCommands({
+    value: composer.value,
+    commands: slashCommands ?? [],
+    onApply: composer.setValue,
+  });
+  const slashOnKeyDown = slash.onKeyDown;
+  const slashIsOpen = slashEnabled && slash.isOpen;
+  // When slash is enabled and the current buffer is a `/verb` missing
+  // a required argument (or an `autoExecute` action), submit is blocked:
+  // the Send button reads disabled and Enter is a no-op. The host-facing
+  // `composer` is wrapped into `gatedComposer` so every downstream
+  // surface (built-in Send, custom SendSlot, TipTap `ComposerRichTextarea`,
+  // plain `<Textarea>`) shares the same gate without each having to
+  // know about slash state.
+  const slashAllowsSubmit = slashEnabled ? slash.canSubmit : true;
+  const gatedComposer = useMemo<UseChatComposerReturn>(() => {
+    if (slashAllowsSubmit) return composer;
+    const baseOnKeyDown = composer.textareaProps.onKeyDown;
+    return {
+      ...composer,
+      canSubmit: false,
+      submit: async () => {
+        // Slash gate refuses — swallow programmatic submit attempts.
+      },
+      textareaProps: {
+        ...composer.textareaProps,
+        onKeyDown: (e) => {
+          // Block Enter (without Shift) so the textarea's own submit
+          // binding cannot fire while the slash gate is closed. Cmd /
+          // Ctrl + Enter is treated the same. Other keys (history,
+          // arrows, etc.) pass through to the original handler.
+          if (e.key === 'Enter' && !e.shiftKey) {
+            e.preventDefault();
+            return;
+          }
+          baseOnKeyDown(e);
+        },
+      },
+    };
+  }, [composer, slashAllowsSubmit]);
+  // Capture-phase handler — runs before the textarea / TipTap own
+  // submit binding, so Enter / Tab pick a verb instead of sending.
+  const handleSlashKeyDownCapture = !slashEnabled
+    ? undefined
+    : (e: React.KeyboardEvent<HTMLDivElement>) => {
+        if (!slash.isOpen) return;
+        slashOnKeyDown(e);
+      };
+
   // Clicking the padding around the input (not a button/link) should focus
   // the editor — same affordance as ChatGPT/Gemini. Works for both the
   // plain `<textarea>` and the TipTap (`contenteditable`) backend by
@@ -282,14 +342,14 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
 
   // Merge built-in send/stop/attach descriptors with host arrays.
   const { actionsStart, actionsEnd } = useComposerActions({
-    composer,
+    composer: gatedComposer,
     isStreaming,
     isDisabled,
     showAttachmentButton,
     onPickFiles: pickFiles,
     actionsStart: composerSlots?.actionsStart,
     actionsEnd: composerSlots?.actionsEnd,
-    onSend: () => void composer.submit(),
+    onSend: () => void gatedComposer.submit(),
     onCancel,
     micSendSwap,
   });
@@ -300,33 +360,45 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
   const ActionBarSlot = slots?.ActionBar;
 
   // ── Textarea ───────────────────────────────────────────────────────────
+  // When slash commands are enabled and the host hasn't supplied its own
+  // Textarea slot, swap in the overlay-mirror `<SlashHighlightTextarea>`
+  // so a leading `/verb` reads as a styled chip while the user types.
+  const sharedTextareaClass = cn(
+    'flex-1 resize-none border-0 bg-transparent shadow-none',
+    'focus-visible:ring-0 focus-visible:outline-none',
+    sz.textarea,
+    sz.text,
+    ap.textarea,
+    ap.text,
+    slotProps?.textarea?.className,
+    textareaClassName,
+  );
   const textareaNode = TextareaSlot ? (
     <TextareaSlot
-      composer={composer}
+      composer={gatedComposer}
       placeholder={placeholder}
       disabled={isDisabled}
       size={size}
       className={slotProps?.textarea?.className ?? textareaClassName}
     />
+  ) : slashEnabled ? (
+    <SlashHighlightTextarea
+      composer={gatedComposer}
+      placeholder={placeholder}
+      disabled={isDisabled}
+      size={size}
+      textareaClassName={sharedTextareaClass}
+    />
   ) : (
     <Textarea
-      {...composer.textareaProps}
+      {...gatedComposer.textareaProps}
       rows={1}
       placeholder={placeholder}
       aria-label={placeholder}
       aria-multiline="true"
       aria-keyshortcuts="Enter"
       disabled={isDisabled}
-      className={cn(
-        'flex-1 resize-none border-0 bg-transparent shadow-none',
-        'focus-visible:ring-0 focus-visible:outline-none',
-        sz.textarea,
-        sz.text,
-        ap.textarea,
-        ap.text,
-        slotProps?.textarea?.className,
-        textareaClassName,
-      )}
+      className={sharedTextareaClass}
     />
   );
 
@@ -359,9 +431,9 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
   const customSend = SendSlot ? (
     <SendSlot
       streaming={isStreaming}
-      disabled={!composer.canSubmit}
+      disabled={!gatedComposer.canSubmit}
       size={size}
-      onSend={() => void composer.submit()}
+      onSend={() => void gatedComposer.submit()}
       onCancel={onCancel}
       {...slotProps?.send}
     />
@@ -428,6 +500,51 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
       />
     ) : null;
 
+  // Click outside the slash menu (and outside the composer surface)
+  // dismisses it. Mounted only while the menu is open to keep the
+  // listener footprint minimal.
+  const slashMenuRef = useRef<HTMLDivElement>(null);
+  const slashClear = slash.clear;
+  useEffect(() => {
+    if (!slashIsOpen) return;
+    const onPointerDown = (e: MouseEvent) => {
+      const target = e.target as Node | null;
+      if (!target) return;
+      if (slashMenuRef.current?.contains(target)) return;
+      // Clicks inside the input surface (textarea, action buttons) are
+      // fine — only outside-of-composer interactions should dismiss.
+      // `surfaceRef` is only mounted in the stacked layout; fall back
+      // to the active editable node so the inline layout works too.
+      if (surfaceRef.current?.contains(target)) return;
+      const editable = composer.textareaRef.current;
+      if (editable && editable.contains(target)) return;
+      slashClear();
+    };
+    document.addEventListener('mousedown', onPointerDown);
+    return () => document.removeEventListener('mousedown', onPointerDown);
+  }, [slashIsOpen, slashClear, composer.textareaRef]);
+
+  // Slash-command floating popover. Anchored to the top of the input
+  // surface; appears just above it so it doesn't cover the textarea.
+  const slashOverlay =
+    slashIsOpen ? (
+      <div
+        className={cn(
+          'pointer-events-auto absolute left-2.5 right-2.5 z-20',
+          'bottom-full mb-1.5',
+        )}
+      >
+        <SlashMenu
+          ref={slashMenuRef}
+          matches={slash.matches}
+          highlight={slash.highlight}
+          query={slash.query}
+          onPick={slash.pick}
+          onHighlight={slash.setHighlight}
+        />
+      </div>
+    ) : null;
+
   // Start cluster sits left of the textarea, end cluster right of it —
   // `[📎][actionsStart] [textarea] [actionsEnd][🎙][▶]` (§3.6).
   if (layout === 'inline') {
@@ -437,6 +554,7 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
         <div
           ref={ref}
           {...dragProps}
+          onKeyDownCapture={handleSlashKeyDownCapture}
           className={cn(
             'relative border-t border-border bg-background/95',
             sz.containerPadding,
@@ -446,6 +564,7 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
         >
           {hiddenFileInput}
           {dragOverlay}
+          {slashOverlay}
           {trayNode ? <div className="mb-1.5">{trayNode}</div> : null}
           <div
             className={cn(
@@ -554,6 +673,7 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
       <div
         ref={ref}
         {...dragProps}
+        onKeyDownCapture={handleSlashKeyDownCapture}
         className={cn(
           'relative border-t border-border bg-background/95',
           sz.containerPadding,
@@ -563,6 +683,7 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
       >
         {hiddenFileInput}
         {dragOverlay}
+        {slashOverlay}
         {trayNode ? <div className="mb-2">{trayNode}</div> : null}
         {surfaceWrapper}
         {footerNode}

package/src/tools/chat/composer/ComposerRichTextarea.tsx

@@ -6,6 +6,7 @@ import {
   LazyMarkdownEditor as MarkdownEditor,
   type MarkdownEditorHandle,
   type MentionConfig,
+  type SlashCommandInfo,
 } from '@djangocfg/ui-tools/markdown-editor';
 
 import { useRegisterComposer } from '../hooks/useAutoFocusOnStreamEnd';
@@ -21,6 +22,23 @@ const MIN_HEIGHT: Record<ComposerSize, number> = {
 export interface ComposerRichTextareaProps extends ComposerTextareaProps {
   /** `@`-mention autocomplete config. Omit for a plain rich textarea. */
   mentions?: MentionConfig;
+  /**
+   * Slash-command verb list. When set, a leading `/verb` in the editor
+   * is painted as an atom chip (same primary-tinted styling as the
+   * plain `<SlashHighlightTextarea>` mirror). The chat composer's slash
+   * menu already lives outside the editor and keeps working without
+   * this prop — pass the verb list here when you also want the
+   * in-editor highlight to match.
+   *
+   * Structurally compatible with `SlashCommand` from
+   * `@djangocfg/ui-tools/chat` — passing the same array you wire into
+   * `composerSlots.slashCommands` is the normal pattern.
+   *
+   * Note: like `mentions`, the underlying TipTap extension is captured
+   * once on first render. If you may register slash commands later,
+   * pass `[]` from the very first render and mutate the list in place.
+   */
+  slashCommands?: readonly SlashCommandInfo[];
 }
 
 /**
@@ -42,10 +60,16 @@ export function ComposerRichTextarea({
   size,
   className,
   mentions,
+  slashCommands,
 }: ComposerRichTextareaProps) {
   // Tiptap captures the mentions object once on first render — keep its
   // identity stable so the suggestion plugin stays wired.
   const stableMentions = useMemo(() => mentions, [mentions]);
+  // `slashCommands` flows through every render — the editor's
+  // SlashCommandNode is registered once on first mount (gated on
+  // `slashCommands !== undefined`) and the current list is read via a
+  // ref by the value-sync effect, so runtime additions / removals
+  // still light up the chip.
 
   // The TipTap editor has no `<textarea>`, so the composer's default
   // `focus` handle (which targets `textareaRef`) is a no-op here.
@@ -73,6 +97,7 @@ export function ComposerRichTextarea({
         value={composer.value}
         onChange={composer.setValue}
         mentions={stableMentions}
+        slashCommands={slashCommands}
         placeholder={placeholder}
         minHeight={MIN_HEIGHT[size]}
         showToolbar={false}

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

@@ -40,6 +40,28 @@ export {
 } from './useComposerAttach';
 export { useComposerAttachContext } from './AttachContext';
 export { fileToAttachment, revokeAttachmentUrl } from './fileToAttachment';
+export {
+  parseSlashState,
+  filterCommands,
+  applyCommand,
+  resolveCommandAction,
+  extractSlashToken,
+  useSlashCommands,
+  SlashMenu,
+  SlashToken,
+  SlashHighlightTextarea,
+  DEFAULT_SLASH_LABELS,
+  type SlashCommand,
+  type SlashState,
+  type SlashConfig,
+  type SlashCommandAction,
+  type UseSlashCommandsOptions,
+  type UseSlashCommandsReturn,
+  type SlashMenuProps,
+  type SlashTokenProps,
+  type SlashHighlightTextareaProps,
+  type SlashMenuLabels,
+} from './slash';
 export type {
   ComposerAction,
   ComposerActionVisibility,