@djangocfg/ui-tools 2.1.412 → 2.1.415

package/src/tools/{Tree → data/Tree}/README.md

@@ -171,7 +171,8 @@ Toggle the bar with `appearance.showActiveIndicator`. Intensity scales with `app
 | Replace icon (per file type) | `renderIcon={(row) => …}` (see `WithIcons` story) |
 | Modified / error / disabled labels | `renderLabel={(row) => …}` (see `WithStatus` story) |
 | Right-side buttons (per row) | `renderActions={(row) => …}` (see `WithActions` story) |
-| Right-click menu | `renderContextMenu={(row, trigger) => <ContextMenu>…</ContextMenu>}` |
+| Right-click menu (declarative, short-form) | `contextMenuActions={(row) => [{ id, label, icon, shortcut, onSelect, destructive }, 'separator', …]}` |
+| Right-click menu (full control: submenus, checkbox/radio items, custom JSX) | `renderContextMenu={(row, trigger) => <ContextMenu>…</ContextMenu>}` |
 | Localised copy | `labels={{ empty: '…', searchPlaceholder: '…' }}` |
 | Persist state | `persistKey="settings.fileTree"`, optional `persistSelection` |
 | Imperative actions | `useTreeActions()` |
@@ -207,7 +208,7 @@ Toggle the bar with `appearance.showActiveIndicator`. Intensity scales with `app
 | WithActions | rename / delete on hover through `renderActions` |
 | WithSearch | built-in search bar + match highlight |
 | WithIndentGuides | opt-in vertical guides |
-| WithContextMenu | right-click via `renderContextMenu` + `ui-core/ContextMenu` |
+| WithContextMenu | declarative right-click via `contextMenuActions={(row) => […]}` |
 | AsyncLazyChildren | `loadChildren` + cache + dedup |
 | ExpandCollapseAll | composition mode with `useTreeActions` |
 | Persisted | localStorage round-trip |
@@ -272,6 +273,69 @@ keyboard input is treated as an explicit user action.
 The active mode is also exposed on each row as
 `data-activation-mode="<mode>"` for CSS-level targeting.
 
+## Right-click menus
+
+Two APIs, pick the lighter one when it fits.
+
+**Short-form — `contextMenuActions`.** Pass a resolver that returns a flat
+list of actions per row. Tree builds a themed `<ContextMenu>` for you. Use
+the string `'separator'` to insert dividers between groups; mark dangerous
+rows with `destructive: true`.
+
+```tsx
+import { Pencil, Copy, Trash2 } from 'lucide-react';
+
+<TreeRoot<FsNode>
+  data={data}
+  getItemName={(n) => n.data.name}
+  contextMenuActions={({ node, isFolder }) => [
+    { id: 'rename', label: 'Rename', icon: Pencil, shortcut: '↵',
+      onSelect: () => rename(node) },
+    { id: 'copy',   label: 'Copy',   icon: Copy,   shortcut: '⌘C',
+      onSelect: () => copy(node) },
+    'separator',
+    { id: 'delete', label: 'Delete', icon: Trash2, shortcut: '⌫',
+      destructive: true,
+      onSelect: () => del(node, { folder: isFolder }) },
+  ]}
+/>
+```
+
+Return `null` / `undefined` / `[]` from the resolver to skip the menu for a
+specific row (e.g. read-only system entries).
+
+**Full control — `renderContextMenu`.** Drop down when you need submenus,
+checkbox / radio items, custom JSX, or want to compose with non-default
+ContextMenu primitives. `renderContextMenu` wins if both props are set.
+
+```tsx
+import {
+  ContextMenu, ContextMenuTrigger, ContextMenuContent,
+  ContextMenuSub, ContextMenuSubTrigger, ContextMenuSubContent,
+  ContextMenuCheckboxItem,
+} from '@djangocfg/ui-core/components';
+
+<TreeRoot<FsNode>
+  data={data}
+  getItemName={(n) => n.data.name}
+  renderContextMenu={({ node }, trigger) => (
+    <ContextMenu>
+      <ContextMenuTrigger asChild>{trigger}</ContextMenuTrigger>
+      <ContextMenuContent>
+        <ContextMenuCheckboxItem checked={isPinned(node.id)}
+          onCheckedChange={(v) => togglePin(node.id, v)}>
+          Pin to top
+        </ContextMenuCheckboxItem>
+        <ContextMenuSub>
+          <ContextMenuSubTrigger>Open with…</ContextMenuSubTrigger>
+          <ContextMenuSubContent>{/* editors */}</ContextMenuSubContent>
+        </ContextMenuSub>
+      </ContextMenuContent>
+    </ContextMenu>
+  )}
+/>
+```
+
 ## VSCode-style file icons
 
 Tree is generic over `T` — it has no opinion on whether nodes are files. For a

package/src/tools/{Tree → data/Tree}/TreeRoot.tsx

@@ -1,7 +1,15 @@
 'use client';
 
-import { useCallback, useEffect, useRef } from 'react';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
 import { cn } from '@djangocfg/ui-core/lib';
+import {
+  ContextMenu,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuSeparator,
+  ContextMenuShortcut,
+  ContextMenuTrigger,
+} from '@djangocfg/ui-core/components';
 
 import { TreeProvider, useTreeContext } from './context/TreeContext';
 import { TreeContent, treeRowDomId } from './components/TreeContent';
@@ -9,7 +17,53 @@ import { TreeSearchInput } from './components/TreeSearchInput';
 import { appearanceToStyle } from './data/appearance';
 import { useTreeKeyboard } from './hooks/useTreeKeyboard';
 import { useTreeTypeAhead } from './hooks/useTreeTypeAhead';
-import type { TreeRootProps } from './types';
+import type {
+  TreeContextMenuActionsResolver,
+  TreeContextMenuSlot,
+  TreeRootProps,
+  TreeRowRenderProps,
+} from './types';
+
+/**
+ * Build a `renderContextMenu` slot from a declarative `actions` resolver.
+ * Used internally by `TreeRoot` when consumers pass `contextMenuActions`
+ * instead of the lower-level `renderContextMenu`.
+ */
+function actionsToRenderContextMenu<T>(
+  resolve: TreeContextMenuActionsResolver<T>,
+): TreeContextMenuSlot<T> {
+  return (rowProps: TreeRowRenderProps<T>, trigger) => {
+    const items = resolve(rowProps);
+    if (!items || items.length === 0) return trigger;
+    return (
+      <ContextMenu>
+        <ContextMenuTrigger asChild>{trigger}</ContextMenuTrigger>
+        <ContextMenuContent>
+          {items.map((item, idx) => {
+            if (item === 'separator') {
+              return <ContextMenuSeparator key={`sep-${idx}`} />;
+            }
+            const Icon = item.icon;
+            return (
+              <ContextMenuItem
+                key={item.id}
+                disabled={item.disabled}
+                variant={item.destructive ? 'destructive' : undefined}
+                onSelect={() => item.onSelect(rowProps)}
+              >
+                {Icon ? <Icon /> : null}
+                {item.label}
+                {item.shortcut ? (
+                  <ContextMenuShortcut>{item.shortcut}</ContextMenuShortcut>
+                ) : null}
+              </ContextMenuItem>
+            );
+          })}
+        </ContextMenuContent>
+      </ContextMenu>
+    );
+  };
+}
 
 /**
  * High-level entry point. Wraps Provider + (optional) search bar + content.
@@ -40,6 +94,7 @@ function TreeRoot<T>(props: TreeRootProps<T>) {
     renderLabel,
     renderActions,
     renderContextMenu,
+    contextMenuActions,
     labels,
     persistKey,
     persistSelection = false,
@@ -47,6 +102,14 @@ function TreeRoot<T>(props: TreeRootProps<T>) {
     style,
   } = props;
 
+  // Short-form actions resolver is auto-converted into a renderContextMenu
+  // slot. The lower-level slot wins if both are provided.
+  const resolvedRenderContextMenu = useMemo<TreeContextMenuSlot<T> | undefined>(() => {
+    if (renderContextMenu) return renderContextMenu;
+    if (contextMenuActions) return actionsToRenderContextMenu(contextMenuActions);
+    return undefined;
+  }, [renderContextMenu, contextMenuActions]);
+
   return (
     <TreeProvider<T>
       data={data}
@@ -67,7 +130,7 @@ function TreeRoot<T>(props: TreeRootProps<T>) {
       renderIcon={renderIcon}
       renderLabel={renderLabel}
       renderActions={renderActions}
-      renderContextMenu={renderContextMenu}
+      renderContextMenu={resolvedRenderContextMenu}
       labels={labels}
       persistKey={persistKey}
       persistSelection={persistSelection}

package/src/tools/{Tree → data/Tree}/index.tsx

@@ -96,6 +96,9 @@ export type {
   TreeRowRenderProps,
   TreeRowSlot,
   TreeContextMenuSlot,
+  TreeContextMenuAction,
+  TreeContextMenuItem,
+  TreeContextMenuActionsResolver,
   TreeLoadChildren,
   FlatRow,
 } from './types';

package/src/tools/{Tree → data/Tree}/lazy.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { createLazyComponent, LoadingFallback } from '../../components/lazy-wrapper';
+import { createLazyComponent, LoadingFallback } from '../../../components/lazy-wrapper';
 import type { TreeRootProps } from './types';
 
 export const LazyTree = createLazyComponent<TreeRootProps<unknown>>(

package/src/tools/{Tree → data/Tree}/types.ts

@@ -97,6 +97,35 @@ export type TreeContextMenuSlot<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?: React.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';
+
+export type TreeContextMenuActionsResolver<T> = (
+  props: TreeRowRenderProps<T>,
+) => TreeContextMenuItem<T>[] | null | undefined;
+
 export interface TreeRootProps<T> {
   /** Root nodes. Top-level items are rendered directly (no synthetic root). */
   data: TreeNode<T>[];
@@ -153,6 +182,13 @@ export interface TreeRootProps<T> {
   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>;

package/src/tools/{Map → dev/Map}/lazy.tsx

@@ -11,7 +11,7 @@
  */
 
 import * as React from 'react';
-import { createLazyComponent, MapLoadingFallback } from '../../components';
+import { createLazyComponent, MapLoadingFallback } from '../../../components';
 import type { MapContainerProps } from './components';
 
 // ============================================================================

package/src/tools/{MarkdownMessage → dev/MarkdownMessage}/CollapseToggle.tsx

@@ -1,6 +1,6 @@
 import React, { memo } from 'react';
 
-import { TOGGLE } from '../Chat/styles/bubbleTokens';
+import { TOGGLE } from '../../chat/styles/bubbleTokens';
 
 interface CollapseToggleProps {
   isCollapsed: boolean;

package/src/tools/{MarkdownMessage → dev/MarkdownMessage}/MarkdownMessage.tsx

@@ -11,7 +11,7 @@ import remarkGfm from 'remark-gfm';
 import remarkSmartypants from 'remark-smartypants';
 import type { Components } from 'react-markdown';
 
-import { useCollapsibleContent } from '../../hooks/useCollapsibleContent';
+import { useCollapsibleContent } from '../../../hooks/useCollapsibleContent';
 import type { MarkdownMessageProps } from './types';
 import { buildSchema, buildUrlTransform } from './sanitize';
 import { looksLikePlainProse } from './plainText';

package/src/tools/{MarkdownMessage → dev/MarkdownMessage}/components.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import type { Components } from 'react-markdown';
 import Mermaid from '../Mermaid';
-import { ANCHOR } from '../Chat/styles/bubbleTokens';
+import { ANCHOR } from '../../chat/styles/bubbleTokens';
 import { CodeBlock, CodeBlockFallback } from './CodeBlock';
 import { extractTextFromChildren } from './plainText';
 

package/src/tools/{Mermaid → dev/Mermaid}/Mermaid.client.tsx

@@ -3,8 +3,8 @@
 import React, { useRef } from 'react';
 
 import { useResolvedTheme } from '@djangocfg/ui-core/hooks';
-import { FloatingToolbar } from '../../components/FloatingToolbar';
-import { CopyAction, FullscreenAction } from '../../components/FloatingToolbar/actions';
+import { FloatingToolbar } from '../../../components/FloatingToolbar';
+import { CopyAction, FullscreenAction } from '../../../components/FloatingToolbar/actions';
 import { MermaidErrorPanel } from './components/MermaidErrorPanel';
 import { MermaidFullscreenModal } from './components/MermaidFullscreenModal';
 import { useMermaidFullscreen } from './hooks/useMermaidFullscreen';

package/src/tools/{Mermaid → dev/Mermaid}/lazy.tsx

@@ -10,7 +10,7 @@
  * import Mermaid from '@djangocfg/ui-tools/mermaid'
  */
 
-import { createLazyComponent, CardLoadingFallback } from '../../components';
+import { createLazyComponent, CardLoadingFallback } from '../../../components';
 import type { MermaidProps } from './index';
 
 // ============================================================================

package/src/tools/{OpenapiViewer → dev/OpenapiViewer}/components/DocsLayout/EndpointDoc/Responses/ResponseBody.tsx

@@ -4,7 +4,7 @@ import { useMemo } from 'react';
 
 import { CopyButton } from '@djangocfg/ui-core/components';
 
-import JsonTree from '../../../../../JsonTree';
+import JsonTree from '../../../../../../data/JsonTree';
 
 // Compact, read-only JsonTree config. Docs longread is space-constrained
 // so we ship less chrome than the interactive ``ResponsePanel`` — copy

package/src/tools/{OpenapiViewer → dev/OpenapiViewer}/components/shared/ResponsePanel/PrettyView.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import JsonTree from '../../../../JsonTree';
+import JsonTree from '../../../../../data/JsonTree';
 import PrettyCode from '../../../../PrettyCode';
 import type { DetectedContent } from './types';
 

package/src/tools/{OpenapiViewer → dev/OpenapiViewer}/lazy.tsx

@@ -11,7 +11,7 @@
  */
 
 import * as React from 'react';
-import { createLazyComponent } from '../../components';
+import { createLazyComponent } from '../../../components';
 import { PlaygroundProvider } from './context/PlaygroundContext';
 import type { ApiKey, PlaygroundConfig, SchemaSource } from './types';
 

package/src/tools/{PrettyCode → dev/PrettyCode}/PrettyCode.client.tsx

@@ -4,8 +4,8 @@ import { Highlight, Language, themes } from 'prism-react-renderer';
 import React, { useMemo, useRef } from 'react';
 
 import { useAppT } from '@djangocfg/i18n';
-import { FloatingToolbar } from '../../components/FloatingToolbar';
-import { CopyAction } from '../../components/FloatingToolbar/actions';
+import { FloatingToolbar } from '../../../components/FloatingToolbar';
+import { CopyAction } from '../../../components/FloatingToolbar/actions';
 
 // Surface palette — fixed dark regardless of host theme. Code blocks
 // follow the IDE / GitHub / ChatGPT convention: syntax highlighting

package/src/tools/{PrettyCode → dev/PrettyCode}/lazy.tsx

@@ -10,7 +10,7 @@
  * import PrettyCode from '@djangocfg/ui-tools/pretty-code'
  */
 
-import { createLazyComponent } from '../../components';
+import { createLazyComponent } from '../../../components';
 import type { Language } from 'prism-react-renderer';
 
 // ============================================================================

package/src/tools/{CodeEditor → forms/CodeEditor}/lazy.tsx

@@ -20,7 +20,7 @@
  * and only render `<LazyEditor>` lower in the tree where it's needed.
  */
 
-import { createLazyComponent, LoadingFallback } from '../../components';
+import { createLazyComponent, LoadingFallback } from '../../../components';
 import type { EditorProps, DiffEditorProps } from './types';
 
 // ============================================================================