@djangocfg/ui-tools 2.1.416 → 2.1.418

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

@@ -0,0 +1,48 @@
+import { Extension } from '@tiptap/core';
+import { TextSelection } from '@tiptap/pm/state';
+
+/**
+ * Notion-style smart Cmd/Ctrl+A:
+ *   1st press → select the current text block
+ *   2nd press → select the whole document
+ *
+ * Default editor behaviour selects everything on first press, which is
+ * jarring in long documents where the user almost always wants "select
+ * paragraph" first. Ported from Novel (`extensions/custom-keymap.ts`).
+ */
+export const CustomKeymap = Extension.create({
+  name: 'notion-custom-keymap',
+
+  addKeyboardShortcuts() {
+    return {
+      'Mod-a': ({ editor }) => {
+        const { selection, doc } = editor.state;
+        const { $from, $to, from, to } = selection;
+
+        // Resolve the boundaries of the current text block. `start`/`end`
+        // on $from/$to give the inclusive content range of the parent
+        // textblock (a paragraph, heading, code block, list item body).
+        const blockStart = $from.start();
+        const blockEnd = $to.end();
+
+        const isWholeBlockSelected = from === blockStart && to === blockEnd;
+        // If the block is already fully selected → escalate to whole doc.
+        if (isWholeBlockSelected) {
+          editor
+            .chain()
+            .setTextSelection({ from: 0, to: doc.content.size })
+            .run();
+          return true;
+        }
+
+        editor
+          .chain()
+          .setTextSelection(
+            TextSelection.create(editor.state.doc, blockStart, blockEnd),
+          )
+          .run();
+        return true;
+      },
+    };
+  },
+});

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

@@ -0,0 +1,133 @@
+'use client';
+
+/**
+ * Cmd/Ctrl+K link prompt. Modeless dialog with a single URL input and
+ * Save/Remove/Cancel actions. Mounted as a side-channel above the editor
+ * so it survives selection collapse — without this, focusing the input
+ * would unset the selection and TipTap couldn't apply the mark.
+ *
+ * We snapshot `from`/`to` of the selection on open and re-apply it
+ * before running the link command. ProseMirror tolerates this because
+ * the dialog is rendered in a portal (Radix's `DialogPortal`) and the
+ * editor's view does not lose its `state` — only its DOM focus.
+ */
+
+import { useEffect, useRef, useState } from 'react';
+import {
+  Button,
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  Input,
+} from '@djangocfg/ui-core';
+import type { Editor } from '@tiptap/react';
+
+/** Reject `javascript:`, `data:`, `vbscript:` schemes. Plain anchors,
+ *  http(s), mailto, tel, and relative paths pass. Same allow-list TipTap
+ *  uses internally when `validate` is omitted, made explicit here. */
+function isSafeHref(value: string): boolean {
+  const trimmed = value.trim();
+  const colon = trimmed.indexOf(':');
+  if (colon === -1) return true; // relative or hash link
+  const scheme = trimmed.slice(0, colon).toLowerCase();
+  return ['http', 'https', 'mailto', 'tel', 'sms', 'ftp'].includes(scheme);
+}
+
+interface LinkDialogProps {
+  editor: Editor;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+export function LinkDialog({ editor, open, onOpenChange }: LinkDialogProps) {
+  const [href, setHref] = useState('');
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  // Remember the selection range when the dialog opened — focusing the
+  // input collapses selection in the editor; we re-apply the snapshot
+  // before running the link command.
+  const rangeRef = useRef<{ from: number; to: number } | null>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    const { from, to } = editor.state.selection;
+    rangeRef.current = { from, to };
+    const existing = editor.getAttributes('link').href as string | undefined;
+    setHref(existing ?? '');
+    // Focus is handled by Radix's `onOpenAutoFocus` below — that fires
+    // after the dialog DOM is in the document and avoids racing the
+    // built-in focus trap.
+  }, [open, editor]);
+
+  const applyLink = (value: string) => {
+    const range = rangeRef.current;
+    if (range) {
+      editor.chain().focus().setTextSelection(range).run();
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+      editor.chain().focus().unsetLink().run();
+    } else if (isSafeHref(trimmed)) {
+      editor.chain().focus().extendMarkRange('link').setLink({ href: trimmed }).run();
+    }
+    onOpenChange(false);
+  };
+
+  const removeLink = () => {
+    const range = rangeRef.current;
+    if (range) {
+      editor.chain().focus().setTextSelection(range).run();
+    }
+    editor.chain().focus().unsetLink().run();
+    onOpenChange(false);
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent
+        className="sm:max-w-md"
+        // Override Radix's default auto-focus (first focusable). We want
+        // the URL input focused + selected — combining `preventDefault`
+        // here with a direct `focus()` call sequences cleanly with the
+        // dialog mount; the earlier queueMicrotask version raced Radix.
+        onOpenAutoFocus={(e) => {
+          e.preventDefault();
+          inputRef.current?.focus();
+          inputRef.current?.select();
+        }}
+      >
+        <DialogHeader>
+          <DialogTitle>Link</DialogTitle>
+        </DialogHeader>
+        <form
+          onSubmit={(e) => {
+            e.preventDefault();
+            applyLink(href);
+          }}
+        >
+          <Input
+            ref={inputRef}
+            type="url"
+            placeholder="https://example.com"
+            value={href}
+            onChange={(e) => setHref(e.target.value)}
+            autoComplete="off"
+            spellCheck={false}
+          />
+          <DialogFooter className="mt-4 gap-2 sm:gap-2">
+            {editor.isActive('link') ? (
+              <Button type="button" variant="outline" onClick={removeLink}>
+                Remove
+              </Button>
+            ) : null}
+            <Button type="button" variant="ghost" onClick={() => onOpenChange(false)}>
+              Cancel
+            </Button>
+            <Button type="submit">Save</Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}

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