@djangocfg/ui-tools 2.1.417 → 2.1.419

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/README.md

@@ -0,0 +1,237 @@
+# NotionEditor
+
+Notion-style WYSIWYG markdown editor built on **TipTap v3**.
+
+Lazy-loaded sibling of [`MarkdownEditor`](../MarkdownEditor/) — same
+markdown round-trip, but with a heavier extension stack and the
+floating menus (slash / bubble / drag handle) that users expect from a
+"document" editor.
+
+```tsx
+import { NotionEditor } from '@djangocfg/ui-tools/notion-editor';
+
+<NotionEditor
+  value={markdown}
+  onChange={setMarkdown}
+  onSave={(md) => writeFile(md)}
+  autoFocus
+  placeholder="Type '/' for commands…"
+/>
+```
+
+## When to use this vs `MarkdownEditor`
+
+| Use case                                | Pick                |
+| --------------------------------------- | ------------------- |
+| Chat composer, single-paragraph input   | `MarkdownEditor`    |
+| Note / doc surface, multi-paragraph     | `NotionEditor`      |
+| `.md` file viewer with full editing     | `NotionEditor`      |
+| Slim mention dropdown, no tables/tasks  | `MarkdownEditor`    |
+| Slash menu, drag handle, tables, hljs   | `NotionEditor`      |
+
+The two coexist intentionally — `NotionEditor` is ~350 KB minified
+(lowlight common pack + tables + drag handle); `MarkdownEditor` is
+~200 KB. Don't mount NotionEditor inside a chat composer just to get
+features the user will never use.
+
+## Features
+
+- **Slash menu (`/`)** — 11 commands: Text, H1-H3, Bullet/Numbered/Todo
+  lists, Quote, Code block, Divider, Table. Each item shows its
+  markdown shorthand (`#`, `- [ ]`, etc.) as a kbd hint. Filtering by
+  title + aliases. `Esc` / click-outside close.
+- **Bubble menu** — floating selection toolbar with Bold, Italic,
+  Underline, Strike, Code, Highlight, Link. Each button has a Tooltip
+  with the keyboard shortcut. Auto-hides inside code blocks and on
+  empty selections.
+- **Cmd+K link prompt** — opens a Radix Dialog with URL input and
+  Save/Remove/Cancel. Snapshots and restores selection across the
+  dialog mount. Rejects unsafe schemes (`javascript:`, `data:`).
+- **Drag handle** — Notion-style ⠿ grip appears on the left of every
+  block on hover (powered by `tiptap-extension-global-drag-handle`).
+  The icon is rendered as a `mask-image` of `lucide`'s `GripVertical`
+  so it matches the rest of the app at the pixel level.
+- **Smart Cmd+A** — first press selects the current text block, second
+  press selects the whole document (Notion convention).
+- **Heading-aware placeholder** — empty H1/H2/H3 show "Heading 1/2/3";
+  empty paragraphs show the supplied placeholder.
+- **Forced-dark code blocks** — code blocks render on a fixed One Dark
+  Pro surface regardless of host theme. Avoids the washed-out
+  "light syntax on light page" look every editor hits.
+- **Task list with ui-core `<Checkbox>`** — `taskItem` uses a React
+  `NodeView` so the checkbox is the same component used everywhere
+  else in the app (theme-aware, focus ring, etc.). Aligned to the
+  text cap-height via `align-items: baseline`.
+- **Cmd+S save hook** — `onSave?: (md: string) => void` bound to
+  Cmd/Ctrl+S via `useHotkey`, scoped to the editor DOM so it doesn't
+  collide with global palettes higher up.
+- **autoFocus** — declarative prop. Pair with `key={path}` upstream
+  when the parent wants a fresh focus per file change.
+- **Markdown shortcuts** — StarterKit's input rules cover `#`, `>`,
+  `-`, `1.`, `` ``` ``, `---` → matching block on type.
+
+## Extension stack
+
+Built once per editor instance (see `extensions.ts`). Order matters
+for markdown serialisation — `Markdown` is registered before
+`Highlight`/`TaskList` so the latter use the markdown extension's
+node spec when serialising.
+
+- `StarterKit` — paragraph, headings 1-4, bold/italic/code/strike,
+  blockquote, ordered+unordered list, link, underline, horizontal
+  rule, history. CodeBlock is **disabled** here — replaced by
+  `CodeBlockLowlight` for syntax highlighting.
+- `Placeholder` — heading-aware ghost text.
+- `Markdown` — bidirectional serialisation via `@tiptap/markdown`.
+  Handles tables, task lists (`- [ ]`), highlight (`==text==`).
+- `Highlight` — `==text==` mark.
+- `TaskList` + `TaskItem.extend({ addNodeView: TaskItemView })`.
+- `Table` + `TableRow` + `TableHeader` + `TableCell`.
+- `CodeBlockLowlight` — uses `lowlight`'s `common` language pack
+  (~25 languages). Add more by importing them and registering on the
+  shared `lowlight` instance.
+- `GlobalDragHandle` — block grabber. **One handle per page** — see
+  the "Known limitations" section below.
+- `SlashExtension` — wraps `@tiptap/suggestion` for the `/` menu.
+- `CustomKeymap` — smart Cmd+A.
+
+## Files
+
+| File                          | Purpose                                                     |
+| ----------------------------- | ----------------------------------------------------------- |
+| `lazy.tsx`                    | Subpath entry — `React.lazy` + `forwardRef` for the handle  |
+| `NotionEditor.tsx`            | Main component + `BubbleSelectionToolbar`                   |
+| `extensions.ts`               | Assembled TipTap stack (factory `notionExtensions()`)       |
+| `types.ts`                    | `NotionEditorProps`, `NotionEditorHandle`                   |
+| `SlashExtension.ts`           | TipTap extension wrapping `@tiptap/suggestion`              |
+| `createSlashSuggestion.ts`    | Suggestion config — floating-ui popup mount/update/teardown |
+| `SlashList.tsx`               | Popover content (listbox + keyboard nav)                    |
+| `slashItems.ts`               | Command list + `filterSlashItems` helper                    |
+| `CustomKeymap.ts`             | Smart Cmd+A extension                                       |
+| `TaskItemView.tsx`            | React NodeView for `taskItem` (mounts ui-core Checkbox)     |
+| `LinkDialog.tsx`              | Cmd+K link prompt (ui-core Dialog)                          |
+| `styles.css`                  | Typography + slash/bubble menu + drag handle + lowlight     |
+
+## Imperative API
+
+```tsx
+const ref = useRef<NotionEditorHandle>(null);
+
+ref.current?.focus();             // focus the editor surface
+ref.current?.moveCursorToEnd();   // focus + caret at end
+ref.current?.getEditor();         // raw TipTap Editor (escape hatch)
+```
+
+`NotionEditorHandle` is structurally compatible with `ComposerHandle`
+from `@djangocfg/ui-tools/composer-registry` — the chat suite can
+register a NotionEditor as a composer if you ever want to swap them in
+the chat input (unusual, but allowed).
+
+## Saving — dirty / pristine handling
+
+The editor is **uncontrolled-ish**: it calls `onChange` on every
+keystroke with the freshly-serialised markdown. The host owns state
+and detects "dirty" however it likes.
+
+Two gotchas the host needs to know about:
+
+1. **TipTap re-serialises markdown on mount** (trailing newline,
+   CRLF → LF normalisation). The first `onChange` after
+   `setContent(value)` is byte-different from `value` even though
+   nobody typed. If you compare `draft !== savedContent` literally,
+   the dirty indicator lights up on every file open. **Fix in the
+   host**: normalise both sides before comparing.
+
+   ```ts
+   const norm = (s: string) => s.replace(/\r\n/g, '\n').trimEnd();
+   const isDirty = norm(draft) !== norm(saved);
+   ```
+
+2. **Cmd+S only fires when focus is inside the editor**. If the user
+   clicked outside (header, sidebar) and presses Cmd+S, this hook
+   doesn't fire. Add a window-level `useHotkey('mod+s', save)` in the
+   host as a fallback — both paths call the same save fn.
+
+See `cmdop/.../document-preview/viewers/text-viewer.tsx` for the
+canonical wiring.
+
+## Markdown round-trip
+
+| Input            | Round-trips? | Notes                              |
+| ---------------- | ------------ | ---------------------------------- |
+| Headings         | ✓            | H1-H4 only (StarterKit config)     |
+| Bold/italic/etc. | ✓            |                                    |
+| Inline code      | ✓            |                                    |
+| Code blocks      | ✓            | Language fence preserved by hljs   |
+| Bullet/ordered   | ✓            | Nested too                         |
+| Task lists       | ✓            | GFM `- [x]` / `- [ ]`              |
+| Blockquote       | ✓            |                                    |
+| Horizontal rule  | ✓            | `---`                              |
+| Tables           | ✓            | GFM tables — alignment via `:--:`  |
+| Links            | ✓            | autolinks too                      |
+| Highlight        | ✓            | `==text==` extension syntax        |
+| Images           | mostly       | Round-trip URLs, no upload yet     |
+| HTML passthrough | ✗            | Stripped on parse                  |
+| Footnotes        | ✗            | Not in StarterKit                  |
+
+## Known limitations
+
+- **One editor per page (drag handle).**
+  `tiptap-extension-global-drag-handle` mints a single DOM grabber
+  attached to `document.body`. Mounting two `NotionEditor` instances
+  on the same page (e.g. a side-by-side diff) makes them fight over
+  the handle. If you need multiple editors, render only one with
+  drag-handle support.
+
+- **Slash popup is portal'd to `document.body`.**
+  If the parent unmounts the editor mid-suggestion, the popup gets
+  cleaned up by ProseMirror's `onExit` — but a hostile race (route
+  change while menu is open) can leave an orphan div. Rare; visible
+  only via the inspector.
+
+- **No image upload pipeline (yet).**
+  `Image` extension is not registered. Pasting an image from the
+  clipboard inserts the data-URL into the document (browser default)
+  but there's no upload integration. Add `@tiptap/extension-image` +
+  a custom paste handler when you have a target storage. See Novel's
+  `plugins/upload-images.tsx` for the canonical pattern.
+
+- **Bubble menu uses `@tiptap/react/menus`'s `BubbleMenu`** (Tippy
+  under the hood). Slash menu uses `floating-ui` directly. Two
+  positioning libraries for one editor — kept this way because
+  `BubbleMenu` is opinionated about anchor invalidation and Tippy
+  handles it correctly; reimplementing on floating-ui would save
+  ~5 KB but cost a week of edge cases.
+
+## Storybook
+
+Stories live at `apps/storybook/stories/ui-tools/markdown/NotionEditor.stories.tsx`:
+
+- Default (empty editor with placeholder)
+- With sample content (every supported block + serialised output panel)
+- Auto-focus on mount
+- Read-only
+- Compact (240px min-height)
+
+Each story renders a right-side panel showing the current serialised
+markdown so you can watch the round-trip live as you type.
+
+## Wiring inside a host
+
+The canonical host is `cmdop`'s document-preview text viewer:
+
+```tsx
+// .md → NotionEditor only (it's already WYSIWYG, no Preview/Source split)
+<div className="mx-auto w-full max-w-[820px] px-6 py-6">
+  <NotionEditor
+    value={draft}
+    onChange={handleChange}
+    onSave={save}
+    autoFocus
+    minHeight={420}
+  />
+</div>
+```
+
+Use `key={path}` on the wrapper if you remount per file — that's what
+makes `autoFocus` fire on each file open.

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