@unmade/text-renderer 1.2.0 → 1.3.0

package/dist/node/layout/index.d.ts

@@ -0,0 +1,77 @@
+import { LoadedFont } from '../loading';
+import { PathEntry } from '../rendering';
+import { BaselineConfig, BaselineType, BoxDimensions, ColourMap, HorizontalTextAlignmentValues, MeasurementUnits, PhysicalSize, TextSpacing, VerticalTextAlignmentValues } from '../types';
+export interface LayoutTextOptions {
+    font: LoadedFont;
+    text: string;
+    boxDimensions: BoxDimensions;
+    physicalSize: PhysicalSize;
+    /** When provided, bypasses the physicalSize → font size calculation. */
+    fontSize?: number;
+    spacing?: TextSpacing;
+    baseline?: BaselineType | BaselineConfig;
+    horizontalAlignment?: HorizontalTextAlignmentValues;
+    verticalAlignment?: VerticalTextAlignmentValues;
+    colourMap?: ColourMap;
+}
+export interface TextLayout {
+    fontSize: number;
+    /** Lines as laid out — curved and custom baselines collapse to one. */
+    lines: string[];
+    /** Every glyph, positioned. Rendering draws these; measuring bounds them. */
+    paths: PathEntry[];
+    spacing: TextSpacing;
+    tallestHeight: number;
+    totalHeight: number;
+    maxBaseline: number;
+}
+/**
+ * Position every glyph of `text` within `boxDimensions`.
+ *
+ * Shared by rendering and measuring so the two cannot disagree: what gets
+ * measured is the same set of positioned glyphs that gets drawn. The
+ * configuration engine has two independent measurement paths that have drifted
+ * apart over time, which is the outcome this exists to prevent.
+ */
+export declare const layoutText: (options: LayoutTextOptions) => TextLayout;
+export interface MeasuredLine {
+    text: string;
+    width: number;
+    height: number;
+    baseline: number;
+}
+export interface TextMeasurement {
+    fontSize: number;
+    /** Bounds of the drawn glyphs, in the box's pixel coordinates. */
+    bbox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    physicalWidth: number;
+    physicalHeight: number;
+    physicalUnits: MeasurementUnits;
+    /**
+     * Physical height of a standard capital at this font size — the cap height.
+     *
+     * Not derivable from `physicalHeight`: that measures the glyphs actually
+     * present, so it moves with descenders and accents, whereas cap height is a
+     * property of the font and size alone. It is persisted with the design and
+     * reaches the factory, so it has to be reported rather than inferred.
+     */
+    physicalCapHeight: number;
+    lines: MeasuredLine[];
+}
+/**
+ * Measure text as it would be drawn.
+ *
+ * Bounds the same positioned glyphs `renderText` draws, rather than
+ * re-deriving dimensions from font metrics — so a measurement can't disagree
+ * with the artwork it describes. In particular a curved line's bounds follow
+ * the arch, which a flat metrics calculation cannot know about.
+ *
+ * Throws where `renderText` would throw, for the same reasons. If this
+ * succeeds, rendering the same options will too.
+ */
+export declare const measureText: (options: LayoutTextOptions) => TextMeasurement;

package/dist/node/renderText.d.ts

@@ -1,5 +1,8 @@
 import { RenderTextOptions } from './types';
 /**
  * Synchronous text renderer. Requires a pre-loaded font.
+ *
+ * Positioning lives in layoutText, shared with measureText so that what is
+ * measured is the same set of glyphs that gets drawn.
  */
 export declare const renderText: (options: RenderTextOptions) => string;

package/dist/renderText.d.ts

@@ -1,5 +1,8 @@
 import { RenderTextOptions } from './types';
 /**
  * Synchronous text renderer. Requires a pre-loaded font.
+ *
+ * Positioning lives in layoutText, shared with measureText so that what is
+ * measured is the same set of glyphs that gets drawn.
  */
 export declare const renderText: (options: RenderTextOptions) => string;

package/dist/worker/fitting/index.d.ts

@@ -67,9 +67,9 @@ export interface FitAndTruncateTextToBoxResult extends FitTextToBoxResult {
 /**
  * Calculate the font size at which `text` fills `boxDimensions` as closely
  * as possible without overflowing, for any baseline shape. This replaces
- * binary-searching for a fitting font size: for flat and custom baselines
- * it's a direct O(1) calculation; for curved baselines it's a bounded
- * numeric solve (see solveCurvedFit).
+ * binary-searching for a fitting font size: flat and custom baselines are
+ * solved in one step, from a single measurement, while curved baselines need
+ * a bounded numeric solve (see solveCurvedFit).
  *
  * `fits: false` means the text doesn't fit even at minFontSize — the caller
  * (e.g. fitAndTruncateTextToBox) should either shorten the text or accept

package/dist/worker/index.d.ts

@@ -3,6 +3,7 @@ export { type GenerateCurvedBaselineOptions, type GenerateFlatBaselineOptions, g
 export { DEFAULT_OUTLINE_FACTOR, DEFAULT_SPACING, LINE_HEIGHT, } from './constants';
 export { type FitAndTruncateTextToBoxResult, type FitConstraint, type FitSize, type FitTextToBoxOptions, type FitTextToBoxResult, fitAndTruncateTextToBox, getFontSizeToFitBox, } from './fitting';
 export { getFontColours } from './glyph/svg-glyph-converter';
+export { type LayoutTextOptions, layoutText, type MeasuredLine, measureText, type TextLayout, type TextMeasurement, } from './layout';
 export { getFontCache, type LoadedFont, loadFont } from './loading';
 export { type GetFontSizeFromPhysicalSizeOptions, type GetTextMetricsAtFontSizeOptions, getFontSizeFromPhysicalSize, getTextMetricsAtFontSize, } from './measuring';
 export type { GetTextAsPathDataOptions, SvgGlyphEntry } from './rendering';