@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/RichText/engine/inlines.ts

@@ -0,0 +1,82 @@
+// inlines.ts — Layer B. Pure helpers over an Inline[]. Never mutate inputs.
+import type { Inline, Mark } from './model';
+import { marksEqual } from './marks';
+
+/**
+ * Concatenate the text of all inline runs, discarding mark information. Tolerates a
+ * missing `inlines` (a void block like `attachment` carries none) — a block with no
+ * runs contributes no text.
+ */
+export function runsText(inlines: Inline[] | undefined): string {
+  return (inlines ?? []).map((r) => r.text).join('');
+}
+
+/**
+ * Total character count across all inline runs (sum of run text lengths). Tolerates a
+ * missing `inlines` (void blocks like `attachment` carry none) → length 0, so the
+ * caret/length math never crashes on an attachment-containing doc.
+ */
+export function runsLength(inlines: Inline[] | undefined): number {
+  return (inlines ?? []).reduce((n, r) => n + r.text.length, 0);
+}
+
+/** Canonical form: adjacent equal-mark runs merged, empty runs dropped, ≥1 run. */
+export function normalizeInlines(inlines: Inline[]): Inline[] {
+  const out: Inline[] = [];
+  for (const run of inlines) {
+    if (run.text === '') continue;
+    const last = out[out.length - 1];
+    if (last && marksEqual(last.marks, run.marks)) {
+      out[out.length - 1] = { text: last.text + run.text, marks: last.marks };
+    } else {
+      out.push({ text: run.text, marks: run.marks });
+    }
+  }
+  return out.length === 0 ? [{ text: '', marks: [] }] : out;
+}
+
+/** Extract the character sub-range [start, end). Returns a normalized Inline[]. */
+export function sliceInlines(inlines: Inline[], start: number, end: number): Inline[] {
+  const out: Inline[] = [];
+  let pos = 0;
+  for (const run of inlines) {
+    const runStart = pos;
+    const runEnd = pos + run.text.length;
+    pos = runEnd;
+    const from = Math.max(start, runStart);
+    const to = Math.min(end, runEnd);
+    if (to > from) {
+      out.push({ text: run.text.slice(from - runStart, to - runStart), marks: run.marks });
+    }
+  }
+  return normalizeInlines(out);
+}
+
+/**
+ * Apply `fn` to the mark set of every character in [start, end), splitting runs
+ * at the boundaries. Characters outside the range keep their marks. Re-normalizes.
+ */
+export function mapMarksOverRange(
+  inlines: Inline[],
+  start: number,
+  end: number,
+  fn: (marks: Mark[]) => Mark[],
+): Inline[] {
+  const out: Inline[] = [];
+  let pos = 0;
+  for (const run of inlines) {
+    const runStart = pos;
+    const runEnd = pos + run.text.length;
+    pos = runEnd;
+    const from = Math.max(start, runStart);
+    const to = Math.min(end, runEnd);
+    if (to <= from) {
+      out.push(run); // entirely outside the range
+      continue;
+    }
+    if (from > runStart) out.push({ text: run.text.slice(0, from - runStart), marks: run.marks });
+    out.push({ text: run.text.slice(from - runStart, to - runStart), marks: fn(run.marks) });
+    if (to < runEnd) out.push({ text: run.text.slice(to - runStart), marks: run.marks });
+  }
+  return normalizeInlines(out);
+}

package/src/components/RichText/engine/listDepths.ts

@@ -0,0 +1,32 @@
+// listDepths.ts — list-item detection + gap-free depth normalization, shared by
+// the renderer (renderDoc) and the HTML serializer (toHtml) so both reconstruct
+// list nesting identically.
+import type { Block } from './model';
+
+/** True for the flat list-item block types. */
+export function isListItem(block: Block): boolean {
+  return block.type === 'bullet_item' || block.type === 'ordered_item';
+}
+
+/**
+ * Effective render depth per block. `depth` is a free integer on the model, but
+ * nesting needs gap-free levels — within each run of consecutive list items,
+ * clamp each item to at most one level deeper than the previous (never below 0).
+ * Non-list blocks get 0 and reset the run. Lossless: no item is dropped during
+ * grouping.
+ */
+export function effectiveDepths(blocks: Block[]): number[] {
+  const eff = new Array<number>(blocks.length).fill(0);
+  let prev = -1; // effective depth of the previous list item in the current run
+  for (let i = 0; i < blocks.length; i += 1) {
+    if (!isListItem(blocks[i])) {
+      prev = -1;
+      continue;
+    }
+    const raw = blocks[i].depth ?? 0;
+    const e = Math.max(0, Math.min(raw, prev + 1));
+    eff[i] = e;
+    prev = e;
+  }
+  return eff;
+}

package/src/components/RichText/engine/marks.ts

@@ -0,0 +1,80 @@
+// marks.ts — Layer A. Pure helpers over a Mark[]. Never mutate inputs.
+import type { Mark, MarkType } from './model';
+
+/**
+ * Inline-mark nesting order, outermost first. Shared by renderDoc + toHtml so
+ * render and serialize nest identically. Color spans sit just inside link/mention
+ * (so a colored link reads `<a><span style>…`) but outside the text-formatting tags.
+ */
+export const MARK_ORDER: MarkType[] = [
+  'mention',
+  'link',
+  'textColor',
+  'bgColor',
+  'bold',
+  'italic',
+  'underline',
+  'strike',
+  'code',
+];
+
+/** Canonical key for set comparison (link by href, mention by id+label, color by key). */
+function markKey(m: Mark): string {
+  if (m.type === 'link') return `link:${m.href}`;
+  if (m.type === 'mention') return `mention:${m.id}:${m.label}`;
+  if (m.type === 'textColor' || m.type === 'bgColor') return `${m.type}:${m.color}`;
+  return m.type;
+}
+
+/**
+ * Order-insensitive string signature of a mark SET. Two runs with the same
+ * signature carry identical formatting. Used by the editor's renderer to fold the
+ * run's formatting into its React key, so that when a run's MARK STRUCTURE changes
+ * (e.g. bold/italic/underline added over an already-colored run) React replaces
+ * the run's subtree cleanly instead of surgically re-wrapping an existing
+ * `contentEditable` text node in place — which can orphan the node (stray leftover
+ * text) or re-point its color span.
+ */
+export function marksSignature(marks: Mark[]): string {
+  if (marks.length === 0) return '';
+  // Sorted so order doesn't matter. A theoretical separator collision (a mark key can
+  // embed free-form href/label text) is harmless: this signature is only ever combined
+  // with the run's index in a React key, which already guarantees uniqueness — at worst
+  // a collision would miss a remount (the pre-fix behavior), never break rendering.
+  return marks.map(markKey).sort().join(' ');
+}
+
+/** Order-insensitive set equality (link href included). */
+export function marksEqual(a: Mark[], b: Mark[]): boolean {
+  if (a === b) return true;
+  if (a.length !== b.length) return false;
+  if (a.length === 0) return true;
+  if (a.length === 1) return markKey(a[0]) === markKey(b[0]);
+  const ka = a.map(markKey).sort();
+  const kb = b.map(markKey).sort();
+  return ka.every((k, i) => k === kb[i]);
+}
+
+/** Returns `true` iff `marks` contains a mark of the given `type`. */
+export function hasMark(marks: Mark[], type: MarkType): boolean {
+  return marks.some((m) => m.type === type);
+}
+
+/** Immutable add; replaces an existing mark of the same type (e.g. new link href). */
+export function withMark(marks: Mark[], mark: Mark): Mark[] {
+  return [...marks.filter((m) => m.type !== mark.type), mark];
+}
+
+/** Immutable remove; returns a new array with all marks of `type` filtered out. */
+export function withoutMark(marks: Mark[], type: MarkType): Mark[] {
+  return marks.filter((m) => m.type !== type);
+}
+
+/**
+ * Immutable toggle: if `marks` already contains `mark.type`, removes it;
+ * otherwise adds `mark` (replacing any existing mark of the same type).
+ * Returns a new array — never mutates the input.
+ */
+export function toggleMark(marks: Mark[], mark: Mark): Mark[] {
+  return hasMark(marks, mark.type) ? withoutMark(marks, mark.type) : withMark(marks, mark);
+}

package/src/components/RichText/engine/mdToHtml.ts

@@ -0,0 +1,178 @@
+// mdToHtml.ts — minimal Markdown → HTML-subset converter (INTERNAL). Emits only
+// the tags fromHtml understands (h1-6, p, pre>code, blockquote, ul/ol/li, and
+// inline strong/em/del/code/a), so fromMarkdown = fromHtml(mdToHtml(md)) reuses
+// one mapping. CommonMark + GFM strikethrough subset. Never throws.
+
+import { escapeHtml, escapeAttr } from './escape';
+
+const LIST_RE = /^(\s*)([-*+]|\d+[.)])\s+(.*)$/;
+
+/** Convert inline Markdown to HTML. Unbalanced markers degrade to literal text. */
+function inline(src: string): string {
+  let out = '';
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    if (c === '\\' && i + 1 < src.length) {
+      out += escapeHtml(src[i + 1]);
+      i += 2;
+      continue;
+    }
+    if (c === '`') {
+      const end = src.indexOf('`', i + 1);
+      if (end !== -1) {
+        out += '<code>' + escapeHtml(src.slice(i + 1, end)) + '</code>';
+        i = end + 1;
+        continue;
+      }
+    }
+    if (c === '!' && src[i + 1] === '[') {
+      const m = /^!\[([^\]]*)\]\(([^)]*)\)/.exec(src.slice(i));
+      if (m) {
+        out += inline(m[1]); // image → its alt text (not a link, not an <img>)
+        i += m[0].length;
+        continue;
+      }
+    }
+    if (c === '[') {
+      // Allow backslash-escaped `]` inside the link text (toMarkdown escapes a
+      // literal `]` to `\]`); a plain `[^\]]*` would stop at it and lose the link.
+      const m = /^\[((?:[^\]\\]|\\.)*)\]\(([^)]*)\)/.exec(src.slice(i));
+      if (m) {
+        out += '<a href="' + escapeAttr(m[2].trim()) + '">' + inline(m[1]) + '</a>';
+        i += m[0].length;
+        continue;
+      }
+    }
+    // Triple marker → bold+italic. Checked before the double marker so `***x***`
+    // isn't mis-split into `**` + a stray `*`.
+    if ((c === '*' || c === '_') && src[i + 1] === c && src[i + 2] === c) {
+      const marker = c + c + c;
+      const end = src.indexOf(marker, i + 3);
+      if (end > i + 3) {
+        out += '<strong><em>' + inline(src.slice(i + 3, end)) + '</em></strong>';
+        i = end + 3;
+        continue;
+      }
+    }
+    if ((c === '*' || c === '_') && src[i + 1] === c) {
+      const marker = c + c;
+      const end = src.indexOf(marker, i + 2);
+      if (end !== -1) {
+        out += '<strong>' + inline(src.slice(i + 2, end)) + '</strong>';
+        i = end + 2;
+        continue;
+      }
+    }
+    if (c === '~' && src[i + 1] === '~') {
+      const end = src.indexOf('~~', i + 2);
+      if (end !== -1) {
+        out += '<del>' + inline(src.slice(i + 2, end)) + '</del>';
+        i = end + 2;
+        continue;
+      }
+    }
+    // Emphasis: require non-space immediately inside the markers (a minimal
+    // CommonMark flanking check) so `a _ b _ c` stays literal instead of
+    // wrapping whitespace in <em>.
+    if ((c === '*' || c === '_') && src[i + 1] !== ' ') {
+      const end = src.indexOf(c, i + 1);
+      if (end > i + 1 && src[end - 1] !== ' ') {
+        out += '<em>' + inline(src.slice(i + 1, end)) + '</em>';
+        i = end + 1;
+        continue;
+      }
+    }
+    out += escapeHtml(c);
+    i += 1;
+  }
+  return out;
+}
+
+/** Parse one list starting at `lines[start]` whose marker indent is `indent`. */
+function parseList(lines: string[], start: number, indent: number): [string, number] {
+  const ordered = /\d/.test(LIST_RE.exec(lines[start])![2]);
+  const tag = ordered ? 'ol' : 'ul';
+  let i = start;
+  let html = `<${tag}>`;
+  while (i < lines.length) {
+    const m = LIST_RE.exec(lines[i]);
+    if (!m || m[1].length < indent) break;
+    if (m[1].length > indent) break; // deeper line handled as nested below
+    let item = '<li>' + inline(m[3].trim());
+    i += 1;
+    while (i < lines.length) {
+      const deeper = LIST_RE.exec(lines[i]);
+      if (deeper && deeper[1].length > indent) {
+        const [nested, consumed] = parseList(lines, i, deeper[1].length);
+        item += nested;
+        i = consumed;
+      } else break;
+    }
+    item += '</li>';
+    html += item;
+  }
+  return [html + `</${tag}>`, i];
+}
+
+/** Convert a Markdown string to the HTML subset fromHtml understands. */
+export function mdToHtml(md: string): string {
+  const lines = md.replace(/\r\n?/g, '\n').split('\n');
+  const out: string[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.trim() === '') {
+      i += 1;
+      continue;
+    }
+    const fence = /^(```|~~~)/.exec(line);
+    if (fence) {
+      i += 1;
+      const code: string[] = [];
+      while (i < lines.length && !lines[i].startsWith(fence[1])) {
+        code.push(lines[i]);
+        i += 1;
+      }
+      if (i < lines.length) i += 1; // skip closing fence
+      out.push('<pre><code>' + escapeHtml(code.join('\n')) + '</code></pre>');
+      continue;
+    }
+    const h = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (h) {
+      const level = h[1].length;
+      out.push(`<h${level}>` + inline(h[2].trim()) + `</h${level}>`);
+      i += 1;
+      continue;
+    }
+    if (/^>\s?/.test(line)) {
+      const quote: string[] = [];
+      while (i < lines.length && /^>\s?/.test(lines[i])) {
+        quote.push(lines[i].replace(/^>\s?/, ''));
+        i += 1;
+      }
+      out.push('<blockquote>' + mdToHtml(quote.join('\n')) + '</blockquote>');
+      continue;
+    }
+    if (LIST_RE.test(line)) {
+      const [html, consumed] = parseList(lines, i, LIST_RE.exec(line)![1].length);
+      out.push(html);
+      i = consumed;
+      continue;
+    }
+    const buf: string[] = [];
+    while (
+      i < lines.length &&
+      lines[i].trim() !== '' &&
+      !/^(```|~~~)/.test(lines[i]) &&
+      !/^#{1,6}\s/.test(lines[i]) &&
+      !/^>\s?/.test(lines[i]) &&
+      !LIST_RE.test(lines[i])
+    ) {
+      buf.push(lines[i].trim());
+      i += 1;
+    }
+    out.push('<p>' + inline(buf.join(' ')) + '</p>');
+  }
+  return out.join('');
+}

package/src/components/RichText/engine/model.ts

@@ -0,0 +1,157 @@
+// model.ts — RichText document model types + constructors. Pure data; no DOM.
+
+/**
+ * All supported block-level content types. `heading` requires a `level`; list
+ * types (`bullet_item`, `ordered_item`) accept a `depth` for nesting.
+ */
+export type BlockType =
+  | 'paragraph'
+  | 'heading'
+  | 'bullet_item'
+  | 'ordered_item'
+  | 'blockquote'
+  | 'code_block'
+  | 'attachment';
+
+/**
+ * All supported inline mark types. `link` carries `href`; `mention` carries `id` + `label`;
+ * `textColor`/`bgColor` carry a palette `color` KEY (e.g. `'red'`), never a raw hex — see
+ * `colorMarks.ts` for the key → CSS-custom-property resolution.
+ */
+export type MarkType =
+  | 'bold'
+  | 'italic'
+  | 'underline'
+  | 'strike'
+  | 'code'
+  | 'link'
+  | 'mention'
+  | 'textColor'
+  | 'bgColor';
+
+/**
+ * A formatting mark. Flags carry no data; `link` carries an href; `mention` an id + label.
+ * `textColor`/`bgColor` carry a palette `color` KEY (e.g. `'red'`), not a raw value — the key
+ * resolves to a token-backed CSS custom property via `colorMarks.ts`.
+ */
+export type Mark =
+  | { type: 'bold' }
+  | { type: 'italic' }
+  | { type: 'underline' }
+  | { type: 'strike' }
+  | { type: 'code' }
+  | { type: 'link'; href: string }
+  | { type: 'mention'; id: string; label: string }
+  | { type: 'textColor'; color: string }
+  | { type: 'bgColor'; color: string };
+
+/** A run of text sharing exactly one mark set. */
+export interface Inline {
+  text: string;
+  marks: Mark[];
+}
+
+/** One line-level block. Lists are flat items addressed by `depth` (no tree). */
+export interface Block {
+  /** Stable id → React keys + position stability. */
+  id: string;
+  type: BlockType;
+  /** Heading level, only for `type: 'heading'`. */
+  level?: 1 | 2 | 3;
+  /** List nesting depth (0-based), only for list items. */
+  depth?: number;
+  /** Inline content. An empty block holds a single empty run. */
+  inlines: Inline[];
+  /** Attachment block only (type === 'attachment'). The uploaded URL — absent while uploading. */
+  src?: string;
+  /** Attachment filename / chip label. */
+  name?: string;
+  /** Attachment MIME — `image/*` renders a preview, else a file chip. */
+  mime?: string;
+  /** Natural image dimensions (layout hints). */
+  width?: number;
+  height?: number;
+  /**
+   * Image alt text. Unlike every label prop in this library, an EMPTY string
+   * is honoured rather than treated as unset: `alt=""` is HTML's own marker
+   * for a decorative image, so it renders literally instead of falling back to
+   * the filename.
+   */
+  alt?: string;
+  /** Attachment image alignment within the editor width. Absent = left. */
+  align?: 'left' | 'center' | 'right';
+  /** Attachment upload state. `ready`/absent = final. */
+  status?: 'uploading' | 'ready' | 'error';
+  /**
+   * Why the last upload failed, shown on the `error` block. Set only from an
+   * `UploadError` rejection; cleared on retry. Transient like `status` — an
+   * error block never serializes to HTML/Markdown.
+   */
+  uploadError?: string;
+}
+
+/** A rich-text document: an ordered list of blocks. */
+export interface RichDoc {
+  blocks: Block[];
+}
+
+/** A point in the document: a character offset within a block. */
+export interface Point {
+  blockId: string;
+  /** 0..blockLength */
+  offset: number;
+}
+
+/** A selection / span. `anchor` may come before or after `focus`. */
+export interface Range {
+  anchor: Point;
+  focus: Point;
+}
+
+// Module-local monotonic id source. NOT Math.random/Date.now (unavailable in
+// some contexts + non-deterministic). Unique within a session — enough for keys.
+let idCounter = 0;
+/**
+ * Generate a session-unique block id. Ids are monotonically incrementing strings
+ * (`rt1`, `rt2`, …) — deterministic within a session but NOT across page reloads.
+ * Use the `id` field in `CreateBlockAttrs` to pin ids in tests.
+ */
+export function nextId(): string {
+  idCounter += 1;
+  return `rt${idCounter}`;
+}
+
+/**
+ * Optional attributes for `createBlock`. All fields are optional.
+ * - `level` — heading level (1–3); only meaningful for `type: 'heading'`.
+ * - `depth` — list nesting depth (0-based); only meaningful for list items.
+ * - `marks` — marks applied to the initial text run.
+ * - `id` — pin the block id (useful for tests and deterministic seeding).
+ */
+export interface CreateBlockAttrs {
+  level?: 1 | 2 | 3;
+  depth?: number;
+  marks?: Mark[];
+  /** Pin the id (tests / deterministic construction). */
+  id?: string;
+}
+
+/** Build a block. Empty `text` → a single empty run. */
+export function createBlock(type: BlockType, text = '', attrs: CreateBlockAttrs = {}): Block {
+  const { level, depth, marks = [], id } = attrs;
+  const inlines: Inline[] = text === '' ? [{ text: '', marks: [] }] : [{ text, marks }];
+  const block: Block = { id: id ?? nextId(), type, inlines };
+  if (level !== undefined) block.level = level;
+  if (depth !== undefined) block.depth = depth;
+  return block;
+}
+
+/** A document with one empty paragraph. */
+export function emptyDoc(): RichDoc {
+  return { blocks: [createBlock('paragraph')] };
+}
+
+/** Build a paragraph-per-line document from plain text (a demo/seed helper). */
+export function docFromText(text: string): RichDoc {
+  return { blocks: text.split('\n').map((line) => createBlock('paragraph', line)) };
+}

package/src/components/RichText/engine/position.ts

@@ -0,0 +1,118 @@
+// position.ts — Layer C. Point/range helpers over a RichDoc.
+import type { RichDoc, Block, Point, Range, Mark } from './model';
+import { runsLength } from './inlines';
+
+/** Total character length of a block (sum of all inline run lengths). */
+export function blockLength(block: Block): number {
+  return runsLength(block.inlines);
+}
+
+/**
+ * The `Range` spanning an entire block — `offset 0` to its full length. Returns
+ * `null` when `blockId` is not found. Used by block-level actions (e.g. coloring
+ * a whole block from the block menu) that target a block rather than an explicit
+ * text selection.
+ */
+export function wholeBlockRange(doc: RichDoc, blockId: string): Range | null {
+  const idx = findBlockIndex(doc, blockId);
+  if (idx === -1) return null;
+  const block = doc.blocks[idx];
+  return {
+    anchor: { blockId, offset: 0 },
+    focus: { blockId, offset: blockLength(block) },
+  };
+}
+
+/**
+ * Returns the index of the block with `blockId` in `doc.blocks`, or `-1` if
+ * not found. Used by transforms to locate blocks before mutation.
+ */
+export function findBlockIndex(doc: RichDoc, blockId: string): number {
+  return doc.blocks.findIndex((b) => b.id === blockId);
+}
+
+/** Document order: -1 if a before b, 1 if after, 0 if equal. */
+export function comparePoints(doc: RichDoc, a: Point, b: Point): -1 | 0 | 1 {
+  if (a.blockId === b.blockId) {
+    return a.offset < b.offset ? -1 : a.offset > b.offset ? 1 : 0;
+  }
+  const ia = findBlockIndex(doc, a.blockId);
+  const ib = findBlockIndex(doc, b.blockId);
+  return ia < ib ? -1 : ia > ib ? 1 : 0;
+}
+
+/**
+ * The marks carried by the character immediately before `point` (raw — includes
+ * `mention`). Empty (`[]`) at a block start (`offset <= 0`) or when the block is
+ * not found. This primitive stays mark-agnostic; typing-inheritance paths use
+ * {@link marksForTypedText}, which applies the exclusions.
+ */
+export function marksBeforeCaret(doc: RichDoc, point: Point): Mark[] {
+  const idx = findBlockIndex(doc, point.blockId);
+  if (idx === -1 || point.offset <= 0) return [];
+  let pos = 0;
+  for (const run of doc.blocks[idx].inlines ?? []) {
+    const end = pos + run.text.length;
+    if (point.offset - 1 >= pos && point.offset - 1 < end) return run.marks;
+    pos = end;
+  }
+  return [];
+}
+
+/**
+ * The marks carried by the character immediately AFTER `point` (raw, like
+ * {@link marksBeforeCaret}). Empty (`[]`) at a block end, where no character
+ * follows. Typing-inheritance paths pair it with `marksBeforeCaret` to tell a
+ * caret INSIDE a run from one resting against its trailing edge.
+ */
+export function marksAfterCaret(doc: RichDoc, point: Point): Mark[] {
+  const idx = findBlockIndex(doc, point.blockId);
+  if (idx === -1 || point.offset < 0) return [];
+  let pos = 0;
+  for (const run of doc.blocks[idx].inlines ?? []) {
+    const end = pos + run.text.length;
+    if (point.offset >= pos && point.offset < end) return run.marks;
+    pos = end;
+  }
+  return [];
+}
+
+/**
+ * The marks text typed at `point` inherits — those of the preceding character,
+ * minus the two that must not grow when the caret merely abuts them:
+ * - `mention`, never (typed text never extends a mention chip);
+ * - `link`, unless the FOLLOWING character carries the same href, i.e. the caret
+ *   sits strictly inside the link rather than against its trailing edge.
+ *
+ * Without the `link` rule, typing after a link appends into the link's TEXT while
+ * its href stays put. Under `renderLink` that is invisible — the widget renders
+ * from the href — so the characters vanish and the caret appears frozen.
+ *
+ * The single source of this rule: both `insertText` and the editor's pending-mark
+ * staging read it, so a mark toggled at a link's edge can't reinstate the link.
+ */
+export function marksForTypedText(doc: RichDoc, point: Point): Mark[] {
+  const after = marksAfterCaret(doc, point);
+  return marksBeforeCaret(doc, point).filter((m) => {
+    if (m.type === 'mention') return false;
+    if (m.type === 'link') return after.some((a) => a.type === 'link' && a.href === m.href);
+    return true;
+  });
+}
+
+/** A collapsed range at a single point. */
+export function collapsedRange(blockId: string, offset = 0): Range {
+  return { anchor: { blockId, offset }, focus: { blockId, offset } };
+}
+
+/** Returns `true` iff `range` is collapsed — anchor and focus point to the same position. */
+export function isCollapsed(range: Range): boolean {
+  return range.anchor.blockId === range.focus.blockId && range.anchor.offset === range.focus.offset;
+}
+
+/** Normalize a range so `start` ≤ `end` in document order. */
+export function orderedRange(doc: RichDoc, range: Range): { start: Point; end: Point } {
+  return comparePoints(doc, range.anchor, range.focus) <= 0
+    ? { start: range.anchor, end: range.focus }
+    : { start: range.focus, end: range.anchor };
+}