@djangocfg/ui-tools 2.1.417 → 2.1.418

package/src/tools/forms/NotionEditor/NotionEditor.tsx

@@ -0,0 +1,304 @@
+'use client';
+
+/**
+ * NotionEditor — Notion-style WYSIWYG built on TipTap v3.
+ *
+ * Composition (vs `MarkdownEditor`):
+ *   - StarterKit (with H1-H4) + Placeholder + Markdown serialiser
+ *   - TaskList + TaskItem (GFM `- [ ]`)
+ *   - Table (+ Row/Header/Cell)
+ *   - CodeBlockLowlight (syntax highlight via lowlight's `common` pack)
+ *   - Highlight (`==text==`)
+ *   - GlobalDragHandle (Notion-style block grabbers)
+ *   - SlashExtension (own `/` menu — see SlashList.tsx)
+ *   - BubbleMenu (floating selection toolbar)
+ *
+ * Why a separate component instead of a variant on MarkdownEditor:
+ *   - Different baseline (no mentions, no slash-as-chip extension that
+ *     the chat composer depends on).
+ *   - ~30KB more deps (tables, lowlight, drag-handle) — would punish
+ *     every chat composer mount if added to the shared editor.
+ *   - Lazy chunk boundary stays clean — Skills / chat composer keep
+ *     their slim TipTap; document-preview pulls the heavy stack.
+ */
+
+import { useEditor, EditorContent, type Editor } from '@tiptap/react';
+import { BubbleMenu } from '@tiptap/react/menus';
+import { forwardRef, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
+import {
+  Bold,
+  Italic,
+  Strikethrough,
+  Code as CodeIcon,
+  Highlighter,
+  Link as LinkIcon,
+  Underline as UnderlineIcon,
+  type LucideIcon,
+} from 'lucide-react';
+import { Kbd, Tooltip, TooltipContent, TooltipTrigger } from '@djangocfg/ui-core';
+import { useHotkey } from '@djangocfg/ui-core/hooks';
+import { notionExtensions } from './extensions';
+import { LinkDialog } from './LinkDialog';
+import type { NotionEditorHandle, NotionEditorProps } from './types';
+import './styles.css';
+
+// Same markdown helper as MarkdownEditor — TipTap v3 augments Editor with
+// `getMarkdown()` when @tiptap/markdown is registered.
+interface MarkdownManager {
+  serialize: (json: Record<string, unknown>) => string;
+}
+function getMarkdown(editor: Editor): string {
+  const withMd = editor as Editor & { getMarkdown?: () => string };
+  if (typeof withMd.getMarkdown === 'function') return withMd.getMarkdown();
+  const storage = editor.storage.markdown as { manager?: MarkdownManager } | undefined;
+  if (!storage?.manager) return editor.getText();
+  return storage.manager.serialize(editor.getJSON());
+}
+
+export const NotionEditor = forwardRef<NotionEditorHandle, NotionEditorProps>(
+  function NotionEditor(
+    {
+      value,
+      onChange,
+      placeholder = "Type '/' for commands…",
+      disabled = false,
+      autoFocus = false,
+      onSave,
+      className = '',
+      minHeight = 320,
+    },
+    ref,
+  ) {
+    const isExternalUpdate = useRef(false);
+    const [linkDialogOpen, setLinkDialogOpen] = useState(false);
+
+    // Build extensions once. Placeholder is captured by closure on first
+    // render — same constraint as MarkdownEditor; mentions / slash items
+    // don't change at runtime here.
+    const extensions = useMemo(() => notionExtensions({ placeholder }), [placeholder]);
+
+    const editor = useEditor({
+      immediatelyRender: false,
+      editable: !disabled,
+      extensions,
+      content: value,
+      contentType: 'markdown',
+      onUpdate: ({ editor }) => {
+        if (isExternalUpdate.current) return;
+        onChange(getMarkdown(editor));
+      },
+      editorProps: {
+        attributes: {
+          class: 'notion-editor-content focus:outline-none',
+          style: `min-height: ${minHeight}px`,
+        },
+      },
+    });
+
+    // Sync external value → editor without looping back into onChange.
+    useEffect(() => {
+      if (!editor) return;
+      const current = getMarkdown(editor);
+      if (current === value) return;
+      isExternalUpdate.current = true;
+      editor.commands.setContent(value, {
+        contentType: 'markdown',
+        emitUpdate: false,
+      });
+      isExternalUpdate.current = false;
+    }, [value, editor]);
+
+    useEffect(() => {
+      editor?.setEditable(!disabled);
+    }, [editor, disabled]);
+
+    // Declarative autoFocus.
+    useEffect(() => {
+      if (!autoFocus || !editor) return;
+      editor.commands.focus('end');
+    }, [autoFocus, editor]);
+
+    // Cmd/Ctrl+S → save, scoped to the editor DOM via guard.
+    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 },
+    );
+
+    // Cmd/Ctrl+K → link prompt. Same focus-scope guard so we don't
+    // collide with global command palettes higher up the tree.
+    useHotkey(
+      'mod+k',
+      () => {
+        if (!editor) return;
+        const dom = editor.view.dom;
+        const active = document.activeElement;
+        if (!active || !dom.contains(active)) return;
+        setLinkDialogOpen(true);
+      },
+      { enabled: !!editor },
+    );
+
+    useImperativeHandle(
+      ref,
+      (): NotionEditorHandle => ({
+        focus: () => {
+          editor?.commands.focus();
+        },
+        moveCursorToEnd: () => {
+          editor?.commands.focus('end');
+        },
+        getEditor: () => editor ?? null,
+      }),
+      [editor],
+    );
+
+    return (
+      <div className={`notion-editor ${disabled ? 'opacity-60' : ''} ${className}`.trim()}>
+        {editor ? (
+          <>
+            <BubbleSelectionToolbar
+              editor={editor}
+              onOpenLink={() => setLinkDialogOpen(true)}
+            />
+            <LinkDialog
+              editor={editor}
+              open={linkDialogOpen}
+              onOpenChange={setLinkDialogOpen}
+            />
+          </>
+        ) : null}
+        <EditorContent editor={editor} />
+      </div>
+    );
+  },
+);
+
+interface BubbleItem {
+  icon: LucideIcon;
+  title: string;
+  /** Keyboard shortcut to display in the tooltip. macOS-style (⌘ B). */
+  shortcut: readonly string[];
+  isActive: () => boolean;
+  run: () => void;
+}
+
+/**
+ * Floating selection toolbar. `@tiptap/extension-bubble-menu` anchors
+ * itself to the current selection; it auto-hides when the selection
+ * collapses, so we only need to declare the buttons. Tooltips show the
+ * keyboard chord — Tiptap installs the shortcuts itself (StarterKit).
+ */
+function BubbleSelectionToolbar({
+  editor,
+  onOpenLink,
+}: {
+  editor: Editor;
+  onOpenLink: () => void;
+}) {
+  const items: BubbleItem[] = [
+    {
+      icon: Bold,
+      title: 'Bold',
+      shortcut: ['⌘', 'B'],
+      isActive: () => editor.isActive('bold'),
+      run: () => editor.chain().focus().toggleBold().run(),
+    },
+    {
+      icon: Italic,
+      title: 'Italic',
+      shortcut: ['⌘', 'I'],
+      isActive: () => editor.isActive('italic'),
+      run: () => editor.chain().focus().toggleItalic().run(),
+    },
+    {
+      icon: UnderlineIcon,
+      title: 'Underline',
+      shortcut: ['⌘', 'U'],
+      isActive: () => editor.isActive('underline'),
+      run: () => editor.chain().focus().toggleUnderline().run(),
+    },
+    {
+      icon: Strikethrough,
+      title: 'Strike',
+      shortcut: ['⌘', '⇧', 'X'],
+      isActive: () => editor.isActive('strike'),
+      run: () => editor.chain().focus().toggleStrike().run(),
+    },
+    {
+      icon: CodeIcon,
+      title: 'Inline code',
+      shortcut: ['⌘', 'E'],
+      isActive: () => editor.isActive('code'),
+      run: () => editor.chain().focus().toggleCode().run(),
+    },
+    {
+      icon: Highlighter,
+      title: 'Highlight',
+      shortcut: ['⌘', '⇧', 'H'],
+      isActive: () => editor.isActive('highlight'),
+      run: () => editor.chain().focus().toggleHighlight().run(),
+    },
+    {
+      icon: LinkIcon,
+      title: 'Link',
+      shortcut: ['⌘', 'K'],
+      isActive: () => editor.isActive('link'),
+      run: onOpenLink,
+    },
+  ];
+
+  return (
+    <BubbleMenu
+      editor={editor}
+      className="notion-bubble-menu"
+      // Hide inside code blocks (Bold/Italic don't apply there) and when
+      // the selection is empty/whitespace-only. Default behaviour shows
+      // the menu on any non-empty range, which is too eager.
+      shouldShow={({ editor, from, to }) => {
+        if (from === to) return false;
+        if (editor.isActive('codeBlock')) return false;
+        const text = editor.state.doc.textBetween(from, to, ' ').trim();
+        return text.length > 0;
+      }}
+    >
+      {items.map((item) => {
+        const Icon = item.icon;
+        const active = item.isActive();
+        return (
+          <Tooltip key={item.title}>
+            <TooltipTrigger asChild>
+              <button
+                type="button"
+                aria-label={item.title}
+                aria-pressed={active}
+                onMouseDown={(e) => e.preventDefault()}
+                onClick={item.run}
+                className={`notion-bubble-btn${active ? ' notion-bubble-btn--active' : ''}`}
+              >
+                <Icon style={{ width: 14, height: 14 }} aria-hidden />
+              </button>
+            </TooltipTrigger>
+            <TooltipContent side="top" sideOffset={6} className="flex items-center gap-1.5">
+              <span>{item.title}</span>
+              <span className="flex items-center gap-0.5">
+                {item.shortcut.map((k) => (
+                  <Kbd key={k}>{k}</Kbd>
+                ))}
+              </span>
+            </TooltipContent>
+          </Tooltip>
+        );
+      })}
+    </BubbleMenu>
+  );
+}

package/src/tools/forms/NotionEditor/SlashExtension.ts

@@ -0,0 +1,32 @@
+import { Extension } from '@tiptap/core';
+import Suggestion, { type SuggestionOptions } from '@tiptap/suggestion';
+
+/**
+ * Tiptap extension that wires `@tiptap/suggestion` for the slash menu.
+ * The actual suggestion config (items / render / floating-ui popup) is
+ * passed in via options — keeps this file UI-agnostic and lets the
+ * popover live in `createSlashSuggestion.ts`.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface SlashExtensionOptions {
+  suggestion: Omit<SuggestionOptions<any>, 'editor'>;
+}
+
+export const SlashExtension = Extension.create<SlashExtensionOptions>({
+  name: 'notion-slash-command',
+
+  addOptions() {
+    return {
+      suggestion: { char: '/' } as Omit<SuggestionOptions<unknown>, 'editor'>,
+    };
+  },
+
+  addProseMirrorPlugins() {
+    return [
+      Suggestion({
+        editor: this.editor,
+        ...this.options.suggestion,
+      }),
+    ];
+  },
+});

package/src/tools/forms/NotionEditor/SlashList.tsx

@@ -0,0 +1,136 @@
+'use client';
+
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from 'react';
+import type { SlashItem } from './slashItems';
+
+export interface SlashListRef {
+  /** Forwarded from `@tiptap/suggestion.render().onKeyDown`, which fires
+   *  the underlying native `KeyboardEvent` — typing this as React's
+   *  synthetic event would be a lie. */
+  onKeyDown: (event: KeyboardEvent) => boolean;
+}
+
+interface SlashListProps {
+  items: SlashItem[];
+  command: (item: SlashItem) => void;
+}
+
+const LISTBOX_ID = 'notion-slash-menu';
+
+/**
+ * Slash-command popover content. Mirrors the MentionList pattern —
+ * Arrow keys / Enter / Tab keyboard navigation, mouse hover preview,
+ * auto-scroll active item into view.
+ */
+export const SlashList = forwardRef<SlashListRef, SlashListProps>(
+  ({ items, command }, ref) => {
+    const [selectedIndex, setSelectedIndex] = useState(0);
+    const itemRefs = useRef<(HTMLButtonElement | null)[]>([]);
+
+    useEffect(() => setSelectedIndex(0), [items]);
+
+    useEffect(() => {
+      itemRefs.current[selectedIndex]?.scrollIntoView({ block: 'nearest' });
+    }, [selectedIndex]);
+
+    const select = useCallback(
+      (index: number) => {
+        const item = items[index];
+        if (item) command(item);
+      },
+      [items, command],
+    );
+
+    useImperativeHandle(ref, () => ({
+      onKeyDown: (event: KeyboardEvent) => {
+        if (items.length === 0) return false;
+        if (event.key === 'ArrowUp') {
+          setSelectedIndex((i) => (i + items.length - 1) % items.length);
+          return true;
+        }
+        if (event.key === 'ArrowDown') {
+          setSelectedIndex((i) => (i + 1) % items.length);
+          return true;
+        }
+        if (event.key === 'Enter' || event.key === 'Tab') {
+          select(selectedIndex);
+          return true;
+        }
+        return false;
+      },
+    }));
+
+    // Empty state — render a "no matches" pill instead of vanishing so
+    // the user gets feedback that the popover is alive (not a bug).
+    if (items.length === 0) {
+      return (
+        <div
+          id={LISTBOX_ID}
+          role="listbox"
+          aria-label="Slash commands"
+          className="notion-slash-list"
+        >
+          <div className="notion-slash-empty">No matching blocks</div>
+        </div>
+      );
+    }
+
+    const activeId = `${LISTBOX_ID}-${selectedIndex}`;
+
+    return (
+      <div
+        id={LISTBOX_ID}
+        role="listbox"
+        aria-label="Slash commands"
+        aria-activedescendant={activeId}
+        className="notion-slash-list"
+      >
+        {items.map((item, i) => {
+          const Icon = item.icon;
+          const isActive = i === selectedIndex;
+          return (
+            <button
+              key={item.title}
+              id={`${LISTBOX_ID}-${i}`}
+              ref={(el) => {
+                itemRefs.current[i] = el;
+              }}
+              type="button"
+              role="option"
+              aria-selected={isActive}
+              onMouseEnter={() => setSelectedIndex(i)}
+              onClick={() => select(i)}
+              // Prevent the click from blurring the editor — without this,
+              // ProseMirror loses its selection before the slash command
+              // can resolve the range.
+              onMouseDown={(e) => e.preventDefault()}
+              className={`notion-slash-item${isActive ? ' notion-slash-item--active' : ''}`}
+            >
+              <span className="notion-slash-icon">
+                <Icon style={{ width: 16, height: 16 }} aria-hidden />
+              </span>
+              <span className="notion-slash-meta">
+                <span className="notion-slash-title">{item.title}</span>
+                <span className="notion-slash-desc">{item.description}</span>
+              </span>
+              {item.hint ? (
+                <span className="notion-slash-hint" aria-hidden>
+                  {item.hint}
+                </span>
+              ) : null}
+            </button>
+          );
+        })}
+      </div>
+    );
+  },
+);
+
+SlashList.displayName = 'SlashList';

package/src/tools/forms/NotionEditor/TaskItemView.tsx

@@ -0,0 +1,41 @@
+'use client';
+
+/**
+ * React NodeView for `taskItem`. The default Tiptap renderer mints a
+ * raw `<input type="checkbox">`; we swap it for our ui-core `<Checkbox>`
+ * so task lists pick up the macOS / app token styling (radius, ring,
+ * focus state) and stay theme-aware.
+ *
+ * Wired via `TaskItem.extend({ addNodeView: () => ReactNodeViewRenderer(TaskItemView) })`
+ * — TaskItem.attributes already expose `checked` and `editor.commands`
+ * persists the change back into ProseMirror state. We only render the UI.
+ */
+
+import { NodeViewContent, NodeViewWrapper, type NodeViewProps } from '@tiptap/react';
+import { Checkbox } from '@djangocfg/ui-core';
+
+export function TaskItemView({ node, updateAttributes, editor }: NodeViewProps) {
+  const checked = node.attrs.checked === true;
+  const isEditable = editor.isEditable;
+
+  return (
+    <NodeViewWrapper
+      as="li"
+      data-type="taskList"
+      data-checked={checked || undefined}
+      className="notion-task-item"
+    >
+      <Checkbox
+        checked={checked}
+        disabled={!isEditable}
+        onCheckedChange={(value) => updateAttributes({ checked: value === true })}
+        // Stop ProseMirror from intercepting the click — without this
+        // the editor steals focus mid-toggle and the state flickers.
+        onClick={(event) => event.stopPropagation()}
+        aria-label={checked ? 'Mark as not done' : 'Mark as done'}
+        className="notion-task-checkbox"
+      />
+      <NodeViewContent as="div" className="notion-task-text" />
+    </NodeViewWrapper>
+  );
+}

package/src/tools/forms/NotionEditor/createSlashSuggestion.ts

@@ -0,0 +1,121 @@
+import { ReactRenderer } from '@tiptap/react';
+import type { SuggestionOptions } from '@tiptap/suggestion';
+import { autoUpdate, computePosition, flip, offset, shift } from '@floating-ui/dom';
+import { SlashList, type SlashListRef } from './SlashList';
+import { filterSlashItems, type SlashItem } from './slashItems';
+
+/**
+ * `@tiptap/suggestion` config for the slash menu. Mirrors the mention
+ * suggestion pattern in `MarkdownEditor/createMentionSuggestion.ts`:
+ * floating-ui positioning, virtual element backed by the caret rect,
+ * keyboard nav delegated to `SlashList` via an imperative ref.
+ *
+ * Editor never imports this directly — `notionExtensions()` consumes it.
+ */
+export function createSlashSuggestion(): Omit<SuggestionOptions<SlashItem>, 'editor'> {
+  return {
+    char: '/',
+    // Block the menu inside code blocks — `/` is valid syntax there
+    // (regex literals, paths) and a floating popover would be noise.
+    // Use `editor.isActive('codeBlock')` rather than `state.doc.resolve()`
+    // so nested cases (code block in a table cell, in a list item) all
+    // resolve correctly — `parent.type.name` only sees the immediate
+    // ancestor, which can be the cell/li instead of the code block.
+    allow: ({ editor }) => !editor.isActive('codeBlock'),
+    items: ({ query }) => filterSlashItems(query),
+    command: ({ editor, range, props }) => {
+      props.command({ editor, range });
+    },
+
+    render: () => {
+      let component: ReactRenderer<SlashListRef> | null = null;
+      let popup: HTMLDivElement | null = null;
+      let cleanupAutoUpdate: (() => void) | null = null;
+      let getReferenceRect: (() => DOMRect | null) | null = null;
+
+      const buildVirtualElement = () => ({
+        getBoundingClientRect: () => getReferenceRect?.() ?? new DOMRect(0, 0, 0, 0),
+      });
+
+      const setPopupVisible = (visible: boolean) => {
+        if (popup) popup.style.display = visible ? '' : 'none';
+      };
+
+      const updatePosition = () => {
+        if (!popup) return;
+        const virtualEl = buildVirtualElement();
+        void computePosition(virtualEl, popup, {
+          placement: 'bottom-start',
+          middleware: [
+            offset(6),
+            flip({ fallbackPlacements: ['top-start'] }),
+            shift({ padding: 8 }),
+          ],
+        }).then(({ x, y }) => {
+          if (!popup) return;
+          popup.style.transform = `translate3d(${Math.round(x)}px, ${Math.round(y)}px, 0)`;
+        });
+      };
+
+      const teardown = () => {
+        cleanupAutoUpdate?.();
+        cleanupAutoUpdate = null;
+        popup?.remove();
+        popup = null;
+        component?.destroy();
+        component = null;
+        getReferenceRect = null;
+      };
+
+      return {
+        onStart: (props) => {
+          component = new ReactRenderer(SlashList, {
+            props: {
+              items: props.items,
+              command: (item: SlashItem) => {
+                props.command(item);
+              },
+            },
+            editor: props.editor,
+          });
+
+          popup = document.createElement('div');
+          popup.style.cssText = 'position: absolute; top: 0; left: 0; z-index: 99999;';
+          popup.appendChild(component.element);
+          document.body.appendChild(popup);
+          setPopupVisible(props.items.length > 0);
+
+          getReferenceRect = () => props.clientRect?.() ?? null;
+          const virtualEl = buildVirtualElement();
+          cleanupAutoUpdate = autoUpdate(virtualEl, popup, updatePosition);
+        },
+
+        onUpdate: (props) => {
+          component?.updateProps({
+            items: props.items,
+            command: (item: SlashItem) => {
+              props.command(item);
+            },
+          });
+          setPopupVisible(props.items.length > 0);
+          getReferenceRect = () => props.clientRect?.() ?? null;
+          updatePosition();
+        },
+
+        onKeyDown: (props) => {
+          if (props.event.key === 'Escape') {
+            teardown();
+            return true;
+          }
+          // `props.event` is a native KeyboardEvent — SlashListRef types
+          // it as such, no cast needed.
+          return component?.ref?.onKeyDown(props.event) ?? false;
+        },
+
+        onExit: () => {
+          teardown();
+        },
+      };
+    },
+  };
+}