@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/RichTextEditor/input.ts

@@ -0,0 +1,209 @@
+// input.ts — map a contentEditable `beforeinput` (inputType + data) at a model
+// Range to an engine transform. Pure: returns the new { doc, selection } or null
+// (null = unsupported; the caller still preventDefaults format* etc.).
+import type { RichDoc, Range, Point, Block } from '../RichText/engine/model';
+import { emptyDoc } from '../RichText/engine/model';
+import {
+  insertText,
+  deleteRange,
+  splitBlock,
+  mergeBlockBackward,
+} from '../RichText/engine/transforms';
+import { isCollapsed, blockLength, findBlockIndex } from '../RichText/engine/position';
+import { runsText } from '../RichText/engine/inlines';
+import { isVoidBlock } from '../RichText/engine/attachment';
+
+/** The new document + caret/selection after an input, or `null` when unsupported. */
+export type InputResult = { doc: RichDoc; selection: Range } | null;
+
+function point(blockId: string, offset: number): Point {
+  return { blockId, offset };
+}
+
+function collapsedAt(blockId: string, offset: number): Range {
+  return { anchor: point(blockId, offset), focus: point(blockId, offset) };
+}
+
+function deleteBackward(doc: RichDoc, caret: Point): InputResult {
+  if (caret.offset > 0) {
+    return deleteRange(doc, { anchor: point(caret.blockId, caret.offset - 1), focus: caret });
+  }
+  return mergeBlockBackward(doc, caret.blockId);
+}
+
+function deleteForward(doc: RichDoc, caret: Point): InputResult {
+  const idx = findBlockIndex(doc, caret.blockId);
+  if (idx === -1) return null;
+  if (caret.offset < blockLength(doc.blocks[idx])) {
+    return deleteRange(doc, { anchor: caret, focus: point(caret.blockId, caret.offset + 1) });
+  }
+  const next = doc.blocks[idx + 1];
+  return next ? mergeBlockBackward(doc, next.id) : null;
+}
+
+function wordBoundaryBackward(text: string, offset: number): number {
+  let i = offset;
+  while (i > 0 && /\s/.test(text[i - 1])) i -= 1;
+  while (i > 0 && !/\s/.test(text[i - 1])) i -= 1;
+  return i;
+}
+
+function wordBoundaryForward(text: string, offset: number): number {
+  let i = offset;
+  while (i < text.length && /\s/.test(text[i])) i += 1;
+  while (i < text.length && !/\s/.test(text[i])) i += 1;
+  return i;
+}
+
+function deleteWord(doc: RichDoc, caret: Point, dir: 'backward' | 'forward'): InputResult {
+  const idx = findBlockIndex(doc, caret.blockId);
+  if (idx === -1) return null;
+  const text = runsText(doc.blocks[idx].inlines);
+  if (dir === 'backward') {
+    if (caret.offset === 0) return mergeBlockBackward(doc, caret.blockId);
+    const start = wordBoundaryBackward(text, caret.offset);
+    return deleteRange(doc, { anchor: point(caret.blockId, start), focus: caret });
+  }
+  if (caret.offset >= text.length) {
+    const next = doc.blocks[idx + 1];
+    return next ? mergeBlockBackward(doc, next.id) : null;
+  }
+  const end = wordBoundaryForward(text, caret.offset);
+  return deleteRange(doc, { anchor: caret, focus: point(caret.blockId, end) });
+}
+
+/**
+ * Map a `beforeinput` event (inputType + data) at a model Range to an engine
+ * transform. Pure: no DOM access, no side effects.
+ *
+ * @returns `{ doc, selection }` — the updated document + where the caret should
+ *   land, or `null` when the inputType is unsupported (e.g. `formatBold`,
+ *   `historyUndo`). The caller must `preventDefault()` and replay the result, or
+ *   allow the event through when `null` is returned.
+ *
+ * @example
+ * const result = applyInput(doc, range, e.inputType, e.data);
+ * if (result) { e.preventDefault(); commit(result); }
+ */
+export function applyInput(
+  doc: RichDoc,
+  range: Range,
+  inputType: string,
+  data: string | null,
+): InputResult {
+  const collapsed = isCollapsed(range);
+  switch (inputType) {
+    case 'insertText':
+    case 'insertReplacementText':
+    case 'insertFromPaste': {
+      const text = data ?? '';
+      if (text === '') return null;
+      if (!collapsed) {
+        const del = deleteRange(doc, range);
+        return insertText(del.doc, del.selection.anchor, text);
+      }
+      return insertText(doc, range.anchor, text);
+    }
+    case 'insertParagraph':
+    case 'insertLineBreak': {
+      if (!collapsed) {
+        const del = deleteRange(doc, range);
+        return splitBlock(del.doc, del.selection.anchor);
+      }
+      return splitBlock(doc, range.anchor);
+    }
+    case 'deleteContentBackward':
+      return collapsed ? deleteBackward(doc, range.anchor) : deleteRange(doc, range);
+    case 'deleteContentForward':
+      return collapsed ? deleteForward(doc, range.anchor) : deleteRange(doc, range);
+    case 'deleteWordBackward':
+      return collapsed ? deleteWord(doc, range.anchor, 'backward') : deleteRange(doc, range);
+    case 'deleteWordForward':
+      return collapsed ? deleteWord(doc, range.anchor, 'forward') : deleteRange(doc, range);
+    default:
+      return null;
+  }
+}
+
+/** Which side of a void block (attachment figure) the DOM caret sits on. */
+export type VoidSide = 'before' | 'after';
+
+/** voidDelete's result; `caretAfterVoid` = put the DOM caret AFTER the selection's
+ *  void (a spot the model's single `{voidId, 0}` point can't name). */
+export type VoidDeleteResult = (NonNullable<InputResult> & { caretAfterVoid?: boolean }) | null;
+
+/**
+ * Remove the block at `idx`, placing the caret where a `dir` delete continues:
+ * forward → start of what follows, backward → end of what precedes (falling back
+ * to the other side at a doc edge). A void target gets the caret before it when
+ * approached forward, after it (`caretAfterVoid`) when approached backward.
+ */
+function removeAt(doc: RichDoc, idx: number, dir: 'backward' | 'forward'): VoidDeleteResult {
+  const blocks = doc.blocks.filter((_, i) => i !== idx);
+  if (blocks.length === 0) {
+    const fresh = emptyDoc();
+    return { doc: fresh, selection: collapsedAt(fresh.blocks[0].id, 0) };
+  }
+  // Candidates in order: the continuing side first, then the other.
+  const ahead = blocks[idx];
+  const behind = blocks[idx - 1];
+  const order: [Block | undefined, 'start' | 'end'][] =
+    dir === 'forward'
+      ? [
+          [ahead, 'start'],
+          [behind, 'end'],
+        ]
+      : [
+          [behind, 'end'],
+          [ahead, 'start'],
+        ];
+  // blocks is non-empty, so `ahead` or `behind` exists.
+  const [target, edge] = order.find(([b]) => b)! as [Block, 'start' | 'end'];
+  if (isVoidBlock(target)) {
+    return {
+      doc: { blocks },
+      selection: collapsedAt(target.id, 0),
+      caretAfterVoid: edge === 'end',
+    };
+  }
+  return {
+    doc: { blocks },
+    selection: collapsedAt(target.id, edge === 'start' ? 0 : blockLength(target)),
+  };
+}
+
+/**
+ * Backspace / Delete with the caret beside a void block. The model has ONE
+ * position per void (`{voidId, 0}`), so the DOM side decides:
+ * - Backspace from AFTER, or Delete from BEFORE → remove the void.
+ * - Backspace from BEFORE / Delete from AFTER → toward the neighboring block:
+ *   another void or an EMPTY text block is removed with the caret staying put,
+ *   otherwise the caret just moves into it (returns the SAME doc — the caller
+ *   applies only the selection; no character is deleted).
+ * Returns null when there is no neighbor in that direction (no-op).
+ */
+export function voidDelete(
+  doc: RichDoc,
+  voidId: string,
+  side: VoidSide,
+  dir: 'backward' | 'forward',
+): VoidDeleteResult {
+  const idx = findBlockIndex(doc, voidId);
+  if (idx === -1) return null;
+  if ((dir === 'backward') === (side === 'after')) return removeAt(doc, idx, dir);
+  const nIdx = dir === 'backward' ? idx - 1 : idx + 1;
+  const neighbor = doc.blocks[nIdx];
+  if (!neighbor) return null;
+  if (isVoidBlock(neighbor) || blockLength(neighbor) === 0) {
+    // Remove just the neighbor; the caret stays where it was, on its side of the void.
+    return {
+      doc: { blocks: doc.blocks.filter((_, i) => i !== nIdx) },
+      selection: collapsedAt(voidId, 0),
+      caretAfterVoid: side === 'after',
+    };
+  }
+  return {
+    doc,
+    selection: collapsedAt(neighbor.id, dir === 'backward' ? blockLength(neighbor) : 0),
+  };
+}

package/src/components/RichTextEditor/inputRules.ts

@@ -0,0 +1,71 @@
+// inputRules.ts — Markdown block input rules for <RichTextEditor>. Pure: match a
+// marker typed at the start of a paragraph (the trigger is always a space) and
+// apply the block conversion by composing existing engine transforms.
+import type { RichDoc, BlockType, Range } from '../RichText/engine/model';
+import { deleteRange, setBlockType } from '../RichText/engine/transforms';
+
+/** The block change a matched rule applies. */
+export interface BlockRuleChange {
+  type: BlockType;
+  level?: 1 | 2 | 3;
+  depth?: number;
+}
+export interface BlockRuleMatch {
+  change: BlockRuleChange;
+  /** Number of leading marker chars to strip from the block. */
+  markerLen: number;
+}
+
+/** Map an exact marker string to a block change, or null. */
+function changeFor(before: string): BlockRuleChange | null {
+  switch (before) {
+    case '#':
+      return { type: 'heading', level: 1 };
+    case '##':
+      return { type: 'heading', level: 2 };
+    case '###':
+      return { type: 'heading', level: 3 };
+    case '-':
+    case '*':
+    case '+':
+      return { type: 'bullet_item', depth: 0 };
+    case '>':
+      return { type: 'blockquote' };
+    case '```':
+      return { type: 'code_block' };
+    default:
+      return /^\d+[.)]$/.test(before) ? { type: 'ordered_item', depth: 0 } : null;
+  }
+}
+
+/**
+ * Match a block input rule. Fires only when `sourceType` is 'paragraph', the
+ * `trigger` is a single space, and `before` (block start → caret) is exactly a
+ * marker. Returns the block change + marker length, or null.
+ */
+export function matchBlockRule(
+  sourceType: BlockType,
+  before: string,
+  trigger: string,
+): BlockRuleMatch | null {
+  if (sourceType !== 'paragraph' || trigger !== ' ') return null;
+  const change = changeFor(before);
+  return change ? { change, markerLen: before.length } : null;
+}
+
+/**
+ * Apply a matched rule to the block: strip the marker prefix, then set the block
+ * type (composing `deleteRange` + `setBlockType`). Returns the `{ doc, selection }`
+ * commit payload with the caret at the block start.
+ */
+export function applyBlockRule(
+  doc: RichDoc,
+  blockId: string,
+  match: BlockRuleMatch,
+): { doc: RichDoc; selection: Range } {
+  const stripped = deleteRange(doc, {
+    anchor: { blockId, offset: 0 },
+    focus: { blockId, offset: match.markerLen },
+  });
+  return setBlockType(stripped.doc, blockId, match.change);
+}

package/src/components/RichTextEditor/links.ts

@@ -0,0 +1,103 @@
+// links.ts — pure link commands for <RichTextEditor>. No DOM, no React. Each
+// command composes the engine's existing mark/text transforms; `setLink` covers
+// the three link cases (selection / caret-in-link / caret-elsewhere). Safety of
+// the stored href is enforced at render time by the engine's `safeHref`.
+import type { RichDoc, Range, Point, Mark } from '../RichText/engine/model';
+import { applyMark, removeMark, insertText } from '../RichText/engine/transforms';
+import { findBlockIndex, blockLength, isCollapsed } from '../RichText/engine/position';
+
+/** The link covering a point: its href and the full contiguous same-href range. */
+export interface LinkAtResult {
+  href: string;
+  range: Range;
+}
+
+/**
+ * The link at a point: its href and the full contiguous run of
+ * characters sharing that exact href, or `null` when the point is not in a link.
+ * The owning character is the one at `offset`, or the one before it when the
+ * caret sits at the block's end (so a caret just after a link still resolves).
+ */
+export function linkAt(doc: RichDoc, point: Point): LinkAtResult | null {
+  const idx = findBlockIndex(doc, point.blockId);
+  if (idx === -1) return null;
+  const block = doc.blocks[idx];
+  const len = blockLength(block);
+  // A zero-length block (empty, or a void `attachment` that carries no `inlines`)
+  // can't host a link — bail before iterating (block.inlines may be undefined).
+  if (len === 0) return null;
+  // Per-character link href across the block (null where no link).
+  const hrefs: (string | null)[] = [];
+  for (const run of block.inlines) {
+    const mark = run.marks.find((m) => m.type === 'link');
+    const href = mark && mark.type === 'link' ? mark.href : null;
+    for (let i = 0; i < run.text.length; i += 1) hrefs.push(href);
+  }
+  const probe = point.offset < len ? point.offset : point.offset - 1;
+  if (probe < 0 || probe >= len) return null;
+  const href = hrefs[probe];
+  if (href === null) return null;
+  let start = probe;
+  while (start > 0 && hrefs[start - 1] === href) start -= 1;
+  let end = probe + 1;
+  while (end < len && hrefs[end] === href) end += 1;
+  return {
+    href,
+    range: {
+      anchor: { blockId: block.id, offset: start },
+      focus: { blockId: block.id, offset: end },
+    },
+  };
+}
+
+/** Remove the link mark over `range`. */
+export function removeLink(doc: RichDoc, range: Range): { doc: RichDoc; selection: Range } {
+  return removeMark(doc, range, 'link');
+}
+
+/**
+ * Apply, update, or insert a link over `range`. Three cases, decided by
+ * `isCollapsed` + `linkAt`:
+ * 1. Non-collapsed selection → link it (replacing any existing href).
+ * 2. Collapsed caret inside a link → re-link the link's full extent.
+ * 3. Collapsed caret elsewhere → insert the href as linked text.
+ * An empty/whitespace href removes an existing link (cases 1–2) or is a no-op
+ * (case 3). `href` is trimmed but otherwise stored verbatim — `safeHref`
+ * sanitizes at render time. Returns the `{ doc, selection }` commit payload.
+ */
+export function setLink(
+  doc: RichDoc,
+  range: Range,
+  href: string,
+): { doc: RichDoc; selection: Range } {
+  const trimmed = href.trim();
+  const collapsed = isCollapsed(range);
+
+  if (trimmed === '') {
+    if (!collapsed) return removeLink(doc, range);
+    const existing = linkAt(doc, range.anchor);
+    return existing ? removeLink(doc, existing.range) : { doc, selection: range };
+  }
+
+  const mark: Mark = { type: 'link', href: trimmed };
+
+  // Case 1 — selection.
+  if (!collapsed) return applyMark(doc, range, mark);
+
+  // Case 2 — caret inside an existing link.
+  const existing = linkAt(doc, range.anchor);
+  if (existing) return applyMark(doc, existing.range, mark);
+
+  // Case 3 — caret elsewhere: insert the href, then link the inserted span.
+  const inserted = insertText(doc, range.anchor, trimmed);
+  // Span from the insert's resulting caret, not range.anchor: beside a void block
+  // the text lands in a NEW paragraph after it.
+  const end = inserted.selection.focus;
+  const linkedSpan: Range = {
+    anchor: { blockId: end.blockId, offset: end.offset - trimmed.length },
+    focus: end,
+  };
+  // Select the inserted link text (not a collapsed caret after it) so the user
+  // sees the link that was just created.
+  return applyMark(inserted.doc, linkedSpan, mark);
+}

package/src/components/RichTextEditor/mentionContext.ts

@@ -0,0 +1,37 @@
+// mentionContext.ts — pure detection of an open mention context at a caret.
+
+/** A detected, open mention context. */
+export interface MentionContext {
+  /** Text typed after the trigger, up to the caret (may be ''). */
+  query: string;
+  /** Offset of the trigger char within the block text. */
+  triggerOffset: number;
+}
+
+/**
+ * Detect an open mention context at a collapsed caret within `blockText`.
+ * Returns a context only when the nearest `trigger` before `caretOffset` is at
+ * block start or preceded by whitespace, and no whitespace sits between it and
+ * the caret. Otherwise returns null.
+ *
+ * @example
+ * getMentionContext('hi @al', 6, '@'); // { query: 'al', triggerOffset: 3 }
+ */
+export function getMentionContext(
+  blockText: string,
+  caretOffset: number,
+  trigger: string,
+): MentionContext | null {
+  if (!trigger) return null;
+  // Scan backward from the caret to the nearest trigger; bail on whitespace.
+  for (let i = caretOffset - 1; i >= 0; i -= 1) {
+    const ch = blockText[i];
+    if (/\s/.test(ch)) return null; // whitespace between trigger and caret → closed
+    if (ch === trigger) {
+      const before = i === 0 ? '' : blockText[i - 1];
+      if (i !== 0 && !/\s/.test(before)) return null; // mid-word trigger
+      return { query: blockText.slice(i + trigger.length, caretOffset), triggerOffset: i };
+    }
+  }
+  return null;
+}

package/src/components/RichTextEditor/mentions.ts

@@ -0,0 +1,28 @@
+// mentions.ts — public types for the RichTextEditor `mentions` prop.
+
+/** One mentionable candidate returned by `MentionsConfig.onQuery`. */
+export interface MentionItem {
+  /** Stable id stored on the mention mark and emitted in serialization (`data-mention-id`). */
+  id: string;
+  /** Display text — becomes the chip's visible text (without the trigger). */
+  label: string;
+  /** Optional secondary line in the menu row (e.g. an email). Menu-only; not stored. */
+  description?: string;
+  /** Optional avatar shown in the menu row. Menu-only; not stored. */
+  avatarUrl?: string;
+}
+
+/**
+ * Enables `@`-mention autocomplete on `<RichTextEditor>`. Omit the `mentions`
+ * prop to disable mentions entirely.
+ */
+export interface MentionsConfig {
+  /**
+   * Resolve candidates for the text typed after the trigger. Called as the user
+   * types; may be sync or async. The editor drops stale async resolutions, so a
+   * slow promise that resolves after the query moved on is ignored.
+   */
+  onQuery: (query: string) => MentionItem[] | Promise<MentionItem[]>;
+  /** Single trigger character that opens the menu. Default `'@'`. Multi-character triggers are not supported. */
+  trigger?: string;
+}

package/src/components/RichTextEditor/preventSelectionLoss.ts

@@ -0,0 +1,15 @@
+// preventSelectionLoss.ts — shared mousedown guard for toolbar/menu controls that
+// act on the editor's current selection (kept in one place to avoid drift).
+import type { MouseEvent } from 'react';
+
+/**
+ * mousedown handler that preserves the editor's DOM selection: focus leaving the
+ * contentEditable would collapse the selection before a toolbar/menu action runs.
+ *
+ * Wire it as `onMouseDown={preventSelectionLoss}` on any toolbar/menu control that
+ * acts on the current editor selection (mark toggles, color swatches, block
+ * actions) so the caret/range is still live when the control's onClick fires.
+ */
+export function preventSelectionLoss(e: MouseEvent): void {
+  e.preventDefault();
+}