Skip to content

Write HTML. Render video. Built for agents.

22.3 KB
Raw Blame
/**
 * Styling a run of characters inside an element being edited in place.
 *
 * Not `document.execCommand`. That is deprecated, and what it emits varies by
 * browser between `<font>`, a class, and an inline style depending on
 * `styleWithCSS`. The output of this goes into the user's composition file, so
 * it has to be one predictable shape, and the shape is a `<span>` carrying an
 * inline style.
 *
 * Not DOM range surgery either, which is the obvious way and the wrong one.
 * Wrapping a range in a span is three lines and then every interesting case is
 * a special case: recolouring nests spans that shadow each other, removing a
 * style cannot reach the ancestor that set it, and styling across an existing
 * run's boundary has to split it. Each fix is a new branch and the branches
 * interact.
 *
 * So the element is read into a flat list of styled runs, the styling is
 * applied to a span of characters in that list, and the element is rebuilt
 * from it. Replacing, removing, splitting and merging all stop being cases:
 * the rebuild emits one span per distinct run and cannot nest or duplicate,
 * whatever was there before. Text elements in a composition are a headline or
 * a sentence, so reading and rebuilding one is not a cost worth avoiding.
 */

import {
  isRichTextFormattingAttribute,
  isRichTextFormattingStyle,
  isRichTextFormattingTag,
} from "@hyperframes/core/rich-text-sanitize";

/** One stretch of characters that are all styled the same way. */
interface StyledRun {
  text: string;
  style: Record<string, string>;
  /**
   * The child element these characters came out of, when they came out of one.
   *
   * Carried because an element's children are not always anonymous formatting:
   * the design panel keeps them as text layers and tracks each by an attribute
   * on it. Rebuilding from style alone emitted fresh, bare spans, which threw
   * that identity away — after colouring a single word the panel could no
   * longer match a layer to its source, so every edit it offered failed to
   * save. The rebuild puts the identity back on the run that still holds it.
   */
  origin: Element | null;
  /**
   * That identity as a value, so two runs can be compared without comparing
   * the nodes they came from. A child with nothing on it but a style has no
   * identity to lose, and merges with its neighbour exactly as before.
   */
  identity: string;
  painter?: Element | null;
}

export type InlineStyleDelta = Record<string, string | null>;

/**
 * Tags that mean a style. They are read as styling and written back as spans,
 * so there is one representation to reason about instead of two that have to
 * agree. Rendering is unchanged; the markup for an edited element is not.
 */
const TAG_STYLES: Record<string, Record<string, string>> = {
  B: { "font-weight": "700" },
  STRONG: { "font-weight": "700" },
  I: { "font-style": "italic" },
  EM: { "font-style": "italic" },
  U: { "text-decoration-line": "underline" },
};

/**
 * Stands in for a `<br>` while the element is a flat string, so a break counts
 * as one character and offsets survive the rebuild.
 *
 * Not a newline. Compositions are written across lines, so an element's text
 * routinely contains real newlines that are only source formatting, and using
 * one as the marker turned every one of them into a visible line break the
 * first time a word was styled. A NUL never appears: the HTML parser replaces
 * it with U+FFFD, so no document can contain one.
 */
const BREAK = "\u0000";

/** Apply `style` to the characters the range covers, then rebuild the element. */
export function applyInlineStyle(range: Range, style: InlineStyleDelta): void {
  if (range.collapsed) return;
  // Resolved from where the selection starts, not from where it and its end
  // happen to meet. A selection dragged past the element's edge meets its end
  // at an ancestor, and taking that as the host would rebuild the ancestor:
  // every sibling element inside it flattened into text by an edit that was
  // meant to colour a word.
  const host = editingHost(range.startContainer);
  if (!host || !holdsBothEnds(host, range)) return;

  const runs = readRuns(host);
  const span = graphemeBounds(
    runs,
    offsetOf(host, range.startContainer, range.startOffset),
    offsetOf(host, range.endContainer, range.endOffset),
  );
  if (!span) return;

  const next = restyle(runs, span.start, span.end, style);
  render(host, next);
  reconcileFillColors(host);
  selectRange(host, span.start, span.end);
}

/**
 * Whether something above the run is painting the glyphs a different colour.
 *
 * `-webkit-text-fill-color` inherits and paints the glyph fill, so an ancestor
 * that sets it wins over any `color` a descendant sets. A composition doing so
 * is not doing anything wrong, but from the editor it reads as the colour
 * picker being broken: the run is saved with the colour asked for and renders
 * in someone else's.
 *
 * Asked of the rendered span rather than worked out from the stylesheet. Its
 * own `color` is set, so its computed colour IS the one that was asked for, and
 * if the fill differs from it then something else is painting it. Both sides
 * come from the same computed style, so neither notation nor inheritance has to
 * be untangled by hand.
 */
function reconcileFillColors(host: Element): void {
  const view = host.ownerDocument.defaultView;
  if (!view?.getComputedStyle) return;
  for (const span of host.querySelectorAll<HTMLElement>("span")) {
    if (!span.style.color) continue;
    // A generated mirror repeats the run's colour. Remove that before asking
    // what would paint the run without it; an authored, different fill stays
    // in place long enough to be detected as the overpaint it is.
    const existingFill = span.style.getPropertyValue("-webkit-text-fill-color");
    if (existingFill === span.style.color) {
      span.style.removeProperty("-webkit-text-fill-color");
    }
    const computed = view.getComputedStyle(span) as CSSStyleDeclaration & {
      webkitTextFillColor?: string;
    };
    const fill = computed.webkitTextFillColor;
    if (!fill || !computed.color) continue;
    if (fill !== computed.color) {
      span.style.setProperty("-webkit-text-fill-color", span.style.color);
    }
  }
}

/**
 * The offsets to style, widened so they never fall inside a character.
 *
 * Selection offsets count UTF-16 units, while one visible character can be a
 * surrogate pair, combining sequence, flag, modifier sequence, or a family
 * joined by zero-width joiners. Splitting any of those across spans corrupts
 * what the user selected even when every individual code point remains valid.
 */
function graphemeBounds(
  runs: StyledRun[],
  start: number | null,
  end: number | null,
): { start: number; end: number } | null {
  if (start === null || end === null || start >= end) return null;
  const text = runs.map((run) => run.text).join("");
  const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
  const boundaries = [0, ...Array.from(segmenter.segment(text), atEndOfSegment)];
  return {
    start: boundaryAtOrBefore(boundaries, start),
    end: boundaries.find((boundary) => boundary >= end) ?? end,
  };
}

function atEndOfSegment({ index, segment }: Intl.SegmentData): number {
  return index + segment.length;
}

function boundaryAtOrBefore(boundaries: number[], offset: number): number {
  let previous = offset;
  for (const boundary of boundaries) {
    if (boundary > offset) return previous;
    previous = boundary;
  }
  return previous;
}

/** Whether the whole selection lives inside this element. */
function holdsBothEnds(host: Element, range: Range): boolean {
  return host.contains(range.startContainer) && host.contains(range.endContainer);
}

export interface InlineStyleChar {
  char: string;
  style: Readonly<Record<string, string>>;
  painter: Element | null;
}

/** Every character the range covers with its style, or null when it covers none. */
export function readCoveredInlineStyleChars(range: Range): readonly InlineStyleChar[] | null {
  const host = editingHost(range.startContainer);
  if (!host || !holdsBothEnds(host, range)) return null;
  const start = offsetOf(host, range.startContainer, range.startOffset);
  const end = offsetOf(host, range.endContainer, range.endOffset);
  if (start === null || end === null) return null;
  const collapsed = start === end;
  const covered = charRuns(readRuns(host))
    .slice(collapsed ? Math.max(0, start - 1) : start, collapsed ? Math.max(1, start) : end)
    .map((entry) => ({ char: entry.char, style: entry.style, painter: entry.painter ?? null }));
  return covered.length > 0 ? covered : null;
}

/**
 * The element the caret is in: the one made editable, never a span inside it.
 *
 * Reading the nearest element instead would rebuild only the run the caret
 * happened to land in, which is how a recolour ends up nested inside the
 * colour it was meant to replace.
 */
function editingHost(node: Node): HTMLElement | null {
  let element = (node.nodeType === 1 ? node : node.parentElement) as HTMLElement | null;
  const editable = element?.closest<HTMLElement>("[contenteditable]");
  if (editable) {
    return editable.getAttribute("contenteditable")?.toLowerCase() === "false" ? null : editable;
  }
  // No open edit, so climb out of the formatting to the element that owns it.
  while (element?.parentElement && isRichTextFormattingTag(element.tagName)) {
    element = element.parentElement;
  }
  return element;
}

/** Read the element as a flat list of runs, in document order. */
interface RunWalkFrame {
  node: Node;
  inherited: Record<string, string>;
  origin: Element | null;
}

function readRuns(host: Element): StyledRun[] {
  const runs: StyledRun[] = [];
  const pending: RunWalkFrame[] = Array.from(
    host.childNodes,
    (node): RunWalkFrame => ({ node, inherited: {}, origin: null }),
  ).reverse();
  for (let frame = pending.pop(); frame; frame = pending.pop()) {
    pending.push(...visitRunFrame(frame, runs));
  }
  return runs;
}

function visitRunFrame(frame: RunWalkFrame, runs: StyledRun[]): RunWalkFrame[] {
  const { node, inherited, origin } = frame;
  if (node.nodeType === 3) {
    const text = node.textContent ?? "";
    if (text) runs.push({ ...styledRun(text, inherited, origin), painter: node.parentElement });
    return [];
  }
  if (!isStyleElement(node)) return [];
  const element = node;
  if (element.tagName === "BR") {
    runs.push(styledRun(BREAK, inherited, origin));
    return [];
  }
  return childRunFrames(element, inherited, origin);
}

function isStyleElement(node: Node): node is HTMLElement {
  return node.nodeType === 1 && "style" in node;
}

function styledRun(text: string, style: Record<string, string>, origin: Element | null): StyledRun {
  return { text, style, origin, identity: identityOf(origin) };
}

function childRunFrames(
  element: HTMLElement,
  inherited: Record<string, string>,
  origin: Element | null,
): RunWalkFrame[] {
  const formatting = isRichTextFormattingTag(element.tagName);
  const nextInherited = formatting
    ? { ...inherited, ...TAG_STYLES[element.tagName], ...ownStyle(element) }
    : inherited;
  // The outermost formatting child that carries anything is the one the panel
  // knows as a layer. Tags the sanitizer unwraps cannot own a layer.
  const nextOrigin =
    formatting && !origin && preservedAttributes(element).size > 0 ? element : origin;
  return Array.from(
    element.childNodes,
    (node): RunWalkFrame => ({ node, inherited: nextInherited, origin: nextOrigin }),
  ).reverse();
}

/** A child's identity as a comparable string, empty when it has none. */
function identityOf(element: Element | null): string {
  if (!element) return "";
  return JSON.stringify([...preservedAttributes(element)].sort(([a], [b]) => (a < b ? -1 : 1)));
}

function ownStyle(element: HTMLElement): Record<string, string> {
  const style: Record<string, string> = {};
  for (let index = 0; index < element.style.length; index += 1) {
    const property = element.style.item(index);
    if (!property) continue;
    const value = element.style.getPropertyValue(property);
    if (isRichTextFormattingStyle(property, value)) style[property] = value;
  }
  return style;
}

/** One entry per character, which is the easiest thing to slice and compare. */
function charRuns(runs: StyledRun[]): Array<Omit<StyledRun, "text"> & { char: string }> {
  const perChar: Array<Omit<StyledRun, "text"> & { char: string }> = [];
  for (const run of runs) {
    // By UTF-16 unit, not code point: `restyle` indexes this list with selection
    // offsets, which count units, so an emoji has to stay two entries long.
    for (let index = 0; index < run.text.length; index += 1) {
      perChar.push({
        char: run.text[index] ?? "",
        style: run.style,
        origin: run.origin,
        identity: run.identity,
        painter: run.painter,
      });
    }
  }
  return perChar;
}

/** Apply the delta to `[start, end)` and hand back runs covering the element. */
function restyle(
  runs: StyledRun[],
  start: number,
  end: number,
  delta: InlineStyleDelta,
): StyledRun[] {
  const text = runs.map((run) => run.text).join("");
  const perChar = charRuns(runs);
  const next: StyledRun[] = [];
  // Indexed by UTF-16 unit, not by code point: `perChar`, `start` and `end` all
  // count units, and spreading the string would count a surrogate pair once and
  // slide every index after an emoji.
  for (let index = 0; index < text.length; index += 1) {
    appendChar(
      next,
      text[index] ?? "",
      charAfter(perChar[index], index >= start && index < end, delta),
    );
  }
  return next;
}

/** What one character is styled with once the delta has been applied to it. */
function charAfter(
  at: Omit<StyledRun, "text"> | undefined,
  inside: boolean,
  delta: InlineStyleDelta,
): Omit<StyledRun, "text"> {
  const style = at?.style ?? {};
  return {
    style: inside ? withDelta(style, delta) : style,
    origin: at?.origin ?? null,
    identity: at?.identity ?? "",
  };
}

/**
 * One character onto the run list, merged into the run before it when they
 * belong together.
 *
 * Merged as it is built, so equal neighbours never become two spans. Two that
 * the design panel tracks as separate layers stay apart even when they now look
 * identical, because merging them deletes one of them.
 */
function appendChar(runs: StyledRun[], char: string, at: Omit<StyledRun, "text">): void {
  const last = runs[runs.length - 1];
  if (last && last.identity === at.identity && sameStyle(last.style, at.style)) {
    last.text += char;
    return;
  }
  runs.push({ text: char, ...at });
}

function withDelta(style: Record<string, string>, delta: InlineStyleDelta): Record<string, string> {
  const next = { ...style };
  for (const [property, value] of Object.entries(delta)) {
    if (value === null) delete next[property];
    else next[property] = value;
  }
  return next;
}

function sameStyle(a: Record<string, string>, b: Record<string, string>): boolean {
  return styleKey(a) === styleKey(b);
}

/** Sorted, so two runs styled the same way compare equal whatever the order. */
function styleKey(style: Record<string, string>): string {
  return Object.keys(style)
    .sort()
    .map((property) => `${property}: ${style[property]}`)
    .join("; ");
}

/** Rebuild the element: bare text where there is no styling, one span where there is. */
function render(host: Element, runs: StyledRun[]): void {
  const doc = host.ownerDocument;
  const nodes = runNodes(doc, runs);
  host.replaceChildren();
  if (nodes.length > 1 && laysOutItsChildren(host)) {
    // Wrapped, because in a flex or grid container every child is an item to
    // be laid out. Text that was one anonymous item becomes several boxes the
    // moment a word inside it is coloured, and the element visibly reflows:
    // centring, wrapping and order all change under an edit that was only ever
    // meant to change a colour. One wrapper keeps it a single item, and the
    // runs inside it stay inline text.
    const wrapper = doc.createElement("span");
    wrapper.append(...nodes);
    host.append(wrapper);
    return;
  }
  host.append(...nodes);
}

function runNodes(doc: Document, runs: StyledRun[]): Node[] {
  const nodes: Node[] = [];
  // One span per origin keeps its attributes: an identity that appeared twice
  // would be two layers claiming to be the same one. A run split off from an
  // origin is a new layer and is written as one.
  const claimed = new Set<Element>();
  for (const run of runs) {
    const carried =
      run.origin && !claimed.has(run.origin) ? preservedAttributes(run.origin) : new Map();
    if (carried.size > 0 && run.origin) claimed.add(run.origin);
    nodes.push(...runNode(doc, run, carried));
  }
  return nodes;
}

/**
 * One run's nodes: its line breaks as `<br>`, and its text as bare text when it
 * has nothing to carry or a span when it has. The identity goes on the first
 * piece only, so a run broken across lines does not claim it twice.
 */
function runNode(doc: Document, run: StyledRun, carried: Map<string, string>): Node[] {
  const key = styleKey(run.style);
  const nodes: Node[] = [];
  for (const [index, piece] of run.text.split(BREAK).entries()) {
    if (index > 0) nodes.push(doc.createElement("br"));
    if (!piece) continue;
    if (!key && carried.size === 0) {
      nodes.push(doc.createTextNode(piece));
      continue;
    }
    const span = doc.createElement("span");
    for (const [name, value] of carried) span.setAttribute(name, value);
    if (key) span.setAttribute("style", key);
    span.textContent = piece;
    nodes.push(span);
    carried.clear();
  }
  return nodes;
}

/**
 * The one attribute the writer assigns rather than the author.
 *
 * Left out on purpose. It is stamped onto every element on the way to disk, so
 * carrying it preserves nothing — and it made the wrapper this rebuild adds
 * inside a flex container look like a layer as soon as the file had been saved
 * once, which put it back to shadowing the real layers underneath it.
 */
const DERIVED_ATTR = "data-hf-id";

/**
 * What a child carries besides its styling: the identity the design panel
 * tracks it by. Its style is not copied — that is what the run holds, already
 * merged with whatever the edit changed.
 */
function preservedAttributes(element: Element): Map<string, string> {
  const kept = new Map<string, string>();
  for (const name of element.getAttributeNames()) {
    if (name === "style" || name === DERIVED_ATTR) continue;
    const value = element.getAttribute(name) ?? "";
    if (isRichTextFormattingAttribute(name, value)) kept.set(name, value);
  }
  return kept;
}

/** Displays whose children are boxes it positions, rather than text it flows. */
const LAYS_OUT_CHILDREN = new Set([
  "flex",
  "inline-flex",
  "grid",
  "inline-grid",
  // How line clamping is written, and it boxes its children like flex.
  "-webkit-box",
  "-webkit-inline-box",
]);

function laysOutItsChildren(host: Element): boolean {
  const view = host.ownerDocument.defaultView;
  if (!view) return false;
  return LAYS_OUT_CHILDREN.has(view.getComputedStyle(host).display);
}

/** Where a DOM position falls, counted in characters from the element's start. */
function offsetOf(host: Element, container: Node, containerOffset: number): number | null {
  // A position between children, expressed as a child index.
  if (container === host) {
    return Array.from(host.childNodes)
      .slice(0, containerOffset)
      .reduce((count, child) => count + subtreeCharLength(child), 0);
  }
  let count = 0;
  const walker = host.ownerDocument.createTreeWalker(
    host,
    NodeFilter.SHOW_TEXT | NodeFilter.SHOW_ELEMENT,
  );
  let node = walker.nextNode();
  while (node) {
    if (node === container) return count + containerOffset;
    count += charLength(node);
    node = walker.nextNode();
  }
  return null;
}

/** How many character positions a node occupies itself: its own text, or one
 *  for a break. An element contributes nothing; the walk visits its text. */
function charLength(node: Node): number {
  if (node.nodeType === 3) return (node.textContent ?? "").length;
  return nodeName(node) === "BR" ? 1 : 0;
}

/** The same count for a child and everything inside it, for a position given as
 *  a child index rather than a place in a text node. */
function subtreeCharLength(node: Node): number {
  let count = 0;
  const pending = [node];
  for (let current = pending.pop(); current; current = pending.pop()) {
    count += charLength(current);
    pending.push(...Array.from(current.childNodes));
  }
  return count;
}

function nodeName(node: Node): string {
  return node.nodeType === 1 ? (node as Element).tagName : "";
}

/** Put the selection back over the characters that were just styled. */
function selectRange(host: Element, start: number, end: number): void {
  const doc = host.ownerDocument;
  const selection = doc.defaultView?.getSelection();
  const from = positionAt(host, start);
  const to = positionAt(host, end);
  if (!selection || !from || !to) return;
  const range = doc.createRange();
  range.setStart(from.node, from.offset);
  range.setEnd(to.node, to.offset);
  selection.removeAllRanges();
  selection.addRange(range);
}

/**
 * The DOM position a character offset lands on, after a rebuild.
 *
 * Counts a line break as one position, because everything that produced the
 * offset did. This walked text nodes only, so in an element containing a `<br>`
 * it landed one character early for every break before the offset — and the
 * selection it put back was not the one that had just been styled.
 *
 * Which was invisible until a control fired more than once. The colour input
 * does: a native picker reports every sample while the pointer moves in it, and
 * each one restyled a selection that had walked one character further along
 * than the last. Choosing a colour for three characters painted a different
 * shade onto each character of the whole line.
 */
function positionAt(host: Element, offset: number): { node: Node; offset: number } | null {
  let count = 0;
  const walker = host.ownerDocument.createTreeWalker(
    host,
    NodeFilter.SHOW_TEXT | NodeFilter.SHOW_ELEMENT,
  );
  let node = walker.nextNode();
  let last: Node | null = null;
  while (node) {
    if (node.nodeType !== 3) {
      if (nodeName(node) === "BR") count += 1;
      node = walker.nextNode();
      continue;
    }
    const length = (node.textContent ?? "").length;
    if (count + length >= offset) return { node, offset: offset - count };
    count += length;
    last = node;
    node = walker.nextNode();
  }
  if (last) return { node: last, offset: (last.textContent ?? "").length };
  return { node: host, offset: 0 };
}