@react-x11/components 0.1.0 → 0.2.0

package/src/html/paint.ts

@@ -0,0 +1,605 @@
+// Painting a laid-out document.
+//
+// Two things make this fast enough to be the answer to "what happens on an
+// expose", which is one of the two numbers this component is built around:
+//
+//  - **Every box carries the bounds of everything it draws**, computed once
+//    after layout. A repaint intersects that against `paintDamage()` and
+//    skips whole subtrees, so an expose of a 40-pixel strip in a document
+//    ten thousand pixels tall touches the handful of boxes that overlap it.
+//    Ink bounds rather than the border box, because `overflow: visible` means
+//    a child may draw outside its parent and a box-rect test would cull
+//    something still on screen.
+//  - **A paragraph is one glyph batch.** ntk's `TextLayout.draw` emits every
+//    line it holds in a single composite, so paint draws each *layout* once
+//    rather than each line — which is why `LineText` records where the
+//    layout's origin goes rather than where its line does.
+//
+// The decorations under and over the glyphs are `src/richtext/runs.ts`'s,
+// unchanged: the runs handed to ntk were richtext's `TextRun`s, so what comes
+// back on the laid-out lines is exactly what that module already knows how to
+// draw.
+import {
+  canFill,
+  lineBands,
+  paintRunBackgrounds,
+  paintRunRules,
+} from '../richtext/runs.js';
+import type { FillContext } from '../richtext/runs.js';
+import { inkColor, isTransparent } from './css/values.js';
+import type { ComputedStyle } from './css/style.js';
+import { Box } from './layout/boxes.js';
+import type { BoxTree, LineBox } from './layout/boxes.js';
+import { layoutOffsets } from './layout/inline.js';
+
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** The context slice painting uses beyond `FillContext`. Everything optional
+ *  is missing on the mock backend, where paint is a structural no-op. */
+export interface PaintContext extends FillContext {
+  beginPath?(): void;
+  rect?(x: number, y: number, w: number, h: number): void;
+  roundRect?(x: number, y: number, w: number, h: number, radii: number[]): void;
+  fill?(): void;
+  clip?(): void;
+  drawImage?(image: unknown, ...args: number[]): void;
+}
+
+export interface PaintOptions {
+  /** Where the document's origin sits in the window. Scrolling is this. */
+  originX: number;
+  originY: number;
+  /** The rectangle being repainted, in window coordinates, or null for all. */
+  damage: Rect | null;
+  /** The document range the selection covers, in code units, or null. */
+  selection: { start: number; end: number } | null;
+  selectionColor: string | null;
+  /** A decoded image for an element, when the host has one. */
+  imageFor(box: Box): unknown | null;
+}
+
+/**
+ * The bounds of everything a box and its descendants draw, in document
+ * coordinates. Computed once per layout; the paint pass reads it.
+ */
+export function computePaintBounds(box: Box): Rect {
+  let x1 = box.x;
+  let y1 = box.y;
+  let x2 = box.x + box.width;
+  let y2 = box.y + box.height;
+  if (box.lines) {
+    for (const line of box.lines) {
+      x1 = Math.min(x1, line.x);
+      y1 = Math.min(y1, line.y);
+      x2 = Math.max(x2, line.x + line.width);
+      y2 = Math.max(y2, line.y + line.height);
+      for (const placed of line.atomics) {
+        const bounds = computePaintBounds(placed.box);
+        x1 = Math.min(x1, bounds.x);
+        y1 = Math.min(y1, bounds.y);
+        x2 = Math.max(x2, bounds.x + bounds.width);
+        y2 = Math.max(y2, bounds.y + bounds.height);
+      }
+    }
+  }
+  if (box.markerLayout) {
+    // The marker hangs in the padding to the left of the content, so it is
+    // outside the border box and has to widen the ink bounds or a repaint
+    // clipped to a narrow strip drops it.
+    x1 = Math.min(x1, box.markerX);
+    y1 = Math.min(y1, box.markerY);
+    x2 = Math.max(x2, box.markerX + box.markerLayout.width);
+    y2 = Math.max(y2, box.markerY + box.markerLayout.height);
+  }
+  for (const child of box.children) {
+    if (child.kind === 'text' || child.kind === 'break') continue;
+    const bounds = computePaintBounds(child);
+    x1 = Math.min(x1, bounds.x);
+    y1 = Math.min(y1, bounds.y);
+    x2 = Math.max(x2, bounds.x + bounds.width);
+    y2 = Math.max(y2, bounds.y + bounds.height);
+  }
+  box.boundsX = x1;
+  box.boundsY = y1;
+  box.boundsWidth = x2 - x1;
+  box.boundsHeight = y2 - y1;
+
+  if (box.lines) {
+    let tallest = 0;
+    for (const line of box.lines) tallest = Math.max(tallest, line.height);
+    box.maxLineHeight = tallest;
+  }
+  buildChildIndexes(box);
+
+  return { x: x1, y: y1, width: box.boundsWidth, height: box.boundsHeight };
+}
+
+/** Children lists past this size get the sorted viewport index; below it a
+ *  linear scan is cheaper than keeping one. */
+const PAINT_INDEX_MIN = 64;
+
+function buildChildIndexes(box: Box): void {
+  box.paintIndex = null;
+  box.positionedPaint = null;
+  let positioned: Box[] | null = null;
+  let paintable = 0;
+  for (const child of box.children) {
+    if (child.kind === 'text' || child.kind === 'break') continue;
+    if (child.outOfFlow) (positioned ??= []).push(child);
+    else paintable += 1;
+  }
+  if (positioned) {
+    // Pre-sorted once per layout instead of filtered and sorted per paint.
+    positioned.sort(byZIndex);
+    box.positionedPaint = positioned;
+  }
+  if (paintable < PAINT_INDEX_MIN) return;
+  const boxes: Box[] = [];
+  for (const child of box.children) {
+    if (child.kind === 'text' || child.kind === 'break' || child.outOfFlow)
+      continue;
+    boxes.push(child);
+  }
+  const order = boxes.map((_, i) => i);
+  order.sort((a, b) => boxes[a].boundsY - boxes[b].boundsY);
+  const sorted = order.map((i) => boxes[i]);
+  const prefixBottom: number[] = new Array<number>(sorted.length);
+  let running = -Infinity;
+  for (let i = 0; i < sorted.length; i += 1) {
+    running = Math.max(running, sorted[i].boundsY + sorted[i].boundsHeight);
+    prefixBottom[i] = running;
+  }
+  box.paintIndex = { boxes: sorted, order, prefixBottom };
+}
+
+/**
+ * The children whose ink can touch `[top, bottom)`, in document order.
+ * The prefix maximum of bottoms is monotone, so the first candidate is a
+ * binary search; the scan stops at the first sorted top past the bottom.
+ */
+export function queryChildIndex(
+  index: NonNullable<Box['paintIndex']>,
+  top: number,
+  bottom: number,
+): Box[] {
+  const { boxes, order, prefixBottom } = index;
+  let lo = 0;
+  let hi = boxes.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (prefixBottom[mid] > top) hi = mid;
+    else lo = mid + 1;
+  }
+  const hits: { at: number; box: Box }[] = [];
+  for (let i = lo; i < boxes.length; i += 1) {
+    const child = boxes[i];
+    if (child.boundsY >= bottom) break;
+    if (child.boundsY + child.boundsHeight > top)
+      hits.push({ at: order[i], box: child });
+  }
+  // Paint order is document order; the handful of visible children sort in
+  // no time, where sorting the whole list per paint was the point of not
+  // filtering per paint.
+  hits.sort((a, b) => a.at - b.at);
+  return hits.map((h) => h.box);
+}
+
+/** Paint a laid-out document. */
+export function paintDocument(
+  ctx: PaintContext,
+  tree: BoxTree,
+  options: PaintOptions,
+): void {
+  if (!canFill(ctx)) return;
+  ctx.save();
+  paintBox(ctx, tree.root, options);
+  ctx.restore();
+}
+
+function paintBox(ctx: PaintContext, box: Box, options: PaintOptions): void {
+  if (!intersects(box, options)) return;
+  const style = box.style;
+  const visible = style.visibility === 'visible';
+
+  if (visible) {
+    paintBackground(ctx, box, options);
+    paintBorders(ctx, box, options);
+    if (box.markerText) paintMarker(ctx, box, options);
+    if (box.replaced === 'image') paintImage(ctx, box, options);
+  }
+
+  // In-flow and floated descendants first, then the inline content, then the
+  // positioned ones — a flattening of CSS's painting order that is right for
+  // everything short of a document that puts a negative z-index under its own
+  // parent's background.
+  const damage = options.damage;
+  if (box.paintIndex && damage) {
+    for (const child of queryChildIndex(
+      box.paintIndex,
+      damage.y - options.originY,
+      damage.y + damage.height - options.originY,
+    )) {
+      paintBox(ctx, child, options);
+    }
+  } else {
+    for (const child of box.children) {
+      if (child.kind === 'text' || child.kind === 'break') continue;
+      if (child.outOfFlow) continue;
+      paintBox(ctx, child, options);
+    }
+  }
+
+  if (box.lines && visible) paintLines(ctx, box, options);
+
+  if (box.positionedPaint) {
+    for (const child of box.positionedPaint) paintBox(ctx, child, options);
+  }
+}
+
+function byZIndex(a: Box, b: Box): number {
+  const az = a.style.zIndex === 'auto' ? 0 : a.style.zIndex;
+  const bz = b.style.zIndex === 'auto' ? 0 : b.style.zIndex;
+  return az - bz;
+}
+
+/** Whether anything this box or its descendants draw is in the damage. */
+function intersects(box: Box, options: PaintOptions): boolean {
+  const damage = options.damage;
+  if (!damage) return true;
+  const x = box.boundsX + options.originX;
+  const y = box.boundsY + options.originY;
+  return (
+    x < damage.x + damage.width &&
+    x + box.boundsWidth > damage.x &&
+    y < damage.y + damage.height &&
+    y + box.boundsHeight > damage.y
+  );
+}
+
+/**
+ * A fill rectangle clamped to the neighbourhood of the damage.
+ *
+ * Load-bearing, not an optimization: the X protocol carries a fill's
+ * position as Int16 and its size as Uint16, so the background of a box
+ * hundreds of thousands of pixels tall *thrown at the server whole* dies in
+ * the request encoder — the pixels beyond the viewport were never going to
+ * exist, but the numbers still had to fit. The margin keeps rounded corners
+ * and antialiasing outside the damage honest; with no damage at all the
+ * Int16 envelope itself is the clamp.
+ */
+const CLAMP_PAD = 64;
+
+function clampRect(
+  options: PaintOptions,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+): { x: number; y: number; w: number; h: number } | null {
+  const damage = options.damage;
+  const left = damage ? damage.x - CLAMP_PAD : -COORD_LIMIT;
+  const top = damage ? damage.y - CLAMP_PAD : -COORD_LIMIT;
+  const right = damage ? damage.x + damage.width + CLAMP_PAD : COORD_LIMIT;
+  const bottom = damage ? damage.y + damage.height + CLAMP_PAD : COORD_LIMIT;
+  const x1 = Math.max(x, left);
+  const y1 = Math.max(y, top);
+  const x2 = Math.min(x + w, right);
+  const y2 = Math.min(y + h, bottom);
+  if (x2 <= x1 || y2 <= y1) return null;
+  return { x: x1, y: y1, w: x2 - x1, h: y2 - y1 };
+}
+
+function paintBackground(
+  ctx: PaintContext,
+  box: Box,
+  options: PaintOptions,
+): void {
+  const color = box.style.backgroundColor;
+  if (isTransparent(color)) return;
+  const rect = clampRect(
+    options,
+    Math.round(box.x + options.originX),
+    Math.round(box.y + options.originY),
+    Math.ceil(box.width),
+    Math.ceil(box.height),
+  );
+  if (!rect) return;
+  ctx.fillStyle = inkColor(color as string, box.style.color);
+  const radii = box.style.borderRadius;
+  if (radii.some((r) => r > 0) && ctx.roundRect && ctx.fill && ctx.beginPath) {
+    // The clamp can only have cut edges further than CLAMP_PAD outside the
+    // damage, and a sane radius is smaller than that — so a corner that
+    // survives the cut is whole, and a cut edge is offscreen.
+    ctx.beginPath();
+    ctx.roundRect(rect.x, rect.y, rect.w, rect.h, radii.slice());
+    ctx.fill();
+    return;
+  }
+  ctx.fillRect(rect.x, rect.y, rect.w, rect.h);
+}
+
+/**
+ * Borders, as four rectangles.
+ *
+ * Not as a stroked path, for the reason richtext gives about its underlines:
+ * the mock backend has no path API, and a 1px border on a pixel grid is a
+ * rectangle rather than something an antialiased stroke improves. Corners are
+ * mitred by drawing the top and bottom full-width and the sides between them,
+ * which is right whenever the two sides share a colour and close enough when
+ * they do not.
+ */
+function paintBorders(
+  ctx: PaintContext,
+  box: Box,
+  options: PaintOptions,
+): void {
+  const s = box.style;
+  const x = Math.round(box.x + options.originX);
+  const y = Math.round(box.y + options.originY);
+  const w = Math.ceil(box.width);
+  const h = Math.ceil(box.height);
+  if (w <= 0 || h <= 0) return;
+
+  const edge = (
+    ex: number,
+    ey: number,
+    ew: number,
+    eh: number,
+    style: ComputedStyle['borderTopStyle'],
+    color: string,
+    horizontal: boolean,
+  ): void => {
+    const rect = clampRect(options, ex, ey, ew, eh);
+    if (!rect) return;
+    ctx.fillStyle = inkColor(color, s.color);
+    // The un-clamped start is the dash phase's origin, so the pattern does
+    // not crawl as the viewport moves along a long edge.
+    fillEdge(ctx, rect, horizontal ? ex : ey, style, horizontal);
+  };
+  if (box.borderTop > 0 && !isTransparent(s.borderTopColor)) {
+    edge(x, y, w, box.borderTop, s.borderTopStyle, s.borderTopColor, true);
+  }
+  if (box.borderBottom > 0 && !isTransparent(s.borderBottomColor)) {
+    edge(
+      x,
+      y + h - box.borderBottom,
+      w,
+      box.borderBottom,
+      s.borderBottomStyle,
+      s.borderBottomColor,
+      true,
+    );
+  }
+  if (box.borderLeft > 0 && !isTransparent(s.borderLeftColor)) {
+    edge(
+      x,
+      y + box.borderTop,
+      box.borderLeft,
+      h - box.borderTop - box.borderBottom,
+      s.borderLeftStyle,
+      s.borderLeftColor,
+      false,
+    );
+  }
+  if (box.borderRight > 0 && !isTransparent(s.borderRightColor)) {
+    edge(
+      x + w - box.borderRight,
+      y + box.borderTop,
+      box.borderRight,
+      h - box.borderTop - box.borderBottom,
+      s.borderRightStyle,
+      s.borderRightColor,
+      false,
+    );
+  }
+}
+
+function fillEdge(
+  ctx: PaintContext,
+  rect: { x: number; y: number; w: number; h: number },
+  phaseOrigin: number,
+  style: ComputedStyle['borderTopStyle'],
+  horizontal: boolean,
+): void {
+  const { x, y, w, h } = rect;
+  const length = horizontal ? w : h;
+  const thickness = horizontal ? h : w;
+  if (length <= 0 || thickness <= 0) return;
+  if (style === 'dashed' || style === 'dotted') {
+    const period = style === 'dotted' ? thickness * 2 : thickness * 3;
+    const on = style === 'dotted' ? thickness : thickness * 2;
+    const from = horizontal ? x : y;
+    // Start on the pattern boundary at or before the clamped start, so the
+    // dash the viewport cuts into is the same dash it always was.
+    let i = Math.floor((from - phaseOrigin) / period) * period + phaseOrigin;
+    for (; i < from + length; i += period) {
+      const start = Math.max(i, from);
+      const run = Math.min(i + on, from + length) - start;
+      if (run <= 0) continue;
+      if (horizontal) ctx.fillRect(start, y, run, thickness);
+      else ctx.fillRect(x, start, thickness, run);
+    }
+    return;
+  }
+  if (style === 'double' && thickness >= 3) {
+    const band = Math.max(1, Math.floor(thickness / 3));
+    if (horizontal) {
+      ctx.fillRect(x, y, length, band);
+      ctx.fillRect(x, y + thickness - band, length, band);
+    } else {
+      ctx.fillRect(x, y, band, length);
+      ctx.fillRect(x + thickness - band, y, band, length);
+    }
+    return;
+  }
+  ctx.fillRect(x, y, w, h);
+}
+
+/** A list item's bullet or number, in the margin. */
+function paintMarker(ctx: PaintContext, box: Box, options: PaintOptions): void {
+  const marker = box.markerLayout;
+  if (!marker) return;
+  const x = box.markerX + options.originX;
+  const y = box.markerY + options.originY;
+  marker.draw(ctx, x, y);
+}
+
+function paintImage(ctx: PaintContext, box: Box, options: PaintOptions): void {
+  const image = options.imageFor(box);
+  const x = Math.round(box.contentX + options.originX);
+  const y = Math.round(box.contentY + options.originY);
+  const w = Math.ceil(box.contentWidth);
+  const h = Math.ceil(box.contentHeight);
+  if (w <= 0 || h <= 0) return;
+  if (image && ctx.drawImage) {
+    ctx.drawImage(image, x, y, w, h);
+    return;
+  }
+  // No image yet, or no image at all: a faint frame where it will be, so a
+  // document with blocked resources still reads as a document with pictures
+  // in it rather than as one with holes.
+  if (!box.style.backgroundColor) {
+    ctx.fillStyle = box.style.color;
+    const t = 1;
+    ctx.fillRect(x, y, w, t);
+    ctx.fillRect(x, y + h - t, w, t);
+    ctx.fillRect(x, y, t, h);
+    ctx.fillRect(x + w - t, y, t, h);
+  }
+}
+
+/**
+ * The X protocol carries glyph positions as Int16, so anything drawn past
+ * ±32767 window coordinates does not clip — it throws in the encoder. The
+ * caller bounds a full repaint to the window (see `HtmlViewNode.paint`),
+ * which keeps every *culled* coordinate in range; this margin is how far a
+ * drawn layout's own lines may run past the damage before the batch itself
+ * would overflow.
+ */
+const COORD_LIMIT = 30000;
+
+function paintLines(ctx: PaintContext, box: Box, options: PaintOptions): void {
+  const lines = box.lines;
+  if (!lines) return;
+  const dx = options.originX;
+  const dy = options.originY;
+  const damage = options.damage;
+
+  // Three passes over the visible lines, not one: ntk draws a whole layout
+  // in one glyph batch, so a multi-line paragraph's ink all lands on the
+  // first line that references it — and anything painted "under the ink" on
+  // a later line would land *over* it. Everything under the glyphs is
+  // painted for every line first, then the ink once per layout, then the
+  // rules over it.
+  const visible: LineBox[] = [];
+  if (damage) {
+    // Lines are built top to bottom, so `y` is monotone; a line's *bottom*
+    // is not (heights vary), which is what the tallest-line slack is for.
+    // Start at the first line that could reach the damage, stop at the
+    // first one past it: the cost is the visible lines, not the box's.
+    const top = damage.y - dy;
+    const bottom = top + damage.height;
+    let lo = 0;
+    let hi = lines.length;
+    const slack = top - box.maxLineHeight;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (lines[mid].y > slack) hi = mid;
+      else lo = mid + 1;
+    }
+    for (let i = lo; i < lines.length; i += 1) {
+      const line = lines[i];
+      if (line.y >= bottom) break;
+      if (line.y + line.height > top) visible.push(line);
+    }
+  } else {
+    visible.push(...lines);
+  }
+  if (!visible.length) return;
+
+  for (const line of visible) {
+    for (const text of line.texts) {
+      const natural = text.layout.lines[text.layoutLine];
+      if (natural)
+        paintRunBackgrounds(ctx, natural, text.drawX + dx, text.drawY + dy);
+    }
+    paintSelection(ctx, line, options);
+  }
+
+  // One `draw` per layout: a paragraph is a single glyph composite, and
+  // drawing it once per line would be one X request per line for the same
+  // batch.
+  const drawn = new Set<unknown>();
+  for (const line of visible) {
+    for (const text of line.texts) {
+      if (drawn.has(text.layout)) continue;
+      drawn.add(text.layout);
+      const top = text.drawY + dy;
+      if (top < -COORD_LIMIT || top + text.layout.height > COORD_LIMIT) {
+        // A single layout so tall its own lines overflow the Int16 envelope
+        // — a one-paragraph document tens of thousands of pixels high. The
+        // element scrolling itself (phase 2, see the PRD) is the real
+        // answer; until then the overflowing batch is skipped rather than
+        // thrown from the protocol encoder.
+        continue;
+      }
+      text.layout.draw(ctx, text.drawX + dx, top);
+    }
+  }
+
+  for (const line of visible) {
+    for (const text of line.texts) {
+      const natural = text.layout.lines[text.layoutLine];
+      if (natural)
+        paintRunRules(ctx, natural, text.drawX + dx, text.drawY + dy);
+    }
+    for (const placed of line.atomics) paintBox(ctx, placed.box, options);
+  }
+}
+
+/**
+ * The band the document selection covers on one line.
+ *
+ * Translucent under the glyphs rather than inverted over them, so the ink
+ * keeps its contrast on either palette — the same call `<textarea>` and
+ * `<richtext>` both make.
+ */
+function paintSelection(
+  ctx: PaintContext,
+  line: LineBox,
+  options: PaintOptions,
+): void {
+  const range = options.selection;
+  if (!range || range.end <= range.start || !options.selectionColor) return;
+  if (line.textEnd <= range.start || line.textStart >= range.end) return;
+  ctx.fillStyle = options.selectionColor;
+  for (const text of line.texts) {
+    const natural = text.layout.lines[text.layoutLine];
+    if (!natural) continue;
+    const from = Math.max(range.start, text.textStart);
+    const to = Math.min(range.end, text.textEnd);
+    if (to <= from) continue;
+    const offsets = layoutOffsets(text.layout);
+    const layoutFrom = text.layoutStart + (from - text.textStart);
+    const layoutTo = text.layoutStart + (to - text.textStart);
+    for (const band of lineBands(
+      text.layout,
+      natural,
+      offsets,
+      layoutFrom,
+      layoutTo,
+    )) {
+      ctx.fillRect(
+        Math.round(band.x + text.drawX + options.originX),
+        Math.round(line.y + options.originY),
+        Math.ceil(band.width),
+        Math.ceil(line.height),
+      );
+    }
+  }
+}