@djangocfg/ui-tools 2.1.415 → 2.1.417

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

@@ -0,0 +1,97 @@
+'use client';
+
+export interface TreeLabels {
+  loading: string;
+  empty: string;
+  error: string;
+  searchPlaceholder: string;
+  searchMatches: (count: number) => string;
+  ariaLabel: string;
+
+  // ---- CRUD flow copy (used by built-in adapter actions + dialogs) ----
+
+  /** Default context-menu item labels. */
+  actionOpen: string;
+  actionRename: string;
+  actionDuplicate: string;
+  actionCut: string;
+  actionCopy: string;
+  actionPaste: string;
+  actionDelete: string;
+  actionNewFile: string;
+  actionNewFolder: string;
+
+  /** Delete confirmation dialog. */
+  confirmDeleteTitle: (count: number) => string;
+  confirmDeleteMessage: (names: string[]) => string;
+  confirmDeleteOk: string;
+  confirmDeleteCancel: string;
+
+  /** New file prompt. */
+  newFileTitle: string;
+  newFileMessage: string;
+  newFilePlaceholder: string;
+  newFileDefault: string;
+
+  /** New folder prompt. */
+  newFolderTitle: string;
+  newFolderMessage: string;
+  newFolderPlaceholder: string;
+  newFolderDefault: string;
+
+  /** Rename prompt (used when inline rename is unavailable / disabled). */
+  renameTitle: string;
+  renameMessage: string;
+
+  /** Name validation. */
+  invalidNameEmpty: string;
+
+  /** Suffix used by the default `duplicate` flow when the consumer's adapter
+   *  needs a hint name. Receives the source name. */
+  duplicateSuffix: (name: string) => string;
+}
+
+export const DEFAULT_TREE_LABELS: TreeLabels = {
+  loading: 'Loading…',
+  empty: 'Nothing to show',
+  error: 'Failed to load',
+  searchPlaceholder: 'Search…',
+  searchMatches: (n) => `${n} match${n === 1 ? '' : 'es'}`,
+  ariaLabel: 'Tree',
+
+  actionOpen: 'Open',
+  actionRename: 'Rename',
+  actionDuplicate: 'Duplicate',
+  actionCut: 'Cut',
+  actionCopy: 'Copy',
+  actionPaste: 'Paste',
+  actionDelete: 'Delete',
+  actionNewFile: 'New file',
+  actionNewFolder: 'New folder',
+
+  confirmDeleteTitle: (n) =>
+    n === 1 ? 'Delete item?' : `Delete ${n} items?`,
+  confirmDeleteMessage: (names) =>
+    names.length === 1
+      ? `"${names[0]}" will be removed. This action cannot be undone.`
+      : `${names.length} items will be removed. This action cannot be undone.`,
+  confirmDeleteOk: 'Delete',
+  confirmDeleteCancel: 'Cancel',
+
+  newFileTitle: 'New file',
+  newFileMessage: 'File name',
+  newFilePlaceholder: 'untitled.txt',
+  newFileDefault: 'untitled.txt',
+
+  newFolderTitle: 'New folder',
+  newFolderMessage: 'Folder name',
+  newFolderPlaceholder: 'untitled folder',
+  newFolderDefault: 'untitled folder',
+
+  renameTitle: 'Rename',
+  renameMessage: 'New name',
+
+  invalidNameEmpty: 'Name cannot be empty',
+
+  duplicateSuffix: (name) => `${name} copy`,
+};

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

@@ -0,0 +1,9 @@
+'use client';
+
+import type { TreeNode } from './node';
+
+/**
+ * Async loader: called the first time a folder is expanded with no inline
+ * `children`. Result is cached; concurrent expansions are de-duplicated.
+ */
+export type TreeLoadChildren<T> = (node: TreeNode<T>) => Promise<TreeNode<T>[]>;

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

@@ -0,0 +1,38 @@
+'use client';
+
+export type TreeItemId = string;
+
+/** A single node in the consumer's tree data. Generic over your payload. */
+export interface TreeNode<T = unknown> {
+  id: TreeItemId;
+  data: T;
+  /** Inline children. Omit (and provide a `loadChildren`) for async loading. */
+  children?: TreeNode<T>[];
+  /**
+   * Set to `true` to mark a node as a folder even when its `children` array
+   * is empty (e.g. an unloaded async folder). Default: derived from
+   * `Array.isArray(children)`.
+   */
+  isFolder?: boolean;
+  /** Disable interaction. */
+  disabled?: boolean;
+}
+
+/**
+ * Internal flat-row representation used by the renderer + keyboard nav.
+ * Produced by `flattenTree`; consumed by `TreeRow`, the keyboard hook,
+ * and the type-ahead hook.
+ */
+export interface FlatRow<T> {
+  node: TreeNode<T>;
+  level: number;
+  parentId: TreeItemId | null;
+  isFolder: boolean;
+  isExpanded: boolean;
+  isLoading: boolean;
+  hasError: boolean;
+  /** 1-based position among visible siblings (for `aria-posinset`). */
+  posInSet: number;
+  /** Count of visible siblings sharing this row's parent (for `aria-setsize`). */
+  setSize: number;
+}

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

@@ -0,0 +1,158 @@
+'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[];
+
+  /**
+   * Imperative handle for outer code. The provided ref receives a
+   * stable handle to `useTreeActions` once Tree mounts. Lets host
+   * components trigger `refresh(id)` / `refreshAll()` from outside
+   * Tree (e.g. after a transport-level mutation completes).
+   */
+  actionsRef?: React.MutableRefObject<TreeActionsHandle | null>;
+
+  className?: string;
+  style?: CSSProperties;
+}
+
+/** Subset of `useTreeActions()` exposed via `<TreeRoot actionsRef={…}>`. */
+export interface TreeActionsHandle {
+  refresh: (id: string) => Promise<void>;
+  refreshAll: () => Promise<void>;
+  expandAll: () => void;
+  collapseAll: () => void;
+}

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/dev/OpenapiViewer/components/DocsLayout/EndpointDoc/Header/MetaActions.tsx

@@ -12,7 +12,6 @@ import {
     Tooltip,
     TooltipContent,
     TooltipTrigger,
-    SafeTooltipProvider,
 } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
@@ -119,13 +118,11 @@ export function MetaActions({ anchor, presentSections }: MetaActionsProps) {
     ) : null;
 
     return (
-        <SafeTooltipProvider delayDuration={200}>
-            <div className="flex items-center gap-0.5">
-                <IconButton label={linkLabel} onClick={copyLink} active={linkCopied}>
-                    {linkIcon}
-                </IconButton>
-                {toggleAllNode}
-            </div>
-        </SafeTooltipProvider>
+        <div className="flex items-center gap-0.5">
+            <IconButton label={linkLabel} onClick={copyLink} active={linkCopied}>
+                {linkIcon}
+            </IconButton>
+            {toggleAllNode}
+        </div>
     );
 }

package/src/tools/dev/OpenapiViewer/components/DocsLayout/index.tsx

@@ -3,7 +3,7 @@
 import React, { useCallback, useMemo, useRef, useState } from 'react';
 import { keyBy } from 'lodash-es';
 
-import { Skeleton, TooltipProvider } from '@djangocfg/ui-core/components';
+import { Skeleton } from '@djangocfg/ui-core/components';
 import { useMediaQuery } from '@djangocfg/ui-core/hooks';
 
 import useOpenApiSchema from '../../hooks/useOpenApiSchema';
@@ -234,8 +234,7 @@ export const DocsLayout: React.FC = () => {
     // ─── Desktop ──────────────────────────────────────────────────────────
 
     return (
-        <TooltipProvider delayDuration={350}>
-            <div className="grid grid-cols-[260px_minmax(0,1fr)] items-start">
+        <div className="grid grid-cols-[260px_minmax(0,1fr)] items-start">
                 <EndpointDraftSync schemaId={currentSchema?.id ?? null} />
                 <div
                     className="sticky top-[var(--navbar-height,64px)]"
@@ -283,6 +282,5 @@ export const DocsLayout: React.FC = () => {
                     above the whole layout (sidebar + navbar included). */}
                 <SlideInPlayground open={slideOpen} onClose={handleCloseSlide} />
             </div>
-        </TooltipProvider>
     );
 };

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