@react-x11/components 0.4.0 → 0.5.0

package/src/reorder/model.ts

@@ -0,0 +1,232 @@
+// The insertion arithmetic under `<ReorderList>`: which slot a pointer is
+// over, and what a move to that slot does to an order. Pure — no React, no
+// display — so every case is asserted on no server (`test/reorder-model.test.ts`),
+// and so a second consumer (a reorderable `<Table>`, say) can take it
+// without taking the component. That promotion is the reason this is its
+// own module rather than a section of `index.ts`.
+//
+// The model is pragmatic-drag-and-drop's **closest edge**: the item nearest
+// the pointer, and which half of it — along the list's axis — the pointer is
+// in. It needs nothing but the items' own rectangles, so it is the same rule
+// for a vertical list, a horizontal strip, an RTL one and a wrapping grid,
+// and it never has to know the gap between two items to answer for a point
+// in it (`docs/prd-reorder.md`, "Geometry: the closest edge").
+
+export type ReorderId = string | number;
+export type ReorderOrientation = 'vertical' | 'horizontal';
+/** Which edge of an item the pointer is nearest — in reading order, so
+ *  `'before'` is the top of a vertical list and the *right* edge of an RTL
+ *  strip. */
+export type ReorderEdge = 'before' | 'after';
+
+/** A rectangle in any one consistent space — the component hands over
+ *  logical pixels, and the tests hand over whatever they like. */
+export interface ReorderRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface ReorderPoint {
+  x: number;
+  y: number;
+}
+
+/** Where a pointer would insert: the slot (`0` … `n`, a gap between items),
+ *  and the item and edge that slot was read off, for whoever draws it. */
+export interface ReorderSlot {
+  slot: number;
+  index: number;
+  edge: ReorderEdge;
+  /**
+   * The pointer is inside the item's middle band and combining is on, so a
+   * drop merges *into* `index` rather than landing beside it. Always false
+   * when the caller passes no band, which is what keeps a list that does not
+   * combine reading exactly as it did before.
+   */
+  combine: boolean;
+}
+
+/** Squared distance from a point to a rectangle; zero inside it. */
+function distance2(rect: ReorderRect, p: ReorderPoint): number {
+  const dx = Math.max(rect.x - p.x, 0, p.x - (rect.x + rect.width));
+  const dy = Math.max(rect.y - p.y, 0, p.y - (rect.y + rect.height));
+  return dx * dx + dy * dy;
+}
+
+/**
+ * The slot a pointer is over, among items laid out in `rects`' order.
+ *
+ * The nearest item wins — the one under the pointer when there is one, and
+ * on a tie the earlier — and its midpoint along the axis decides the edge.
+ * `null` only when there are no items, where the caller's answer is slot 0.
+ *
+ * `combineBand` is the fraction of the item's length at *each* end that
+ * still reads as an edge: 0 (the default) means every point picks an edge,
+ * and 0.25 means the middle half of an item reads as "merge into this one"
+ * — but only for a point genuinely inside it, since a point in the gap
+ * between two items is not over either of them.
+ */
+export function closestSlot(
+  rects: readonly ReorderRect[],
+  point: ReorderPoint,
+  orientation: ReorderOrientation,
+  direction: 'ltr' | 'rtl' = 'ltr',
+  combineBand = 0,
+): ReorderSlot | null {
+  if (rects.length === 0) return null;
+  let index = 0;
+  let best = Infinity;
+  for (let i = 0; i < rects.length; i++) {
+    const d = distance2(rects[i]!, point);
+    if (d < best) {
+      best = d;
+      index = i;
+    }
+  }
+  const rect = rects[index]!;
+  const vertical = orientation === 'vertical';
+  const start = vertical ? rect.y : rect.x;
+  const length = vertical ? rect.height : rect.width;
+  const along = vertical ? point.y : point.x;
+  let before = along < start + length / 2;
+  // the start edge of an RTL strip is on the right
+  if (!vertical && direction === 'rtl') before = !before;
+  const edge: ReorderEdge = before ? 'before' : 'after';
+  // `best === 0` is the point being inside the rectangle: a band is about
+  // the item under the pointer, and a gap belongs to neither of its
+  // neighbours' middles.
+  const fraction = length > 0 ? (along - start) / length : 0.5;
+  const combine =
+    combineBand > 0 &&
+    best === 0 &&
+    fraction >= combineBand &&
+    fraction <= 1 - combineBand;
+  return { slot: before ? index : index + 1, index, edge, combine };
+}
+
+/**
+ * Where the indicator goes for a slot: the **one** place that names it.
+ *
+ * `closestSlot` answers with the item the pointer is nearest and the half of
+ * it the pointer is in, and two different answers can mean the same gap —
+ * the lower half of item 2 and the upper half of item 3 are both "between
+ * them". Drawing the mark from that answer puts the line in two places for
+ * one insertion point, which reads as two, and flickers between them as the
+ * pointer crosses. So the mark is derived from the slot instead: the start
+ * edge of the item that would follow it, or the end edge of the last item
+ * for the slot past the end.
+ */
+export function slotMark(
+  count: number,
+  slot: number,
+): { index: number; edge: ReorderEdge } | null {
+  if (count <= 0) return null;
+  const at = Math.min(Math.max(slot, 0), count);
+  return at < count
+    ? { index: at, edge: 'before' }
+    : { index: count - 1, edge: 'after' };
+}
+
+/**
+ * `list` with the item at `from` moved to `to` — a new array, always, so it
+ * can be handed straight to a state setter. Indices past either end clamp.
+ * dnd-kit's helper, by its name, because it is what every `onReorder`
+ * handler ends up calling.
+ */
+export function arrayMove<T>(
+  list: readonly T[],
+  from: number,
+  to: number,
+): T[] {
+  const out = list.slice();
+  if (out.length === 0) return out;
+  const a = Math.min(Math.max(from, 0), out.length - 1);
+  const b = Math.min(Math.max(to, 0), out.length - 1);
+  if (a === b) return out;
+  const [item] = out.splice(a, 1);
+  out.splice(b, 0, item as T);
+  return out;
+}
+
+/** Whether dropping the item at `from` into `slot` would change nothing:
+ *  the gap before it, and the gap after it, are both where it already is. */
+export function isNoopSlot(from: number, slot: number): boolean {
+  return from >= 0 && (slot === from || slot === from + 1);
+}
+
+/**
+ * What a drop of `id` into `slot` does to `order`: the new order and the
+ * two indices, or `null` when nothing would move — the item is not in the
+ * list, or the slot is one of its own two gaps. `to` is where the item
+ * ends up *after* it has been taken out, which is what `arrayMove` wants
+ * and what a caller holding objects splices with.
+ */
+export function moveToSlot(
+  order: readonly ReorderId[],
+  id: ReorderId,
+  slot: number,
+): { items: ReorderId[]; from: number; to: number } | null {
+  const many = moveManyToSlot(order, [id], slot, id);
+  return many && { items: many.items, from: many.from, to: many.to };
+}
+
+/**
+ * The same move with a **set** of items — a multi-drag. The set travels in
+ * the list's own order, whatever order it was selected in, and lands as one
+ * run at `slot`; `from`/`to` are where `primary` (the item actually under
+ * the pointer) started and ended up.
+ *
+ * The slot counts gaps in the *original* order, so the arithmetic has to
+ * discount the members of the set that were before it — which is also why
+ * the single-item no-op rule generalizes rather than being special-cased:
+ * a set that lands where it already was produces the order it started from,
+ * and that is what `null` reports.
+ */
+export function moveManyToSlot(
+  order: readonly ReorderId[],
+  ids: readonly ReorderId[],
+  slot: number,
+  primary: ReorderId = ids[0]!,
+): { items: ReorderId[]; ids: ReorderId[]; from: number; to: number } | null {
+  const taking = new Set(ids);
+  // the set in the list's order, and only the members the list actually has
+  const moving = order.filter((id) => taking.has(id));
+  if (moving.length === 0) return null;
+  const from = order.indexOf(primary);
+  if (from < 0) return null;
+  const rest = order.filter((id) => !taking.has(id));
+  const before = order
+    .slice(0, Math.max(slot, 0))
+    .filter((id) => taking.has(id)).length;
+  const at = Math.min(Math.max(slot - before, 0), rest.length);
+  const items = [...rest.slice(0, at), ...moving, ...rest.slice(at)];
+  if (
+    items.length === order.length &&
+    items.every((id, i) => id === order[i])
+  ) {
+    return null;
+  }
+  return { items, ids: moving, from, to: items.indexOf(primary) };
+}
+
+/** `order` with `id` inserted at `slot` — an item arriving from elsewhere. */
+export function insertAtSlot(
+  order: readonly ReorderId[],
+  id: ReorderId,
+  slot: number,
+): ReorderId[] {
+  return insertManyAtSlot(order, [id], slot);
+}
+
+/** The same, with a set arriving together — a multi-drag from another list. */
+export function insertManyAtSlot(
+  order: readonly ReorderId[],
+  ids: readonly ReorderId[],
+  slot: number,
+): ReorderId[] {
+  const out = order.slice();
+  out.splice(Math.min(Math.max(slot, 0), out.length), 0, ...ids);
+  return out;
+}

package/src/richtext/node.ts

@@ -131,8 +131,10 @@ interface LaidRunLike {
   /** Extent within the paragraph, in **code units** (ntk's run vocabulary). */
   start: number;
   end: number;
-  span: TextRun;
-  run: {
+  /** Optional for the same reason as `runs.ts`'s `LaidRun`: react-x11's
+   *  Cocoa engine hands back a run's geometry and nothing else. */
+  span?: TextRun;
+  run?: {
     font: { metrics(size: number): FontMetricsLike };
     size: number;
     direction?: 'ltr' | 'rtl';
@@ -252,9 +254,10 @@ export class RichTextNode extends Node {
     const fonts = (this.app as { fonts?: FontsLike } | null)?.fonts;
     let layout: TextLayoutLike | null = null;
     if (fonts) {
+      const s = this._scale;
       layout = fonts.layout(
-        this._runs(),
-        { family: 'sans-serif', size: 14 },
+        this._deviceRuns(s),
+        { family: 'sans-serif', size: 14 * s },
         {
           maxWidth: Number.isFinite(maxWidth) ? maxWidth : undefined,
           lineHeight: this.style.lineHeight,
@@ -267,6 +270,34 @@ export class RichTextNode extends Node {
     return layout;
   }
 
+  // --- units ---------------------------------------------------------------
+  //
+  // The layout, `abs` and the paint are device pixels (react-x11's
+  // docs/scale.md). A `TextRun.size` is a length the application wrote, so
+  // like every style length it is logical, and unlike a style length nothing
+  // in core multiplies it on the way in — `_deviceRuns` does, so the runs are
+  // shaped at `size * scale` and a 14 on a 2x panel is the size a
+  // `fontSize: 14` is, sharper rather than smaller. A synthetic event's
+  // `x`/`y` are logical too, which is what `hrefAtPoint` is handed; the four
+  // selection accessors are core's device-pixel contract and stay device.
+
+  /** Device pixels per logical pixel — the display scale this element's
+   *  window resolved to, constant for the node's life. */
+  private get _scale(): number {
+    return this.scale > 0 ? this.scale : 1;
+  }
+
+  /** The runs with their sizes on the device grid. The array identity is
+   *  what the layout cache keys on, so at 1x the props' own array is
+   *  returned untouched. */
+  private _deviceRuns(scale: number): TextRun[] {
+    const runs = this._runs();
+    if (scale === 1) return runs;
+    return runs.map((r) =>
+      typeof r.size === 'number' ? { ...r, size: r.size * scale } : r,
+    );
+  }
+
   /**
    * The layout this node is currently painted with — and, because it is the
    * one thing every accessor below answers from, the reason a caret rect and
@@ -302,8 +333,9 @@ export class RichTextNode extends Node {
   // The four accessors from react-x11#291. Implementing them is the whole of
   // joining a `selectable` document: core walks the subtree, asks, and pushes
   // back a `selectionRange` for `paint` to fill. Indices are **code points**
-  // and rectangles are in the **owning window's** coordinates, which is the
-  // space `abs` and a mouse event's `x`/`y` are already in.
+  // and rectangles are in the **owning window's** coordinates in **device**
+  // pixels — the space `abs` is in, and the one core asks in (it reads the
+  // point back off the native event; a synthetic `x`/`y` is logical).
 
   override textContent(): string {
     if (this._text === null) {
@@ -344,18 +376,20 @@ export class RichTextNode extends Node {
     }));
   }
 
-  /** The run's link target under a point, if any — for click-to-follow.
-   *  Not part of the selection seam: core deliberately left hover and
-   *  `cursorAt` out of #291, so following a link stays this package's. */
+  /** The run's link target under a **logical** window point — the one a
+   *  mouse event carries — if any, for click-to-follow. Not part of the
+   *  selection seam: core deliberately left hover and `cursorAt` out of
+   *  #291, so following a link stays this package's. */
   hrefAtPoint(x: number, y: number): string | null {
     const layout = this._paintLayout();
     if (!layout) return null;
-    const lx = x - this.abs.x;
-    const ly = y - this.abs.y;
+    const s = this._scale;
+    const lx = x * s - this.abs.x;
+    const ly = y * s - this.abs.y;
     for (const line of layout.lines) {
       if (ly < line.y || ly >= line.y + line.height) continue;
       for (const r of line.runs) {
-        const href = r.span.href;
+        const href = r.span?.href;
         if (href == null) continue;
         if (lx >= line.x + r.x && lx <= line.x + r.x + r.width) return href;
       }
@@ -370,12 +404,13 @@ export class RichTextNode extends Node {
     const layout = this._paintLayout();
     if (!layout || !canFill(ctx)) return;
     const { x, y } = this.abs;
+    const s = this._scale;
 
     ctx.save();
 
     // 1. run decorations that sit under everything: the code chip, and the
     //    terminal's cell backgrounds
-    for (const line of layout.lines) paintRunBackgrounds(ctx, line, x, y);
+    for (const line of layout.lines) paintRunBackgrounds(ctx, line, x, y, s);
 
     // 2. the band the document selection has claimed of this element's text,
     //    translucent so the ink keeps its contrast on either palette (the
@@ -399,7 +434,7 @@ export class RichTextNode extends Node {
     layout.draw(ctx, x, y);
 
     // 4. rules over the ink: link underlines, strikethrough
-    for (const line of layout.lines) paintRunRules(ctx, line, x, y);
+    for (const line of layout.lines) paintRunRules(ctx, line, x, y, s);
 
     ctx.restore();
   }

package/src/richtext/runs.ts

@@ -29,15 +29,26 @@ export function canFill(ctx: unknown): ctx is FillContext {
   return typeof (ctx as Partial<FillContext> | null)?.fillRect === 'function';
 }
 
-/** One run of one laid-out line, as much of it as decoration reads. */
+/**
+ * One run of one laid-out line, as much of it as decoration reads.
+ *
+ * `span` and `run` are what ntk's layout hands back and what every
+ * decoration is read from: the span the run came from, markers and all, and
+ * the face it was shaped with. Both are optional because react-x11's Cocoa
+ * engine (2.3.x) reports only a run's geometry — `{ x, width, start, end }`
+ * — and a paint that assumed the rest threw on the first paragraph on
+ * macOS. A run without its span has no decoration to draw; a run without
+ * its face takes its vertical extent from the line, which both engines
+ * report.
+ */
 export interface LaidRun {
   x: number;
   width: number;
   /** Extent within the laid-out text, in **code units** (ntk's vocabulary). */
   start: number;
   end: number;
-  span: TextRun;
-  run: {
+  span?: TextRun;
+  run?: {
     font: { metrics(size: number): { ascent: number; descent: number } };
     size: number;
     direction?: 'ltr' | 'rtl';
@@ -50,6 +61,11 @@ export interface LaidLine {
   y: number;
   height: number;
   baseline: number;
+  /** The tallest face on the line, above and below `baseline`. Both engines
+   *  report them; they stand in for a run's own metrics when the engine did
+   *  not hand the run's face back. */
+  ascent?: number;
+  descent?: number;
   start: number;
   end: number;
   runs: LaidRun[];
@@ -65,24 +81,76 @@ export interface CaretSource {
   };
 }
 
+/**
+ * The vertical extent of a run's ink, above and below the baseline: the
+ * run's own face when the engine handed it back, otherwise the line's.
+ */
+function inkExtent(
+  r: LaidRun,
+  line: LaidLine,
+): { ascent: number; descent: number } {
+  if (r.run) return r.run.font.metrics(r.run.size);
+  return {
+    ascent: line.ascent ?? line.baseline - line.y,
+    descent: line.descent ?? line.y + line.height - line.baseline,
+  };
+}
+
+let warnedSpanless = false;
+
+/**
+ * Say so, once, when a laid-out run arrives without the span it came from:
+ * every decoration is read off that span, so none will be drawn, and a
+ * document that suddenly has no code chips or link underlines should not be
+ * a mystery. react-x11's Cocoa engine (2.3.x) is the one that does this.
+ *
+ * `process` and `console` come off `globalThis` because `src/` compiles
+ * with `types: []` — a Node global that wandered in would fail the build
+ * rather than become an implicit `@types/node` dependency.
+ */
+function warnSpanless(): void {
+  if (warnedSpanless) return;
+  warnedSpanless = true;
+  const g = globalThis as {
+    process?: { env?: Record<string, string | undefined> };
+    console?: { warn(message: string): void };
+  };
+  if (g.process?.env?.NODE_ENV === 'production') return;
+  g.console?.warn(
+    '@react-x11/components: the text engine handed back laid-out runs ' +
+      'without their spans, so run decorations (backgrounds, underlines, ' +
+      "strikethrough) and inline link hit-testing are off. react-x11's " +
+      "Cocoa text engine (2.3.x) does this; ntk's does not.",
+  );
+}
+
 /**
  * The fills that sit **under** the glyphs: the inline-code chip, a
  * terminal's cell backgrounds, a highlighted `<span>`.
  *
  * `dx`/`dy` translate the line's own coordinates into the target space, so a
- * caller that placed this line itself passes where it placed it.
+ * caller that placed this line itself passes where it placed it. `scale` is
+ * the display scale: the chip's two-pixel inset is a logical length that
+ * never passes through a style, and grows with it.
  */
 export function paintRunBackgrounds(
   ctx: FillContext,
   line: LaidLine,
   dx: number,
   dy: number,
+  scale = 1,
 ): void {
+  const inset = Math.round(2 * scale);
   for (const r of line.runs) {
-    const bg = r.span.bg;
+    const span = r.span;
+    if (!span) {
+      warnSpanless();
+      continue;
+    }
+    const bg = span.bg;
     if (!bg) continue;
     ctx.fillStyle = bg;
-    if (r.span.bgFill === 'line') {
+    if (span.bgFill === 'line') {
       // Both edges are rounded from absolute positions rather than the left
       // being rounded and the width ceiled, so two adjacent runs agree on the
       // pixel between them: no seam, and no overlap either.
@@ -96,56 +164,70 @@ export function paintRunBackgrounds(
       );
       continue;
     }
-    const m = r.run.font.metrics(r.run.size);
+    const m = inkExtent(r, line);
     ctx.fillRect(
-      Math.round(dx + line.x + r.x - 2),
+      Math.round(dx + line.x + r.x - inset),
       Math.round(dy + line.baseline - m.ascent),
-      Math.ceil(r.width + 4),
+      Math.ceil(r.width + inset * 2),
       Math.ceil(m.ascent + m.descent),
     );
   }
 }
 
-/** The rules that sit **over** the glyphs: link underlines, strikethrough. */
+/** The rules that sit **over** the glyphs: link underlines, strikethrough.
+ *  A rule is one logical pixel thick — `scale` device pixels, so a link on a
+ *  2x panel is underlined as heavily as on a 1x one, not with a hairline. */
 export function paintRunRules(
   ctx: FillContext,
   line: LaidLine,
   dx: number,
   dy: number,
+  scale = 1,
 ): void {
+  const t = ruleThickness(scale);
   for (const r of line.runs) {
-    const { underline, strike } = r.span;
+    const span = r.span;
+    if (!span) continue;
+    const { underline, strike } = span;
     if (underline) {
       ctx.fillStyle = underline;
       underlineRule(
         ctx,
         Math.round(dx + line.x + r.x),
-        Math.round(dy + line.baseline + 2),
+        Math.round(dy + line.baseline + 2 * t),
         Math.ceil(r.width),
-        r.span.underlineStyle ?? 'single',
+        span.underlineStyle ?? 'single',
+        t,
       );
     }
     if (strike) {
-      const m = r.run.font.metrics(r.run.size);
+      const m = inkExtent(r, line);
       ctx.fillStyle = strike;
       ctx.fillRect(
         Math.round(dx + line.x + r.x),
         Math.round(dy + line.baseline - m.ascent * 0.38),
         Math.ceil(r.width),
-        1,
+        t,
       );
     }
   }
 }
 
+/** One logical pixel on the device grid, never less than one device pixel. */
+function ruleThickness(scale: number): number {
+  return Math.max(1, Math.round(scale));
+}
+
 /**
  * The rule under a run, in one of SGR 4's five styles.
  *
- * All five are built from 1px rectangles rather than a stroked path: the mock
- * backend has no path API, and a hairline stroke on a text baseline is not
- * worth an antialiased path even where there is one. The curl is a two-level
- * square wave — at a text size it reads as a squiggle, which is the entire
- * job.
+ * All five are built from rectangles `t` pixels thick — one logical pixel —
+ * rather than a stroked path: the mock backend has no path API, and a
+ * hairline stroke on a text baseline is not worth an antialiased path even
+ * where there is one. The curl is a two-level square wave — at a text size
+ * it reads as a squiggle, which is the entire job. The dot pitch and the
+ * dash length scale with the thickness, so the pattern is the pattern at
+ * any display scale.
  */
 export function underlineRule(
   ctx: FillContext,
@@ -153,31 +235,34 @@ export function underlineRule(
   y: number,
   width: number,
   style: NonNullable<TextRun['underlineStyle']>,
+  t = 1,
 ): void {
   switch (style) {
     case 'double':
-      ctx.fillRect(x, y, width, 1);
-      ctx.fillRect(x, y + 2, width, 1);
+      ctx.fillRect(x, y, width, t);
+      ctx.fillRect(x, y + 2 * t, width, t);
       return;
     case 'dotted':
-      for (let i = 0; i < width; i += 2) ctx.fillRect(x + i, y, 1, 1);
+      for (let i = 0; i < width; i += 2 * t) {
+        ctx.fillRect(x + i, y, Math.min(t, width - i), t);
+      }
       return;
     case 'dashed':
-      for (let i = 0; i < width; i += 6)
-        ctx.fillRect(x + i, y, Math.min(3, width - i), 1);
+      for (let i = 0; i < width; i += 6 * t)
+        ctx.fillRect(x + i, y, Math.min(3 * t, width - i), t);
       return;
     case 'curly':
-      for (let i = 0; i < width; i += 2) {
+      for (let i = 0; i < width; i += 2 * t) {
         ctx.fillRect(
           x + i,
-          y + (i % 4 === 0 ? 0 : 1),
-          Math.min(2, width - i),
-          1,
+          y + (i % (4 * t) === 0 ? 0 : t),
+          Math.min(2 * t, width - i),
+          t,
         );
       }
       return;
     default:
-      ctx.fillRect(x, y, width, 1);
+      ctx.fillRect(x, y, width, t);
       return;
   }
 }