@unmade/text-renderer 0.1.2 → 0.1.4

package/dist/node/index.d.ts

@@ -1,6 +1,15 @@
 import { default as default_2 } from 'opentype.js';
 import { SVGGlyphData } from '@unmade/svg-glyphs';
 
+export declare type BaselineConfig = {
+    type: 'flat';
+} | {
+    type: 'curved';
+} | {
+    type: 'custom';
+    path: string;
+};
+
 export declare type BaselineType = 'flat' | 'curved';
 
 export declare type BoxDimensions = {
@@ -11,52 +20,120 @@ export declare type BoxDimensions = {
     physicalUnits: MeasurementUnits;
 };
 
+export declare interface ColourInfo {
+    readonly hex: string;
+    readonly reference?: string;
+}
+
+/** Maps original hex colour → replacement ColourInfo. */
+export declare type ColourMap = Readonly<Record<string, ColourInfo>>;
+
 export declare const DEFAULT_OUTLINE_FACTOR = 0.03125;
 
+export declare const DEFAULT_SPACING: TextSpacing;
+
 /**
- * Generate a path command to curve text and align that text to the top of the box
- * We use two quadratic bezier curves[1] - one from the bottom left to the peak of the path, and a second, mirrored, from the peak to the end of the path
- * Using two curves allows us to explicitly define the peak of the curve, which will be at the horizontal centre of the box, far enough down from the top of the box that there's space for the text
- * SVG Quadratic curves require two sets of coordinates - a control point and end point, with the start point being the end point of the previous command
- * [1] https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths#B%C3%A9zier_Curves
+ * 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 so this does not handle multiline parameters
+ * Curved text is not currently supported for multiline text.
  *
- * @param boxWidth - the width of the box
- * @param boxHeight - the height of the box
- * @param textBaselineYPosition - the distance from the top of rendered text to the baseline
- * @param textHeight - the height of the text being rendered
- * @param verticalAlignment - the vertical alignment of the text
  * @returns an SVG path command to draw the curve
  */
-export declare const generateCurvedBaseline: (boxDimensions: BoxDimensions, textBaselineYPosition: number, textHeight: number, verticalAlignment: VerticalTextAlignmentValues) => string;
+export declare const generateCurvedBaseline: ({ boxDimensions, baseline, textHeight, verticalAlignment, }: GenerateCurvedBaselineOptions) => string;
+
+export declare interface GenerateCurvedBaselineOptions {
+    boxDimensions: BoxDimensions;
+    baseline: number;
+    textHeight: number;
+    verticalAlignment: VerticalTextAlignmentValues;
+}
 
 /**
  * Generate a path as a baseline for straight text
  * This can be called multiple times for multiline text by incrementing the lineNumber parameter
  *
- * @param boxDimensions - dimensions of the box into which the text will be rendered
- * @param totalHeightOfAllTextLines - combined measured height of all lines of text
- * @param textBaselineYPosition - the y position of the measured baseline for this specific line of text
- * @param heightOfThisTextLine - the height of this specific line of text
- * @param verticalAlignment - vertical alignment of the text within the box
- * @param lineNumber - the line number of this text line (starting from 0)
- * @returns an SVG path command to draw the curve
+ * @returns an SVG path command to draw the baseline
  */
-export declare const generateFlatBaseline: (boxDimensions: BoxDimensions, totalHeightOfAllTextLines: number, textBaselineYPosition: number, heightOfThisTextLine: number, verticalAlignment?: VerticalTextAlignmentValues, lineNumber?: number) => string;
+export declare const generateFlatBaseline: ({ boxDimensions, totalTextHeight, baseline, lineHeight, verticalAlignment, lineNumber, }: GenerateFlatBaselineOptions) => string;
+
+export declare interface GenerateFlatBaselineOptions {
+    boxDimensions: BoxDimensions;
+    totalTextHeight: number;
+    baseline: number;
+    lineHeight: number;
+    verticalAlignment?: VerticalTextAlignmentValues;
+    lineNumber?: number;
+}
 
 export declare const getFontCache: () => Map<any, any>;
 
-export declare const getFontSizeFromPhysicalSize: (font: LoadedFont, boxDimensions: BoxDimensions, physicalFontSize: PhysicalSize, textOutlineFactor?: number) => number;
+/**
+ * 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[];
+
+export declare const getFontSizeFromPhysicalSize: ({ font, boxDimensions, physicalSize, spacing, }: GetFontSizeFromPhysicalSizeOptions) => number;
 
-export declare const getRenderedText: (options: RenderTextOptions) => Promise<string>;
+export declare interface GetFontSizeFromPhysicalSizeOptions {
+    font: LoadedFont;
+    boxDimensions: BoxDimensions;
+    physicalSize: PhysicalSize;
+    spacing?: TextSpacing;
+}
 
-export declare const getTextMetricsAtFontSize: (font: LoadedFont, text: string, fontSize: number, outlineFactor?: number) => {
+/**
+ * Async text renderer. Loads font from URL, then delegates to renderText.
+ */
+export declare const getRenderedText: (options: GetRenderedTextOptions) => Promise<string>;
+
+/** Options for async getRenderedText (loads font from URL). */
+export declare interface GetRenderedTextOptions {
+    text: string;
+    fontUrl: string;
+    physicalSize: PhysicalSize;
+    boxDimensions: BoxDimensions;
+    spacing?: TextSpacing;
+    verticalAlignment?: VerticalTextAlignmentValues;
+    baseline?: BaselineType | BaselineConfig;
+    horizontalAlignment?: HorizontalTextAlignmentValues;
+    fillColour?: ColourInfo;
+    strokeColour?: ColourInfo;
+    colourMap?: ColourMap;
+}
+
+export declare interface GetTextAsPathDataOptions {
+    font: LoadedFont;
+    baselinePath: string;
+    text: string;
+    fontSize: number;
+    spacing?: TextSpacing;
+    horizontalAlignment?: HorizontalTextAlignmentValues;
+    colourMap?: ColourMap;
+}
+
+export declare const getTextMetricsAtFontSize: ({ font, text, fontSize, spacing, }: GetTextMetricsAtFontSizeOptions) => {
     width: number;
     height: number;
     baseline: number;
 };
 
+export declare interface GetTextMetricsAtFontSizeOptions {
+    font: LoadedFont;
+    text: string;
+    fontSize: number;
+    spacing?: TextSpacing;
+}
+
+export declare interface GlyphFill {
+    readonly pathData: string;
+    readonly colour: ColourInfo;
+}
+
 export declare type HorizontalTextAlignmentValues = 'left' | 'centre' | 'right' | 'distributed';
 
 export declare const LINE_HEIGHT = 1.1;
@@ -71,21 +148,54 @@ export declare const loadOpentypeFont: (fontUrl: string, fetchSVGGlyphs?: boolea
 
 export declare type MeasurementUnits = 'mm' | 'in';
 
+/**
+ * Normalise a baseline option (string shorthand or object) into a BaselineConfig.
+ */
+export declare const normaliseBaselineOption: (baseline: BaselineType | BaselineConfig | undefined) => BaselineConfig;
+
 export declare type PhysicalSize = [height: number, units: MeasurementUnits];
 
+/**
+ * Synchronous text renderer. Requires a pre-loaded font.
+ */
+export declare const renderText: (options: RenderTextOptions) => string;
+
+/** Options for synchronous renderText (font already loaded). */
 export declare interface RenderTextOptions {
     text: string;
-    fontUrl: string;
+    font: LoadedFont;
     physicalSize: PhysicalSize;
     boxDimensions: BoxDimensions;
-    outlineFactor?: number;
+    spacing?: TextSpacing;
     verticalAlignment?: VerticalTextAlignmentValues;
-    baseline?: BaselineType;
+    baseline?: BaselineType | BaselineConfig;
     horizontalAlignment?: HorizontalTextAlignmentValues;
-    fillColour?: string;
-    strokeColour?: string;
+    fillColour?: ColourInfo;
+    strokeColour?: ColourInfo;
+    colourMap?: ColourMap;
+}
+
+export declare interface SvgGlyphEntry {
+    content: string;
+    viewBox: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    glyphIndex: number;
+}
+
+export declare interface TextSpacing {
+    readonly outlineWidth: number;
+    readonly letterSpacing: number;
+    readonly letterSpacingOutline: number;
 }
 
+/**
+ * Validate a custom baseline SVG path string.
+ */
+export declare const validateCustomBaselinePath: (path: string) => void;
+
 export declare type VerticalTextAlignmentValues = 'centre' | 'top' | 'bottom';
 
 export { }