@djangocfg/ui-tools 2.1.415 → 2.1.416

package/src/tools/data/Tree/types/root-props.ts

@@ -0,0 +1,142 @@
+'use client';
+
+import type { CSSProperties } from 'react';
+
+import type { TreeAppearance } from '../data/appearance';
+import type { TreeActivateOptions, TreeActivationMode } from './activation';
+import type {
+  TreeAdapter,
+  TreeBuiltinAction,
+  TreeMovePosition,
+} from './adapter';
+import type { TreeLabels } from './labels';
+import type { TreeLoadChildren } from './loader';
+import type { TreeItemId, TreeNode } from './node';
+import type { TreeSelectionMode } from './selection';
+import type {
+  TreeContextMenuActionsResolver,
+  TreeContextMenuSlot,
+  TreeRowSlot,
+} from './slots';
+
+export interface TreeRootProps<T> {
+  /** Root nodes. Top-level items are rendered directly (no synthetic root). */
+  data: TreeNode<T>[];
+  /** Returns the human-readable name for a node (used by search/type-ahead). */
+  getItemName: (node: TreeNode<T>) => string;
+
+  /** Async loader for folders without inline `children`. */
+  loadChildren?: TreeLoadChildren<T>;
+
+  /** Selection behaviour. Default: `'single'`. */
+  selectionMode?: TreeSelectionMode;
+  /** Pointer activation behaviour. Default: `'single-click'`. */
+  activationMode?: TreeActivationMode;
+  /** Initially expanded ids. */
+  initialExpandedIds?: TreeItemId[];
+  /** Initially selected ids. */
+  initialSelectedIds?: TreeItemId[];
+  /** Pixels of indent per nesting level. Default: 16. (Shortcut for `appearance.indent`.) */
+  indent?: number;
+  /** Cosmetic configuration: density, sizes, accent intensity, radius. */
+  appearance?: TreeAppearance;
+
+  /** Triggered when selection changes. */
+  onSelectionChange?: (selectedIds: TreeItemId[]) => void;
+  /** Triggered when expanded set changes. */
+  onExpansionChange?: (expandedIds: TreeItemId[]) => void;
+  /**
+   * Triggered when a leaf is activated (Enter / dblclick / click depending
+   * on `activationMode`). Folders never call this — they toggle instead.
+   */
+  onActivate?: (node: TreeNode<T>, opts: TreeActivateOptions) => void;
+
+  /**
+   * Optional predicate. Nodes returning `false` (and their descendants) are
+   * not rendered and not searchable. Use this to hide dot-files, system
+   * entries, or anything else the consumer wants to filter out.
+   */
+  filterNode?: (node: TreeNode<T>) => boolean;
+
+  /** Show built-in search input. Default: false. */
+  enableSearch?: boolean;
+  /** Type printable letters to jump to a matching name. Default: true. */
+  enableTypeAhead?: boolean;
+  /** Render vertical indent guides under expanded folders. Default: false. */
+  showIndentGuides?: boolean;
+  /**
+   * Allow inline rename. When true, F2 starts an inline `<input>`; the
+   * value is committed through `adapter.rename`. Requires `adapter.rename`.
+   * Default: false.
+   */
+  enableInlineRename?: boolean;
+  /**
+   * Enable Finder/Explorer keyboard shortcuts (delete, rename, duplicate,
+   * new file/folder, cut/copy/paste). Bindings only fire when the tree
+   * container has focus. Individual shortcuts are still gated by the
+   * adapter — `⌘⌫` does nothing if `adapter.remove` is undefined.
+   * Default: false.
+   */
+  enableFinderHotkeys?: boolean;
+  /**
+   * Enable drag-and-drop reorder + move-into-folder. Requires
+   * `adapter.move`. Powered by `@dnd-kit/core` — pointer + keyboard
+   * sensors, accessible.
+   * Default: false.
+   */
+  enableDnD?: boolean;
+  /**
+   * Custom drop validation. Returns `true` to allow, `false` to forbid.
+   * The default validator rejects self-drops and cycles (dropping a
+   * folder into its own descendant). Use this to add domain rules
+   * (read-only branches, type matching, …).
+   */
+  canDrop?: (ctx: {
+    source: TreeNode<T>[];
+    target: TreeNode<T> | null;
+    position: TreeMovePosition;
+  }) => boolean;
+
+  /** Custom row renderer. Falls back to the default <TreeRow />. */
+  renderRow?: TreeRowSlot<T>;
+  /** Replace default folder/file icon. */
+  renderIcon?: TreeRowSlot<T>;
+  /** Replace default label rendering. */
+  renderLabel?: TreeRowSlot<T>;
+  /** Right-side actions slot (per row). */
+  renderActions?: TreeRowSlot<T>;
+  /** Wrap each row in a context menu (right-click). Receives the row meta + trigger element. */
+  renderContextMenu?: TreeContextMenuSlot<T>;
+  /**
+   * Declarative right-click menu — short-form. Pass `(row) => [items]` and the
+   * Tree builds a `<ContextMenu>` for you with sensible defaults. Ignored if
+   * `renderContextMenu` is also set. Return `null`/`undefined`/`[]` to skip
+   * the menu for that row.
+   */
+  contextMenuActions?: TreeContextMenuActionsResolver<T>;
+
+  /** Override built-in copy in your locale. */
+  labels?: Partial<TreeLabels>;
+  /** Persist expanded + (optional) selected ids in localStorage under this key. */
+  persistKey?: string;
+  /** Persist selection alongside expansion. Default: false. */
+  persistSelection?: boolean;
+
+  /**
+   * CRUD adapter. When set, Tree builds default context-menu items and
+   * Finder hotkeys for every method the adapter defines. Methods that
+   * are not provided produce no UI — no greyed-out items.
+   */
+  adapter?: TreeAdapter<T>;
+  /**
+   * Which built-in actions to expose in the auto-built context menu. If
+   * omitted, every action whose adapter method exists is shown.
+   *
+   * Pass `[]` to suppress the auto-built menu entirely while keeping the
+   * adapter for hotkeys / DnD.
+   */
+  defaultMenuItems?: TreeBuiltinAction[];
+
+  className?: string;
+  style?: CSSProperties;
+}

package/src/tools/data/Tree/types/selection.ts

@@ -0,0 +1,3 @@
+'use client';
+
+export type TreeSelectionMode = 'none' | 'single' | 'multiple';

package/src/tools/data/Tree/types/slots.ts

@@ -0,0 +1,64 @@
+'use client';
+
+import type { ComponentType, ReactNode } from 'react';
+
+import type { TreeNode } from './node';
+
+export interface TreeRowRenderProps<T> {
+  node: TreeNode<T>;
+  level: number;
+  isSelected: boolean;
+  isExpanded: boolean;
+  isFocused: boolean;
+  isFolder: boolean;
+  isLoading: boolean;
+  isMatchingSearch: boolean;
+}
+
+export type TreeRowSlot<T> = (props: TreeRowRenderProps<T>) => ReactNode;
+
+export type TreeContextMenuSlot<T> = (
+  props: TreeRowRenderProps<T>,
+  trigger: ReactNode,
+) => ReactNode;
+
+/**
+ * Declarative context-menu item. Pass `'separator'` (string) in place of an
+ * object to insert a `<ContextMenuSeparator />` between groups.
+ *
+ * For more advanced needs (submenus, checkbox items, custom JSX), drop down
+ * to `renderContextMenu` instead.
+ */
+export interface TreeContextMenuAction<T> {
+  /** Stable React key. */
+  id: string;
+  label: ReactNode;
+  /** Lucide-style icon component. Rendered as `<icon className="size-4" />`. */
+  icon?: ComponentType<{ className?: string }>;
+  /** Right-aligned keyboard hint (e.g. `'⌘C'`, `'↵'`). Cosmetic. */
+  shortcut?: ReactNode;
+  /** Disable the item — still rendered, not selectable. */
+  disabled?: boolean;
+  /** Style as destructive (red). */
+  destructive?: boolean;
+  /** Click / Enter handler. Receives the row meta. */
+  onSelect: (props: TreeRowRenderProps<T>) => void;
+}
+
+export type TreeContextMenuItem<T> = TreeContextMenuAction<T> | 'separator';
+
+/**
+ * Context passed to a `contextMenuActions` resolver. `row` is the row the
+ * user right-clicked. `selectedNodes` is the multi-selection at the
+ * moment the menu opens — when the right-clicked row was not in the
+ * selection, Tree first switches selection to that single row, so
+ * `selectedNodes` always contains the right-clicked node.
+ */
+export interface TreeContextMenuActionsContext<T> extends TreeRowRenderProps<T> {
+  /** Multi-selection at the moment the menu opens. Always non-empty. */
+  selectedNodes: TreeNode<T>[];
+}
+
+export type TreeContextMenuActionsResolver<T> = (
+  ctx: TreeContextMenuActionsContext<T>,
+) => TreeContextMenuItem<T>[] | null | undefined;

package/src/tools/forms/MarkdownEditor/MarkdownEditor.tsx

@@ -13,6 +13,9 @@ import {
 } from 'lucide-react';
 import { createMentionSuggestion } from './createMentionSuggestion';
 import { mentionPresets } from './mentionPresets';
+import { SlashCommandNode } from './slash/SlashCommandNode';
+import { syncLeadingSlashNode } from './slash/syncSlashNode';
+import type { SlashCommandInfo } from './slash/types';
 import { SubmitOnEnter } from './submitOnEnter';
 import type { MentionAttrs, MentionConfig } from './types';
 import './styles.css';
@@ -84,6 +87,23 @@ export interface MarkdownEditorProps {
    * no-op for the live editor.
    */
   mentions?: MentionConfig;
+  /**
+   * Slash-command verb list. When set, the editor registers a
+   * `SlashCommandNode` extension and replaces a leading `/verb` (whose
+   * verb is in this list) in the document with an atomic chip — the
+   * TipTap analogue of the plain `<SlashHighlightTextarea>` mirror.
+   *
+   * Like `mentions`, this is captured by `useEditor` exactly once on
+   * first render. To register slash commands at all, pass `[]` from
+   * the very first render and mutate / swap as needed. The conversion
+   * effect re-reads the list on every value sync (it lives in a ref),
+   * so verbs added later are recognised next time the buffer is set.
+   *
+   * Lives in `@djangocfg/ui-tools/markdown-editor` (not chat) so the
+   * editor stays a leaf dependency. Structurally compatible with the
+   * chat package's `SlashCommand[]` — pass either directly.
+   */
+  slashCommands?: readonly SlashCommandInfo[];
   /** Called when mentioned IDs change */
   onMentionIdsChange?: (ids: string[]) => void;
   /**
@@ -136,6 +156,7 @@ export const MarkdownEditor = forwardRef<MarkdownEditorHandle, MarkdownEditorPro
     showToolbar = true,
     unstyled = false,
     mentions,
+    slashCommands,
     onMentionIdsChange,
     onSubmit,
   },
@@ -150,6 +171,35 @@ export const MarkdownEditor = forwardRef<MarkdownEditorHandle, MarkdownEditorPro
   onSubmitRef.current = onSubmit;
   const isExternalUpdate = useRef(false);
 
+  // Slash list lives in a ref so verbs added at runtime (e.g. context-
+  // aware commands registered after a first reply) are still recognised
+  // by the post-`setContent` conversion pass. The editor extension itself
+  // is registered once on mount — that is intentional and matches how
+  // `mentions` works (Tiptap's `useEditor` captures extensions once).
+  const slashCommandsRef = useRef<readonly SlashCommandInfo[]>(
+    slashCommands ?? [],
+  );
+  slashCommandsRef.current = slashCommands ?? [];
+  const slashEnabledOnMountRef = useRef<boolean>(slashCommands !== undefined);
+  const slashWarnedRef = useRef(false);
+  if (
+    process.env.NODE_ENV !== 'production' &&
+    !slashEnabledOnMountRef.current &&
+    slashCommands !== undefined &&
+    !slashWarnedRef.current
+  ) {
+    slashWarnedRef.current = true;
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[MarkdownEditor] `slashCommands` flipped from undefined to a list ' +
+        'after mount. Tiptap only installs the SlashCommandNode extension ' +
+        'on first render — the in-editor chip will NOT appear for this ' +
+        'editor instance. Pass `[]` from the very first render and mutate ' +
+        'the array in place (or swap references) so the conversion effect ' +
+        'sees the new verbs.',
+    );
+  }
+
   // ── Dev-mode trap detector ──
   // Tiptap initialises the editor once with the extensions array from
   // first render. If `mentions` is undefined on mount and becomes
@@ -194,6 +244,16 @@ export const MarkdownEditor = forwardRef<MarkdownEditorHandle, MarkdownEditorPro
       }),
     ];
 
+    // SlashCommandNode — TipTap atom that paints the `/verb` chip.
+    // Registered whenever `slashCommands` was defined on first render
+    // (the empty array still counts as "I want this feature"). The
+    // node has no suggestion plugin of its own — the chat composer's
+    // floating menu drives selection and the editor only needs to
+    // know how to render + serialize the atom.
+    if (slashEnabledOnMountRef.current) {
+      exts.push(SlashCommandNode);
+    }
+
     if (mentions) {
       // ── Why .extend() with renderMarkdown ──
       //
@@ -260,6 +320,20 @@ export const MarkdownEditor = forwardRef<MarkdownEditorHandle, MarkdownEditorPro
     contentType: 'markdown',
     onUpdate: ({ editor }) => {
       if (isExternalUpdate.current) return;
+      // Promote a freshly-typed `/verb ` text run into a chip so users
+      // who type the command without going through the menu still see
+      // the highlight — matches the plain mirror's behaviour where
+      // `extractSlashToken` works for any leading slash. The helper is
+      // idempotent and a no-op when no leading text-slash exists.
+      if (slashEnabledOnMountRef.current) {
+        const replaced = syncLeadingSlashNode(editor, slashCommandsRef.current);
+        if (replaced) {
+          // The chain() above triggers an extra onUpdate. The string
+          // serialisation is unchanged (atom flattens to its token via
+          // `renderText`), so we still want the outer onChange to fire
+          // with the canonical value. Falling through is fine.
+        }
+      }
       onChange(getMarkdown(editor));
 
       if (onMentionIdsChange) {
@@ -284,6 +358,17 @@ export const MarkdownEditor = forwardRef<MarkdownEditorHandle, MarkdownEditorPro
     if (current !== value) {
       isExternalUpdate.current = true;
       editor.commands.setContent(value, { contentType: 'markdown', emitUpdate: false });
+      // After the new content is written, convert a leading `/verb` text
+      // run into a `SlashCommandNode` atom so the chip appears. The
+      // helper is a no-op when (a) slash commands are not enabled,
+      // (b) the buffer doesn't start with a known verb, or (c) the
+      // document already begins with the atom. `emitUpdate: false` on
+      // setContent + `isExternalUpdate.current` still being `true`
+      // suppresses the onUpdate -> onChange feedback loop the chain()
+      // call would otherwise trigger.
+      if (slashEnabledOnMountRef.current) {
+        syncLeadingSlashNode(editor, slashCommandsRef.current);
+      }
       isExternalUpdate.current = false;
     }
   }, [value, editor]);

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

@@ -7,3 +7,4 @@ export type {
   MentionMarkdownRenderer,
 } from './types';
 export { mentionPresets } from './mentionPresets';
+export type { SlashCommandInfo } from './slash/types';

package/src/tools/forms/MarkdownEditor/lazy.tsx

@@ -65,3 +65,9 @@ export type {
   MentionAttrs,
   MentionMarkdownRenderer,
 } from './types';
+
+// Slash command surface — opt-in by passing `slashCommands` to
+// `MarkdownEditor` (or `<ComposerRichTextarea>`, which forwards). The
+// node itself is mounted by the editor on first render. `SlashCommandInfo`
+// is structurally compatible with the chat package's `SlashCommand`.
+export type { SlashCommandInfo } from './slash/types';

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));