@peculiar/pdf-font/build/index.d.ts

Font handling library for PDF document generation

import { BufferSource } from 'pvtsutils';

declare enum DefaultFonts {
    Courier = "Courier",
    CourierBold = "Courier-Bold",
    CourierBoldOblique = "Courier-BoldOblique",
    CourierOblique = "Courier-Oblique",
    Helvetica = "Helvetica",
    HelveticaBold = "Helvetica-Bold",
    HelveticaBoldOblique = "Helvetica-BoldOblique",
    HelveticaOblique = "Helvetica-Oblique",
    Symbol = "Symbol",
    TimesBold = "Times-Bold",
    TimesBoldItalic = "Times-BoldItalic",
    TimesItalic = "Times-Italic",
    TimesRoman = "Times-Roman",
    ZapfDingbats = "ZapfDingbats"
}
declare const DefaultFontsZip: Map<DefaultFonts, string>;

/**
 * Interface representing a font glyph
 * @remarks
 * A font glyph is a specific graphical representation of a character in a font.
 */
interface IFontGlyph {
    /**
     * Index of the glyph in the font
     */
    index: number;
    /**
     * The glyph's advance width, in font units.
     */
    advanceWidth: number;
    /**
     * Unicode scalar value(s) associated with the glyph
     */
    unicode: number[];
}

declare class FontGlyph implements IFontGlyph {
    index: number;
    advanceWidth: number;
    unicode: number[];
    constructor(params?: Partial<FontGlyph>);
}

declare class FontHead {
    xMin: number;
    xMax: number;
    yMin: number;
    yMax: number;
}

declare class FontName {
    fontFamily: string;
    fontSubfamily: string;
    fullName: string;
    postScriptName: string;
}

declare class FontOS2 {
    sCapHeight: number;
    sxHeight: number;
    usWeightClass: number;
}

declare class FontPost {
    italicAngle: number;
}

/**
 * Information about a font.
 */
interface IFontInfo {
    /**
     * The number of font units per em square.
     */
    unitsPerEm: number;
    /**
     * The font's ascent value, defined as the vertical distance from the baseline to the top of the font.
     */
    ascent: number;
    /**
     * The font's descent value, defined as the vertical distance from the baseline to the bottom of the font.
     */
    descent: number;
    /**
     * Looks for the GLYPH by the unicode
     * @param code unicode
     * @returns
     */
    findGlyph(code: number): IFontGlyph | null;
}

/**
 * Implementation of IFontInfo interface that provides comprehensive information about a font.
 * Contains font metrics, glyph data, and various font properties from different font tables
 * (name, head, OS/2, post).
 */
declare class FontInfo implements IFontInfo {
    name: FontName;
    head: FontHead;
    os2: FontOS2;
    post: FontPost;
    glyphs: FontGlyph[];
    unitsPerEm: number;
    ascent: number;
    descent: number;
    /**
     * Looks for the GLYPH by the unicode
     * @param code unicode
     * @returns
     */
    findGlyph(code: number): FontGlyph | null;
    /**
     * Returns a list of unique glyphs for all characters in the specified text.
     * The glyphs are sorted by their index in ascending order.
     * @param text - The input text to get glyphs for
     * @returns Array of FontGlyph objects corresponding to unique characters in the text
     */
    getGlyphs(text: string): FontGlyph[];
    /**
     * Compares two FontGlyph objects by their index for sorting purposes.
     * @param a - First FontGlyph to compare
     * @param b - Second FontGlyph to compare
     * @returns -1 if a < b, 1 if a > b, 0 if equal
     * @private
     */
    private static sortByIndex;
}

/**
 * Factory class for creating and managing font objects.
 * Provides functionality to create fonts from different sources,
 * manage default fonts, and create font subsets.
 */
declare abstract class FontFactory {
    private static readonly cache;
    /**
     * Creates a FontInfo object from either a default font or a buffer source.
     * @param source - The font source, either a DefaultFonts enum value or a BufferSource
     * @returns A FontInfo object representing the font
     */
    static create(source: DefaultFonts | BufferSource): FontInfo;
    /**
     * Creates a FontInfo object from a default font.
     * Uses internal caching to improve performance for frequently used fonts.
     * @param source - The default font to create
     * @returns A FontInfo object representing the default font
     * @throws Error if the specified default font doesn't exist
     */
    static createDefault(source: DefaultFonts): FontInfo;
    /**
     * Creates a FontInfo object from a font file buffer.
     * @param source - The font file buffer
     * @returns A FontInfo object containing the parsed font data
     * @throws Error if required font tables are missing
     */
    static createFile(source: BufferSource): FontInfo;
    /**
     * Gets glyph indexes for the specified text from a font.
     * @param fontjs - The font object
     * @param text - The text to get indexes for
     * @returns An array of glyph indexes
     * @private
     */
    private static getIndexes;
    /**
     * Creates a subset of a font containing only the glyphs needed for the specified text.
     * @param source - The original font buffer
     * @param text - The text that determines which glyphs to include in the subset
     * @returns A new ArrayBuffer containing the subsetted font
     */
    static subsetFont(source: BufferSource, text: string): ArrayBuffer;
}

export { DefaultFonts, DefaultFontsZip, FontFactory, FontGlyph, FontHead, FontInfo, FontName, FontOS2, type IFontGlyph, type IFontInfo };