@djangocfg/widget-editor 0.1.1

package/src/markdown/submitOnEnter.ts

@@ -0,0 +1,83 @@
+// SubmitOnEnter — Tiptap extension that hooks ProseMirror's keymap
+// before StarterKit's HardBreak so Enter and Cmd/Ctrl+Enter both submit
+// while Shift+Enter inserts a newline (ChatGPT / Telegram behaviour).
+//
+// Why an extension and not a wrapper `onKeyDown` handler:
+//
+//   Tiptap registers its keymaps inside the ProseMirror keymap
+//   plugin, which runs in the ProseMirror dispatch pipeline. A React
+//   `onKeyDown` / `onKeyDownCapture` on a wrapper div fires AFTER
+//   ProseMirror has already committed the HardBreak transaction in
+//   the same event tick — so calling `preventDefault()` there is too
+//   late: the user sees a hard-break flash in, the React handler
+//   then runs its preventDefault, and the next Enter submits.
+//
+//   Registering the keybinding via `addKeyboardShortcuts` puts us in
+//   the same keymap pipeline at a higher priority than StarterKit's
+//   default Enter binding, so we intercept before HardBreak runs.
+//
+// The handler also respects IME composition and the mention popover
+// (Tiptap's suggestion plugin captures Enter when its popover is
+// open — we mirror that by checking `.markdown-mention-list` in the
+// DOM; same predicate the wrapper used).
+
+import { Extension } from '@tiptap/core';
+
+export interface SubmitOnEnterOptions {
+  /** Fired when Enter is pressed without Shift, no IME composition,
+   *  and no mention popover open. Return `true` to consume the key
+   *  (default behaviour), `false` to let ProseMirror handle it (i.e.
+   *  fall back to HardBreak). */
+  onSubmit: () => boolean | void;
+}
+
+export const SubmitOnEnter = Extension.create<SubmitOnEnterOptions>({
+  name: 'submitOnEnter',
+
+  addOptions() {
+    return {
+      // Default no-op — explicit consumer must override. We never
+      // intercept Enter unless an onSubmit is wired, so leaving the
+      // extension installed with no handler is safe.
+      onSubmit: () => false,
+    };
+  },
+
+  addKeyboardShortcuts() {
+    // Shared by `Enter` and `Mod-Enter` so the two can never drift into
+    // different submit rules.
+    const submit = () => {
+      // Mention suggestion popover owns Enter while open.
+      // The suggestion plugin renders the list with this class
+      // (see createMentionSuggestion.ts).
+      if (typeof document !== 'undefined' && document.querySelector('.markdown-mention-list')) {
+        return false;
+      }
+      const result = this.options.onSubmit();
+      // Default: consume the key (true). Only let it fall through
+      // to HardBreak if onSubmit explicitly returned false.
+      return result !== false;
+    };
+
+    return {
+      Enter: submit,
+      // Cmd/Ctrl+Enter submits too. ProseMirror matches a chord EXACTLY, so the
+      // `Enter` binding above does NOT fire while a modifier is held — without
+      // this line Cmd+Enter fell through to the default and did nothing, in a
+      // rich composer only. The plain `<textarea>` path has always sent on it
+      // (`useChatComposer`: `!e.shiftKey` is true with Meta down), so the two
+      // hosts disagreed about the same keystroke depending on which one the
+      // surface happened to mount.
+      //
+      // Both keys are ONE intent — "send this" — so they share `submit` and go
+      // through the composer's single `submit()`, which is what routes to a
+      // queued follow-up mid-turn instead of a second send path.
+      'Mod-Enter': submit,
+      // Shift+Enter — always insert a newline. Tiptap's StarterKit
+      // already binds this to HardBreak; we re-bind to `false` (not
+      // handled) so the chain falls through cleanly even if other
+      // extensions try to grab Shift+Enter.
+      'Shift-Enter': () => false,
+    };
+  },
+});

package/src/markdown/types.ts

@@ -0,0 +1,50 @@
+/** Item that can be mentioned via @ trigger */
+export interface MentionItem {
+  id: string;
+  label: string;
+  description?: string;
+  thumbnail?: string;
+}
+
+/**
+ * Attributes available when rendering a mention to markdown.
+ *
+ * Same shape Tiptap stores on the `mention` node — `id` is the stable
+ * identifier the suggestion popover injected, `label` is the human text
+ * shown to the user. Either field may be empty if the upstream config
+ * never populated it; renderers should fall back accordingly.
+ */
+export interface MentionAttrs {
+  id: string;
+  label: string;
+}
+
+/**
+ * Function that converts a mention node into its markdown serialization.
+ *
+ * The returned string is what `@tiptap/markdown` writes into the markdown
+ * output of `MarkdownEditor.getMarkdown()`.
+ */
+export type MentionMarkdownRenderer = (attrs: MentionAttrs) => string;
+
+/** Mention configuration */
+export interface MentionConfig {
+  /** Trigger character (default: '@') */
+  trigger?: string;
+  /** Available items */
+  items: MentionItem[];
+  /** Max dropdown items (default: 5) */
+  maxItems?: number;
+  /**
+   * Custom serializer for mentions when `MarkdownEditor.getMarkdown()` runs.
+   *
+   * Defaults to `mentionPresets.plainAt` which yields `@<label>` (or `@<id>`
+   * when `label` is missing). Use one of `mentionPresets`, or supply your
+   * own function for full control over how mentions appear in the output
+   * markdown string.
+   *
+   * Note: this only affects the *markdown* output. `editor.getText()` and
+   * the rendered DOM still go through `renderText` (`@<label>` by default).
+   */
+  renderMarkdown?: MentionMarkdownRenderer;
+}

package/src/markdown/url/detect.ts

@@ -0,0 +1,227 @@
+/**
+ * URL detection + display helpers for the chat editor's "URL chip" node.
+ * Pure, side-effect-free, and unit-testable — no TipTap / ProseMirror /
+ * React imports live here so the same functions back the editor node and
+ * any standalone use alike.
+ *
+ * Design goal mirrors `../filePath/detect.ts`: **LOW false-positive**. We
+ * only treat a token as a URL when it carries an explicit web scheme
+ * (`http`/`https`/`ftp`/`mailto`/`file`) or a bare `www.` host — exactly
+ * the set the editor's `shouldAutoLinkUrl` whitelist already accepts, so
+ * the chip never disagrees with the autolinker. Bare file paths and dotted
+ * filenames (`manifest.md`) are intentionally NOT matched here — those are
+ * the file-path node's job.
+ */
+
+// ── Match result ──
+
+export interface UrlMatch {
+  /** Inclusive start offset into the scanned string. */
+  start: number;
+  /** Exclusive end offset into the scanned string. */
+  end: number;
+  /**
+   * The matched URL text, normalised to a navigable href (a bare `www.`
+   * host gets an `https://` prefix so the chip's anchor works). Trailing
+   * prose punctuation is trimmed.
+   */
+  href: string;
+  /** The raw matched text exactly as it appeared (no scheme added). */
+  raw: string;
+}
+
+/**
+ * Trailing sentence punctuation that, when it hangs off the END of a
+ * detected URL token, is almost certainly prose and not part of the URL —
+ * trim it. (A URL effectively never ends in these for display purposes;
+ * a real trailing `)` that balances an opening `(` is the classic edge
+ * case but rare in a chat composer and not worth the complexity.)
+ */
+const TRAILING_PUNCT = new Set([
+  '.', ',', ')', ']', '}', ';', ':', '!', '?',
+  '«', '»', '"', "'", '”', '’', '…',
+]);
+
+/**
+ * URL shapes, as a single alternation. Each alternative is whitespace-
+ * bounded by construction (`\S` runs). Order: explicit schemes first, then
+ * the bare `www.` host.
+ *
+ * - `mailto:user@host`     — mail scheme (no `//`).
+ * - `scheme://host/...`    — http/https/ftp/file with authority.
+ * - `www.host...`          — schemeless web host (we prepend https).
+ */
+const URL_RE = new RegExp(
+  [
+    String.raw`mailto:[^\s]+`,
+    String.raw`(?:https?|ftp|file):\/\/[^\s]+`,
+    String.raw`www\.[^\s/$.?#][^\s]*`,
+  ].join('|'),
+  'giu',
+);
+
+function trimTrailingPunct(raw: string): string {
+  let end = raw.length;
+  while (end > 1 && TRAILING_PUNCT.has(raw[end - 1]!)) {
+    end -= 1;
+  }
+  return raw.slice(0, end);
+}
+
+/** Normalise a raw token to a navigable href (prepend https for `www.`). */
+export function normalizeHref(raw: string): string {
+  if (/^www\./i.test(raw)) return `https://${raw}`;
+  return raw;
+}
+
+/**
+ * Find every URL in `text`. Returns matches in document order with
+ * `{ start, end, href, raw }` where `[start, end)` are offsets into the
+ * ORIGINAL string (after trailing-punctuation trimming). File paths and
+ * bare relative tokens are intentionally NOT matched.
+ */
+export function findUrls(text: string): UrlMatch[] {
+  if (!text) return [];
+
+  const out: UrlMatch[] = [];
+  URL_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+
+  while ((m = URL_RE.exec(text)) !== null) {
+    const raw = m[0];
+    const start = m.index;
+
+    if (raw.length === 0) {
+      URL_RE.lastIndex += 1;
+      continue;
+    }
+
+    // Leading-boundary guard: a real URL token starts the string or
+    // follows whitespace / an opening delimiter. Glued onto a preceding
+    // non-space char it's a substring of a larger token — reject.
+    if (start > 0) {
+      const prev = text[start - 1]!;
+      if (!/[\s([{<«"'‘“]/.test(prev)) continue;
+    }
+
+    const trimmed = trimTrailingPunct(raw);
+    if (trimmed.length < 4) continue;
+
+    out.push({
+      start,
+      end: start + trimmed.length,
+      href: normalizeHref(trimmed),
+      raw: trimmed,
+    });
+  }
+
+  return out;
+}
+
+// ── Split / label (Chrome-style domain + middle-ellipsis path) ──
+
+export interface SplitUrl {
+  /** Host without a leading `www.` (e.g. `github.com`). Empty if unparseable. */
+  domain: string;
+  /** Host for favicon lookup (with `www.` stripped). */
+  host: string;
+  /** Path + query + hash, leading `/` included (empty for a bare host). */
+  rest: string;
+  /** `mailto:` address (no scheme) when the URL is a mail link, else ''. */
+  mail: string;
+}
+
+/**
+ * Split an href into `{ domain, host, rest, mail }`. Uses the platform
+ * `URL` parser; falls back to a light regex when `URL` throws (it
+ * shouldn't for our matched shapes, but stay robust).
+ */
+export function splitUrl(href: string): SplitUrl {
+  if (/^mailto:/i.test(href)) {
+    const mail = href.slice('mailto:'.length);
+    const at = mail.lastIndexOf('@');
+    const domain = at >= 0 ? mail.slice(at + 1) : '';
+    return { domain, host: domain, rest: '', mail };
+  }
+
+  try {
+    const u = new URL(normalizeHref(href));
+    const host = u.hostname.replace(/^www\./i, '');
+    const rest = `${u.pathname === '/' ? '' : u.pathname}${u.search}${u.hash}`;
+    return { domain: host, host: u.hostname, rest, mail: '' };
+  } catch {
+    // Best-effort fallback for an unparseable token.
+    const noScheme = normalizeHref(href).replace(/^[a-z]+:\/\//i, '');
+    const slash = noScheme.indexOf('/');
+    const host = (slash >= 0 ? noScheme.slice(0, slash) : noScheme).replace(/^www\./i, '');
+    const rest = slash >= 0 ? noScheme.slice(slash) : '';
+    return { domain: host, host, rest, mail: '' };
+  }
+}
+
+const ELLIPSIS = '…';
+
+export interface UrlLabelOptions {
+  /**
+   * Approximate max characters for the WHOLE label (domain + path). The
+   * domain is always kept in full; only the path's middle collapses.
+   * Default 40.
+   */
+  maxChars?: number;
+}
+
+/**
+ * Produce a compact, Chrome-omnibox-style label for a URL: the domain is
+ * sacred (always shown in full), then the path's MIDDLE collapses to `…`
+ * while the LAST path segment (often the meaningful slug / filename) is
+ * kept.
+ *
+ * Examples (maxChars ≈ 40):
+ *   https://github.com/wailsapp/wails/blob/main/v3/README.md
+ *     → github.com/…/README.md
+ *   https://github.com/wailsapp/wails
+ *     → github.com/wailsapp/wails   (short — unchanged)
+ *   mailto:me@example.com → me@example.com
+ */
+export function truncateUrlLabel(href: string, opts: UrlLabelOptions = {}): string {
+  const maxChars = opts.maxChars ?? 40;
+  const { domain, rest, mail } = splitUrl(href);
+
+  if (mail) {
+    return mail.length <= maxChars ? mail : `${ELLIPSIS}${mail.slice(mail.length - (maxChars - 1))}`;
+  }
+
+  const full = `${domain}${rest}`;
+  if (full.length <= maxChars) return full;
+
+  // Collapse the path's middle, keeping the last segment.
+  const segments = rest.split('/').filter((s) => s.length > 0);
+  if (segments.length === 0) {
+    // Only a domain, but it's longer than maxChars — return as-is (CSS
+    // ellipsis is the safety net in the chip).
+    return domain;
+  }
+  const last = segments[segments.length - 1]!;
+
+  const candidates: string[] = [];
+  if (segments.length >= 2) {
+    candidates.push(`${domain}/${segments[0]!}/${ELLIPSIS}/${last}`);
+  }
+  candidates.push(`${domain}/${ELLIPSIS}/${last}`);
+  candidates.push(`${domain}/${ELLIPSIS}`);
+
+  for (const c of candidates) {
+    if (c.length <= maxChars) return c;
+  }
+  return `${domain}/${ELLIPSIS}/${last}`;
+}
+
+/**
+ * Favicon URL for a host via Google's S2 service. Degrades to the globe
+ * icon on error (the chip wires an `onerror` handler). Returns '' when the
+ * host is empty.
+ */
+export function faviconUrl(host: string, size = 32): string {
+  if (!host) return '';
+  return `https://www.google.com/s2/favicons?domain=${encodeURIComponent(host)}&sz=${size}`;
+}

package/src/notion/BookmarkNode.ts

@@ -0,0 +1,161 @@
+/**
+ * `BookmarkNode` — a NotionEditor block ATOM node that renders a link-preview
+ * "bookmark" card (the shared `common/link-preview/LinkPreviewCard`). It holds
+ * a single `url` attribute and renders via a React NodeView (mirrors
+ * `TaskItemView` → `ReactNodeViewRenderer`).
+ *
+ * Trigger — paste a BARE URL on an EMPTY line/block:
+ *
+ *   The `handlePaste` plugin only hijacks the paste when the clipboard is a
+ *   SINGLE bare URL AND the current block is empty (an empty paragraph). In
+ *   that case it replaces the empty block with a `bookmark` node. A URL
+ *   pasted mid-text, a labelled link, or multi-line clipboard content all
+ *   fall through to the editor's normal paste (the URL stays inline). This is
+ *   the conservative Notion rule — bookmark only on an explicit empty line.
+ *
+ * Resolver injection:
+ *
+ *   `notionExtensions({ resolveLinkPreview })` threads a host resolver into
+ *   the node's `options`. The NodeView reads it from `extension.options` and
+ *   passes it to the card, so the host (Wails/Go, a Next.js API route) unfurls
+ *   the URL exactly like chat does. Default `undefined` → the card renders its
+ *   own hostname/favicon fallback.
+ *
+ * Serialisation (markdown fidelity):
+ *
+ *   `renderMarkdown` emits the bare `url`, so `getMarkdown()` yields the raw
+ *   URL (NOT card markup) — same pattern the MarkdownEditor chip node uses.
+ *   On the next `setContent`/paste of a bare URL on an empty line the node is
+ *   re-created, so the round-trip is stable.
+ */
+
+import { Node, mergeAttributes } from '@tiptap/core';
+import { ReactNodeViewRenderer } from '@tiptap/react';
+import { Plugin, PluginKey } from '@tiptap/pm/state';
+import type { ResolveLinkPreview } from '../link-preview';
+import { BookmarkView } from './BookmarkView';
+
+export interface BookmarkNodeOptions {
+  /** Host resolver for URL unfurl. Default `undefined` → card fallback. */
+  resolveLinkPreview?: ResolveLinkPreview;
+  HTMLAttributes: Record<string, unknown>;
+}
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    bookmark: {
+      /** Insert a bookmark (link-preview) block for the given URL. */
+      setBookmark: (url: string) => ReturnType;
+    };
+  }
+}
+
+const bookmarkPasteKey = new PluginKey('notion-bookmark-paste');
+
+/** A single bare URL (http/https), nothing else on the line. */
+const BARE_URL_RE = /^https?:\/\/[^\s<>]+$/i;
+
+/** True when `text` is exactly one bare URL (no surrounding prose). */
+function isBareUrl(text: string): boolean {
+  const trimmed = text.trim();
+  if (!trimmed || /\s/.test(trimmed)) return false;
+  return BARE_URL_RE.test(trimmed);
+}
+
+export const BookmarkNode = Node.create<BookmarkNodeOptions>({
+  name: 'bookmark',
+  group: 'block',
+  atom: true,
+  draggable: true,
+  selectable: true,
+
+  addOptions() {
+    return {
+      resolveLinkPreview: undefined,
+      HTMLAttributes: {},
+    };
+  },
+
+  addAttributes() {
+    return {
+      url: {
+        default: '',
+        parseHTML: (el) => el.getAttribute('data-url') ?? '',
+        renderHTML: (attrs) => (attrs.url ? { 'data-url': attrs.url as string } : {}),
+      },
+    };
+  },
+
+  parseHTML() {
+    return [{ tag: 'div[data-type="bookmark"]' }];
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return [
+      'div',
+      mergeAttributes({ 'data-type': 'bookmark' }, this.options.HTMLAttributes, HTMLAttributes),
+    ];
+  },
+
+  addNodeView() {
+    return ReactNodeViewRenderer(BookmarkView);
+  },
+
+  addCommands() {
+    return {
+      setBookmark:
+        (url: string) =>
+        ({ commands }) =>
+          commands.insertContent({ type: this.name, attrs: { url } }),
+    };
+  },
+
+  // `@tiptap/markdown` reads this — emit the bare URL so a round-trip through
+  // `getMarkdown()` yields the literal URL, never card markup.
+  // `attrs` is optional in tiptap's `JSONContent`: a node written by hand or
+  // arriving from a paste can carry none, and the narrower annotation this had
+  // made the signature incompatible rather than making the object safer.
+  renderMarkdown(node: { attrs?: Record<string, unknown> }) {
+    return (node.attrs?.url as string) ?? '';
+  },
+
+  addProseMirrorPlugins() {
+    const type = this.type;
+
+    return [
+      new Plugin({
+        key: bookmarkPasteKey,
+        props: {
+          // Bare-URL-on-empty-line → bookmark. Conservative: only when the
+          // clipboard is a SINGLE bare URL and the current textblock is empty.
+          handlePaste: (view, event) => {
+            const text = event.clipboardData?.getData('text/plain');
+            if (!text || !isBareUrl(text)) return false;
+
+            const { state } = view;
+            const { selection } = state;
+            const { $from, empty } = selection;
+            // Only replace when the caret sits in an EMPTY textblock with a
+            // collapsed selection — i.e. the user is on a fresh empty line.
+            if (!empty) return false;
+            const parent = $from.parent;
+            if (!parent.isTextblock || parent.content.size !== 0) return false;
+
+            const url = text.trim();
+            // Replace the empty block with the bookmark node.
+            const node = type.create({ url });
+            const tr = state.tr.replaceWith(
+              $from.before(),
+              $from.after(),
+              node,
+            );
+            view.dispatch(tr.scrollIntoView());
+            return true;
+          },
+        },
+      }),
+    ];
+  },
+});
+
+export default BookmarkNode;

package/src/notion/BookmarkView.tsx

@@ -0,0 +1,45 @@
+'use client';
+
+/**
+ * React NodeView for the NotionEditor `bookmark` node. Renders the shared
+ * `LinkPreviewCard` (`appearance="full"`) inside a `NodeViewWrapper`, reading
+ * the host resolver injected via the node's `extension.options`
+ * (`resolveLinkPreview`). Mirrors `TaskItemView` — we only render the UI; the
+ * node owns the `url` attribute + markdown serialisation.
+ */
+
+import type { ReactNode } from 'react';
+import { NodeViewWrapper, type NodeViewProps } from '@tiptap/react';
+import { LinkPreviewCard } from '../link-preview';
+import { BlockError, LinkPreviewDataSchema, safeParseBlock } from '../blocks';
+import type { BookmarkNodeOptions } from './BookmarkNode';
+
+export function BookmarkView({ node, extension }: NodeViewProps) {
+  const url = (node.attrs.url as string) || '';
+  const resolver = (extension.options as BookmarkNodeOptions).resolveLinkPreview;
+
+  // An empty url is a legitimate "nothing to show yet" state (freshly inserted
+  // node) — render nothing. A NON-empty but malformed url fails the schema and
+  // shows a safe fallback instead of risking a throw downstream.
+  const validated = url ? safeParseBlock(LinkPreviewDataSchema, { url }) : null;
+
+  let content: ReactNode = null;
+  if (validated && validated.ok === true) {
+    content = <LinkPreviewCard url={validated.data.url} resolver={resolver} appearance="full" />;
+  } else if (validated && validated.ok === false) {
+    content = <BlockError label="bookmark" reason={validated.error} />;
+  }
+
+  return (
+    <NodeViewWrapper
+      data-type="bookmark"
+      className="notion-bookmark"
+      // The drag handle reorders the whole block; keep the card from stealing
+      // the drag target by marking the wrapper draggable=false (the node is
+      // already `draggable: true` at the schema level for the global handle).
+      draggable={false}
+    >
+      {content}
+    </NodeViewWrapper>
+  );
+}

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