@djangocfg/ui-tools 2.1.417 → 2.1.419

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

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

@@ -0,0 +1,105 @@
+import type { AnyExtension } from '@tiptap/core';
+import { ReactNodeViewRenderer } from '@tiptap/react';
+import StarterKit from '@tiptap/starter-kit';
+import Placeholder from '@tiptap/extension-placeholder';
+import Highlight from '@tiptap/extension-highlight';
+import TaskList from '@tiptap/extension-task-list';
+import TaskItem from '@tiptap/extension-task-item';
+import { Table } from '@tiptap/extension-table';
+import { TableRow } from '@tiptap/extension-table-row';
+import { TableHeader } from '@tiptap/extension-table-header';
+import { TableCell } from '@tiptap/extension-table-cell';
+import CodeBlockLowlight from '@tiptap/extension-code-block-lowlight';
+import { Markdown } from '@tiptap/markdown';
+import { common, createLowlight } from 'lowlight';
+import GlobalDragHandle from 'tiptap-extension-global-drag-handle';
+import { SlashExtension } from './SlashExtension';
+import { createSlashSuggestion } from './createSlashSuggestion';
+import { TaskItemView } from './TaskItemView';
+import { CustomKeymap } from './CustomKeymap';
+
+// Lowlight bundle: "common" languages cover ts/js/json/py/go/rust/etc.
+// The full language pack pulls in ~300KB more — opt-in case by case.
+const lowlight = createLowlight(common);
+
+export interface BuildExtensionsOptions {
+  placeholder: string;
+}
+
+/**
+ * Assemble the Notion-flavour TipTap extension stack.
+ *
+ * Why a single factory rather than inline `useEditor({ extensions: [...] })`:
+ *   - `useEditor` captures extensions once on first render. If we built
+ *     them inline, every parent re-render would create new instances and
+ *     React's deps array would force a teardown loop (or, with stable
+ *     deps, we'd be hiding the problem).
+ *   - All consumers want the same baseline. Splitting per-extension wires
+ *     to a builder keeps the assembly readable.
+ *
+ * StarterKit overrides:
+ *   - `codeBlock: false` — replaced by `CodeBlockLowlight` for syntax
+ *     highlighting via lowlight's `common` language pack.
+ *
+ * Markdown serialisation:
+ *   - `@tiptap/markdown` already handles starter-kit nodes + tables.
+ *   - Task lists serialise as GFM `- [x]` / `- [ ]` via the same package.
+ *   - `Highlight` round-trips as `==text==` (tiptap-markdown default).
+ */
+export function notionExtensions(opts: BuildExtensionsOptions): AnyExtension[] {
+  return [
+    StarterKit.configure({
+      heading: { levels: [1, 2, 3, 4] },
+      // Disable starter-kit's plain CodeBlock — we replace it with the
+      // lowlight variant below for syntax highlighting.
+      codeBlock: false,
+    }),
+    Placeholder.configure({
+      // Per-node placeholder: empty H1 → "Heading 1", H2 → "Heading 2",
+      // empty paragraph → the supplied placeholder ("Type / for…").
+      // Matches Notion: an empty heading is labelled with its level so the
+      // user sees structure before content; an empty body block shows the
+      // command hint. The function form is supported by tiptap-extensions
+      // Placeholder; the `node` arg is the block at the caret.
+      placeholder: ({ node }) => {
+        if (node.type.name === 'heading') {
+          const level = node.attrs.level as number | undefined;
+          return level ? `Heading ${level}` : 'Heading';
+        }
+        return opts.placeholder;
+      },
+      // includeChildren=true so placeholders also reach inside list items
+      // and quotes (otherwise an empty bullet line shows no hint).
+      includeChildren: true,
+    }),
+    Markdown,
+    Highlight.configure({ multicolor: false }),
+    TaskList,
+    // React NodeView swaps Tiptap's default `<input type="checkbox">`
+    // for our ui-core <Checkbox> — picks up macOS / token styling and
+    // tracks the editor theme automatically. See TaskItemView.tsx.
+    TaskItem.extend({
+      addNodeView() {
+        return ReactNodeViewRenderer(TaskItemView);
+      },
+    }).configure({ nested: true }),
+    Table.configure({ resizable: false }),
+    TableRow,
+    TableHeader,
+    TableCell,
+    CodeBlockLowlight.configure({ lowlight }),
+    // Drag handle for blocks. Renders a small grabber to the left of the
+    // hovered block; clicking + dragging reorders the document. Reads CSS
+    // from our styles.css (`.drag-handle`).
+    GlobalDragHandle.configure({
+      dragHandleWidth: 18,
+      // `scrollTreshold` (sic) is the option name the upstream library
+      // ships — typo and all. Spelling it correctly is silently ignored.
+      scrollTreshold: 100,
+    }),
+    SlashExtension.configure({
+      suggestion: createSlashSuggestion(),
+    }),
+    CustomKeymap,
+  ];
+}

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

@@ -0,0 +1 @@
+export * from './lazy';

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

@@ -0,0 +1,44 @@
+'use client';
+
+/**
+ * `@djangocfg/ui-tools/notion-editor` subpath entrypoint.
+ *
+ * `NotionEditor` is a TipTap WYSIWYG with the full Notion-style stack:
+ * StarterKit + Markdown + Highlight + Table + TaskList + CodeBlockLowlight
+ * + GlobalDragHandle + a custom `/` slash menu. The full bundle including
+ * lowlight's `common` language pack lands around ~350KB minified — wrap
+ * the component in React.lazy so pages that don't render the editor pay
+ * nothing.
+ *
+ * Why a hand-rolled lazy wrapper (mirrors MarkdownEditor/lazy.tsx):
+ * `createLazyComponent` returns a plain function component that does not
+ * forward `ref`, so the imperative `NotionEditorHandle` would be silently
+ * dropped. The wrapper below is a `forwardRef` so the ref reaches the
+ * underlying TipTap editor through `React.lazy`.
+ */
+
+import { Suspense, forwardRef, lazy } from 'react';
+import { LoadingFallback } from '../../../common';
+import type { NotionEditorHandle, NotionEditorProps } from './types';
+
+const NotionEditorImpl = lazy(() =>
+  import('./NotionEditor').then((m) => ({ default: m.NotionEditor })),
+);
+
+export const LazyNotionEditor = forwardRef<NotionEditorHandle, NotionEditorProps>(
+  function LazyNotionEditor(props, ref) {
+    return (
+      <Suspense fallback={<LoadingFallback minHeight={240} text="Loading editor…" />}>
+        <NotionEditorImpl {...props} ref={ref} />
+      </Suspense>
+    );
+  },
+);
+
+// `NotionEditor` is the public eager-looking name — it resolves to the
+// same lazy component so importing it from this subpath does NOT pull
+// ~350KB of TipTap + lowlight into the caller's initial bundle.
+export { LazyNotionEditor as NotionEditor };
+
+export type { NotionEditorHandle, NotionEditorProps } from './types';
+export type { SlashItem } from './slashItems';

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

@@ -0,0 +1,159 @@
+import {
+  CheckSquare,
+  Code,
+  Heading1,
+  Heading2,
+  Heading3,
+  List,
+  ListOrdered,
+  Minus,
+  Quote,
+  Table as TableIcon,
+  Text,
+  type LucideIcon,
+} from 'lucide-react';
+import type { Editor, Range } from '@tiptap/react';
+
+export interface SlashItem {
+  title: string;
+  description: string;
+  icon: LucideIcon;
+  /** Markdown shorthand hint shown right-aligned in the menu — teaches
+   *  the user that they can also type this directly (e.g. `#`, `- [ ]`). */
+  hint?: string;
+  /** Extra search aliases (besides `title`). */
+  aliases?: string[];
+  command: (ctx: { editor: Editor; range: Range }) => void;
+}
+
+/**
+ * Canonical Notion-style slash menu. Each command runs `deleteRange(range)`
+ * first so the typed `/verb` text is removed, then applies the block
+ * transformation. `focus()` keeps the caret in the editor after the
+ * popover closes.
+ */
+export const slashItems: SlashItem[] = [
+  {
+    title: 'Text',
+    description: 'Plain paragraph.',
+    icon: Text,
+    aliases: ['p', 'paragraph'],
+    command: ({ editor, range }) => {
+      editor.chain().focus().deleteRange(range).setNode('paragraph').run();
+    },
+  },
+  {
+    title: 'Heading 1',
+    description: 'Big section heading.',
+    icon: Heading1,
+    hint: '#',
+    aliases: ['h1', 'title'],
+    command: ({ editor, range }) => {
+      editor.chain().focus().deleteRange(range).setNode('heading', { level: 1 }).run();
+    },
+  },
+  {
+    title: 'Heading 2',
+    description: 'Medium section heading.',
+    icon: Heading2,
+    hint: '##',
+    aliases: ['h2', 'subtitle'],
+    command: ({ editor, range }) => {
+      editor.chain().focus().deleteRange(range).setNode('heading', { level: 2 }).run();
+    },
+  },
+  {
+    title: 'Heading 3',
+    description: 'Small section heading.',
+    icon: Heading3,
+    hint: '###',
+    aliases: ['h3'],
+    command: ({ editor, range }) => {
+      editor.chain().focus().deleteRange(range).setNode('heading', { level: 3 }).run();
+    },
+  },
+  {
+    title: 'Bullet list',
+    description: 'Simple unordered list.',
+    icon: List,
+    hint: '- ',
+    aliases: ['ul', 'unordered'],
+    command: ({ editor, range }) => {
+      editor.chain().focus().deleteRange(range).toggleBulletList().run();
+    },
+  },
+  {
+    title: 'Numbered list',
+    description: 'List with auto-numbering.',
+    icon: ListOrdered,
+    hint: '1. ',
+    aliases: ['ol', 'ordered', 'numbered'],
+    command: ({ editor, range }) => {
+      editor.chain().focus().deleteRange(range).toggleOrderedList().run();
+    },
+  },
+  {
+    title: 'To-do list',
+    description: 'Tasks with checkboxes.',
+    icon: CheckSquare,
+    hint: '- [ ]',
+    aliases: ['todo', 'task', 'checkbox', 'check'],
+    command: ({ editor, range }) => {
+      editor.chain().focus().deleteRange(range).toggleTaskList().run();
+    },
+  },
+  {
+    title: 'Quote',
+    description: 'Capture a quote.',
+    icon: Quote,
+    hint: '> ',
+    aliases: ['blockquote'],
+    command: ({ editor, range }) => {
+      editor.chain().focus().deleteRange(range).toggleBlockquote().run();
+    },
+  },
+  {
+    title: 'Code block',
+    description: 'Syntax-highlighted code.',
+    icon: Code,
+    hint: '```',
+    aliases: ['codeblock', 'pre'],
+    command: ({ editor, range }) => {
+      editor.chain().focus().deleteRange(range).toggleCodeBlock().run();
+    },
+  },
+  {
+    title: 'Divider',
+    description: 'Horizontal rule.',
+    icon: Minus,
+    hint: '---',
+    aliases: ['hr', 'rule', 'separator'],
+    command: ({ editor, range }) => {
+      editor.chain().focus().deleteRange(range).setHorizontalRule().run();
+    },
+  },
+  {
+    title: 'Table',
+    description: '3×3 starter table.',
+    icon: TableIcon,
+    aliases: ['grid'],
+    command: ({ editor, range }) => {
+      editor
+        .chain()
+        .focus()
+        .deleteRange(range)
+        .insertTable({ rows: 3, cols: 3, withHeaderRow: true })
+        .run();
+    },
+  },
+];
+
+/** Case-insensitive filter over title + aliases. */
+export function filterSlashItems(query: string): SlashItem[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return slashItems;
+  return slashItems.filter((item) => {
+    if (item.title.toLowerCase().includes(q)) return true;
+    return item.aliases?.some((a) => a.toLowerCase().includes(q)) ?? false;
+  });
+}