ntk 5.4.0 → 6.0.0

package/lib/text/layout.js

@@ -28,11 +28,17 @@ function isWsGlyph(g) {
  * - `align` — 'left' | 'right' | 'center' | 'start' | 'end'
  * - `lineHeight` — multiplier over natural font line height (default 1)
  * - `direction` — 'ltr' | 'rtl' | 'auto' base paragraph direction
+ * - `maxLines` — cap the number of lines (default: unlimited)
+ * - `overflow` — 'clip' (default) or 'ellipsis', what a `maxLines` cut looks
+ *   like. See `_elide`.
  *
- * The result is inspectable before/without drawing: `width`, `height`, and
- * `lines[] = { x, y, baseline, width, ascent, descent, runs, start, end }`
- * with `runs[] = { x, width, run, span, start, end }` in visual order
- * (`start`/`end` are logical UTF-16 ranges into the full text).
+ * The result is inspectable before/without drawing: `width`, `height`,
+ * `truncated`, and `lines[] = { x, y, height, baseline, width, ascent,
+ * descent, runs, start, end }` with
+ * `runs[] = { x, width, run, span, start, end }` in visual order
+ * (`start`/`end` are logical UTF-16 ranges into the full text). A line's
+ * box is `y` to `y + height`; its glyphs sit centred in it, from
+ * `baseline - ascent` to `baseline + descent`.
  *
  * `caretPosition(index)` / `indexAt(x, y)` map logical code-point indices
  * to visual caret geometry and back (bidi/ligature/trailing-whitespace
@@ -143,6 +149,17 @@ export class TextLayout {
       if (cur.length) lineTokens.push(cur);
     }
 
+    // ---- cap the line count ----
+    // The cut happens here, between filling and assembly, so the dropped
+    // lines cost nothing to position and `height` counts only what is kept.
+    const maxLines = Number.isFinite(options.maxLines)
+      ? Math.max(0, Math.floor(options.maxLines))
+      : Infinity;
+    /** did `maxLines` drop content? */
+    this.truncated = lineTokens.length > maxLines;
+    if (this.truncated) lineTokens.length = maxLines;
+    const elide = this.truncated && options.overflow === 'ellipsis';
+
     // ---- assemble lines: strip trailing ws, bidi-reorder, position ----
     const baseSpan = spans[0];
     const lineHeightMul = options.lineHeight ?? 1;
@@ -150,7 +167,16 @@ export class TextLayout {
     let y = 0;
     let layoutWidth = 0;
 
-    for (const toks of lineTokens) {
+    for (let li = 0; li < lineTokens.length; li++) {
+      let toks = lineTokens[li];
+      const lineStart = toks.length ? toks[0].start : 0;
+      let lineEnd = toks.length ? toks[toks.length - 1].end : lineStart;
+
+      // Elision is the last kept line's business only, and it happens before
+      // entries exist, because dropping content means re-shaping the tail.
+      const ellipsis = elide && li === lineTokens.length - 1 ? this._elide(toks, baseSpan) : null;
+      if (ellipsis) toks = this._fitBefore(toks, maxWidth - ellipsis.width);
+
       // entries carry .level so reorderRuns can order them (UAX#9 L2);
       // .start/.end are absolute code-unit ranges into the full text, kept
       // for caret positioning (caretPosition / indexAt)
@@ -168,14 +194,34 @@ export class TextLayout {
           }
         }
       }
-      const lineStart = toks[0].start;
-      const lineEnd = toks[toks.length - 1].end;
-      const trailing = stripTrailingWhitespace(entries);
+      let trailing = stripTrailingWhitespace(entries);
       const contentEnd = trailing
         ? trailing.start
         : entries.length
           ? entries[entries.length - 1].end
           : lineStart;
+      if (ellipsis) {
+        // The ellipsis takes the *paragraph* level, which is what a neutral
+        // at the end of a paragraph resolves to under UAX#9 — so reorderRuns
+        // puts it at the right edge of an LTR line and the left edge of an
+        // RTL one, without a special case here. Its logical range is empty
+        // and pinned at the cut, so caret mapping treats it as the end of
+        // the visible text rather than as characters of its own.
+        for (const run of ellipsis.shaped.runs) {
+          entries.push({
+            run,
+            span: ellipsis.span,
+            level: this.baseLevel,
+            start: contentEnd,
+            end: contentEnd,
+            ellipsis: true
+          });
+        }
+        // whatever whitespace was stripped is gone for good, not merely
+        // pushed past the line edge: there is no wrap for it to precede
+        trailing = null;
+        lineEnd = contentEnd;
+      }
       entries = reorderRuns(entries);
 
       let ascent = 0;
@@ -184,7 +230,9 @@ export class TextLayout {
       const runs = [];
       let x = 0;
       for (const e of entries) {
-        runs.push({ x, width: e.run.width, run: e.run, span: e.span, start: e.start, end: e.end });
+        const positioned = { x, width: e.run.width, run: e.run, span: e.span, start: e.start, end: e.end };
+        if (e.ellipsis) positioned.ellipsis = true;
+        runs.push(positioned);
         x += e.run.width;
         const m = e.run.font.metrics(e.run.size);
         if (m.ascent > ascent) ascent = m.ascent;
@@ -199,10 +247,23 @@ export class TextLayout {
         natural = m.lineHeight;
       }
       if (x > layoutWidth) layoutWidth = x;
+      // Half-leading (CSS Inline Layout 3): the slack between the glyphs and
+      // the line box is split evenly above and below, rather than all of it
+      // landing under the text. This is what makes a single line sit
+      // centred in a box measured from `layout.height`, and it applies at
+      // `lineHeight: 1` too — a font's natural line height includes its line
+      // gap, which is 8px at 16px for some UI faces.
+      //
+      // A multiplier small enough to make the box shorter than the glyphs
+      // gives negative leading and the text overflows evenly on both sides,
+      // which is also what CSS does.
+      const box = natural * lineHeightMul;
+      const leading = (box - (ascent + descent)) / 2;
       this.lines.push({
         x: 0,
         y,
-        baseline: y + ascent,
+        height: box,
+        baseline: y + leading + ascent,
         width: x,
         ascent,
         descent,
@@ -212,7 +273,7 @@ export class TextLayout {
         _contentEnd: contentEnd,
         _trailing: trailing
       });
-      y += natural * lineHeightMul;
+      y += box;
     }
 
     this.width = layoutWidth;
@@ -243,7 +304,9 @@ export class TextLayout {
       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, start: pos });
+        // the levels ride along so a later split can re-shape a piece at the
+        // level it actually has, rather than assuming ltr
+        fragments.push({ text: fragText, span, shaped, start: pos, levels: fragLevels });
         width += shaped.width;
       }
       pos = fragEnd;
@@ -261,6 +324,67 @@ export class TextLayout {
     return { fragments, width, wsWidth, required, start, end };
   }
 
+  /**
+   * The ellipsis to append to a line that was cut short: `{ text, span,
+   * shaped, width }`.
+   *
+   * Shaped in the style of the line's **logically trailing** span, so an
+   * elided line ending in a large or bold word gets a matching ellipsis
+   * rather than one in the paragraph's base style. That span is chosen
+   * before the cut, not after: choosing it after would make the ellipsis
+   * width depend on a cut that depends on the ellipsis width.
+   *
+   * U+2026 is not universal — a subsetted icon or maths face may well lack
+   * it — so when neither the span's font nor any fallback covers it, three
+   * periods stand in. Shaping the real character through a font that has no
+   * glyph for it would draw a .notdef box, which is a worse way to say
+   * "there is more text".
+   */
+  _elide(toks, baseSpan) {
+    let span = baseSpan;
+    for (let i = toks.length - 1; i >= 0; i--) {
+      const frags = toks[i].fragments;
+      if (frags.length) {
+        span = frags[frags.length - 1].span;
+        break;
+      }
+    }
+    const covered =
+      span.font.hasGlyph(0x2026) || this.fonts.fallbackFor(0x2026, span.family, span) !== null;
+    const text = covered ? '…' : '...';
+    const shaped = this.fonts._shapeCached(text, span, String(this.baseLevel));
+    return { text, span, shaped, width: shaped.width };
+  }
+
+  /**
+   * The longest prefix of a line's tokens whose width fits `budget` — whole
+   * tokens while they fit, then a grapheme-boundary cut into the first one
+   * that does not.
+   *
+   * Cutting has to happen here rather than by slicing the text, because the
+   * tail is re-shaped: kerning and ligatures across the cut change widths,
+   * and in a mixed-direction line the visually-last run is not the logically
+   * last one. Working in tokens keeps both facts inside the machinery that
+   * already knows them.
+   */
+  _fitBefore(toks, budget) {
+    const kept = [];
+    let used = 0;
+    for (const token of toks) {
+      // trailing whitespace does not count against the budget, exactly as it
+      // does not count during the greedy fill
+      if (used + token.width - token.wsWidth <= budget) {
+        kept.push(token);
+        used += token.width;
+        continue;
+      }
+      const [head] = this._forceBreak(token, budget - used);
+      if (head && head.fragments.length) kept.push(head);
+      break;
+    }
+    return kept;
+  }
+
   // split an over-wide token at the widest cluster boundary that fits
   _forceBreak(token, maxWidth) {
     const headFrags = [];
@@ -272,15 +396,22 @@ export class TextLayout {
         used += frag.shaped.width;
         continue;
       }
-      // binary search the longest codepoint prefix of this fragment that fits
-      const cps = Array.from(frag.text);
+      // binary search the longest grapheme prefix of this fragment that fits.
+      // Graphemes rather than code points: cutting between a base character
+      // and its combining mark, or inside an emoji ZWJ sequence, leaves a
+      // dotted circle or a pair of half-emoji on the two sides of the break.
+      const cps = graphemes(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');
+        // shaped at the bidi level this text actually has: assuming level 0
+        // here re-shapes an rtl word as ltr, which lays its glyphs out
+        // backwards and hands reorderRuns an even level that stops it from
+        // being reordered at all
+        const shaped = this.fonts._shapeCached(prefix, frag.span, sliceLevels(frag.levels, 0, prefix.length));
         if (used + shaped.width <= maxWidth) {
           best = { len: prefix.length, shaped, text: prefix };
           lo = mid + 1;
@@ -289,17 +420,26 @@ export class TextLayout {
         }
       }
       if (best) {
-        headFrags.push({ text: best.text, span: frag.span, shaped: best.shaped, start: frag.start });
+        headFrags.push({
+          text: best.text,
+          span: frag.span,
+          shaped: best.shaped,
+          start: frag.start,
+          levels: sliceLevels(frag.levels, 0, best.len)
+        });
       }
 
       const restFrags = [];
-      const restText = frag.text.slice(best ? best.len : 0);
+      const cut = best ? best.len : 0;
+      const restText = frag.text.slice(cut);
       if (restText) {
+        const restLevels = sliceLevels(frag.levels, cut, frag.text.length);
         restFrags.push({
           text: restText,
           span: frag.span,
-          shaped: this.fonts._shapeCached(restText, frag.span, '0'),
-          start: frag.start + (best ? best.len : 0)
+          shaped: this.fonts._shapeCached(restText, frag.span, restLevels),
+          start: frag.start + cut,
+          levels: restLevels
         });
       }
       restFrags.push(...token.fragments.slice(i + 1));
@@ -417,8 +557,13 @@ export class TextLayout {
    * `[0, codePointCount]` (out-of-range indices clamp).
    *
    * @returns {{ x, y, height, line }} `x` is the caret's visual x within
-   *   the layout box (alignment included), `y` the top of the line box,
+   *   the layout box (alignment included), `y` the top of the **glyphs**,
    *   `height` = ascent + descent, `line` the line index.
+   *
+   * `y` tracks the text rather than the line box, so a caret drawn from it
+   * stays locked to the glyphs whatever the leading. For a full-height
+   * selection band instead, the line box is `line.y` to `line.y +
+   * line.height`.
    */
   caretPosition(index) {
     const offs = this._offsets();
@@ -435,7 +580,7 @@ export class TextLayout {
     const line = this.lines[li];
     return {
       x: this._caretXInLine(line, cu),
-      y: line.y,
+      y: line.baseline - line.ascent,
       height: line.ascent + line.descent,
       line: li
     };
@@ -484,6 +629,9 @@ export class TextLayout {
         break;
       }
     }
+    // the ellipsis stands for text that is not displayed, so anywhere on it
+    // is the end of what is: it has no indices of its own to land in
+    if (target.ellipsis) return this._cpOf(line._contentEnd);
     return this._cpOf(this._runIndexAt(target, cx));
   }
 
@@ -623,6 +771,24 @@ export class TextLayout {
   }
 }
 
+// Grapheme clusters (UAX#29), for cut points that never land inside one.
+// Intl.Segmenter is in node >= 16 and every current browser; where it is
+// somehow absent, code points are the old behaviour and still safe for the
+// scripts that reach a force-break most often.
+let segmenter;
+function graphemes(text) {
+  if (segmenter === undefined) {
+    segmenter =
+      typeof Intl !== 'undefined' && Intl.Segmenter
+        ? new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+        : null;
+  }
+  if (!segmenter) return Array.from(text);
+  const out = [];
+  for (const { segment } of segmenter.segment(text)) out.push(segment);
+  return out;
+}
+
 // UTF-16 length of a glyph cluster's codePoints array
 function cuLength(codePoints) {
   let len = 0;
@@ -683,6 +849,14 @@ function stripTrailingWhitespace(entries) {
   return result();
 }
 
+// The levels key for a code-unit slice of a fragment. A uniform key covers
+// any slice of itself; a per-character one has to be cut to match.
+function sliceLevels(key, start, end) {
+  if (key === undefined) return '0';
+  if (!key.includes(',')) return key;
+  return key.split(',').slice(start, end).join(',');
+}
+
 // compact levels key for the shaping cache: single char when uniform
 function normalizedLevels(levels, start, end) {
   let uniform = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ntk",
-  "version": "5.4.0",
+  "version": "6.0.0",
   "description": "Desktop UI toolkit for X11 with canvas-like 2d and OpenGL rendering",
   "author": "Andrey Sidorov <sidorares@yandex.ru>",
   "license": "MIT",