@unmade/text-renderer 1.1.0 → 1.2.0

package/dist/loading/createLoadedFont.d.ts

@@ -0,0 +1,53 @@
+import { Face, Font } from 'harfbuzzjs';
+export interface SVGGlyphData {
+    svg: string;
+    viewbox: string;
+}
+export interface LoadedFont {
+    unitsPerEm: number;
+    names: {
+        fontFamily: string;
+    };
+    svgGlyphs?: Map<number, SVGGlyphData>;
+    charToGlyph(char: string): {
+        index: number;
+        advanceWidth: number;
+        name: string;
+        getBoundingBox(): {
+            x1: number;
+            y1: number;
+            x2: number;
+            y2: number;
+        };
+    };
+    getPath(text: string, x: number, y: number, fontSize: number, options?: {
+        drawSVG?: boolean;
+    }): {
+        getBoundingBox(): {
+            x1: number;
+            y1: number;
+            x2: number;
+            y2: number;
+        };
+        toPathData(decimals?: number): string;
+    };
+    getPaths(text: string, x: number, y: number, fontSize: number, options?: {
+        drawSVG?: boolean;
+    }): Array<{
+        getBoundingBox(): {
+            x1: number;
+            y1: number;
+            x2: number;
+            y2: number;
+        };
+        toPathData(decimals?: number): string;
+    }>;
+}
+export declare function boundsFromPath(pathData: string): {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+} | null;
+export declare function transformPath(pathData: string, scaleX: number, scaleY: number, dx: number): string;
+export declare function createLoadedFont(face: Face, font: Font, familyName: string, svgGlyphs?: Map<number, SVGGlyphData>): LoadedFont;

package/dist/loading/index.d.ts

@@ -0,0 +1,4 @@
+import { createLoadedFont, LoadedFont } from './createLoadedFont';
+export { createLoadedFont, type LoadedFont };
+export declare const getFontCache: () => Map<string, LoadedFont>;
+export declare const loadFont: (fontUrl: string, fetchSVGGlyphs?: boolean) => Promise<LoadedFont>;

package/dist/measuring/conversion.d.ts

@@ -0,0 +1,2 @@
+export declare function millimetersToInches(value: number): number;
+export declare function inchesToMillimeters(value: number): number;

package/dist/measuring/index.d.ts

@@ -0,0 +1,28 @@
+import { LoadedFont } from '../loading';
+import { BoxDimensions, PhysicalSize, TextSpacing } from '../types';
+export interface GetFontSizeFromPhysicalSizeOptions {
+    font: LoadedFont;
+    boxDimensions: BoxDimensions;
+    physicalSize: PhysicalSize;
+    spacing?: TextSpacing;
+}
+export interface GetTextMetricsAtFontSizeOptions {
+    font: LoadedFont;
+    text: string;
+    fontSize: number;
+    spacing?: TextSpacing;
+}
+/**
+ * This is the character we use to calculate font sizes
+ * when fixed physical text height is set for a placement.
+ *
+ * The 'I' character is used because of its flat top and bottom.
+ * https://en.wikipedia.org/wiki/Cap_height
+ */
+export declare const getStandardCharacter: (font: LoadedFont) => string;
+export declare const getFontSizeFromPhysicalSize: ({ font, boxDimensions, physicalSize, spacing, }: GetFontSizeFromPhysicalSizeOptions) => number;
+export declare const getTextMetricsAtFontSize: ({ font, text, fontSize, spacing, }: GetTextMetricsAtFontSizeOptions) => {
+    width: number;
+    height: number;
+    baseline: number;
+};

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

@@ -0,0 +1,59 @@
+import { BaselineConfig, BaselineType, BoxDimensions, VerticalTextAlignmentValues } from '../types';
+/**
+ * Normalise a baseline option (string shorthand or object) into a BaselineConfig.
+ */
+export declare const normaliseBaselineOption: (baseline: BaselineType | BaselineConfig | undefined) => BaselineConfig;
+/**
+ * Validate a custom baseline SVG path string.
+ */
+export declare const validateCustomBaselinePath: (path: string) => void;
+export interface GenerateFlatBaselineOptions {
+    boxDimensions: BoxDimensions;
+    totalTextHeight: number;
+    baseline: number;
+    lineHeight: number;
+    verticalAlignment?: VerticalTextAlignmentValues;
+    lineNumber?: number;
+}
+/**
+ * Generate a path as a baseline for straight text
+ * This can be called multiple times for multiline text by incrementing the lineNumber parameter
+ *
+ * @returns an SVG path command to draw the baseline
+ */
+export declare const generateFlatBaseline: ({ boxDimensions, totalTextHeight, baseline, lineHeight, verticalAlignment, lineNumber, }: GenerateFlatBaselineOptions) => string;
+export interface GenerateCurvedBaselineOptions {
+    boxDimensions: BoxDimensions;
+    baseline: number;
+    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
+ * second mirrored from the peak to the end.
+ *
+ * Curved text is not currently supported for multiline text.
+ *
+ * @returns an SVG path command to draw the curve
+ */
+export declare const generateCurvedBaseline: ({ boxDimensions, baseline, textHeight, verticalAlignment, }: GenerateCurvedBaselineOptions) => string;

package/dist/node/ce-adapter/ce-types.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Type declarations for @unmade/configuration-engine
+ *
+ * CE doesn't ship .d.ts files. These types cover the subset of the
+ * factory API and editor shape that the CE adapter needs.
+ */
+export interface EditorPaletteColour {
+    id: number;
+    hex: string;
+    name: string;
+    display_name?: string;
+    reference?: string | null;
+    extra?: object | null;
+    categories?: string[];
+    lab?: [number, number, number];
+}
+export interface EditorPalette {
+    id: number;
+    name: string;
+    slug: string;
+    colours: EditorPaletteColour[];
+    extended_palette_id?: number;
+    extendedPalette?: EditorPalette;
+    categories?: string[];
+}
+export interface EditorGarment {
+    slug: string;
+    size: string;
+    name?: string;
+    panels_svg?: string;
+    embellishment_positions?: EmbellishmentPosition[];
+}
+export interface EmbellishmentPosition {
+    placement: string;
+    width: number;
+    height: number;
+    physical_width?: number;
+    physical_height?: number;
+    physical_width_decimal: number;
+    physical_height_decimal: number;
+    physical_size_units: string;
+    baseline_path?: string;
+    rotation: number;
+    variant?: string;
+}
+export interface TextLibraryItemFont {
+    id: number;
+    font_url: string;
+    font_family: string;
+    letter_spacing?: number;
+    letter_spacing_outline?: number;
+    outline_width?: number;
+    fixed_colours?: Record<string, {
+        reference: string;
+        hex: string;
+        id: string;
+        text: string;
+    }>;
+}
+export interface TextLibraryItem {
+    id: string;
+    type: 'text';
+    fonts: TextLibraryItemFont[];
+    palette?: number;
+}
+export interface PlacementLibraryItem {
+    id: string;
+    type: string;
+    palette?: number;
+}
+export interface BasePlacementSettings {
+    manufacturing_methods?: {
+        name: string;
+    }[];
+    vertical_alignment?: string;
+    horizontal_alignment?: string;
+}
+export interface PlacementsSettings {
+    byId: Record<string, BasePlacementSettings>;
+    library: Record<string, PlacementLibraryItem | TextLibraryItem>;
+}
+export interface CombinedEditorSettings {
+    editor: string;
+    mixins: string[];
+    garments: EditorGarment[];
+    palettes: number[];
+    allPalettes: Record<number, EditorPalette>;
+    endpoints: {
+        palettes: string;
+        [key: string]: string | undefined;
+    };
+    placements?: PlacementsSettings;
+    embellishments?: PlacementsSettings;
+    [key: string]: unknown;
+}
+export interface BasePlacementState {
+    type: string;
+    libraryItemID: string;
+    meta?: Record<string, unknown>;
+}
+export interface EditorStateVals {
+    placements?: Record<string, BasePlacementState>;
+    embellishments?: Record<string, BasePlacementState>;
+    [key: string]: unknown;
+}
+export interface EditorState {
+    garment?: string;
+    vals?: EditorStateVals;
+    [key: string]: unknown;
+}
+export interface Palettes {
+    byId: Record<string, unknown>;
+    getColours(paletteId: number): EditorPaletteColour[];
+    getUsedColours(paletteId: number, ids: (number | null)[]): (EditorPaletteColour | null)[];
+    getExtendedColours(paletteId: number): EditorPaletteColour[];
+}
+export interface PlacementPositionResult {
+    placement: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    dimensionsForCanvas: {
+        width: number;
+        height: number;
+        x: number;
+        y: number;
+    };
+    variant: string;
+    panel: string;
+    rotation: boolean;
+    physical_width: number;
+    physical_height: number;
+    physical_width_decimal: string;
+    physical_height_decimal: string;
+    physical_size_units: string;
+}
+export interface EditorVariant {
+    name: string;
+    placements: string[];
+}
+/**
+ * Editor instance returned by CE's factory.
+ *
+ * The exact shape depends on which mixins are applied at runtime.
+ * We type the parts the CE adapter needs and treat the rest as opaque.
+ * Uses Element rather than SVGElement for cross-environment compatibility.
+ */
+export interface ConfigEditor {
+    getState(): EditorState & {
+        vals: NonNullable<EditorState['vals']>;
+    };
+    palettes: Palettes;
+    settings: CombinedEditorSettings;
+    placements?: {
+        initialise(): Promise<void>;
+        getAssetsAsSVGElements(state: EditorState, manufacturingMethod: string): Promise<Record<string, {
+            asset: Element;
+            position: PlacementPositionResult;
+        }>>;
+    };
+    embellishments?: {
+        initialise(): Promise<void>;
+        getAssetsAsSVGElements(state: EditorState, manufacturingMethod: string): Promise<Record<string, {
+            asset: Element;
+            position: PlacementPositionResult;
+        }>>;
+    };
+    getVariants?(): EditorVariant[];
+    getCurrentVariant?(): string;
+}

package/dist/node/ce-adapter/extractTextPlacements.d.ts

@@ -0,0 +1,11 @@
+import { ConfigEditor } from './ce-types';
+import { LoadedTextPlacement } from './types';
+/**
+ * Extract text placements from a loaded config editor instance.
+ *
+ * Reads the editor state, resolves fonts and colours from settings and
+ * palettes, and returns a structured array of text placements ready for
+ * rendering or comparison. Processes both the placements and embellishments
+ * buckets.
+ */
+export declare function extractTextPlacements(editor: ConfigEditor): LoadedTextPlacement[];

package/dist/node/ce-adapter/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * CE Adapter for @unmade/text-renderer
+ *
+ * Utilities for extracting text placement state from a loaded
+ * @unmade/configuration-engine editor instance and mapping it to
+ * renderer options. Intended for use in server-side comparison pipelines
+ * and any environment that bridges CE state to the text-renderer.
+ */
+export { extractTextPlacements } from './extractTextPlacements';
+export { mapStateToRendererOptions } from './mapStateToRendererOptions';
+export type { BasePlacementSettings, BasePlacementState, CombinedEditorSettings, ConfigEditor, EditorGarment, EditorPalette, EditorPaletteColour, EditorState, EditorStateVals, EditorVariant, EmbellishmentPosition, Palettes, PlacementLibraryItem, PlacementPositionResult, PlacementsSettings, TextLibraryItem, TextLibraryItemFont, } from './ce-types';
+export type { LoadedTextPlacement, TextPlacementFont, TextPlacementPosition, TextPlacementSpacing, } from './types';

package/dist/node/ce-adapter/mapStateToRendererOptions.d.ts

@@ -0,0 +1,13 @@
+import { GetRenderedTextOptions } from '../types';
+import { LoadedTextPlacement } from './types';
+/**
+ * Map a LoadedTextPlacement to GetRenderedTextOptions for the text-renderer.
+ *
+ * Handles the key differences between config-engine and text-renderer:
+ * - American to British English ('center' -> 'centre')
+ * - isDistributed flag -> horizontalAlignment: 'distributed'
+ * - isCurved flag -> baseline: 'curved'
+ * - baselinePath -> baseline: { type: 'custom', path }
+ * - snake_case spacing -> camelCase spacing
+ */
+export declare function mapStateToRendererOptions(placement: LoadedTextPlacement): GetRenderedTextOptions;

package/dist/node/ce-adapter/types.d.ts

@@ -0,0 +1,56 @@
+import { EditorPaletteColour } from './ce-types';
+export interface TextPlacementPosition {
+    width: number;
+    height: number;
+    physicalWidth: number;
+    physicalHeight: number;
+    physicalUnits: string;
+    baselinePath?: string;
+    rotation: number;
+}
+export interface TextPlacementFont {
+    id: number;
+    fontUrl: string;
+    fontFamily: string;
+    letterSpacing: number;
+    letterSpacingOutline: number;
+    outlineWidth: number;
+    fixedColours?: Record<string, {
+        reference: string;
+        hex: string;
+        id: string;
+        text: string;
+    }>;
+}
+export interface TextPlacementSpacing {
+    letter_spacing: number;
+    letter_spacing_outline: number;
+    line_height?: number;
+}
+export interface LoadedTextPlacement {
+    placementId: string;
+    displayName: string;
+    source: 'placements' | 'embellishments';
+    text: string;
+    font: TextPlacementFont;
+    isCurved: boolean;
+    isDistributed: boolean;
+    verticalAlignment: string;
+    horizontalAlignment: string;
+    rotation: number;
+    spacing: TextPlacementSpacing | null;
+    fillColour: EditorPaletteColour | null;
+    outlineColour: EditorPaletteColour | null;
+    position: TextPlacementPosition;
+    userSetPhysicalSize: [number, string] | null;
+    fontMetrics: {
+        size: number;
+        height: number;
+        baseline: number;
+        width: number;
+        physicalHeight?: number;
+        physicalUnits?: string;
+        physicalFontSize?: [number, 'mm' | 'in'];
+    };
+    manufacturingMethod: string;
+}

package/dist/node/constants.d.ts

@@ -0,0 +1,5 @@
+import { TextSpacing } from './types';
+export declare const DEFAULT_OUTLINE_FACTOR = 0.03125;
+export declare const LINE_HEIGHT = 1.1;
+export declare const CURVE_DEPTH = 0.2;
+export declare const DEFAULT_SPACING: TextSpacing;

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: for flat and custom baselines
+ * it's a direct O(1) calculation; for curved baselines it's 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/glyph/svg-glyph-converter.d.ts

@@ -0,0 +1,42 @@
+import { LoadedFont } from '../loading';
+import { ColourInfo, ColourMap, GlyphFill } from '../types';
+/**
+ * Get the unique colours used by a font's SVG glyphs.
+ *
+ * @param font - A loaded font with svgGlyphs populated
+ * @returns Array of unique hex colour strings found in the font's SVG glyphs
+ */
+export declare function getFontColours(font: LoadedFont): string[];
+/**
+ * Extract fill paths from SVG content with optional colour remapping.
+ *
+ * @param svgContent - Raw SVG string from the font's SVG table
+ * @param colourMap - Optional mapping of original colours to replacements
+ * @returns Array of GlyphFill objects
+ */
+export declare function extractFillsFromSVG(svgContent: string, colourMap?: ColourMap): GlyphFill[];
+/**
+ * Apply colour map to remap a colour value.
+ *
+ * @param colour - Original colour hex string
+ * @param colourMap - Optional colour replacement mapping
+ * @returns ColourInfo with hex and optional reference
+ */
+export declare function applyColourMap(colour: string, colourMap?: ColourMap): ColourInfo;
+/**
+ * Extract the inner content from a raw SVG glyph string.
+ * Strips the XML declaration and outer <svg> wrapper, returning the inner elements.
+ */
+export declare function extractSvgGlyphContent(rawSvg: string): string;
+/**
+ * Namespace all IDs in SVG content to prevent collisions when multiple
+ * glyphs are embedded in the same document. Prefixes all id attributes
+ * and updates all references (href, url(), clip-path, mask, filter).
+ */
+export declare function namespaceSvgIds(svgContent: string, prefix: string): string;
+/**
+ * Remap colour values in raw SVG content. Replaces fill, stroke,
+ * and stop-color attribute values according to the colour map.
+ * Also handles elements without explicit fill that default to black.
+ */
+export declare function remapSvgColours(svgContent: string, colourMap: ColourMap): string;

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

@@ -0,0 +1,34 @@
+import { PlatformMatrix } from '../types';
+export declare class Box {
+    corners: DOMPoint[];
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    _x3: number | undefined;
+    _y3: number | undefined;
+    _x4: number | undefined;
+    _y4: number | undefined;
+    get x3(): number;
+    get y3(): number;
+    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: PlatformMatrix): void;
+    toPointsArray(): number[][];
+    getBBox(): BBox;
+}
+export declare class BBox extends Box {
+    get x(): number;
+    get y(): number;
+    get width(): number;
+    get height(): number;
+    add(box: Box): void;
+    addPoint(x: number, y: number): void;
+    serialize(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}

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

@@ -0,0 +1,17 @@
+export declare class Point {
+    private x;
+    private y;
+    constructor(x: number, y: number);
+    get X(): number;
+    get Y(): number;
+    toSVGString(): string;
+}
+/**
+ * Rotate a point about a pivot point
+ *
+ * @param point - the point to rotate
+ * @param rotate - the amount in degrees
+ * @param pivotPoint - the point around which to rotate
+ * @returns the new point
+ */
+export declare function rotatePoint(point: Point, rotate: number, pivotPoint?: Point): Point;

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

@@ -0,0 +1 @@
+export declare function escapeXML(str: string): string;