ntk 2.2.0 → 3.1.0

package/lib/text/layout.js

@@ -0,0 +1,356 @@
+import LineBreaker from 'linebreak';
+
+import { drawGlyphRuns } from './glyphs.js';
+import { embeddingLevels, reorderRuns } from './shape.js';
+
+const WS = new Set([0x20, 0x09, 0xa0]);
+const HARD_BREAKS = /[\n\r\u2028\u2029]+$/;
+const TRAILING_WS = /[ \t\u00a0]+$/;
+
+function isWsGlyph(g) {
+  return g.codePoints.length > 0 && g.codePoints.every((cp) => WS.has(cp));
+}
+
+/**
+ * Multi-line text layout: breaks (possibly styled) text into lines for a
+ * target container width, with full shaping — kerning, ligatures, complex
+ * scripts, bidi and font fallback all apply.
+ *
+ * Line-break opportunities follow UAX#14 (via the `linebreak` package);
+ * shaping happens per inter-break segment (so results are cached and reused
+ * across relayouts), and bidi reordering is applied per line (UAX#9 L2).
+ *
+ * Content is a plain string or an array of spans
+ * `{ text, family?, size?, weight?, style?, features?, language?, color? }`;
+ * span fields override the base style. Options:
+ *
+ * - `maxWidth` — target container width (default: unlimited)
+ * - `align` — 'left' | 'right' | 'center' | 'start' | 'end'
+ * - `lineHeight` — multiplier over natural font line height (default 1)
+ * - `direction` — 'ltr' | 'rtl' | 'auto' base paragraph direction
+ *
+ * The result is inspectable before/without drawing: `width`, `height`, and
+ * `lines[] = { x, y, baseline, width, ascent, descent, runs }` with
+ * `runs[] = { x, width, run, span }` in visual order.
+ */
+export class TextLayout {
+  constructor(fonts, content, style = {}, options = {}) {
+    this.fonts = fonts;
+    this.options = options;
+    const maxWidth = options.maxWidth ?? Infinity;
+
+    // ---- normalize spans, resolve fonts eagerly ----
+    // unknown span fields ride along untouched (widgets attach markers like
+    // MarkdownView's _deco/_href and read them back from line runs)
+    const spans = (typeof content === 'string' ? [{ text: content }] : content).map((s) => {
+      const merged = {
+        ...s,
+        text: String(s.text ?? ''),
+        family: s.family ?? style.family ?? 'sans-serif',
+        size: s.size ?? style.size ?? 16,
+        weight: s.weight ?? style.weight,
+        style: s.style ?? style.style,
+        features: s.features ?? style.features,
+        language: s.language ?? style.language,
+        color: s.color ?? style.color ?? null
+      };
+      merged.font = s.font ?? style.font ?? fonts.match(merged.family, merged);
+      return merged;
+    });
+
+    const text = spans.map((s) => s.text).join('');
+    const emb = embeddingLevels(text, options.direction);
+    const levels = emb.levels;
+    this.baseLevel = emb.paragraphs.length ? emb.paragraphs[0].level & 1 : 0;
+
+    // span boundaries, for binary search by char position
+    const spanStarts = [];
+    {
+      let pos = 0;
+      for (const s of spans) {
+        spanStarts.push(pos);
+        pos += s.text.length;
+      }
+    }
+    const spanAt = (pos) => {
+      let lo = 0;
+      let hi = spanStarts.length - 1;
+      while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (spanStarts[mid] <= pos) lo = mid;
+        else hi = mid - 1;
+      }
+      return {
+        span: spans[lo],
+        end: lo + 1 < spanStarts.length ? spanStarts[lo + 1] : text.length
+      };
+    };
+
+    // ---- tokenize at UAX#14 break opportunities ----
+    const tokens = [];
+    {
+      const breaker = new LineBreaker(text);
+      let prev = 0;
+      let bk;
+      while ((bk = breaker.nextBreak())) {
+        tokens.push(this._makeToken(text, prev, bk.position, levels, spanAt, bk.required));
+        prev = bk.position;
+      }
+      if (prev < text.length || tokens.length === 0) {
+        tokens.push(this._makeToken(text, prev, text.length, levels, spanAt, false));
+      }
+    }
+
+    // ---- greedy line fill ----
+    const lineTokens = [];
+    {
+      let cur = [];
+      let curWidth = 0;
+      const flush = () => {
+        lineTokens.push(cur);
+        cur = [];
+        curWidth = 0;
+      };
+      for (let token of tokens) {
+        while (curWidth + token.width - token.wsWidth > maxWidth) {
+          if (cur.length > 0) {
+            flush();
+          } else {
+            // single token wider than the container: force-break it
+            const [head, rest] = this._forceBreak(token, maxWidth);
+            if (!head) break; // not even one cluster fits: let it overflow
+            cur.push(head);
+            flush();
+            token = rest;
+          }
+        }
+        cur.push(token);
+        curWidth += token.width;
+        if (token.required) flush();
+      }
+      if (cur.length) lineTokens.push(cur);
+    }
+
+    // ---- assemble lines: strip trailing ws, bidi-reorder, position ----
+    const baseSpan = spans[0];
+    const lineHeightMul = options.lineHeight ?? 1;
+    this.lines = [];
+    let y = 0;
+    let layoutWidth = 0;
+
+    for (const toks of lineTokens) {
+      // entries carry .level so reorderRuns can order them (UAX#9 L2)
+      let entries = [];
+      for (const token of toks) {
+        for (const frag of token.fragments) {
+          for (const run of frag.shaped.runs) {
+            entries.push({ run, span: frag.span, level: run.level });
+          }
+        }
+      }
+      stripTrailingWhitespace(entries);
+      entries = reorderRuns(entries);
+
+      let ascent = 0;
+      let descent = 0;
+      let natural = 0;
+      const runs = [];
+      let x = 0;
+      for (const e of entries) {
+        runs.push({ x, width: e.run.width, run: e.run, span: e.span });
+        x += e.run.width;
+        const m = e.run.font.metrics(e.run.size);
+        if (m.ascent > ascent) ascent = m.ascent;
+        if (m.descent > descent) descent = m.descent;
+        if (m.lineHeight > natural) natural = m.lineHeight;
+      }
+      if (runs.length === 0) {
+        // empty line (blank paragraph): base style metrics
+        const m = baseSpan.font.metrics(baseSpan.size);
+        ascent = m.ascent;
+        descent = m.descent;
+        natural = m.lineHeight;
+      }
+      if (x > layoutWidth) layoutWidth = x;
+      this.lines.push({ x: 0, y, baseline: y + ascent, width: x, ascent, descent, runs });
+      y += natural * lineHeightMul;
+    }
+
+    this.width = layoutWidth;
+    this.height = y;
+
+    // ---- horizontal alignment ----
+    const container = Number.isFinite(maxWidth) ? maxWidth : this.width;
+    let align = options.align ?? 'start';
+    if (align === 'start') align = this.baseLevel ? 'right' : 'left';
+    if (align === 'end') align = this.baseLevel ? 'left' : 'right';
+    if (align !== 'left') {
+      for (const line of this.lines) {
+        const free = container - line.width;
+        line.x = align === 'right' ? free : free / 2;
+      }
+    }
+  }
+
+  _makeToken(text, start, end, levels, spanAt, required) {
+    const fragments = [];
+    let width = 0;
+    let pos = start;
+    while (pos < end) {
+      const { span, end: spanEnd } = spanAt(pos);
+      const fragEnd = Math.min(end, spanEnd);
+      // hard-break controls only terminate the line; never shape them
+      const fragText = text.slice(pos, fragEnd).replace(HARD_BREAKS, '');
+      if (fragText.length > 0) {
+        const fragLevels = normalizedLevels(levels, pos, pos + fragText.length);
+        const shaped = this.fonts._shapeCached(fragText, span, fragLevels);
+        fragments.push({ text: fragText, span, shaped });
+        width += shaped.width;
+      }
+      pos = fragEnd;
+    }
+    // trailing whitespace does not count against the container width
+    let wsWidth = 0;
+    const last = fragments[fragments.length - 1];
+    if (last) {
+      const m = TRAILING_WS.exec(last.text);
+      if (m) {
+        const spaceGlyph = last.span.font.fk.glyphForCodePoint(0x20);
+        wsWidth = m[0].length * spaceGlyph.advanceWidth * last.span.font.scale(last.span.size);
+      }
+    }
+    return { fragments, width, wsWidth, required };
+  }
+
+  // split an over-wide token at the widest cluster boundary that fits
+  _forceBreak(token, maxWidth) {
+    const headFrags = [];
+    let used = 0;
+    for (let i = 0; i < token.fragments.length; i++) {
+      const frag = token.fragments[i];
+      if (used + frag.shaped.width <= maxWidth) {
+        headFrags.push(frag);
+        used += frag.shaped.width;
+        continue;
+      }
+      // binary search the longest codepoint prefix of this fragment that fits
+      const cps = Array.from(frag.text);
+      let lo = 0;
+      let hi = cps.length - 1;
+      let best = null;
+      while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const prefix = cps.slice(0, mid + 1).join('');
+        const shaped = this.fonts._shapeCached(prefix, frag.span, '0');
+        if (used + shaped.width <= maxWidth) {
+          best = { len: prefix.length, shaped, text: prefix };
+          lo = mid + 1;
+        } else {
+          hi = mid - 1;
+        }
+      }
+      if (best) headFrags.push({ text: best.text, span: frag.span, shaped: best.shaped });
+
+      const restFrags = [];
+      const restText = frag.text.slice(best ? best.len : 0);
+      if (restText) {
+        restFrags.push({
+          text: restText,
+          span: frag.span,
+          shaped: this.fonts._shapeCached(restText, frag.span, '0')
+        });
+      }
+      restFrags.push(...token.fragments.slice(i + 1));
+      const sum = (frags) => frags.reduce((w, f) => w + f.shaped.width, 0);
+      const head = headFrags.length
+        ? { fragments: headFrags, width: sum(headFrags), wsWidth: 0, required: false }
+        : null;
+      const rest = {
+        fragments: restFrags,
+        width: sum(restFrags),
+        wsWidth: token.wsWidth,
+        required: token.required
+      };
+      return [head, rest];
+    }
+    // everything fit after all (float rounding): no split needed
+    return [
+      { ...token, required: false },
+      { fragments: [], width: 0, wsWidth: 0, required: token.required }
+    ];
+  }
+
+  /**
+   * Draw onto a 2d context at (x, y) = top-left of the layout box.
+   * Span `color`s override the context fillStyle; consecutive same-color
+   * runs are batched into single CompositeGlyphs requests.
+   */
+  draw(ctx, x = 0, y = 0) {
+    const app = ctx.window.app;
+    const Render = app.display.Render;
+    for (const line of this.lines) {
+      let batch = [];
+      let batchColor;
+      const flush = () => {
+        if (batch.length === 0) return;
+        const src = batchColor ? ctx._stylePicture(batchColor) : ctx._backgroundPicture;
+        drawGlyphRuns(app, Render.PictOp.Over, src.id, ctx.picture.id, batch);
+        batch = [];
+      };
+      for (const r of line.runs) {
+        const color = r.span.color;
+        if (batch.length && color !== batchColor) flush();
+        batchColor = color;
+        batch.push({ run: r.run, x: x + line.x + r.x, y: y + line.baseline });
+      }
+      flush();
+    }
+    ctx._markDirty();
+    return this;
+  }
+}
+
+// Drop trailing whitespace glyphs from the logical end of a line.
+// Shaped runs are shared via the shaping cache — clone instead of mutating.
+function stripTrailingWhitespace(entries) {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const run = entries[i].run;
+    // rtl runs store glyphs in visual order: their logical end is index 0
+    const fromFront = run.direction === 'rtl';
+    let count = 0;
+    let wsWidth = 0;
+    while (count < run.glyphs.length) {
+      const g = run.glyphs[fromFront ? count : run.glyphs.length - 1 - count];
+      if (!isWsGlyph(g)) break;
+      count++;
+      wsWidth += g.ax;
+    }
+    if (count === 0) return;
+    if (count === run.glyphs.length) {
+      entries.splice(i, 1);
+      continue;
+    }
+    entries[i] = {
+      ...entries[i],
+      run: {
+        ...run,
+        glyphs: fromFront ? run.glyphs.slice(count) : run.glyphs.slice(0, -count),
+        width: run.width - wsWidth
+      }
+    };
+    return;
+  }
+}
+
+// compact levels key for the shaping cache: single char when uniform
+function normalizedLevels(levels, start, end) {
+  let uniform = true;
+  for (let i = start + 1; i < end; i++) {
+    if (levels[i] !== levels[start]) {
+      uniform = false;
+      break;
+    }
+  }
+  if (uniform) return String(levels[start] ?? 0);
+  return Array.prototype.slice.call(levels, start, end).join(',');
+}

package/lib/text/shape.js

@@ -0,0 +1,141 @@
+import bidiFactory from 'bidi-js';
+
+const bidi = bidiFactory();
+
+// characters that never force a font switch: whitespace and default-ignorable
+// format controls stay with the surrounding font
+function neverSwitches(cp) {
+  return (
+    cp === 0x20 ||
+    cp === 0x09 ||
+    cp === 0x0a ||
+    cp === 0x0d ||
+    cp === 0xa0 ||
+    (cp >= 0x200b && cp <= 0x200f) || // zw space/nonjoiner/joiner, lrm/rlm
+    (cp >= 0x202a && cp <= 0x202e) || // bidi embedding controls
+    (cp >= 0x2066 && cp <= 0x2069) || // bidi isolate controls
+    (cp >= 0xfe00 && cp <= 0xfe0f) || // variation selectors
+    cp === 0xfeff
+  );
+}
+
+/**
+ * UAX#9 embedding levels for a string. `direction` is 'ltr', 'rtl' or 'auto'
+ * (first-strong detection). Returns bidi-js's result object.
+ */
+export function embeddingLevels(text, direction = 'auto') {
+  const explicit = direction === 'ltr' || direction === 'rtl' ? direction : null;
+  return bidi.getEmbeddingLevels(text, explicit);
+}
+
+/**
+ * Shape a string through the full pipeline:
+ *
+ *   1. bidi resolution (UAX#9, bidi-js) — unless precomputed `levels` are
+ *      passed in (TextLayout resolves whole paragraphs at once)
+ *   2. itemization: split into maximal runs of same bidi level and same font,
+ *      switching to a fallback font for codepoints the primary font lacks
+ *   3. OpenType shaping per run (fontkit): kerning, ligatures, contextual
+ *      forms; RTL runs come back in visual glyph order
+ *
+ * Runs are returned in **logical order**, each tagged with its bidi `level`;
+ * use `reorderRuns()` to get visual order for drawing.
+ *
+ * @param {FontManager} fonts
+ * @param {string} text
+ * @param {object} style { font | family/weight/style, size, features,
+ *   language, direction: 'ltr'|'rtl'|'auto' }
+ * @param {ArrayLike<number>} [levels] precomputed embedding levels for `text`
+ * @returns {{text, width, baseLevel, runs: Array<{font, size, direction,
+ *   level, width, glyphs, text, start, end}>}}
+ */
+export function shapeText(fonts, text, style, levels) {
+  const size = style.size ?? 16;
+  const family = style.family ?? 'sans-serif';
+  const baseFont = style.font ?? fonts.match(family, style);
+
+  let baseLevel = 0;
+  if (!levels) {
+    const emb = embeddingLevels(text, style.direction);
+    levels = emb.levels;
+    baseLevel = emb.paragraphs.length ? emb.paragraphs[0].level : 0;
+  } else {
+    baseLevel = levels.length ? levels[0] & ~1 : 0;
+  }
+
+  // itemize: walk codepoints, splitting where bidi level or font changes
+  const items = []; // { font, level, start, end }
+  let cur = null;
+  let curFont = baseFont;
+  let i = 0;
+  for (const ch of text) {
+    const cp = ch.codePointAt(0);
+    const level = levels[i] ?? baseLevel;
+    let font = curFont;
+    if (!neverSwitches(cp)) {
+      // the primary font always wins when it covers the char, so fallback
+      // runs stay as short as possible
+      if (baseFont.hasGlyph(cp)) font = baseFont;
+      else if (!font.hasGlyph(cp)) font = fonts.fallbackFor(cp, family, style) ?? baseFont;
+    }
+    if (cur && cur.font === font && cur.level === level) {
+      cur.end = i + ch.length;
+    } else {
+      cur = { font, level, start: i, end: i + ch.length };
+      items.push(cur);
+    }
+    curFont = font;
+    i += ch.length;
+  }
+
+  const runs = [];
+  let width = 0;
+  for (const item of items) {
+    const direction = item.level & 1 ? 'rtl' : 'ltr';
+    const sub = text.slice(item.start, item.end);
+    const shaped = item.font.shape(sub, size, {
+      direction,
+      features: style.features,
+      language: style.language
+    });
+    shaped.level = item.level;
+    shaped.text = sub;
+    shaped.start = item.start;
+    shaped.end = item.end;
+    width += shaped.width;
+    runs.push(shaped);
+  }
+
+  return { text, width, baseLevel, runs };
+}
+
+/**
+ * Reorder logical runs into visual (left-to-right drawing) order —
+ * UAX#9 rule L2 applied at run granularity.
+ */
+export function reorderRuns(runs) {
+  if (runs.length < 2) return runs.slice();
+  let max = 0;
+  let minOdd = Infinity;
+  for (const r of runs) {
+    if (r.level > max) max = r.level;
+    if (r.level & 1 && r.level < minOdd) minOdd = r.level;
+  }
+  const out = runs.slice();
+  for (let level = max; level >= minOdd; level--) {
+    let start = -1;
+    for (let j = 0; j <= out.length; j++) {
+      if (j < out.length && out[j].level >= level) {
+        if (start === -1) start = j;
+      } else if (start !== -1) {
+        for (let a = start, b = j - 1; a < b; a++, b--) {
+          const tmp = out[a];
+          out[a] = out[b];
+          out[b] = tmp;
+        }
+        start = -1;
+      }
+    }
+  }
+  return out;
+}

package/lib/trapezoid.js

@@ -0,0 +1,131 @@
+// Trapezoidal decomposition of flattened closed polygons (non-zero winding
+// by default, even-odd optionally), producing XRender AddTraps data.
+//
+// A horizontal slab sweep: slab boundaries are the sorted unique vertex y
+// coordinates, so edges never cross inside a slab (self-intersecting input —
+// e.g. overlapping composite-glyph contours — degrades gracefully to a
+// near-correct fill instead of failing). Spans where the winding number is
+// non-zero become trapezoids; a span whose left/right edges continue through
+// consecutive slabs is merged into a single tall trapezoid, which is what
+// keeps the output at roughly one trapezoid per outline edge.
+//
+// Output is the flat number list node-x11's Render.AddTraps expects:
+// 6 values per trapezoid — top spanfix (left x, right x, y) then bottom
+// spanfix (left x, right x, y), y-down, top.y < bottom.y.
+
+/**
+ * @param {Array<Array<number>>} polys closed polygons as flat [x0,y0,x1,y1,…]
+ * @param {number} [dx] translation applied to every x
+ * @param {number} [dy] translation applied to every y
+ * @param {Array<number>} [out] existing array to append trapezoid data to
+ * @param {'nonzero'|'evenodd'} [rule] fill rule (default non-zero winding)
+ * @returns {Array<number>} `out`
+ */
+export function trapezoidize(polys, dx = 0, dy = 0, out = [], rule = 'nonzero') {
+  const evenodd = rule === 'evenodd';
+  // collect non-horizontal edges, normalized to y0 < y1 with winding dir
+  const edges = [];
+  const ys = [];
+  for (const poly of polys) {
+    const n = poly.length / 2;
+    for (let i = 0; i < n; ++i) {
+      const j = (i + 1) % n;
+      const ax = poly[i * 2] + dx;
+      const ay = poly[i * 2 + 1] + dy;
+      const bx = poly[j * 2] + dx;
+      const by = poly[j * 2 + 1] + dy;
+      if (ay === by) continue;
+      edges.push(
+        ay < by
+          ? { x0: ax, y0: ay, x1: bx, y1: by, dir: 1, xa: 0, xb: 0 }
+          : { x0: bx, y0: by, x1: ax, y1: ay, dir: -1, xa: 0, xb: 0 }
+      );
+      ys.push(ay, by);
+    }
+  }
+  if (edges.length === 0) return out;
+
+  ys.sort((a, b) => a - b);
+  edges.sort((a, b) => a.y0 - b.y0);
+
+  const active = [];
+  let nextEdge = 0;
+  // spans open from the previous slab, for vertical merging:
+  // { l: leftEdge, r: rightEdge, at: index of the trap in `out` }
+  let prevSpans = [];
+
+  for (let yi = 0; yi < ys.length - 1; ++yi) {
+    const ya = ys[yi];
+    const yb = ys[yi + 1];
+    if (yb === ya) continue;
+
+    // update the active edge list for this slab
+    for (let i = active.length - 1; i >= 0; --i) {
+      if (active[i].y1 <= ya) active.splice(i, 1);
+    }
+    while (nextEdge < edges.length && edges[nextEdge].y0 <= ya) {
+      if (edges[nextEdge].y1 > ya) active.push(edges[nextEdge]);
+      nextEdge++;
+    }
+    if (active.length === 0) {
+      prevSpans = [];
+      continue;
+    }
+
+    // x at slab top/bottom for each active edge; sort left-to-right
+    for (const e of active) {
+      const inv = (e.x1 - e.x0) / (e.y1 - e.y0);
+      e.xa = e.x0 + (ya - e.y0) * inv;
+      e.xb = e.x0 + (yb - e.y0) * inv;
+    }
+    active.sort((a, b) => a.xa + a.xb - (b.xa + b.xb));
+
+    // emit a span per maximal interior interval; interiority is decided by
+    // the fill rule (non-zero winding, or crossing parity for even-odd)
+    const spans = [];
+    let winding = 0;
+    let crossings = 0;
+    let left = null;
+    for (const e of active) {
+      const wasInside = evenodd ? (crossings & 1) === 1 : winding !== 0;
+      winding += e.dir;
+      crossings++;
+      const isInside = evenodd ? (crossings & 1) === 1 : winding !== 0;
+      if (!wasInside && isInside) {
+        left = e;
+      } else if (wasInside && !isInside && left) {
+        // merge with a span from the previous slab bounded by the same edges
+        let merged = false;
+        for (const p of prevSpans) {
+          if (p.l === left && p.r === e && out[p.at + 5] === ya) {
+            out[p.at + 3] = left.xb;
+            out[p.at + 4] = e.xb;
+            out[p.at + 5] = yb;
+            spans.push(p);
+            merged = true;
+            break;
+          }
+        }
+        if (!merged && (e.xa > left.xa || e.xb > left.xb)) {
+          spans.push({ l: left, r: e, at: out.length });
+          out.push(left.xa, e.xa, ya, left.xb, e.xb, yb);
+        }
+        left = null;
+      }
+    }
+    prevSpans = spans;
+  }
+  return out;
+}
+
+/** area covered by a trapezoid list (useful for tests/diagnostics) */
+export function trapArea(traps) {
+  let area = 0;
+  for (let i = 0; i < traps.length; i += 6) {
+    const [tl, tr, ty, bl, br, by] = [
+      traps[i], traps[i + 1], traps[i + 2], traps[i + 3], traps[i + 4], traps[i + 5]
+    ];
+    area += ((tr - tl + (br - bl)) / 2) * (by - ty);
+  }
+  return area;
+}