@weasel-js/text 1.13.0-rc.0 → 1.14.0

package/dist/{test-seams-B0BDm36M.d.ts → test-seams-DHGfE_6p.d.ts}

@@ -37,12 +37,13 @@ interface TransformedRunText {
  * `capitalize`'s word starts see across run boundaries — a word split by
  * styling still gets one capital.
  *
- * Mappings are the locale-independent ones JavaScript's `toUpperCase` /
- * `toLowerCase` implement, which include `ß` → `SS` and final sigma.
+ * Mappings are JavaScript's `toLocaleUpperCase` / `toLocaleLowerCase` under
+ * `langs[i]`, a BCP 47 tag, so `i` uppercases to `İ` under `tr`; absent is
+ * the locale-independent mapping. Both include `ß` → `SS` and final sigma.
  * `capitalize` titlecases the first code point of each word when it has a
  * case to change, and leaves every other character as it was.
  */
-declare function transformRunTexts(texts: readonly string[], transforms: readonly TextTransform[]): TransformedRunText[];
+declare function transformRunTexts(texts: readonly string[], transforms: readonly TextTransform[], langs?: readonly (string | undefined)[]): TransformedRunText[];
 
 /**
  * Synthetic small caps: lowercase drawn as capitals at a smaller size, the
@@ -71,8 +72,8 @@ declare function smallCapsScale(face?: FaceMetrics): number;
  *  resolved through the font registry exactly as layout resolves the run. */
 declare function smallCapsScaleFor(family: string, weight: number, style: FontStyle): number;
 /** Whether small caps draws `ch` as a smaller capital: whether it has a
- *  capital other than itself. */
-declare function isSmallCapsLetter(ch: string): boolean;
+ *  capital other than itself under `lang`, a BCP 47 tag. */
+declare function isSmallCapsLetter(ch: string, lang?: string): boolean;
 /** A run's drawn text under small caps. `small[i]` says whether UTF-16 unit
  *  `i` of `text` draws at the small size; absent when none does. */
 interface SmallCapsText {
@@ -83,9 +84,10 @@ interface SmallCapsText {
 /**
  * Apply small caps to a run's drawn text. `srcMap` is the map `textTransform`
  * already produced for it, if any; the result's map composes the two, so
- * each drawn unit still names the source character it came from.
+ * each drawn unit still names the source character it came from. Capitals
+ * are `lang`'s, so `i` is drawn `İ` under `tr`.
  */
-declare function smallCapsText(text: string, srcMap?: RunSourceMap): SmallCapsText;
+declare function smallCapsText(text: string, srcMap?: RunSourceMap, lang?: string): SmallCapsText;
 
 /**
  * Canonical inline-styling primitive for text nodes. A node's text is
@@ -162,6 +164,19 @@ interface StyledRun {
      * own; `'normal'` turns an inherited one off.
      */
     fontVariantCaps?: FontVariantCaps;
+    /**
+     * Degrees to turn each of this run's glyphs, clockwise, each about its own
+     * pen on the baseline — SVG's `rotate` with one value for the run. The
+     * glyphs keep their places along the line; only their angle changes. A
+     * different angle per glyph is a run per glyph.
+     */
+    rotate?: number;
+    /**
+     * The run's language, as a BCP 47 tag (`'sr'`, `'ur-PK'`): a shaper draws
+     * the face's forms for it, such as Serbian Cyrillic italics or Urdu digits.
+     * Overrides the node's own; absent inherits it.
+     */
+    lang?: string;
 }
 /** Normalize the two accepted spellings of text content — a plain string or
  *  an array of runs — to runs. Throws on a run with no string `text`. */
@@ -308,6 +323,12 @@ interface TextStyle {
      * have had. Absent is ordinary text.
      */
     script?: 'super' | 'sub';
+    /**
+     * The text's language, as a BCP 47 tag (`'sr'`, `'ur-PK'`), which every run
+     * inherits: a shaper draws the face's forms for it. Absent draws the face's
+     * default forms.
+     */
+    lang?: string;
 }
 /** `TextStyle` with all fields filled in from defaults — what the renderer actually consumes. */
 interface ResolvedTextStyle {
@@ -334,6 +355,8 @@ interface ResolvedTextStyle {
     fontVariantCaps: FontVariantCaps;
     /** Absent is ordinary text. */
     script?: 'super' | 'sub';
+    /** Absent is no language: the face's default forms. */
+    lang?: string;
     /** Absent means no outline — unlike the other fields, this one has no
      *  default to fall back to. See {@link TextPaint.stroke}. */
     stroke?: Stroke;
@@ -431,6 +454,16 @@ interface ResolvedRun {
      * `fontSize`.
      */
     strutSize?: number;
+    /** Degrees each glyph turns, clockwise about its pen on the baseline.
+     *  Absent is upright. */
+    rotate?: number;
+    /** OpenType features a shaper turns on for this run (`'smcp'` for small
+     *  caps drawn from the face's own glyphs). Absent is none; a run that is not
+     *  shaped ignores it. */
+    fontFeatures?: readonly string[];
+    /** BCP 47 language tag a shaper selects the face's forms by: the run's own,
+     *  else the node's. Absent is none. */
+    lang?: string;
 }
 /** What one script preset expands to. */
 type ScriptPreset = Readonly<{
@@ -454,6 +487,14 @@ declare function scriptMetrics(face?: FaceMetrics): Readonly<Record<'super' | 's
  * either half per run with `baselineShift` / `fontScale`.
  */
 declare function scriptMetricsFor(family: string, weight: number, style: FontStyle): Readonly<Record<'super' | 'sub', ScriptPreset>>;
+/**
+ * How far below the top of a line box a face's ascent starts, CSS's way: half
+ * the leading a line height of `lineHeight` (a multiple of `fontSize`) leaves
+ * around the face's ascent and descent, in the units `fontSize` is in. It is
+ * negative for a face taller than its line. `undefined` when no registered
+ * face of `(family, weight, style)` states its ascent and descent.
+ */
+declare function halfLeadingFor(family: string, weight: number, style: FontStyle, fontSize: number, lineHeight: number): number | undefined;
 /** A `TextStyle.fontWeight` as a number: the CSS keywords `bold` and
  *  `normal` read as 700 and 400, anything unparseable as 400. */
 declare function numericWeight(w: number | string): number;
@@ -512,6 +553,74 @@ interface BidiResolver {
     baseLevel(analysis: BidiAnalysis): number;
 }
 
+/**
+ * The shaping contract, declared here and implemented elsewhere.
+ *
+ * This package does not depend on `@weasel-js/text-shaping` and must not, for the
+ * reason it does not depend on `@weasel-js/bidi`: a consumer setting only
+ * Latin text never downloads HarfBuzz's WebAssembly, and another engine can
+ * stand in. `@weasel-js/text-shaping` satisfies these types structurally.
+ *
+ * Without a shaper, layout finds each code point's glyph on its own and kerns
+ * pairs, which is right for Latin, Greek, Cyrillic and CJK and wrong for any
+ * script whose letters change shape with their neighbors.
+ */
+/** One glyph a shaping produced. Every length is in ems, and y grows down. */
+interface ShapedGlyph {
+    /** Glyph index in the face; 0 (`.notdef`) when it has none for the cluster. */
+    gid: number;
+    /** UTF-16 offset in the shaped text where the glyph's cluster starts. */
+    cluster: number;
+    advance: number;
+    /** Where it is drawn, from the pen. */
+    dx: number;
+    dy: number;
+    /** Whether it was shaped right to left, in which case the shaper already
+     *  drew a mirrored character as its mirror. */
+    rtl: boolean;
+}
+/**
+ * A shaping engine: registered with `registerShaper` or passed to
+ * `layoutRuns` as `opts.shaper`. `@weasel-js/text-shaping`'s `loadShaper()`
+ * resolves with one. `face` is a font file's bytes (an sfnt), the same buffer
+ * every call for the same face.
+ */
+interface TextShaper {
+    /** Glyphs in logical order: clusters by ascending `cluster`, and the glyphs
+     *  of one cluster in the order they are drawn, left to right. `language` is
+     *  a BCP 47 tag selecting the face's forms for that language; absent draws
+     *  its default forms. */
+    shape(face: ArrayBuffer, text: string, features?: readonly string[], language?: string): readonly ShapedGlyph[];
+    /** Em-space path data for glyph `gid`, moved by `(dx, dy)`; null for one
+     *  with no contours. */
+    glyphD(face: ArrayBuffer, gid: number, dx?: number, dy?: number): string | null;
+    /** Whether the face has OpenType feature `tag`. */
+    hasFeature(face: ArrayBuffer, tag: string): boolean;
+}
+/**
+ * What a shaped code point draws: the glyphs of the cluster it opens, set
+ * from its pen. The other code points of a cluster carry one with no glyphs.
+ */
+interface ShapedCluster {
+    /** Em-space outline of every glyph in the cluster at its place, or null
+     *  when none has contours. */
+    d: string | null;
+    /** Names `d` among the glyphs of one face, for caching what is built from it. */
+    key: string;
+    /** Each glyph and where it is drawn, in ems from the pen, y down. */
+    glyphs: readonly {
+        gid: number;
+        x: number;
+        y: number;
+    }[];
+    /** Whether it was shaped right to left. */
+    rtl: boolean;
+    /** The text the cluster's glyphs stand for, in logical order: what a reader
+     *  copies or searches for when it reads them back. Empty on a code point
+     *  another one draws. */
+    text: string;
+}
+
 /** Options for `layoutRuns`. */
 interface LayoutRunsOpts {
     /** Wrap width. `Infinity` never wraps. */
@@ -545,6 +654,13 @@ interface LayoutRunsOpts {
      * detects the latter without one.
      */
     bidi?: BidiResolver;
+    /**
+     * Shaping engine. Default: the one given to `registerShaper`. With neither,
+     * each code point is laid out as its own glyph and pairs are kerned, which
+     * is wrong for scripts whose letters join or reorder, Arabic and Devanagari
+     * among them.
+     */
+    shaper?: TextShaper;
     /**
      * Reading direction: the base direction of the bidi analysis, and what
      * `start` / `end` resolve against. Default `'auto'`, each paragraph's own
@@ -594,8 +710,8 @@ interface LayoutRunsOpts {
 /**
  * One advance cell: a single code point's slot on a line.
  *
- * A cell spans its code point *plus* the kerning that precedes the next one,
- * so a caret snapped to the midpoint between two `x`s lands where the glyphs
+ * A cell spans its code point *plus* the kerning that precedes the glyph to
+ * its right, so a caret snapped to the midpoint between two `x`s lands where the glyphs
  * were actually painted rather than where an unkerned re-measure would put it.
  */
 interface LaidOutCell {
@@ -614,7 +730,10 @@ interface LaidOutCell {
      *  order; never assume `cells[i + 1].x` is this cell's right edge. */
     x: number;
     /** Width of the cell: its glyph's advance, plus its run's tracking when it
-     *  closes a grapheme cluster, plus a justified gap's share of the slack. */
+     *  closes a grapheme cluster, plus a justified gap's share of the slack,
+     *  plus the kerning before the glyph to its right. A cell ends at its right
+     *  neighbor's `x`, except across a combining mark that takes no room: the
+     *  mark keeps 0 and the glyph it sits on takes the kerning. */
     advance: number;
     /** Resolved bidi embedding level — even reads left-to-right. 0 with no
      *  engine, which is the same as saying the text was laid out logically. */
@@ -660,15 +779,24 @@ interface PlacedGlyph {
      *  record gains its atlas rect in place when its bake lands. */
     font: BmFont | null;
     glyph: BmFontChar | null;
+    /** What it draws when a shaper shaped its run: its cluster's glyphs, set
+     *  from this pen, in place of the glyph its code point maps to. Null or
+     *  absent when its run was not shaped. */
+    shaped?: ShapedCluster | null;
     /** Pen position: the left edge of the glyph's slot. */
     x: number;
     /** Its line's baseline, raised by its run's `baselineShift`. */
     baselineY: number;
     /** The glyph's own advance. */
     advance: number;
-    /** How far the pen moved past it: `advance`, its run's tracking, and a
-     *  justified gap's share of the slack. */
+    /** How far the pen moved past it: `advance`, its run's tracking, a
+     *  justified gap's share of the slack, and the kerning before the next glyph
+     *  along the line. */
     step: number;
+    /** Degrees its run turns each glyph, clockwise about `(x, baselineY)`, its
+     *  pen on the baseline. 0, or absent on a glyph built by hand, is upright.
+     *  The turn moves no pen: the glyphs after it sit where they would. */
+    rotate?: number;
 }
 /**
  * One laid-out line's box.
@@ -752,15 +880,19 @@ declare function layoutRuns(runs: readonly ResolvedRun[], opts: LayoutRunsOpts):
  * compare. `kit:text`'s memoized `paint` hands back a stable array per node,
  * so the renderer stays on this path.
  *
- * **Structure**, in a bounded `Map`, for every caller that cannot. Measuring
+ * **Structure**, in a bounded list, for every caller that cannot. Measuring
  * a pose resolves its style and allocates a fresh `ResolvedRun[]` each call,
  * so an identity-keyed cache could never hold anything for it — and those
- * callers run on the drag path, once per pose change. Serializing the runs is
- * real work, unlike the pointer compare above, which is exactly why it is
- * second: an identity hit never pays for it.
+ * callers run on the drag path, once per pose change. The runs are hashed,
+ * and a matching hash compared field by field with the runs that filled the
+ * entry, which it holds. No key is built: a HUD readout whose text changes
+ * every frame misses here every frame, and a string key was a string of
+ * every label's text a frame for the collector. Those held runs are why a
+ * run must not be mutated once laid out, the promise the identity key
+ * already asks of its array.
  *
  * Under either, one entry per distinct `(maxWidth, alignWidth, lineHeight,
- * align, direction, bidi engine, tab size)`. Position is deliberately absent:
+ * align, direction, bidi engine, shaper, tab size)`. Position is deliberately absent:
  * `layoutRuns` emits origin-relative geometry and `drawText` translates at
  * upload, so a text node dragged across the page keeps hitting the same entry.
  * So is everything that only changes what is drawn — a run's fill, stroke and
@@ -782,9 +914,18 @@ declare function layoutRuns(runs: readonly ResolvedRun[], opts: LayoutRunsOpts):
  *
  * Variants per runs array are capped and evicted wholesale, matching
  * `outlineMeshCache`: the refill cost is one layout, and the bookkeeping would
- * cost more than the misses it avoids. The structural map cannot ride an
- * array's lifetime the way the `WeakMap` does — nothing collects its keys —
- * so it is a real LRU with a hard entry count.
+ * cost more than the misses it avoids. The structural list cannot ride an
+ * array's lifetime the way the `WeakMap` does, so it is a real LRU with a
+ * hard entry count.
+ *
+ * ### Giving arrays back
+ *
+ * A layout's columns and its paintings' quads go back to a pool for the next
+ * text of the same size once nothing can reach them: `dropRuns` has removed
+ * every runs array filing it, the structural list has evicted it, and every
+ * call handed it passed `'read'`. One `'keep'` handout pins it for good. That
+ * is what lets a readout rewritten every frame, whose widget drops the runs it
+ * replaces and whose renderer only reads, lay out into last frame's arrays.
  */
 
 /** Distinct option combinations held for one runs array before the whole set
@@ -793,6 +934,10 @@ declare const LAYOUT_CACHE_VARIANT_LIMIT = 8;
 /** Layouts held against the structural key before the least recently used one
  *  is dropped. Sized for "every text node visible on a page, plus slack". */
 declare const LAYOUT_CACHE_STRUCTURAL_LIMIT = 64;
+/** What a call means to do with the layout it is handed: `'keep'` may hold
+ *  it, or anything in it, for as long as it likes; `'read'` is done with it
+ *  before its next call into the text caches, and keeps nothing of it. */
+type CacheUse = 'keep' | 'read';
 /**
  * Lay `runs` out, reusing the previous result when nothing it depends on has
  * changed. Drop-in for `layoutRuns` — same arguments, same return value.
@@ -801,8 +946,21 @@ declare const LAYOUT_CACHE_STRUCTURAL_LIMIT = 64;
  * applies position and `verticalAlign` while packing vertices rather than by
  * shifting the layout, precisely so it can be handed the same object every
  * frame.
+ *
+ * `use` is `'read'` for a caller done with the result before its next call
+ * into these caches, keeping nothing of it, which lets the cache recycle the
+ * layout's arrays later; see "Giving arrays back".
+ */
+declare function cachedLayoutRuns(runs: readonly ResolvedRun[], opts: LayoutRunsOpts, use?: CacheUse): LaidOutRuns;
+/**
+ * Forget what the caches hold for `runs`, which its caller will not lay out
+ * again: a readout replacing its text drops the runs it drew last. A layout no
+ * other runs array or caller can reach gives its arrays to the next layout of
+ * the same size, so text rewritten every frame stops allocating them.
+ *
+ * Passing `runs` again afterwards is only a cache miss.
  */
-declare function cachedLayoutRuns(runs: readonly ResolvedRun[], opts: LayoutRunsOpts): LaidOutRuns;
+declare function dropRuns(runs: readonly ResolvedRun[]): void;
 /** Test helper. Do not call from product code. */
 declare function _resetLayoutCacheForTests(): void;
 
@@ -827,4 +985,4 @@ declare function paragraphDirection(text: string, direction?: TextDirection | 'a
 /** Test helper. Do not call from product code. */
 declare function _resetBidiWarningForTests(): void;
 
-export { _resetBidiWarningForTests as $, layoutRuns as A, type BidiAnalysis as B, markdownToRuns as C, DEFAULT_TEXT_FILL as D, numericWeight as E, type FontVariantCaps as F, paragraphDirection as G, registerBidi as H, resolveAlign as I, resolveRunFace as J, resolveRuns as K, type LaidOutRuns as L, MARKDOWN_RUN_GRAMMAR as M, resolveTextStyle as N, runsToMarkdown as O, type PlacedGlyph as P, runsToPlainText as Q, type ResolvedTextStyle as R, type StyledRun as S, type TextStyle as T, scriptMetrics as U, scriptMetricsFor as V, smallCapsScale as W, smallCapsScaleFor as X, smallCapsText as Y, toRuns as Z, transformRunTexts as _, type ResolvedRun as a, _resetLayoutCacheForTests as a0, type LayoutRunsOpts as b, type TextPaint as c, type BidiReordering as d, type BidiResolver as e, DEFAULT_TEXT_STYLE as f, LAYOUT_CACHE_STRUCTURAL_LIMIT as g, LAYOUT_CACHE_VARIANT_LIMIT as h, type LaidOutCell as i, type LaidOutLineBox as j, type RunFlag as k, type RunGrammar as l, type RunMarker as m, type RunSourceMap as n, SCRIPT_METRICS as o, SMALL_CAPS_SCALE as p, type ScriptPreset as q, type SmallCapsText as r, type TextAlign as s, type TextDirection as t, type TextTransform as u, type TransformedRunText as v, cachedLayoutRuns as w, fontString as x, isBoldWeight as y, isSmallCapsLetter as z };
+export { scriptMetricsFor as $, dropRuns as A, type BidiAnalysis as B, type CacheUse as C, DEFAULT_TEXT_FILL as D, fontString as E, type FontVariantCaps as F, halfLeadingFor as G, isBoldWeight as H, isSmallCapsLetter as I, layoutRuns as J, markdownToRuns as K, type LaidOutRuns as L, MARKDOWN_RUN_GRAMMAR as M, numericWeight as N, paragraphDirection as O, type PlacedGlyph as P, registerBidi as Q, type ResolvedTextStyle as R, type StyledRun as S, type TextStyle as T, resolveAlign as U, resolveRunFace as V, resolveRuns as W, resolveTextStyle as X, runsToMarkdown as Y, runsToPlainText as Z, scriptMetrics as _, type ResolvedRun as a, smallCapsScale as a0, smallCapsScaleFor as a1, smallCapsText as a2, toRuns as a3, transformRunTexts as a4, _resetBidiWarningForTests as a5, _resetLayoutCacheForTests as a6, type LayoutRunsOpts as b, type TextShaper as c, type TextPaint as d, type BidiReordering as e, type BidiResolver as f, DEFAULT_TEXT_STYLE as g, LAYOUT_CACHE_STRUCTURAL_LIMIT as h, LAYOUT_CACHE_VARIANT_LIMIT as i, type LaidOutCell as j, type LaidOutLineBox as k, type RunFlag as l, type RunGrammar as m, type RunMarker as n, type RunSourceMap as o, SCRIPT_METRICS as p, SMALL_CAPS_SCALE as q, type ScriptPreset as r, type ShapedCluster as s, type ShapedGlyph as t, type SmallCapsText as u, type TextAlign as v, type TextDirection as w, type TextTransform as x, type TransformedRunText as y, cachedLayoutRuns as z };

package/dist/test-seams.d.ts

@@ -1,3 +1,3 @@
-export { $ as _resetBidiWarningForTests, a0 as _resetLayoutCacheForTests } from './test-seams-B0BDm36M.js';
+export { a5 as _resetBidiWarningForTests, a6 as _resetLayoutCacheForTests } from './test-seams-DHGfE_6p.js';
 import '@weasel-js/paint';
 import '@weasel-js/font';

package/dist/test-seams.js

@@ -1,3 +1,3 @@
-export { _resetBidiWarningForTests, _resetLayoutCacheForTests } from './chunk-ADRQIIHS.js';
+export { _resetBidiWarningForTests, _resetLayoutCacheForTests } from './chunk-FODNMBHI.js';
 //# sourceMappingURL=test-seams.js.map
 //# sourceMappingURL=test-seams.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/text",
-  "version": "1.13.0-rc.0",
+  "version": "1.14.0",
   "description": "Typography for weasel: styled runs, style resolution, kerned glyph layout, wrap and measurement. No scene graph, no React.",
   "license": "MIT",
   "type": "module",
@@ -20,9 +20,9 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@weasel-js/geom": "1.13.0-rc.0",
-    "@weasel-js/paint": "1.13.0-rc.0",
-    "@weasel-js/registry": "1.13.0-rc.0"
+    "@weasel-js/geom": "1.14.0",
+    "@weasel-js/paint": "1.14.0",
+    "@weasel-js/registry": "1.14.0"
   },
   "scripts": {
     "test": "vitest run",
@@ -51,9 +51,9 @@
     "provenance": true
   },
   "devDependencies": {
-    "@weasel-js/bidi": "1.13.0-rc.0"
+    "@weasel-js/bidi": "1.14.0"
   },
   "peerDependencies": {
-    "@weasel-js/font": "1.13.0-rc.0"
+    "@weasel-js/font": "1.14.0"
   }
 }