@djangocfg/widget-editor 0.1.1

package/src/notion/NotionEditor.tsx

@@ -0,0 +1,309 @@
+'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,
+      resolveLinkPreview,
+    },
+    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. The link-preview resolver is likewise
+    // captured on first build; pass a stable reference (it's a host method).
+    const extensions = useMemo(
+      () => notionExtensions({ placeholder, resolveLinkPreview }),
+      [placeholder, resolveLinkPreview],
+    );
+
+    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/notion/README.md

@@ -0,0 +1,158 @@
+# 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, the floating
+menus (slash / bubble / drag handle) users expect from a "document"
+editor, **and serializable block nodes** (a link-preview *bookmark*
+card and an interactive *map* block) that round-trip through markdown.
+
+```tsx
+import { NotionEditor } from '@djangocfg/ui-tools/notion-editor';
+
+<NotionEditor
+  value={markdown}
+  onChange={setMarkdown}
+  onSave={(md) => writeFile(md)}
+  autoFocus
+  placeholder="Type '/' for commands…"
+  resolveLinkPreview={unfurl}   // optional — powers bookmark cards
+/>
+```
+
+> **Bundle.** The full stack (lowlight common pack + tables + drag
+> handle, plus the lazy MapLibre chunk when a map block mounts) lands
+> around ~350 KB minified. `@djangocfg/ui-tools/notion-editor` is the
+> **lazy** entry (`lazy.tsx`) — pages that never render the editor pay
+> nothing. All of it is `'use client'`.
+
+## 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`   |
+| Bookmark cards / embedded map blocks    | `NotionEditor`   |
+
+The two coexist intentionally — `NotionEditor` is heavier; don't mount
+it inside a chat composer just to get features the user will never use.
+
+## Props
+
+`NotionEditorProps` (see `types.ts`):
+
+| Prop                 | Type                       | Default              | Notes |
+| -------------------- | -------------------------- | -------------------- | ----- |
+| `value`              | `string`                   | —                    | Markdown source (required). |
+| `onChange`           | `(md: string) => void`     | —                    | Fired on every keystroke with freshly-serialised markdown (required). |
+| `placeholder`        | `string`                   | `"Type '/' for commands…"` | Ghost text on an empty paragraph. |
+| `disabled`           | `boolean`                  | `false`              | Read-only renderer (also makes map blocks static). |
+| `autoFocus`          | `boolean`                  | `false`              | Focus on mount. Pair with `key={path}` upstream for fresh focus per file. |
+| `onSave`             | `(md: string) => void`     | —                    | Bound to Cmd/Ctrl+S, scoped to the editor DOM. |
+| `className`          | `string`                   | `''`                 | Extra class on the outer wrapper. |
+| `minHeight`          | `number`                   | `320`                | Min height of the editor surface (px). |
+| `resolveLinkPreview` | `ResolveLinkPreview`       | `undefined`          | **Host URL-unfurl resolver** threaded into the bookmark node. `undefined` → cards render a hostname/favicon fallback. See [nodes.md](./@docs/nodes.md#bookmark-block). |
+
+`resolveLinkPreview` is captured on first build (memoised on
+`[placeholder, resolveLinkPreview]`) — pass a **stable reference** (a
+host method), not a new closure per render.
+
+### 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.
+
+## Features at a glance
+
+- **Slash menu (`/`)** — 12 commands: Text, H1-H3, Bullet/Numbered/Todo
+  lists, Quote, Code block, Divider, Table, and **Map**. Filtering by
+  title + aliases; each item shows its markdown shorthand as a hint.
+  See [slash.md](./@docs/slash.md).
+- **Block nodes** — a **bookmark** (link-preview) card from pasting a
+  bare URL on an empty line, and an interactive **map** block from
+  `/map`. Both round-trip through markdown. See [nodes.md](./@docs/nodes.md).
+- **Interactive map editing** — drag a pin, click-to-add, remove,
+  switch basemap; every edit writes back into the document via
+  `useNodeAttrs`. See [interactivity.md](./@docs/interactivity.md).
+- **Safe block rendering** — each block parses its attrs through a Zod
+  schema; a malformed payload renders `<BlockError>` instead of
+  crashing the editor. See [interactivity.md](./@docs/interactivity.md#safe-rendering).
+- **Bubble menu** — floating selection toolbar (Bold, Italic, Underline,
+  Strike, Code, Highlight, Link) with shortcut tooltips. Auto-hides in
+  code blocks and on empty selections.
+- **Cmd+K link prompt**, **drag handle**, **smart Cmd+A**,
+  **heading-aware placeholder**, **forced-dark code blocks**,
+  **task list** (ui-core `<Checkbox>`), **Cmd+S save hook**,
+  **markdown input rules**. See [editor.md](./@docs/editor.md).
+
+## Docs
+
+| Doc | Covers |
+|---|---|
+| [nodes.md](./@docs/nodes.md) | The **bookmark** + **map** block nodes — triggers, payload shapes, the `resolveLinkPreview` injection, and markdown serialisation / round-trip. |
+| [interactivity.md](./@docs/interactivity.md) | The `useNodeAttrs` write-back seam (how map edits persist) and the Zod-validator / `<BlockError>` safety net. |
+| [slash.md](./@docs/slash.md) | The `/` slash menu — the command list, filtering, and how to add a command (incl. `/map`). |
+| [editor.md](./@docs/editor.md) | Base editor config — the TipTap extension stack, keymap, task items, drag handle, link dialog, markdown round-trip table, and known limitations. |
+| [stories.md](./@docs/stories.md) | The Storybook stories list. |
+
+## 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`                   |
+| `BookmarkNode.ts` · `BookmarkView.tsx` | Bookmark (link-preview) block node + NodeView      |
+| `MapNode.ts` · `MapView.tsx` · `MapEditLayer.tsx` | Map block node, NodeView, editable layer |
+| `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     |
+
+Shared seams used by the block nodes live under `src/common/` (outside
+this folder): `common/link-preview` (the `LinkPreviewCard` +
+`ResolveLinkPreview` contract), `common/blocks` (payload types, Zod
+schemas, `<BlockError>`), and `common/tiptap` (the `useNodeAttrs`
+write-back hook).
+
+## Saving — dirty / pristine handling
+
+The editor calls `onChange` on every keystroke with the freshly
+serialised markdown; the host owns state and detects "dirty" however it
+likes. Two gotchas:
+
+1. **TipTap re-serialises markdown on mount** (trailing newline, CRLF →
+   LF). The first `onChange` after `setContent(value)` is byte-different
+   from `value` even though nobody typed. Normalise both sides before a
+   dirty comparison:
+
+   ```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.** 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. Use `key={path}` on the wrapper if you remount per
+file — that's what makes `autoFocus` fire on each file open.

package/src/notion/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/notion/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/notion/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>
+  );
+}