@unmade/text-renderer 1.1.1 → 1.3.0

package/dist/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/baselines/index.d.ts

@@ -28,6 +28,25 @@ export interface GenerateCurvedBaselineOptions {
     textHeight: number;
     verticalAlignment: VerticalTextAlignmentValues;
 }
+/** Where the arch sits vertically: its peak, and the baseline at its ends. */
+export interface CurvedBaselineGeometry {
+    /** y of the peak — the highest point of the baseline. */
+    curveTop: number;
+    /** y of the two ends — the lowest points of the baseline. */
+    curveBottom: number;
+    /** Horizontal gap left at each end so the outer glyphs are not clipped. */
+    curveXInset: number;
+}
+/**
+ * The arch's placement, on its own so that the path and anything reasoning
+ * about where the text will land come from one calculation.
+ *
+ * Sizing needs this: it has to know where the renderer will actually put the
+ * baseline before it can say whether the text riding it clears the box. Working
+ * that out separately is what let the fit engine believe a size fitted while
+ * the render clipped.
+ */
+export declare const curvedBaselineGeometry: ({ boxDimensions, baseline, textHeight, verticalAlignment, }: GenerateCurvedBaselineOptions) => CurvedBaselineGeometry;
 /**
  * Generate a path command to curve text and align that text to the top of the box.
  * Uses two quadratic bezier curves — one from the bottom left to the peak, and a

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

@@ -0,0 +1,86 @@
+import { LoadedFont } from '../loading';
+import { BaselineConfig, BaselineType, BoxDimensions, PhysicalSize, TextSpacing, VerticalTextAlignmentValues } from '../types';
+/**
+ * How the font size is arrived at.
+ *
+ * `fitToBox` solves for the largest size the box allows. The other two pin the
+ * size and leave the text length as the free variable instead — which is what a
+ * fixed size preset is: hold 60mm, and fit as many characters as will go. All
+ * three then behave identically downstream, so a pinned size is an ordinary mode
+ * rather than a special path.
+ */
+export type FitSize = {
+    mode: 'fitToBox';
+    minFontSize: number;
+    maxFontSize: number;
+} | {
+    mode: 'fontSize';
+    fontSize: number;
+} | {
+    mode: 'physicalSize';
+    physicalSize: PhysicalSize;
+};
+export interface FitTextToBoxOptions {
+    font: LoadedFont;
+    text: string;
+    boxDimensions: BoxDimensions;
+    size: FitSize;
+    spacing?: TextSpacing;
+    baseline?: BaselineType | BaselineConfig;
+    verticalAlignment?: VerticalTextAlignmentValues;
+}
+/**
+ * Which limit decided the outcome.
+ *
+ * - `width` — the box width, or the arc/custom path length for a non-flat baseline
+ * - `height` — the box height
+ * - `requestedSize` — the size the caller asked for, reached before the box
+ *   mattered. Covers both hitting `maxFontSize` when solving and simply getting
+ *   the pinned size that was requested.
+ */
+export type FitConstraint = 'width' | 'height' | 'requestedSize';
+export interface FitTextToBoxResult {
+    fontSize: number;
+    /** False when the text cannot fit within the box even at minFontSize. */
+    fits: boolean;
+    /**
+     * When `fits`, the limit that capped the size. When not, the limit that could
+     * not be satisfied.
+     *
+     * Callers need this to tell one failure from another: overflowing the width
+     * and overflowing the height call for different responses, and in the
+     * configuration engine they surface as different messages to the user.
+     */
+    boundBy: FitConstraint;
+}
+export interface FitAndTruncateTextToBoxResult extends FitTextToBoxResult {
+    text: string;
+    truncated: boolean;
+    /**
+     * How the text was shortened. Reported separately because dropping a line and
+     * trimming characters are different outcomes with different messages, and a
+     * single pass can do both — drop a line, then still need to trim.
+     */
+    linesDropped: number;
+    charactersRemoved: number;
+}
+/**
+ * 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: 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
+ * the overflow at minFontSize.
+ */
+export declare const getFontSizeToFitBox: (options: FitTextToBoxOptions) => FitTextToBoxResult;
+/**
+ * Like getFontSizeToFitBox, but when text doesn't fit even at minFontSize,
+ * shortens it (dropping the last whole line first if there is more than
+ * one, otherwise trimming trailing characters) and retries until it fits
+ * or there's nothing left to remove. Mirrors CE's existing truncation UX —
+ * text lost this way is a caller/product concern, not a rendering one.
+ */
+export declare const fitAndTruncateTextToBox: (options: FitTextToBoxOptions) => FitAndTruncateTextToBoxResult;

package/dist/node/helpers/bbox.d.ts

@@ -1,3 +1,4 @@
+import { PlatformMatrix } from '../types';
 export declare class Box {
     corners: DOMPoint[];
     x1: number;
@@ -13,7 +14,7 @@ export declare class Box {
     get x4(): number;
     get y4(): number;
     constructor(x1: number, y1: number, x2: number, y2: number, x3?: number, y3?: number, x4?: number, y4?: number);
-    transform(matrix: DOMMatrix): void;
+    transform(matrix: PlatformMatrix): void;
     toPointsArray(): number[][];
     getBBox(): BBox;
 }

package/dist/node/index.d.ts

@@ -1,7 +1,9 @@
 import { GetRenderedTextOptions } from './types';
 export { type GenerateCurvedBaselineOptions, type GenerateFlatBaselineOptions, generateCurvedBaseline, generateFlatBaseline, normaliseBaselineOption, validateCustomBaselinePath, } from './baselines';
 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';