@weasel-js/text 1.13.0 → 1.14.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { S as StyledRun, T as TextStyle, L as LaidOutRuns, R as ResolvedTextStyle, a as ResolvedRun, b as LayoutRunsOpts, c as TextPaint } from './test-seams-B0BDm36M.js';
-export { B as BidiAnalysis, d as BidiReordering, e as BidiResolver, D as DEFAULT_TEXT_FILL, f as DEFAULT_TEXT_STYLE, F as FontVariantCaps, g as LAYOUT_CACHE_STRUCTURAL_LIMIT, h as LAYOUT_CACHE_VARIANT_LIMIT, i as LaidOutCell, j as LaidOutLineBox, M as MARKDOWN_RUN_GRAMMAR, P as PlacedGlyph, k as RunFlag, l as RunGrammar, m as RunMarker, n as RunSourceMap, o as SCRIPT_METRICS, p as SMALL_CAPS_SCALE, q as ScriptPreset, r as SmallCapsText, s as TextAlign, t as TextDirection, u as TextTransform, v as TransformedRunText, w as cachedLayoutRuns, x as fontString, y as isBoldWeight, z as isSmallCapsLetter, A as layoutRuns, C as markdownToRuns, E as numericWeight, G as paragraphDirection, H as registerBidi, I as resolveAlign, J as resolveRunFace, K as resolveRuns, N as resolveTextStyle, O as runsToMarkdown, Q as runsToPlainText, U as scriptMetrics, V as scriptMetricsFor, W as smallCapsScale, X as smallCapsScaleFor, Y as smallCapsText, Z as toRuns, _ as transformRunTexts } from './test-seams-B0BDm36M.js';
-import { FaceRuleMetrics, FaceMetrics, FontStyle, BmFontChar, ResolveResult } from '@weasel-js/font';
+import { S as StyledRun, T as TextStyle, L as LaidOutRuns, R as ResolvedTextStyle, a as ResolvedRun, b as LayoutRunsOpts, c as TextShaper, C as CacheUse, d as TextPaint, P as PlacedGlyph } from './test-seams-DHGfE_6p.js';
+export { B as BidiAnalysis, e as BidiReordering, f as BidiResolver, D as DEFAULT_TEXT_FILL, g as DEFAULT_TEXT_STYLE, F as FontVariantCaps, h as LAYOUT_CACHE_STRUCTURAL_LIMIT, i as LAYOUT_CACHE_VARIANT_LIMIT, j as LaidOutCell, k as LaidOutLineBox, M as MARKDOWN_RUN_GRAMMAR, l as RunFlag, m as RunGrammar, n as RunMarker, o as RunSourceMap, p as SCRIPT_METRICS, q as SMALL_CAPS_SCALE, r as ScriptPreset, s as ShapedCluster, t as ShapedGlyph, u as SmallCapsText, v as TextAlign, w as TextDirection, x as TextTransform, y as TransformedRunText, z as cachedLayoutRuns, A as dropRuns, E as fontString, G as halfLeadingFor, H as isBoldWeight, I as isSmallCapsLetter, J as layoutRuns, K as markdownToRuns, N as numericWeight, O as paragraphDirection, Q as registerBidi, U as resolveAlign, V as resolveRunFace, W as resolveRuns, X as resolveTextStyle, Y as runsToMarkdown, Z as runsToPlainText, _ as scriptMetrics, $ as scriptMetricsFor, a0 as smallCapsScale, a1 as smallCapsScaleFor, a2 as smallCapsText, a3 as toRuns, a4 as transformRunTexts } from './test-seams-DHGfE_6p.js';
+import { FaceRuleMetrics, FaceMetrics, BmFontChar, FontStyle, ResolveResult } from '@weasel-js/font';
 import { Fill, Stroke } from '@weasel-js/paint';
 import { Rect, PolygonPath, PathInWorldPose } from '@weasel-js/geom';
 import { Mixed } from '@weasel-js/registry';
@@ -132,14 +132,26 @@ interface TextPoseLayout {
 declare function layoutTextPose(pose: TextPose, scale?: number): TextPoseLayout;
 
 /**
- * What to draw for laid-out text: which tier paints each glyph, which glyphs
- * can be staged together, and the decoration rules. Layout places the glyphs
- * and knows nothing of this; no decision here moves one.
+ * Where the shaping engine arrives, the way the bidi engine does
+ * (`bidiRegistry.ts`): registered once, found by every layout.
+ */
+
+/**
+ * Give every text layout a shaping engine: `registerShaper(await
+ * loadShaper())`, with `loadShaper` from `@weasel-js/text-shaping`. `layoutRuns` uses
+ * it whenever its options carry none. Pass `null`, or call the function
+ * returned, to take it out again.
  *
- * Underline, strikethrough and overline come out as solid rectangles built
- * from pen positions, not from quad extents: quads exist only for glyphs with
- * ink, so a decorated stretch's spaces would punch holes in a rule derived
- * from them.
+ * Shaping reaches the text whose face was registered with
+ * `registerFontOutlines` from TrueType or OpenType bytes: those are the faces
+ * whose glyphs are drawn by index. Text drawn from a baked or canvas atlas,
+ * whose glyphs are looked up by code point, is laid out as before.
+ */
+declare function registerShaper(shaper: TextShaper | null): () => void;
+
+/**
+ * A glyph quad as painting packs it: the numbers `LaidOutGroup.quadData`
+ * holds for each atlas glyph, and the object view a reader can ask for instead.
  */
 
 /** One textured glyph quad, relative to the text's own top-left: what
@@ -155,10 +167,29 @@ interface LaidOutQuad {
     v1: number;
     /** The glyph's baseline. The synthetic-italic skew leans vertices about it. */
     baselineY: number;
+    /** The glyph's pen on that baseline, which it turns about. */
+    penX: number;
+    /** Degrees the quad turns, clockwise about `(penX, baselineY)`, after the
+     *  skew. 0 is upright. */
+    rotate: number;
     /** On a `'color'` group's quads, the glyph's record, which a renderer drawing
      *  it larger than its bake asks for a sharper one (`sharperColorGlyph`). */
     colorGlyph?: BmFontChar;
 }
+/** Numbers per quad in `LaidOutGroup.quadData`. */
+declare const QUAD_STRIDE = 11;
+
+/**
+ * What to draw for laid-out text: which tier paints each glyph, which glyphs
+ * can be staged together, and the decoration rules. Layout places the glyphs
+ * and knows nothing of this; no decision here moves one.
+ *
+ * Underline, strikethrough and overline come out as solid rectangles built
+ * from pen positions, not from quad extents: quads exist only for glyphs with
+ * ink, so a decorated stretch's spaces would punch holes in a rule derived
+ * from them.
+ */
+
 /**
  * One glyph the renderer should tessellate rather than sample.
  *
@@ -177,6 +208,9 @@ interface LaidOutOutlineGlyph {
     baselineY: number;
     /** World units per em — the glyph's `fontSize`, since em space is unit-scale. */
     scale: number;
+    /** Degrees the glyph turns, clockwise about the pen, after any synthetic
+     *  italic shear. Absent is upright. */
+    rotate?: number;
 }
 /**
  * Glyphs that share a resolved face, glyph source and paint, so a renderer
@@ -215,7 +249,7 @@ interface LaidOutGroup {
      *  (no registered outlines) stays on the atlas, unstroked. */
     stroke?: Stroke;
     /** Textured glyph quads, {@link QUAD_STRIDE} numbers each, in
-     *  `LaidOutQuad`'s field order: `x0 y0 x1 y1 u0 v0 u1 v1 baselineY`. What
+     *  `LaidOutQuad`'s field order: `x0 y0 x1 y1 u0 v0 u1 v1 baselineY penX rotate`. What
      *  a painter reads; `quads` is a view of it. Empty for an `'outline'` group. */
     quadData: readonly number[];
     /** On a `'color'` group, each quad's glyph record, which a renderer drawing
@@ -258,8 +292,6 @@ interface PaintedRuns {
      *  strikethrough then overline. Empty when nothing is decorated. */
     decorations: LaidOutDecoration[];
 }
-/** Numbers per quad in `LaidOutGroup.quadData`. */
-declare const QUAD_STRIDE = 9;
 /**
  * Derive what to draw for `laid`, the layout of `runs` — or of runs that
  * differ from them only in paint and decoration, which a layout does not read.
@@ -271,9 +303,11 @@ declare function paintRuns(laid: LaidOutRuns, runs: readonly ResolvedRun[], opts
  * threshold's effect, and the glyphs available are what they were. `laid` must
  * be the layout of `runs`, as for `paintRuns`.
  *
- * **The result is shared and must be treated as immutable.**
+ * **The result is shared and must be treated as immutable.** `use` is as for
+ * `cachedLayoutRuns`: a `'read'` painting's quads go back to the pool with its
+ * layout.
  */
-declare function cachedPaintRuns(laid: LaidOutRuns, runs: readonly ResolvedRun[], opts?: PaintRunsOpts): PaintedRuns;
+declare function cachedPaintRuns(laid: LaidOutRuns, runs: readonly ResolvedRun[], opts?: PaintRunsOpts, use?: CacheUse): PaintedRuns;
 
 /**
  * Wrap-aware text measurement for a 2D context. Lines end where `layoutRuns`
@@ -671,6 +705,10 @@ declare function setFlagOverRange(runs: readonly StyledRun[], style: TextStyle,
  */
 declare const SYNTHETIC_ITALIC_RADIANS = 0.2094;
 
+/** A glyph turned `rotate` degrees, clockwise with y down, as the cosine and
+ *  sine its points turn by: `x' = x·cos − y·sin`, `y' = x·sin + y·cos`. */
+declare function glyphTurn(rotate: number | undefined): readonly [number, number];
+
 /**
  * Synthetic bold as geometry. The renderer fakes a missing bold face by
  * dropping the distance-field threshold, which moves every edge of the glyph
@@ -726,6 +764,13 @@ declare class TextOutlinesError extends Error {
     readonly style: FontStyle;
     constructor(reason: TextOutlinesFailure, family: string, weight: number, style: FontStyle, detail: string, caller?: string);
 }
+/**
+ * `d`, the em-space outline data of `g`'s glyph, set where the renderer's
+ * outline tier draws it: wound positive, grown for synthetic bold, sheared
+ * for synthetic italic, turned by `g.rotate`, at the pen `(g.x + dx, g.baselineY + dy)`. For a
+ * caller reading `d` from a source of its own rather than the registered face.
+ */
+declare function glyphOutlineAt(d: string, g: PlacedGlyph, dx: number, dy: number): PolygonPath;
 
 /**
  * Text as path geometry: the glyph outlines a text node draws, placed in
@@ -810,6 +855,22 @@ interface TextCluster {
     paths: TextPaintPath[];
     /** Height of the x-height's middle above the baseline. */
     middle: number;
+    /** The decoration rules crossing the slot, cut to it, in the frame `paths` use; underline, then strikethrough, then
+     *  overline. A rule running on into the next slot ends at `advance` here and starts at 0 there. */
+    rules: TextClusterRule[];
+}
+/** The stretch of one decoration rule inside a cluster's slot. */
+interface TextClusterRule {
+    kind: DecorationKind;
+    /** Its ends along the slot, 0..`advance`. */
+    x0: number;
+    x1: number;
+    /** Its top and bottom edges, y down from the baseline. */
+    y0: number;
+    y1: number;
+    /** The paint its run wears, as the cluster's `paths` carry it. */
+    fill: Fill | null;
+    stroke?: Stroke;
 }
 /** Options for {@link textClusters}. */
 interface TextClustersOptions extends TextToPathOptions {
@@ -823,13 +884,18 @@ interface TextClustersOptions extends TextToPathOptions {
  * laid at the node's box origin with no pose applied; the lines after it are
  * dropped. The slots tile the
  * line: each cluster's `advance` runs to the next one's `x`, so the kerning
- * between two clusters belongs to the left one. Decoration rules are left out.
+ * between two clusters belongs to the left one. A decoration rule is cut into
+ * the slots it crosses (`rules`).
  *
  * Throws `TextOutlinesError` as `textToPath` does, except that a color
  * glyph, or one drawn by a fallback face with no outlines, keeps its slot
  * with no `paths`. Only a code point that inks its slot is drawn, so a color
  * cluster's leading code points stay blank too.
+ *
+ * Remembered per `data` object: the same `data`, `width` and `scale` hand
+ * back the same array until a face or glyph changes, so treat `data` as
+ * immutable and don't mutate the result. A throw is not remembered.
  */
 declare function textClusters(data: TextOutlineSource, opts?: TextClustersOptions): TextCluster[];
 
-export { BREAK_ALLOWED, BREAK_MANDATORY, DEFAULT_DECORATION_METRICS, type DecorationKind, type FaceMetricsFn, type FitTextPoseOptions, type FlagKey, type LabelOptions, type LaidOutDecoration, type LaidOutGroup, type LaidOutOutlineGlyph, type LaidOutQuad, LaidOutRuns, type LayoutLine, type LayoutResult, LayoutRunsOpts, type MarkdownFontOptions, type MeasureFn, type MeasureTextBoundsOpts, type MeasuredSpan, type MeasuredText, NO_BREAK, type PaintRunsOpts, type PaintedRuns, type PointInTextPoseOpts, type PositionedRun, QUAD_STRIDE, type RangeStyle, ResolvedRun, ResolvedTextStyle, type RunStylePatch, SYNTHETIC_ITALIC_RADIANS, type SetFlagResult, type StyleKey, StyledRun, type TextCluster, type TextClustersOptions, type TextLineBoxesOpts, type TextNodeSource, type TextOutlineSource, TextOutlinesError, type TextOutlinesFailure, TextPaint, type TextPaintPath, type TextPose, type TextPoseLayout, type TextPoseLayoutInput, type TextRenderer, TextStyle, type TextToPathOptions, type TextVerticalAlign, applyStyleToRange, cachedPaintRuns, caretIndexAt, createMarkdownRenderer, decorationMetrics, defaultLabelTextRenderer, effectiveRangeStyle, emboldenGlyphD, fitTextPose, isHardLineBreak, isTextData, layoutMarkdown, layoutTextPose, lineBreakOpportunities, loadTextOutlines, measureText, measureTextBounds, measuredWidth, nodeHasFlag, paintRuns, patchRangeStyle, pointInTextPose, rangeWeight, renderLabel, runsCarryStyling, setFlagOverRange, styleAtRange, supersededKey, syntheticBoldOffset, textClusters, textLineBoxes, textPoseLayoutInput, textToPath, textToPathsByPaint, unboldPatch, verticalAlignOffset };
+export { BREAK_ALLOWED, BREAK_MANDATORY, CacheUse, DEFAULT_DECORATION_METRICS, type DecorationKind, type FaceMetricsFn, type FitTextPoseOptions, type FlagKey, type LabelOptions, type LaidOutDecoration, type LaidOutGroup, type LaidOutOutlineGlyph, type LaidOutQuad, LaidOutRuns, type LayoutLine, type LayoutResult, LayoutRunsOpts, type MarkdownFontOptions, type MeasureFn, type MeasureTextBoundsOpts, type MeasuredSpan, type MeasuredText, NO_BREAK, type PaintRunsOpts, type PaintedRuns, PlacedGlyph, type PointInTextPoseOpts, type PositionedRun, QUAD_STRIDE, type RangeStyle, ResolvedRun, ResolvedTextStyle, type RunStylePatch, SYNTHETIC_ITALIC_RADIANS, type SetFlagResult, type StyleKey, StyledRun, type TextCluster, type TextClusterRule, type TextClustersOptions, type TextLineBoxesOpts, type TextNodeSource, type TextOutlineSource, TextOutlinesError, type TextOutlinesFailure, TextPaint, type TextPaintPath, type TextPose, type TextPoseLayout, type TextPoseLayoutInput, type TextRenderer, TextShaper, TextStyle, type TextToPathOptions, type TextVerticalAlign, applyStyleToRange, cachedPaintRuns, caretIndexAt, createMarkdownRenderer, decorationMetrics, defaultLabelTextRenderer, effectiveRangeStyle, emboldenGlyphD, fitTextPose, glyphOutlineAt, glyphTurn, isHardLineBreak, isTextData, layoutMarkdown, layoutTextPose, lineBreakOpportunities, loadTextOutlines, measureText, measureTextBounds, measuredWidth, nodeHasFlag, paintRuns, patchRangeStyle, pointInTextPose, rangeWeight, registerShaper, renderLabel, runsCarryStyling, setFlagOverRange, styleAtRange, supersededKey, syntheticBoldOffset, textClusters, textLineBoxes, textPoseLayoutInput, textToPath, textToPathsByPaint, unboldPatch, verticalAlignOffset };