@djangocfg/widget-editor 0.1.1

package/src/markdown/createMentionSuggestion.ts

@@ -0,0 +1,131 @@
+import { ReactRenderer } from '@tiptap/react';
+import type { SuggestionOptions } from '@tiptap/suggestion';
+import { autoUpdate, computePosition, flip, offset, shift } from '@floating-ui/dom';
+import { MentionList, type MentionListRef } from './MentionList';
+import type { MentionItem, MentionConfig } from './types';
+
+export function createMentionSuggestion(
+  config: MentionConfig,
+): Omit<SuggestionOptions<MentionItem>, 'editor'> {
+  const { maxItems = 5, trigger = '@' } = config;
+
+  return {
+    char: trigger,
+
+    items: ({ query }) => {
+      const q = query.toLowerCase();
+      return config.items
+        .filter((item) => item.label.toLowerCase().includes(q))
+        .slice(0, maxItems);
+    },
+
+    render: () => {
+      let component: ReactRenderer<MentionListRef> | null = null;
+      let popup: HTMLDivElement | null = null;
+      let cleanupAutoUpdate: (() => void) | null = null;
+      let getReferenceRect: (() => DOMRect | null) | null = null;
+
+      // Floating-UI virtual element backed by Tiptap's clientRect.
+      // We re-read it on every reposition so caret movement is tracked.
+      const buildVirtualElement = () => ({
+        getBoundingClientRect: () => {
+          const rect = getReferenceRect?.();
+          // Fallback to a zero-sized rect at origin if the editor is detached
+          // (e.g. mid-teardown). Floating-UI tolerates this.
+          return rect ?? new DOMRect(0, 0, 0, 0);
+        },
+      });
+
+      // The popup wrapper is mounted in onStart and removed in onExit.
+      // While mounted it must stay hidden whenever MentionList renders
+      // nothing (empty query / no matches), otherwise an empty positioned
+      // div lingers next to the caret as a ghost block.
+      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(4),
+            flip({ fallbackPlacements: ['top-start'] }),
+            shift({ padding: 8 }),
+          ],
+        }).then(({ x, y }) => {
+          if (!popup) return;
+          // transform is more performant than top/left and avoids
+          // sub-pixel layout thrash during scroll/resize.
+          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(MentionList, {
+            props: {
+              items: props.items,
+              command: (item: MentionItem) => {
+                props.command({ id: item.id, label: item.label });
+              },
+            },
+            editor: props.editor,
+          });
+
+          popup = document.createElement('div');
+          // top/left at 0; actual position is applied via transform by computePosition.
+          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;
+
+          // autoUpdate handles scroll, resize, ancestor scroll/resize, layout shifts.
+          // It calls updatePosition synchronously on registration too — no manual first call needed.
+          const virtualEl = buildVirtualElement();
+          cleanupAutoUpdate = autoUpdate(virtualEl, popup, updatePosition);
+        },
+
+        onUpdate: (props) => {
+          component?.updateProps({
+            items: props.items,
+            command: (item: MentionItem) => {
+              props.command({ id: item.id, label: item.label });
+            },
+          });
+
+          setPopupVisible(props.items.length > 0);
+
+          // Refresh reference accessor so autoUpdate sees the new caret rect.
+          getReferenceRect = () => props.clientRect?.() ?? null;
+          updatePosition();
+        },
+
+        onKeyDown: (props) => {
+          if (props.event.key === 'Escape') {
+            teardown();
+            return true;
+          }
+          return component?.ref?.onKeyDown(props.event as unknown as React.KeyboardEvent) ?? false;
+        },
+
+        onExit: () => {
+          teardown();
+        },
+      };
+    },
+  };
+}

package/src/markdown/filePath/FilePathChip.tsx

@@ -0,0 +1,68 @@
+'use client';
+
+/**
+ * `<FilePathChip>` — a compact, presentational chip for a LOCAL file path
+ * (Cursor / VSCode / Finder style): the extension-correct file icon +
+ * a smart middle-ellipsized label, monospace, with the full path on hover.
+ *
+ * Standalone by design — it imports only the pure detector helpers and the
+ * shared `FileIcon`, so it can render a known path in a chat message,
+ * a file list, etc., entirely outside the TipTap editor.
+ *
+ * Presentational only: it never mutates or links anything. Inside the
+ * editor the SAME visual is reproduced by the `editorChip` atom NODE
+ * (see `../chip/ChipNode.ts`, `kind: 'path'`) — this component is the
+ * React/standalone counterpart, still useful for rendering a known path
+ * outside the editor (chat messages, file lists).
+ */
+
+import { cn } from '@djangocfg/ui-core/lib';
+import { FileIcon } from '@djangocfg/widget-data/file-icon';
+import { splitPath, truncatePathLabel } from './detect';
+
+export interface FilePathChipProps {
+  /** The full, raw file path (Unix / macOS / Windows / UNC / `file://`). */
+  path: string;
+  /**
+   * Approximate max characters for the truncated label. The basename is
+   * always preserved; only the middle collapses. Default 40.
+   */
+  maxChars?: number;
+  /** Icon size in px. Default 14 (matches inline text). */
+  iconSize?: 12 | 14 | 16;
+  className?: string;
+}
+
+/**
+ * Render a path as an inline chip. Uses the folder icon when the path
+ * resolves to a directory (no file extension / trailing separator).
+ */
+export function FilePathChip({
+  path,
+  maxChars = 40,
+  iconSize = 14,
+  className,
+}: FilePathChipProps) {
+  const { base, isDir } = splitPath(path);
+  const label = truncatePathLabel(path, { maxChars });
+
+  return (
+    <span
+      className={cn(
+        // Inline pill: muted surface + border, monospace, semantic tokens
+        // only (mirrors the inline-code look). `max-w` + `truncate` is the
+        // CSS safety net under the semantic middle-ellipsis label.
+        'inline-flex max-w-[22rem] items-center gap-1 rounded',
+        'border border-border bg-muted px-1.5 py-0.5 align-baseline',
+        'font-mono text-[0.8125em] leading-tight text-foreground',
+        className,
+      )}
+      title={path}
+    >
+      <FileIcon name={base} isFolder={isDir} size={iconSize} />
+      <span className="truncate">{label}</span>
+    </span>
+  );
+}
+
+export default FilePathChip;

package/src/markdown/filePath/detect.ts

@@ -0,0 +1,289 @@
+/**
+ * File-path detection + display helpers for the chat editor's "file chip"
+ * decoration. Pure, side-effect-free, and unit-testable — no TipTap /
+ * ProseMirror / React imports live here so the same functions back the
+ * standalone `<FilePathChip>` and the editor decoration alike.
+ *
+ * Design goal: **LOW false-positive**. We only treat a token as a local
+ * file path when it matches an explicit, unambiguous ABSOLUTE shape —
+ * never a bare relative token (`./x`, `src/y`) and never a web URL. See
+ * `reports/research.md` for the rationale (there is no single universal
+ * path regex; detect by safe shapes only).
+ */
+
+// ── Match result ──
+
+export interface FilePathMatch {
+  /** Inclusive start offset into the scanned string. */
+  start: number;
+  /** Exclusive end offset into the scanned string. */
+  end: number;
+  /** The matched path text (already trailing-punctuation-trimmed). */
+  path: string;
+}
+
+// ── Detector ──
+
+/**
+ * Trailing sentence punctuation that, when it hangs off the END of a
+ * detected path token, is almost certainly prose and not part of the
+ * filename — trim it. Real filenames effectively never end in these.
+ * (A leading `.` like a dotfile is fine — we only trim the tail.)
+ */
+const TRAILING_PUNCT = new Set([
+  '.', ',', ')', ']', '}', ';', ':', '!', '?',
+  '«', '»', '"', "'", '”', '’', '…',
+]);
+
+/**
+ * The four absolute path shapes, as a single alternation. Each alternative
+ * is whitespace-bounded by construction (`\S` runs, no raw spaces). Order
+ * matters: more specific schemes (`file://`, UNC, drive) come before the
+ * bare Unix root so the longest correct form wins.
+ *
+ * - `file://…`            — `file:` URI (any non-space tail).
+ * - `\\server\share…`     — Windows UNC (two leading backslashes).
+ * - `C:\…` / `C:/…`       — Windows drive (single letter + `:` + slash).
+ * - `~/…`                 — home-relative (Unix/macOS).
+ * - `/seg/seg…`           — Unix/macOS absolute, REQUIRES ≥2 segments so a
+ *                           lone `/` or prose `a / b` never matches.
+ *
+ * Unicode is allowed inside segments (`@projects`, Cyrillic dirs) — we
+ * match on "not whitespace" rather than an ASCII allow-list, then strip
+ * trailing punctuation afterwards.
+ */
+const PATH_RE = new RegExp(
+  [
+    // file:// URI — scheme then a non-space tail.
+    String.raw`file:\/\/\S+`,
+    // UNC: \\server\share...  (need a host char after the two slashes).
+    String.raw`\\\\[^\s\\/][^\s]*`,
+    // Windows drive: C:\... or C:/... (single drive letter).
+    String.raw`[A-Za-z]:[\\/][^\s]*`,
+    // Home: ~/...
+    String.raw`~[\\/][^\s]+`,
+    // Unix/macOS absolute: /seg/seg... — at least TWO segments. A
+    // segment is a run of non-space, non-separator chars; we require
+    // a separator + segment to repeat at least once after the root.
+    String.raw`\/[^\s\\/]+(?:[\\/][^\s\\/]+)+[\\/]?`,
+  ].join('|'),
+  'gu',
+);
+
+/**
+ * Trim trailing prose punctuation from a raw token. Repeats so multiple
+ * trailing marks (`manifest.md).` → `manifest.md`) all come off, but
+ * stops as soon as the tail is a normal path char. We never trim into an
+ * empty string.
+ */
+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);
+}
+
+/**
+ * Find every absolute local file path in `text`.
+ *
+ * Returns matches in document order with `{ start, end, path }` where
+ * `[start, end)` are offsets into the ORIGINAL string (after trailing-
+ * punctuation trimming, `end` points just past the kept path — the
+ * trimmed punctuation is left out of the range so the chip doesn't cover
+ * it). Web URLs (`https://x.com/y`), bare relative tokens, and a lone
+ * prose slash are intentionally NOT matched.
+ */
+export function findFilePaths(text: string): FilePathMatch[] {
+  if (!text) return [];
+
+  const out: FilePathMatch[] = [];
+  PATH_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+
+  while ((m = PATH_RE.exec(text)) !== null) {
+    const raw = m[0];
+    const start = m.index;
+
+    // Guard against a zero-width match (shouldn't happen with these
+    // alternatives, but keep the loop safe).
+    if (raw.length === 0) {
+      PATH_RE.lastIndex += 1;
+      continue;
+    }
+
+    // Leading-boundary guard. A real path token starts the string or
+    // follows whitespace / an opening delimiter. If it's glued onto a
+    // preceding non-space char it's a SUBSTRING of a larger token — most
+    // importantly a web URL's path (`https://x.com/y/z` → the `/y/z`
+    // would otherwise match the Unix-absolute shape). Reject those.
+    if (start > 0) {
+      const prev = text[start - 1]!;
+      if (!/[\s([{<«"'‘“]/.test(prev)) continue;
+    }
+
+    const trimmed = trimTrailingPunct(raw);
+    // A bare drive root (`C:\`) or `~/` with nothing meaningful is not a
+    // useful chip — but the regexes above already require a tail segment,
+    // so `trimmed` here is always a real path. Still, skip if trimming
+    // collapsed it to a non-path remnant.
+    if (trimmed.length < 2) continue;
+
+    out.push({
+      start,
+      end: start + trimmed.length,
+      path: trimmed,
+    });
+  }
+
+  return out;
+}
+
+// ── Split (separator-agnostic) ──
+
+export interface SplitPath {
+  /** Everything before the basename (no trailing separator). */
+  dir: string;
+  /** Last non-empty path segment (the file or folder name). */
+  base: string;
+  /**
+   * Heuristic: the path points at a directory rather than a file —
+   * either it ends in a separator, or its basename has no file
+   * extension (a dotted `manifest.md` reads as a file; `positioning`
+   * reads as a dir).
+   */
+  isDir: boolean;
+}
+
+/**
+ * Strip a `file://` (or `file:`) scheme prefix for display/splitting.
+ * `file:///Users/x` → `/Users/x`; `file://host/share` → `host/share`.
+ */
+function stripFileScheme(path: string): string {
+  const lower = path.toLowerCase();
+  if (lower.startsWith('file://')) {
+    // file:///abs  → /abs   (three slashes: empty host, keep the root)
+    // file://host  → host
+    return path.slice('file://'.length);
+  }
+  if (lower.startsWith('file:')) return path.slice('file:'.length);
+  return path;
+}
+
+/** True when `base` looks like it carries a real file extension. */
+function hasExtension(base: string): boolean {
+  const dot = base.lastIndexOf('.');
+  // No dot, leading dot only (dotfile like `.gitignore` — treat as file),
+  // or a trailing dot → decide:
+  //  - `.gitignore` (dot at 0) IS a file → has "extension".
+  //  - `name.` (dot last) → not a real extension.
+  if (dot === -1) return false;
+  if (dot === base.length - 1) return false; // trailing dot
+  if (dot === 0) return true; // dotfile
+  return true;
+}
+
+/**
+ * Split a path into `{ dir, base, isDir }`, separator-agnostic (handles
+ * `/` and `\` mixed). The basename is the last NON-EMPTY segment so a
+ * trailing separator (`/Users/me/docs/`) still yields `base = "docs"`
+ * and `isDir = true`.
+ */
+export function splitPath(path: string): SplitPath {
+  const cleaned = stripFileScheme(path);
+  const endsWithSep = /[\\/]$/.test(cleaned);
+
+  // Split on either separator, drop empty segments (collapses `//`,
+  // leading root, trailing sep).
+  const segments = cleaned.split(/[\\/]+/).filter((s) => s.length > 0);
+  const base = segments.length > 0 ? segments[segments.length - 1]! : cleaned;
+  const dirSegments = segments.slice(0, -1);
+  const dir = dirSegments.join('/');
+
+  const isDir = endsWithSep || !hasExtension(base);
+
+  return { dir, base, isDir };
+}
+
+// ── Truncate (Apple/Finder middle-ellipsis) ──
+
+export interface TruncateOptions {
+  /**
+   * Approximate max characters for the label. The basename is ALWAYS
+   * kept in full (never cut); only the middle collapses. Default 40.
+   */
+  maxChars?: number;
+}
+
+const ELLIPSIS = '…';
+
+/**
+ * Produce a compact, Finder/Chrome-style label for a path: the basename
+ * is sacred (always shown in full), the MIDDLE collapses to `…`, and a
+ * leading root hint is kept when there's room.
+ *
+ * Examples (maxChars ≈ 40):
+ *   /Users/me/dev/proj/positioning/manifest.md
+ *     → /Users/…/positioning/manifest.md
+ *   /a/b.md                → /a/b.md   (already short — unchanged)
+ *   C:\Users\me\notes.md   → C:\…\notes.md (separator preserved? — we
+ *                            normalise display to `/` for compactness)
+ */
+export function truncatePathLabel(path: string, opts: TruncateOptions = {}): string {
+  const maxChars = opts.maxChars ?? 40;
+  const display = stripFileScheme(path);
+
+  // Short enough — show as-is.
+  if (display.length <= maxChars) return display;
+
+  const endsWithSep = /[\\/]$/.test(display);
+  const segments = display.split(/[\\/]+/).filter((s) => s.length > 0);
+  if (segments.length <= 1) {
+    // Single segment longer than maxChars — keep the basename intact
+    // (CSS ellipsis is the safety net in the chip).
+    return display;
+  }
+
+  const base = segments[segments.length - 1]!;
+  const baseLabel = endsWithSep ? `${base}/` : base;
+
+  // Detect a leading root hint we can preserve:
+  //  - Unix/macOS absolute → leading "/" + first segment.
+  //  - Windows drive → "C:".
+  //  - `~` home → "~".
+  let rootHint = '';
+  if (/^[A-Za-z]:[\\/]/.test(display)) {
+    rootHint = display.slice(0, 2); // "C:"
+  } else if (display.startsWith('~')) {
+    rootHint = '~';
+  } else if (/^[\\/]/.test(display)) {
+    rootHint = `/${segments[0]!}`;
+  }
+
+  // The penultimate segment (parent folder) is a useful hint to keep
+  // when room allows — `.../positioning/manifest.md`.
+  const parent = segments.length >= 2 ? segments[segments.length - 2]! : '';
+
+  // Build candidates from most-informative to least, pick the first that
+  // fits within maxChars (the basename is never sacrificed).
+  const candidates: string[] = [];
+  if (rootHint && parent) {
+    candidates.push(`${rootHint}/${ELLIPSIS}/${parent}/${baseLabel}`);
+  }
+  if (parent) {
+    candidates.push(`${ELLIPSIS}/${parent}/${baseLabel}`);
+  }
+  if (rootHint) {
+    candidates.push(`${rootHint}/${ELLIPSIS}/${baseLabel}`);
+  }
+  candidates.push(`${ELLIPSIS}/${baseLabel}`);
+
+  for (const c of candidates) {
+    if (c.length <= maxChars) return c;
+  }
+
+  // Even `…/base` overflows (a very long basename) — return it anyway;
+  // the chip's CSS `text-overflow: ellipsis` clips the tail visually
+  // while the full path stays in the tooltip.
+  return `${ELLIPSIS}/${baseLabel}`;
+}

package/src/markdown/filePath/index.ts

@@ -0,0 +1,15 @@
+'use client';
+
+export { FilePathChip } from './FilePathChip';
+export type { FilePathChipProps } from './FilePathChip';
+
+export {
+  findFilePaths,
+  splitPath,
+  truncatePathLabel,
+} from './detect';
+export type {
+  FilePathMatch,
+  SplitPath,
+  TruncateOptions,
+} from './detect';

package/src/markdown/index.ts

@@ -0,0 +1,29 @@
+export { MarkdownEditor } from './MarkdownEditor';
+export type { MarkdownEditorProps, MarkdownEditorHandle } from './MarkdownEditor';
+export type {
+  MentionItem,
+  MentionConfig,
+  MentionAttrs,
+  MentionMarkdownRenderer,
+} from './types';
+export { mentionPresets } from './mentionPresets';
+export type { SlashCommandInfo } from './slash/types';
+
+// File-path chip — the standalone presentational chip plus the pure
+// detector helpers (usable outside the editor, e.g. rendering a known
+// path in a chat message).
+export { FilePathChip } from './filePath/FilePathChip';
+export type { FilePathChipProps } from './filePath/FilePathChip';
+export { findFilePaths, splitPath, truncatePathLabel } from './filePath/detect';
+export type { FilePathMatch, SplitPath, TruncateOptions } from './filePath/detect';
+
+// URL chip — pure detector + display helpers backing the in-editor URL chip
+// (the `editorChip` node's `kind: 'url'`). Usable standalone too.
+export {
+  findUrls,
+  splitUrl,
+  truncateUrlLabel,
+  faviconUrl,
+  normalizeHref,
+} from './url/detect';
+export type { UrlMatch, SplitUrl, UrlLabelOptions } from './url/detect';

package/src/markdown/lazy.tsx

@@ -0,0 +1,88 @@
+'use client';
+
+/**
+ * `@djangocfg/widget-editor/markdown` subpath entrypoint.
+ *
+ * `MarkdownEditor` is a TipTap WYSIWYG with the full ProseMirror + TipTap
+ * extension stack — `@tiptap/react`, `starter-kit`, `markdown`, `mention`,
+ * `placeholder`, plus our `createMentionSuggestion` (floating-ui anchored
+ * dropdown). Together that's ~200 KB minified — wrap it in React.lazy so
+ * pages that don't render an editor don't pay.
+ *
+ * Why a hand-rolled lazy wrapper instead of `createLazyComponent`:
+ * `createLazyComponent` returns a plain function component that does not
+ * forward `ref`, so the imperative `MarkdownEditorHandle` (focus /
+ * moveCursorToEnd — used by chat composer registration + voice slot)
+ * would be silently dropped. The wrapper below is a `forwardRef` so the
+ * ref reaches the underlying TipTap editor through `React.lazy`.
+ *
+ * Light surface kept here:
+ *   - All public types (erased at compile time).
+ *   - `mentionPresets` — pure data describing how to render mentions to
+ *     markdown. No TipTap imports at module scope.
+ */
+
+import { Suspense, lazy, forwardRef } from 'react';
+import { InlineLoadingFallback } from '@djangocfg/widget-kit/lazy';
+import type { MarkdownEditorProps, MarkdownEditorHandle } from './MarkdownEditor';
+
+const MarkdownEditorImpl = lazy(() =>
+  import('./MarkdownEditor').then((m) => ({ default: m.MarkdownEditor })),
+);
+
+/**
+ * Lazy-loaded `MarkdownEditor`. Forwards `ref` (`MarkdownEditorHandle`)
+ * to the underlying TipTap editor once the chunk resolves.
+ */
+export const LazyMarkdownEditor = forwardRef<MarkdownEditorHandle, MarkdownEditorProps>(
+  function LazyMarkdownEditor(props, ref) {
+    // Input-sized, not panel-sized: this editor IS the composer's text field,
+    // so the 140px tinted block with a 32px disc and a caption was out of
+    // scale and shifted the layout when TipTap mounted. A bare 14px spinner is
+    // enough — the wait is short and nothing is actionable during it. The
+    // label survives for screen readers.
+    return (
+      <Suspense fallback={<InlineLoadingFallback />}>
+        <MarkdownEditorImpl {...props} ref={ref} />
+      </Suspense>
+    );
+  },
+);
+
+// `MarkdownEditor` is the public eager-looking name — it resolves to the
+// same lazy component so importing it from this subpath does NOT pull
+// ~200 KB of TipTap into the caller's initial bundle. Keeping the name
+// here means `@djangocfg/widget-editor/markdown` exposes
+// `MarkdownEditor`, `LazyMarkdownEditor`, and `mentionPresets`.
+export { LazyMarkdownEditor as MarkdownEditor };
+
+// Light surface — pure helpers + types.
+export { mentionPresets } from './mentionPresets';
+
+// File-path chip — the standalone presentational chip + the pure detector
+// helpers. The chip is light enough to export eagerly (no TipTap at module
+// scope — it only pulls `FileIcon` + the pure detector), so consumers can
+// render a known path outside the editor without loading the ~200 KB
+// TipTap chunk.
+export { FilePathChip } from './filePath/FilePathChip';
+export type { FilePathChipProps } from './filePath/FilePathChip';
+export { findFilePaths, splitPath, truncatePathLabel } from './filePath/detect';
+export type { FilePathMatch, SplitPath, TruncateOptions } from './filePath/detect';
+
+export type {
+  MarkdownEditorProps,
+  MarkdownEditorHandle,
+} from './MarkdownEditor';
+
+export type {
+  MentionItem,
+  MentionConfig,
+  MentionAttrs,
+  MentionMarkdownRenderer,
+} from './types';
+
+// Slash command surface — opt-in by passing `slashCommands` to
+// `MarkdownEditor` (or `<ComposerRichTextarea>`, which forwards). The
+// node itself is mounted by the editor on first render. `SlashCommandInfo`
+// is structurally compatible with the chat package's `SlashCommand`.
+export type { SlashCommandInfo } from './slash/types';