@djangocfg/ui-tools 2.1.416 → 2.1.418

package/src/tools/data/Tree/context/TreeContext.tsx

@@ -10,6 +10,7 @@ import {
   DEFAULT_TREE_LABELS,
   type FlatRow,
   type TreeActivateOptions,
+  type TreeContextMenuSlot,
   type TreeItemId,
   type TreeLabels,
   type TreeNode,
@@ -22,7 +23,7 @@ import { useExpansion } from './expansion';
 import { useSelection } from './selection';
 import { useRename } from './rename';
 import { useClipboard } from './clipboard';
-import { useResolvedMenu } from './menu';
+import { useResolvedMenu, renderItemsAsContextMenu, tidyMenuItems } from './menu';
 import { useDnd, type UseDndReturn } from './dnd';
 import { usePersistSync } from './persist';
 import type { TreeContextValue } from './TreeContextValue';
@@ -282,6 +283,24 @@ export function TreeProvider<T>(props: TreeProviderProps<T>) {
     pasteFromClipboard: clipboard.pasteFromClipboard,
   });
 
+  // Translate the declarative resolver into a slot-form
+  // `renderContextMenu` so <TreeRow> doesn't need to know about it.
+  // Explicit slot prop wins (escape-hatch for full custom menus).
+  const finalRenderContextMenu = useMemo<TreeContextMenuSlot<T> | undefined>(
+    () => {
+      if (renderContextMenu) return renderContextMenu;
+      const resolve = resolvedContextMenuActions;
+      if (!resolve) return undefined;
+      return (rowProps, trigger) => {
+        const items = resolve(rowProps);
+        const cleaned = items ? tidyMenuItems(items) : null;
+        if (!cleaned || cleaned.length === 0) return trigger;
+        return renderItemsAsContextMenu(rowProps, cleaned, trigger);
+      };
+    },
+    [renderContextMenu, resolvedContextMenuActions],
+  );
+
   // ---- Final value --------------------------------------------------
 
   const value = useMemo<TreeContextValue<T>>(
@@ -333,7 +352,7 @@ export function TreeProvider<T>(props: TreeProviderProps<T>) {
       renderIcon,
       renderLabel,
       renderActions,
-      renderContextMenu,
+      renderContextMenu: finalRenderContextMenu,
 
       adapter,
       resolvedContextMenuActions,
@@ -371,7 +390,7 @@ export function TreeProvider<T>(props: TreeProviderProps<T>) {
       renderIcon,
       renderLabel,
       renderActions,
-      renderContextMenu,
+      finalRenderContextMenu,
       adapter,
       resolvedContextMenuActions,
       nodeById,

package/src/tools/data/Tree/context/menu/index.ts

@@ -8,3 +8,4 @@ export {
 export type { BuiltinActionContext } from './builtin-actions';
 export { useResolvedMenu } from './use-resolved-menu';
 export type { UseResolvedMenuOptions } from './use-resolved-menu';
+export { renderItemsAsContextMenu, tidyMenuItems } from './render';

package/src/tools/data/Tree/context/menu/render.tsx

@@ -0,0 +1,75 @@
+'use client';
+
+import {
+  ContextMenu,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuSeparator,
+  ContextMenuShortcut,
+  ContextMenuTrigger,
+} from '@djangocfg/ui-core/components';
+
+import type {
+  TreeContextMenuItem,
+  TreeRowRenderProps,
+} from '../../types';
+
+/**
+ * Render an array of declarative menu items as a themed `<ContextMenu>`
+ * wrapped around the supplied trigger element. Pure presentational layer
+ * — the caller resolves and merges items.
+ */
+export function renderItemsAsContextMenu<T>(
+  rowProps: TreeRowRenderProps<T>,
+  items: TreeContextMenuItem<T>[],
+  trigger: React.ReactNode,
+): React.ReactNode {
+  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>
+  );
+}
+
+/**
+ * Drop trailing / leading / duplicate separators so a merged menu never
+ * shows a separator next to a section header or another separator.
+ */
+export function tidyMenuItems<T>(
+  items: TreeContextMenuItem<T>[],
+): TreeContextMenuItem<T>[] {
+  const out: TreeContextMenuItem<T>[] = [];
+  for (const it of items) {
+    if (it === 'separator') {
+      if (out.length === 0) continue;
+      if (out[out.length - 1] === 'separator') continue;
+      out.push(it);
+    } else {
+      out.push(it);
+    }
+  }
+  while (out.length > 0 && out[out.length - 1] === 'separator') out.pop();
+  return out;
+}

package/src/tools/data/Tree/context/menu/use-resolved-menu.ts

@@ -7,16 +7,30 @@ import type {
   TreeAdapter,
   TreeBuiltinAction,
   TreeContextMenuActionsResolver,
+  TreeContextMenuItem,
   TreeItemId,
   TreeLabels,
   TreeMovePosition,
   TreeNode,
+  TreeRowRenderProps,
 } from '../../types';
+
+export type { TreeContextMenuActionsResolver };
 import {
   buildDefaultMenuItems,
   type BuiltinActionContext,
 } from './builtin-actions';
 
+/**
+ * Internal row-driven resolver — same shape as
+ * `TreeContextMenuActionsResolver` but takes a plain `TreeRowRenderProps`
+ * instead of the context-with-selection. The provider injects
+ * `selectedNodes` itself.
+ */
+export type ResolvedMenuResolver<T> = (
+  row: TreeRowRenderProps<T>,
+) => TreeContextMenuItem<T>[] | null | undefined;
+
 export interface UseResolvedMenuOptions<T> {
   adapter?: TreeAdapter<T>;
   contextMenuActions?: TreeContextMenuActionsResolver<T>;
@@ -50,7 +64,7 @@ export interface UseResolvedMenuOptions<T> {
  */
 export function useResolvedMenu<T>(
   opts: UseResolvedMenuOptions<T>,
-): TreeContextMenuActionsResolver<T> | undefined {
+): ResolvedMenuResolver<T> | undefined {
   const {
     adapter,
     contextMenuActions,
@@ -67,7 +81,7 @@ export function useResolvedMenu<T>(
     pasteFromClipboard,
   } = opts;
 
-  return useMemo<TreeContextMenuActionsResolver<T> | undefined>(() => {
+  return useMemo<ResolvedMenuResolver<T> | undefined>(() => {
     if (!adapter && !contextMenuActions) return undefined;
 
     return (rowProps) => {

package/src/tools/data/Tree/index.tsx

@@ -105,6 +105,7 @@ export type {
 
 export { DEFAULT_TREE_LABELS } from './types';
 export type {
+  TreeActionsHandle,
   TreeRootProps,
   TreeNode,
   TreeItemId,

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

@@ -24,4 +24,4 @@ export type {
   TreeAdapter,
   TreeBuiltinAction,
 } from './adapter';
-export type { TreeRootProps } from './root-props';
+export type { TreeRootProps, TreeActionsHandle } from './root-props';

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

@@ -137,6 +137,22 @@ export interface TreeRootProps<T> {
    */
   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/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/CodeEditor/components/Editor.tsx

@@ -46,6 +46,8 @@ export const Editor = forwardRef<EditorRef, EditorProps>(function Editor(
     autoHeight = false,
     minHeight = 100,
     maxHeight = 600,
+    autoFocus = false,
+    onSave,
   },
   ref
 ) {
@@ -67,9 +69,11 @@ export const Editor = forwardRef<EditorRef, EditorProps>(function Editor(
   // without going stale when the parent passes new function identities.
   const onChangeRef = useRef(onChange);
   const onMountRef = useRef(onMount);
+  const onSaveRef = useRef(onSave);
   useEffect(() => {
     onChangeRef.current = onChange;
     onMountRef.current = onMount;
+    onSaveRef.current = onSave;
   });
 
   // Expose editor methods via ref
@@ -126,6 +130,21 @@ export const Editor = forwardRef<EditorRef, EditorProps>(function Editor(
       updateContentHeight(editor);
     }
 
+    // Cmd/Ctrl+S → save. Registered as a Monaco command so it wins over
+    // the browser's "save page" default whenever the editor has focus.
+    // Read through the ref so swapping handlers does not need to rebuild.
+    editor.addCommand(monaco.KeyMod.CtrlCmd | monaco.KeyCode.KeyS, () => {
+      onSaveRef.current?.(editor.getValue());
+    });
+
+    // autoFocus on first mount — Monaco refuses focus during layout
+    // measurement otherwise.
+    if (autoFocus) {
+      // queueMicrotask: defer past Monaco's own post-create layout so the
+      // focus call lands on a fully laid-out editor.
+      queueMicrotask(() => editorRef.current?.focus());
+    }
+
     // Call onMount callback
     onMountRef.current?.(editor);
 

package/src/tools/forms/CodeEditor/types/index.ts

@@ -61,6 +61,13 @@ export interface EditorProps {
   minHeight?: number;
   /** Max height in px when autoHeight is enabled (default: 600) */
   maxHeight?: number;
+  /** Focus the editor once Monaco mounts. Pair with `key={path}` upstream
+   *  for per-file focus reset. */
+  autoFocus?: boolean;
+  /** Bound to Cmd/Ctrl+S inside the editor via Monaco's command palette.
+   *  Receives the current value. The browser default is suppressed by
+   *  Monaco when a command is registered for that chord. */
+  onSave?: (value: string) => void;
 }
 
 export interface DiffEditorProps {

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

@@ -7,6 +7,7 @@ import Mention from '@tiptap/extension-mention';
 import { Markdown } from '@tiptap/markdown';
 import type { AnyExtension } from '@tiptap/core';
 import { forwardRef, useEffect, useImperativeHandle, useMemo, useRef } from 'react';
+import { useHotkey } from '@djangocfg/ui-core/hooks';
 import {
   Bold, Italic, Strikethrough, Heading1, Heading2, Heading3,
   List, ListOrdered, Quote, Minus, Code, type LucideIcon,
@@ -125,6 +126,17 @@ export interface MarkdownEditorProps {
    * empty draft".
    */
   onSubmit?: () => boolean | void;
+  /**
+   * Focus the editor on mount. Pair with `key={file}` upstream when the
+   *  host wants a fresh focus per file change (inspector / editor tab).
+   */
+  autoFocus?: boolean;
+  /**
+   * Called when the user presses Cmd/Ctrl+S inside the editor. Receives
+   * the current markdown. The browser's "save page" default is suppressed
+   *  only when this handler is supplied — otherwise Cmd+S falls through.
+   */
+  onSave?: (markdown: string) => void;
 }
 
 /**
@@ -159,6 +171,8 @@ export const MarkdownEditor = forwardRef<MarkdownEditorHandle, MarkdownEditorPro
     slashCommands,
     onMentionIdsChange,
     onSubmit,
+    autoFocus = false,
+    onSave,
   },
   ref,
 ) {
@@ -380,6 +394,32 @@ export const MarkdownEditor = forwardRef<MarkdownEditorHandle, MarkdownEditorPro
     editor?.setEditable(!disabled);
   }, [editor, disabled]);
 
+  // Declarative autoFocus — runs once the editor instance exists. Hosts
+  // that want per-file focus reset should pair this with `key={path}`.
+  useEffect(() => {
+    if (!autoFocus || !editor) return;
+    editor.commands.focus('end');
+  }, [autoFocus, editor]);
+
+  // Cmd/Ctrl+S → save. Uses the shared `useHotkey` (inInput=true by
+  // default for modifier combos). Guarded to fire only when focus is
+  // inside this editor's ProseMirror DOM, so multiple sibling editors
+  // don't all fire on one chord.
+  const onSaveRef = useRef(onSave);
+  onSaveRef.current = onSave;
+  useHotkey(
+    'mod+s',
+    () => {
+      const h = onSaveRef.current;
+      if (!h || !editor) return;
+      const dom = editor.view.dom;
+      const active = document.activeElement;
+      if (!active || !dom.contains(active)) return;
+      h(getMarkdown(editor));
+    },
+    { enabled: !!editor && !!onSave },
+  );
+
   // Imperative API for hosts that drive the editor without owning a
   // TipTap ref directly — chat composer registration, voice slot,
   // focus-on-stream-end.

package/src/tools/forms/MarkdownEditor/styles.css

@@ -2,49 +2,88 @@
   outline: none;
 }
 
-/* Inherit semantic foreground so the editor renders correctly in both
-   light + dark themes (and under any active preset). Without this the
-   browser falls back to UA black on a token-driven background. */
+/* ─────────────────────────────────────────────────────────────────────
+ * Typography — Notion-inspired: comfy line-height, generous heading
+ * scale, restrained spacing. Calibrated so the chat composer (compact,
+ * single-paragraph) and the document-preview editor (long-form, with
+ * many headings) both feel right without a variant prop.
+ *
+ * Inherit semantic foreground so the editor renders correctly in both
+ * light + dark themes (and under any active preset).
+ * ───────────────────────────────────────────────────────────────────── */
 .markdown-editor .tiptap,
 .markdown-editor .ProseMirror {
   color: var(--color-foreground, var(--foreground));
+  font-family:
+    -apple-system, BlinkMacSystemFont, "SF Pro Text", "Segoe UI", Roboto,
+    "Helvetica Neue", Arial, sans-serif;
+  font-size: 15px;
+  line-height: 1.6;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  text-rendering: optimizeLegibility;
 }
 
 .markdown-editor .tiptap a,
 .markdown-editor .ProseMirror a {
   color: var(--color-primary, var(--primary));
   text-decoration: underline;
+  text-underline-offset: 2px;
+  text-decoration-thickness: 1px;
 }
 
+.markdown-editor .tiptap a:hover,
+.markdown-editor .ProseMirror a:hover {
+  text-decoration-thickness: 2px;
+}
+
+/* Headings — Notion scale. Top-padding > bottom so a heading sits
+ * visually grouped with the paragraph below it. */
 .markdown-editor .tiptap h1 {
-  font-size: 1.5em;
+  font-size: 1.875em;
   font-weight: 700;
-  margin: 0.5em 0 0.25em;
-  line-height: 1.3;
+  line-height: 1.25;
+  margin: 1em 0 0.25em;
+  letter-spacing: -0.015em;
 }
 
 .markdown-editor .tiptap h2 {
-  font-size: 1.25em;
+  font-size: 1.5em;
   font-weight: 600;
-  margin: 0.5em 0 0.25em;
   line-height: 1.3;
+  margin: 0.9em 0 0.25em;
+  letter-spacing: -0.01em;
 }
 
 .markdown-editor .tiptap h3 {
+  font-size: 1.25em;
+  font-weight: 600;
+  line-height: 1.35;
+  margin: 0.8em 0 0.2em;
+}
+
+.markdown-editor .tiptap h4 {
   font-size: 1.1em;
   font-weight: 600;
-  margin: 0.4em 0 0.2em;
-  line-height: 1.3;
+  line-height: 1.4;
+  margin: 0.7em 0 0.2em;
+}
+
+/* First heading at the very top of the document has no leading air —
+ * Notion convention. */
+.markdown-editor .tiptap > :is(h1, h2, h3, h4):first-child {
+  margin-top: 0;
 }
 
 .markdown-editor .tiptap p {
   margin: 0.25em 0;
 }
 
+/* Lists — Notion uses tighter row spacing than browser default. */
 .markdown-editor .tiptap ul,
 .markdown-editor .tiptap ol {
   padding-left: 1.5em;
-  margin: 0.25em 0;
+  margin: 0.35em 0;
 }
 
 .markdown-editor .tiptap ul {
@@ -56,29 +95,138 @@
 }
 
 .markdown-editor .tiptap li {
-  margin: 0.1em 0;
+  margin: 0.15em 0;
+}
+
+.markdown-editor .tiptap li > p {
+  margin: 0;
+}
+
+/* Nested lists get a subtler marker. */
+.markdown-editor .tiptap ul ul {
+  list-style: circle;
+}
+.markdown-editor .tiptap ul ul ul {
+  list-style: square;
+}
+
+/* Task list (GFM `- [ ] item`). StarterKit ships TaskList extension. */
+.markdown-editor .tiptap ul[data-type="taskList"] {
+  list-style: none;
+  padding-left: 0.25em;
+}
+
+.markdown-editor .tiptap ul[data-type="taskList"] li {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.5em;
+}
+
+.markdown-editor .tiptap ul[data-type="taskList"] li > label {
+  flex-shrink: 0;
+  margin-top: 0.3em;
+  user-select: none;
+}
+
+.markdown-editor .tiptap ul[data-type="taskList"] li > div {
+  flex: 1;
+  min-width: 0;
+}
+
+.markdown-editor .tiptap ul[data-type="taskList"] li[data-checked="true"] > div {
+  opacity: 0.55;
+  text-decoration: line-through;
 }
 
+/* Blockquote — Notion uses a chunky left bar without italic. */
 .markdown-editor .tiptap blockquote {
   border-left: 3px solid var(--color-border, var(--border));
-  padding-left: 1em;
-  margin: 0.5em 0;
-  opacity: 0.8;
+  padding: 0.2em 0 0.2em 1em;
+  margin: 0.6em 0;
+  color: color-mix(in oklab, var(--color-foreground, var(--foreground)) 80%, transparent);
+}
+
+.markdown-editor .tiptap blockquote > :first-child {
+  margin-top: 0;
+}
+.markdown-editor .tiptap blockquote > :last-child {
+  margin-bottom: 0;
 }
 
+/* Divider — full-width thin rule with breathing room. */
 .markdown-editor .tiptap hr {
   border: none;
   border-top: 1px solid var(--color-border, var(--border));
-  margin: 0.75em 0;
+  margin: 1.5em 0;
 }
 
+/* Inline code — monospace pill, restrained tint. */
 .markdown-editor .tiptap code {
+  background: color-mix(in oklab, var(--color-muted, var(--muted)) 70%, transparent);
+  color: var(--color-foreground, var(--foreground));
+  padding: 0.15em 0.35em;
+  border-radius: 4px;
+  font-size: 0.875em;
+  font-family:
+    "SF Mono", ui-monospace, "JetBrains Mono", "Fira Code", Menlo, Consolas,
+    monospace;
+  border: 1px solid color-mix(in oklab, var(--color-border, var(--border)) 60%, transparent);
+}
+
+/* Code block — darker surface so it stands apart from inline code. */
+.markdown-editor .tiptap pre {
   background: var(--color-muted, var(--muted));
-  color: var(--color-muted-foreground, var(--muted-foreground));
-  padding: 0.15em 0.3em;
-  border-radius: 0.25em;
-  font-size: 0.9em;
-  font-family: monospace;
+  color: var(--color-foreground, var(--foreground));
+  padding: 0.9em 1em;
+  border-radius: 6px;
+  margin: 0.75em 0;
+  font-family:
+    "SF Mono", ui-monospace, "JetBrains Mono", "Fira Code", Menlo, Consolas,
+    monospace;
+  font-size: 0.875em;
+  line-height: 1.55;
+  overflow-x: auto;
+  border: 1px solid color-mix(in oklab, var(--color-border, var(--border)) 50%, transparent);
+}
+
+.markdown-editor .tiptap pre code {
+  background: transparent;
+  border: none;
+  padding: 0;
+  border-radius: 0;
+  font-size: inherit;
+  color: inherit;
+}
+
+/* Tables — borderless, subtle row separators (Notion-flavour). */
+.markdown-editor .tiptap table {
+  border-collapse: collapse;
+  width: 100%;
+  margin: 0.75em 0;
+  font-size: 0.95em;
+  table-layout: fixed;
+}
+
+.markdown-editor .tiptap th,
+.markdown-editor .tiptap td {
+  border: 1px solid var(--color-border, var(--border));
+  padding: 0.45em 0.75em;
+  vertical-align: top;
+  text-align: left;
+  min-width: 4ch;
+}
+
+.markdown-editor .tiptap th {
+  background: color-mix(in oklab, var(--color-muted, var(--muted)) 60%, transparent);
+  font-weight: 600;
+}
+
+/* Images — rounded, never overflow. */
+.markdown-editor .tiptap img {
+  max-width: 100%;
+  height: auto;
+  border-radius: 6px;
+  margin: 0.5em 0;
 }
 
 .markdown-editor .tiptap strong {
@@ -93,6 +241,11 @@
   text-decoration: line-through;
 }
 
+/* Selection highlight — semantic ring colour, not browser-blue. */
+.markdown-editor .tiptap ::selection {
+  background: color-mix(in oklab, var(--color-primary, var(--primary)) 25%, transparent);
+}
+
 .markdown-editor .tiptap p.is-editor-empty:first-child::before {
   content: attr(data-placeholder);
   float: left;