@djangocfg/widget-editor 0.1.1

package/src/notion/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/notion/extensions.ts

@@ -0,0 +1,120 @@
+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';
+import { BookmarkNode } from './BookmarkNode';
+import { MapNode } from './MapNode';
+import type { ResolveLinkPreview } from '../link-preview';
+
+// 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;
+  /**
+   * Host resolver for the `bookmark` (link-preview) node. Given a URL it
+   * returns unfurl metadata. Threaded into `BookmarkNode.options` and read by
+   * its NodeView. Default `undefined` → the card renders its own
+   * hostname/favicon fallback (same seam as chat's `config.linkPreview`).
+   */
+  resolveLinkPreview?: ResolveLinkPreview;
+}
+
+/**
+ * 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,
+    }),
+    // Bookmark (link-preview) block — paste a bare URL on an empty line and
+    // it becomes a card. The host resolver is threaded through options.
+    BookmarkNode.configure({ resolveLinkPreview: opts.resolveLinkPreview }),
+    // Map block — inserted via the `/map` slash command (see slashItems).
+    MapNode,
+    SlashExtension.configure({
+      suggestion: createSlashSuggestion(),
+    }),
+    CustomKeymap,
+  ];
+}

package/src/notion/index.ts

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

package/src/notion/lazy.tsx

@@ -0,0 +1,44 @@
+'use client';
+
+/**
+ * `@djangocfg/widget-editor/notion` 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 '@djangocfg/widget-kit/lazy';
+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/notion/notion-editor.stories.tsx

@@ -0,0 +1,293 @@
+import { useEffect, useRef, useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  NotionEditor,
+  type NotionEditorHandle,
+} from './lazy';
+import type { LinkPreviewData, ResolveLinkPreview } from '../link-preview';
+
+const SAMPLE = `# Welcome to NotionEditor
+
+A **Notion-style** WYSIWYG editor backed by *TipTap v3* with a curated extension stack.
+
+## Try these
+
+- Type \`/\` on an empty line to open the slash menu.
+- Select any text — a **bubble toolbar** appears (bold / italic / strike / code / highlight).
+- Hover a block — the drag handle (⠿) shows up on the left so you can reorder.
+
+### Lists
+
+1. Numbered lists work
+2. With auto-incrementing markers
+3. And nested items
+
+- Bullet lists too
+- With **inline formatting**
+- And \`inline code\`
+
+### Tasks
+
+- [ ] A pending task
+- [x] A completed one
+- [ ] Mix and match
+
+### Quote
+
+> Knowledge is power, but enthusiasm pulls the switch.
+> — Ivern Ball
+
+### Code
+
+\`\`\`ts
+function greet(name: string): string {
+  return \`Hello, \${name}!\`;
+}
+\`\`\`
+
+### Table
+
+| Feature       | Status   |
+| ------------- | -------- |
+| Slash menu    | ✓ ready  |
+| Bubble menu   | ✓ ready  |
+| Drag handle   | ✓ ready  |
+| Tables        | ✓ ready  |
+| Code blocks   | ✓ ready  |
+
+---
+
+The editor serialises everything back to **GitHub-Flavoured Markdown** on every change.
+`;
+
+function Host(props: {
+  initial?: string;
+  disabled?: boolean;
+  autoFocus?: boolean;
+  minHeight?: number;
+  placeholder?: string;
+  showOutput?: boolean;
+  resolveLinkPreview?: ResolveLinkPreview;
+  /** When set, seed a bookmark card for this URL once the editor mounts. */
+  seedBookmark?: string;
+}) {
+  const [value, setValue] = useState(props.initial ?? '');
+  const ref = useRef<NotionEditorHandle>(null);
+
+  // Seed a bookmark via the imperative editor command once it's ready. This
+  // demonstrates the bookmark node without relying on a real paste — the same
+  // node a bare-URL paste on an empty line produces.
+  const seed = props.seedBookmark;
+  useEffect(() => {
+    if (!seed) return;
+    let tries = 0;
+    const id = window.setInterval(() => {
+      const editor = ref.current?.getEditor();
+      tries += 1;
+      if (editor) {
+        editor.chain().focus().setBookmark(seed).run();
+        window.clearInterval(id);
+      } else if (tries > 40) {
+        window.clearInterval(id);
+      }
+    }, 50);
+    return () => window.clearInterval(id);
+  }, [seed]);
+
+  return (
+    <div className="grid w-full max-w-[1400px] grid-cols-1 gap-6 lg:grid-cols-[1fr_400px]">
+      <div className="rounded-lg border border-border bg-card p-4">
+        <NotionEditor
+          ref={ref}
+          value={value}
+          onChange={setValue}
+          disabled={props.disabled}
+          autoFocus={props.autoFocus}
+          minHeight={props.minHeight ?? 420}
+          placeholder={props.placeholder}
+          resolveLinkPreview={props.resolveLinkPreview}
+          onSave={(md) => console.log('[onSave]', md)}
+        />
+      </div>
+      {props.showOutput !== false ? (
+        <div className="rounded-lg border border-border bg-muted/30 p-3">
+          <div className="mb-2 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            Serialised markdown
+          </div>
+          <pre className="max-h-[420px] overflow-auto whitespace-pre-wrap break-words text-[12px] leading-relaxed font-mono">
+            {value || '(empty)'}
+          </pre>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+// ── A fake link-preview resolver (stands in for the host's Wails/Go or
+//    Next.js /api/unfurl fetcher), mirroring the chat LinkPreview story. ──
+const LINK_FIXTURES: Record<string, LinkPreviewData> = {
+  'https://github.com/wailsapp/wails': {
+    url: 'https://github.com/wailsapp/wails',
+    title: 'wailsapp/wails: Create beautiful applications using Go',
+    description:
+      'Build desktop applications using Go & Web Technologies. Wails bundles a ' +
+      'Go binary with a native webview front-end.',
+    image: 'https://picsum.photos/seed/wails-og/640/320',
+    favicon: 'https://www.google.com/s2/favicons?domain=github.com&sz=64',
+    siteName: 'GitHub',
+  },
+  'https://www.notion.so': {
+    url: 'https://www.notion.so',
+    title: 'Notion – The all-in-one workspace',
+    description: 'Write, plan, share. With AI built in. Notion is the connected workspace.',
+    favicon: 'https://www.google.com/s2/favicons?domain=notion.so&sz=64',
+    siteName: 'Notion',
+  },
+};
+
+/** Mock resolver — 500ms latency to show the card skeleton, then the fixture. */
+const mockResolveLinkPreview: ResolveLinkPreview = (url) =>
+  new Promise((resolve) => {
+    setTimeout(() => resolve(LINK_FIXTURES[url] ?? { url }), 500);
+  });
+
+// An initial document that already contains a `/map` block (a fenced ```map
+// JSON block). The MapNode's markdown tokenizer parses it back into a live
+// map on load — proving the round-trip.
+const MAP_DOC = `# Trip plan
+
+Drop a map anywhere with **/map** — or paste a fenced \`map\` block:
+
+\`\`\`map
+{
+  "center": { "lat": 48.8584, "lng": 2.2945 },
+  "zoom": 13,
+  "markers": [
+    { "id": "m1", "lat": 48.8584, "lng": 2.2945, "label": "Eiffel Tower" },
+    { "id": "m2", "lat": 48.8606, "lng": 2.3376, "label": "Louvre" }
+  ]
+}
+\`\`\`
+
+The map serialises back to the same fenced block on every change.
+`;
+
+const meta = {
+  title: 'Widgets/Editor/NotionEditor',
+  component: Host,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Notion-style WYSIWYG markdown editor built on TipTap v3. Type `/` for the slash menu, select text for the bubble menu, hover any block to reveal the drag handle on the left.',
+      },
+    },
+  },
+} satisfies Meta<typeof Host>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  name: 'Default (empty)',
+  render: () => <Host showOutput />,
+};
+
+export const WithContent: Story = {
+  name: 'With sample content',
+  render: () => <Host initial={SAMPLE} showOutput />,
+};
+
+export const AutoFocus: Story = {
+  name: 'Auto-focus on mount',
+  render: () => (
+    <Host initial="" autoFocus placeholder="Type / to open the slash menu…" showOutput />
+  ),
+};
+
+export const ReadOnly: Story = {
+  name: 'Read-only',
+  render: () => <Host initial={SAMPLE} disabled showOutput={false} />,
+};
+
+export const Compact: Story = {
+  name: 'Compact (240px min-height)',
+  render: () => <Host minHeight={240} showOutput />,
+};
+
+/**
+ * Bookmark (link-preview) block. Paste a BARE URL on an EMPTY line and it
+ * becomes a link-preview card (Notion behaviour). A labelled link or a URL
+ * pasted mid-text stays an inline link. The `resolveLinkPreview` host resolver
+ * unfurls the URL into title/description/image; the node serialises back to
+ * the raw URL (see the markdown panel). This story pre-seeds one card on
+ * mount; try pasting `https://www.notion.so` on a fresh empty line too.
+ */
+export const Bookmark: Story = {
+  name: 'Bookmark (paste a URL → card)',
+  render: () => (
+    <Host
+      seedBookmark="https://github.com/wailsapp/wails"
+      resolveLinkPreview={mockResolveLinkPreview}
+      placeholder="Paste a bare URL on an empty line…"
+      showOutput
+    />
+  ),
+};
+
+/**
+ * Map block. Insert one via the slash menu (`/map`) — it drops a live map
+ * seeded with a default center + marker. This story loads a document that
+ * already contains a fenced ```` ```map ```` JSON block, which the MapNode's
+ * markdown tokenizer parses into a live map on mount (round-trip proof).
+ */
+export const Map: Story = {
+  name: 'Map (/map → map block)',
+  render: () => <Host initial={MAP_DOC} showOutput />,
+};
+
+// A document with a DELIBERATELY BROKEN ```map block — malformed JSON (a
+// trailing comma + a non-numeric coordinate). The MapNode tokenizer parses it
+// without throwing and hands the node attrs that FAIL the schema, so the
+// NodeView renders a `<BlockError>` card. The editor stays fully alive — type
+// below the broken block to prove it. This is the "don't let a corrupted
+// payload take down the editor" guarantee.
+const BROKEN_MAP_DOC = `# Broken block recovery
+
+This map block has corrupted JSON — it renders a safe error card, **not** a crash:
+
+\`\`\`map
+{
+  "center": { "lat": "not-a-number", "lng": 2.2945 },
+  "zoom": 13,
+}
+\`\`\`
+
+The editor is still fully usable — try typing here. ✏️
+`;
+
+/**
+ * Broken payload → `<BlockError>`. A malformed ```` ```map ```` JSON (a
+ * non-numeric latitude) fails the shared Zod schema; the NodeView renders a
+ * compact "Couldn't render this map" card instead of throwing. The editor
+ * keeps working. Proves the validator safety net (phase 2).
+ */
+export const BrokenMap: Story = {
+  name: 'Broken map block → BlockError',
+  render: () => <Host initial={BROKEN_MAP_DOC} showOutput />,
+};
+
+/**
+ * Editable map — drag a pin and watch the serialised ```` ```map ```` JSON in
+ * the markdown panel update to the new coordinates. Use the on-map controls
+ * (top-left) to ADD a pin (click the map to place) or REMOVE pins, and the
+ * Layers chip (top-right) to switch the basemap — each writes back into the
+ * markdown. This is the headline interaction (phase 3).
+ */
+export const EditableMap: Story = {
+  name: 'Editable map (drag → markdown updates)',
+  render: () => <Host initial={MAP_DOC} showOutput />,
+};