@mlightcad/mtext-renderer 0.8.8 → 0.8.9

package/lib/cache/fontCacheManager.d.ts

@@ -0,0 +1,71 @@
+import { FontData } from '../font';
+/**
+ * A simple font cache interface that provides map-like operations for font data
+ */
+export declare class FontCacheManager {
+    private static readonly DATABASE_NAME;
+    private static readonly DATABASE_VERSION;
+    private static _instance;
+    private db;
+    private isClosing;
+    private constructor();
+    /**
+     * Returns the singleton instance of the FontCacheManager
+     */
+    static get instance(): FontCacheManager;
+    /**
+     * Sets a font in the cache
+     * @param fileName The font file name (key)
+     * @param fontData The font data to store
+     */
+    set(fileName: string, fontData: FontData): Promise<void>;
+    /**
+     * Gets a font from the cache
+     * @param fileName The font file name (key)
+     * @returns The font data if found, undefined otherwise
+     */
+    get(fileName: string): Promise<FontData | undefined>;
+    /**
+     * Deletes a font from the cache
+     * @param fileName The font file name (key)
+     */
+    delete(fileName: string): Promise<void>;
+    /**
+     * Gets all fonts from the cache
+     * @returns An array of all font data in the cache
+     */
+    getAll(): Promise<FontData[]>;
+    /**
+     * Clears all fonts from the cache
+     */
+    clear(): Promise<void>;
+    /**
+     * Checks if a font exists in the cache
+     * @param fileName The font file name (key)
+     */
+    has(fileName: string): Promise<boolean>;
+    /**
+     * Closes the database connection and cleans up resources.
+     * After calling this, any further operations will require reopening the database.
+     */
+    close(): void;
+    /**
+     * Destroys the database instance and deletes all data.
+     * Use with caution as this operation cannot be undone.
+     */
+    destroy(): Promise<void>;
+    private getDatabase;
+    /**
+     * Applies all schema versions that are greater than the old version and less than or equal to the new version
+     * @param db The database instance
+     * @param oldVersion The old version of the database
+     * @param newVersion The new version of the database
+     */
+    private handleUpgrade;
+    /**
+     * Applies a single schema version's changes to the database
+     * @param db The database instance
+     * @param schema The schema version to apply
+     */
+    private applySchemaVersion;
+}

package/lib/cache/index.d.ts

@@ -0,0 +1 @@
+export * from './fontCacheManager';

package/lib/cache/schema.d.ts

@@ -0,0 +1,27 @@
+import { DBSchema } from 'idb';
+import { FontData } from '../font/font';
+/**
+ * Store name constant
+ */
+export declare const DB_STORES: {
+    readonly fonts: "fonts";
+};
+/**
+ * Database schema interface for the font cache
+ */
+export interface DbFontCacheSchema extends DBSchema {
+    [DB_STORES.fonts]: {
+        key: string;
+        value: FontData;
+    };
+}
+/**
+ * Database schema versions
+ */
+export declare const dbSchema: {
+    version: number;
+    stores: {
+        name: "fonts";
+        keyPath: string;
+    }[];
+}[];

package/lib/common/eventManager.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The class representing one event manager
+ */
+export declare class EventManager<T = unknown> {
+    private listeners;
+    /**
+     * Add the event listener
+     * @param listener Input listener to be added
+     */
+    addEventListener(listener: (payload: T) => void): void;
+    /**
+     * Remove the listener
+     * @param listener Input listener to be removed
+     */
+    removeEventListener(listener: (payload: T) => void): void;
+    /**
+     * Remove all listeners bound to the target and add one new listener
+     * @param listener Input listener to be added
+     */
+    replaceEventListener(listener: (payload: T) => void): void;
+    /**
+     * Notify all listeners
+     * @param payload Input payload passed to listener
+     */
+    dispatch(payload?: T, ...args: unknown[]): void;
+}

package/lib/common/index.d.ts

@@ -0,0 +1,2 @@
+export * from './eventManager';
+export * from './utils';

package/lib/common/utils.d.ts

@@ -0,0 +1,11 @@
+export declare const getExtension: (url: string) => string;
+export declare const getFileName: (url: string) => string | undefined;
+export declare const getFileNameWithoutExtension: (url: string) => string;
+/**
+ * AutoCAD files sometimes use an indexed color value between 1 and 255 inclusive.
+ * Each value corresponds to a color. index 1 is red, that is 16711680 or 0xFF0000.
+ * index 0 and 256, while included in this array, are actually reserved for inheritance
+ * values in AutoCAD so they should not be used for index color lookups.
+ */
+export declare const AUTOCAD_COLOR_INDEX: number[];
+export declare const getColorByIndex: (index: number) => number;

package/lib/font/baseFont.d.ts

@@ -0,0 +1,81 @@
+import { BaseTextShape } from './baseTextShape';
+import { CharGeometryCache } from './charGeometryCache';
+import { FontData, FontType } from './font';
+/**
+ * Abstract base class for font implementations.
+ * Provides common functionality and interface for font handling.
+ * This class defines the core interface that all font types must implement.
+ */
+export declare abstract class BaseFont {
+    /** The type of font (shx or mesh) */
+    abstract readonly type: FontType;
+    /**
+     * The parsed font data. Different types of fonts have different data structures.
+     * This data is used to render characters and calculate metrics.
+     */
+    abstract readonly data: unknown;
+    /**
+     * Font names. One font may have multiple names.
+     */
+    names: Set<string>;
+    /**
+     * Encoding used by character code. Please refer to the following link for encoding name.
+     * https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API/Encodings
+     */
+    encoding?: string;
+    /**
+     * Caching of font character geometries to improve text rendering performance.
+     */
+    cache: CharGeometryCache;
+    constructor(fontData: FontData);
+    /**
+     * Return true if this font contains glyph of the specified character. Otherwise, return false.
+     * @param char - The character to check
+     * @returns True if this font contains glyph of the specified character. Otherwise, return false.
+     */
+    abstract hasChar(char: string): boolean;
+    /**
+     * Return true if this font contains glyph of the specified character code. Otherwise, return false.
+     * @param code - The character code to check
+     * @returns True if this font contains glyph of the specified character code. Otherwise, return false.
+     */
+    abstract hasCode(code: number): boolean;
+    /**
+     * Record of characters that are not supported by this font.
+     * Maps character strings to their occurrence count.
+     * Used for tracking and reporting unsupported characters.
+     */
+    unsupportedChars: Record<string, number>;
+    /**
+     * Gets the shape data for a specific character at a given size.
+     * @param char - The character to get the shape for
+     * @param size - The desired size of the character
+     * @returns The shape data for the character, or undefined if not found
+     */
+    abstract getCharShape(char: string, size: number): BaseTextShape | undefined;
+    /**
+     * Gets the shape data for a specific character code at a given size.
+     * @param code - The character code to get the shape for
+     * @param size - The desired size of the character
+     * @returns The shape data for the character code, or undefined if not found
+     */
+    abstract getCodeShape(code: number, size: number): BaseTextShape | undefined;
+    /**
+     * Gets the scale factor for this font.
+     * This is used to adjust the size of characters when rendering.
+     * @returns The scale factor as a number
+     */
+    abstract getScaleFactor(): number;
+    /**
+     * Gets the shape to display when a character is not found in the font.
+     * @param size - The desired size of the not found shape
+     * @returns The shape data for the not found indicator, or undefined if not available
+     */
+    abstract getNotFoundTextShape(size: number): BaseTextShape | undefined;
+    /**
+     * Records an unsupported character in the font.
+     * Increments the count for the given character in unsupportedChars.
+     * @param char - The unsupported character to record
+     */
+    protected addUnsupportedChar(char: string): void;
+}

package/lib/font/baseTextShape.d.ts

@@ -0,0 +1,17 @@
+import * as THREE from 'three';
+/**
+ * Abstract base class for text shape implementations.
+ * Provides common functionality and interface for text shape handling.
+ * This class defines the core interface that all text shape types must implement.
+ */
+export declare abstract class BaseTextShape extends THREE.Shape {
+    /**
+     * Width used to render this character
+     */
+    width: number;
+    /**
+     * Converts the text shape to a THREE.js geometry
+     * @returns A THREE.js BufferGeometry representing the text shape
+     */
+    abstract toGeometry(): THREE.BufferGeometry;
+}

package/lib/font/charGeometryCache.d.ts

@@ -0,0 +1,43 @@
+import * as THREE from 'three';
+/**
+ * Manages caching of font character geometries to improve text rendering performance.
+ */
+export declare class CharGeometryCache {
+    private cache;
+    constructor();
+    /**
+     * Returns true if the geometry of the specified character code exists in the cache.
+     * Otherwise, returns false.
+     * @param code One character code.
+     * @param size The font size.
+     * @returns True if the geometry of the specified character code exists in the cache.
+     * Otherwise, returns false.
+     */
+    hasGeometry(code: number, size: number): boolean;
+    /**
+     * Get the geometry for a single character from cache if available.
+     * The cache key includes both character codeand size.
+     * @param code The character code to get geometry from cache.
+     * @param size The font size.
+     * @returns The geometry for a single character from cache if avaiable.
+     * Return undefined if the character not found in cache.
+     */
+    getGeometry(code: number, size: number): THREE.BufferGeometry | undefined;
+    /**
+     * Set the geometry to cache for a single character.
+     * @param char The character to set geometry for.
+     * @param size The font size.
+     * @param geometry The geometry to set.
+     */
+    setGeometry(code: number, size: number, geometry: THREE.BufferGeometry): void;
+    /**
+     * Dispose all cached geometries.
+     */
+    dispose(): void;
+    /**
+     * Generates cache key by character and font size.
+     * @param char One character code.
+     * @param size The font size.
+     */
+    private generateKey;
+}

package/lib/font/defaultFontLoader.d.ts

@@ -0,0 +1,50 @@
+import { FontInfo, FontLoader, FontLoadStatus } from './fontLoader';
+/**
+ * Default implementation of the FontLoader interface.
+ * This class provides font loading functionality using [this font repository](https://mlightcad.gitlab.io/cad-data/fonts/).
+ * It loads font metadata from a JSON file and provides access to available fonts.
+ */
+export declare class DefaultFontLoader implements FontLoader {
+    /** List of available fonts in the system */
+    private _avaiableFonts;
+    private _baseUrl;
+    private _avaiableFontMap;
+    /**
+     * Creates a new instance of DefaultFontLoader
+     */
+    constructor();
+    /**
+     * Base URL to load fonts
+     */
+    get baseUrl(): string;
+    set baseUrl(value: string);
+    /**
+     * Gets the list of available fonts
+     * @returns Array of FontInfo objects describing available fonts
+     */
+    get avaiableFonts(): FontInfo[];
+    /**
+     * Triggered when font url changed
+     * @param url - New font url value
+     */
+    onFontUrlChanged(url: string): void;
+    /**
+     * Retrieves information about all available fonts in the system.
+     * Loads font metadata from a CDN if not already loaded.
+     * @returns Promise that resolves to an array of FontInfo objects
+     * @throws {Error} If font metadata cannot be loaded from the CDN
+     */
+    getAvailableFonts(): Promise<FontInfo[]>;
+    /**
+     * Loads the specified fonts into the system. If one font is already loaded,
+     * the font will not be loaded again. If no font names are provided, just loads
+     * all available fonts information (not fonts).
+     * @param fontNames - Array of font names to load
+     * @returns Promise that resolves to an array of FontLoadStatus objects
+     */
+    load(fontNames: string[]): Promise<FontLoadStatus[]>;
+    /**
+     * Build one font map. The key is font name. The value is font info.
+     */
+    private buildFontMap;
+}

package/lib/font/font.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Represents the type of font supported by the system
+ * - 'shx': SHX font format commonly used in CAD systems
+ * - 'mesh': Mesh-based font format (e.g., TTF, OTF, WOFF)
+ */
+export type FontType = 'shx' | 'mesh';
+/**
+ * Represents font data stored in the cache database.
+ * This interface defines the structure of font data that is stored and retrieved from the cache.
+ */
+export interface FontData {
+    /** The font name */
+    name: string;
+    /** The alias names of the font */
+    alias: string[];
+    /** The type of font (shx or mesh) */
+    type: FontType;
+    /**
+     * Encoding used by character code. Please refer to the following link for encoding name.
+     * https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API/Encodings
+     */
+    encoding?: string;
+    /** The parsed font data. Different types of fonts have different data structures. */
+    data: unknown;
+}

package/lib/font/fontFactory.d.ts

@@ -0,0 +1,31 @@
+import { BaseFont } from './baseFont';
+import { FontData } from './font';
+/**
+ * A singleton factory class for creating font instances.
+ * This factory can create both ShxFont and MeshFont instances based on the provided font data.
+ * It handles the creation of appropriate font objects based on the font type and data format.
+ *
+ * @example
+ * ```typescript
+ * const fontFactory = FontFactory.getInstance();
+ * const font = fontFactory.createFont(fontData);
+ * ```
+ */
+export declare class FontFactory {
+    private static _instance;
+    private constructor();
+    /**
+     * Gets the singleton instance of the FontFactory
+     * @returns The FontFactory instance
+     */
+    static get instance(): FontFactory;
+    /**
+     * Creates a font instance based on the provided font data.
+     * The type of font created (ShxFont or MeshFont) is determined by the font type.
+     *
+     * @param data - The font data to create the font instance from
+     * @returns A new instance of either ShxFont or MeshFont
+     * @throws {Error} If the font data type is not supported
+     */
+    createFont(data: FontData): BaseFont;
+}

package/lib/font/fontLoader.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Represents information about a font in the system
+ */
+export interface FontInfo {
+    /** Array of font names/aliases */
+    name: string[];
+    /** Font file name */
+    file: string;
+    /** Type of the font - either mesh or shx format */
+    type: 'mesh' | 'shx';
+    /** URL where the font can be accessed */
+    url: string;
+    /**
+     * Encoding used by character code. Please refer to the following link for encoding name.
+     * https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API/Encodings
+     */
+    encoding?: string;
+}
+/**
+ * Represents the status of a font loading operation
+ */
+export interface FontLoadStatus {
+    /** Name of the font that was loaded */
+    fontName: string;
+    /** URL from which the font was loaded */
+    url: string;
+    /**
+     * The status to load font
+     * - Success
+     * - Font not found in font repository
+     * - Failed to load font from font repository
+     */
+    status: 'Success' | 'NotFound' | 'FailedToLoad';
+}
+/**
+ * Interface that defines font loading functionality.
+ * Applications should implement this interface to provide font loading capabilities.
+ * This interface abstracts the font loading process, allowing different implementations
+ * for different font sources or loading strategies.
+ */
+export interface FontLoader {
+    /**
+     * Loads the specified fonts into the system
+     * @param fontNames - Array of font names to load
+     * @returns Promise that resolves to an array of FontLoadStatus objects indicating the load status of each font
+     */
+    load(fontNames: string[]): Promise<FontLoadStatus[]>;
+    /**
+     * Retrieves information about all available fonts in the system
+     * @returns Promise that resolves to an array of FontInfo objects containing details about available fonts
+     */
+    getAvailableFonts(): Promise<FontInfo[]>;
+    /**
+     * Base URL to load fonts
+     */
+    get baseUrl(): string;
+    set baseUrl(value: string);
+}

package/lib/font/fontManager.d.ts

@@ -0,0 +1,192 @@
+import { EventManager } from '../common';
+import { BaseFont } from './baseFont';
+import { BaseTextShape } from './baseTextShape';
+import { FontType } from './font';
+import { FontInfo, FontLoader, FontLoadStatus } from './fontLoader';
+/**
+ * Font mappings configuration.
+ * Maps original font names to their replacement font names.
+ * - The key is the original font name
+ * - The value is the mapped font name
+ */
+export type FontMapping = Record<string, string>;
+/**
+ * Event arguments for font-related events.
+ */
+export interface FontManagerEventArgs {
+    /** Name of font which can't be found */
+    fontName: string;
+    /** The number of characters which use this font. This is only used when the font is not found. */
+    count?: number;
+}
+/**
+ * Manages font loading, caching, and text rendering.
+ * This class is responsible for:
+ * - Loading fonts from URLs or cache
+ * - Managing font mappings and replacements
+ * - Providing text shapes for rendering
+ * - Tracking unsupported characters and missed fonts
+ */
+export declare class FontManager {
+    private static _instance;
+    /** THREE.js file loader for loading font files */
+    private loader;
+    /** Font loader which can be swapped by users */
+    private fontLoader;
+    /** Mapping of original font names to their replacements */
+    protected fontMapping: FontMapping;
+    /** Map of loaded fonts, keyed by font name */
+    protected loadedFontMap: Map<string, BaseFont>;
+    /** List of font file names that have been loaded */
+    protected fileNames: string[];
+    /** Record of characters that are not supported by any loaded font */
+    unsupportedChars: Record<string, number>;
+    /** Record of fonts that were requested but not found */
+    missedFonts: Record<string, number>;
+    /** Flag to enable/disable font caching */
+    enableFontCache: boolean;
+    /** Default font to use when a requested font is not found */
+    defaultFont: string;
+    /** Event managers for font-related events */
+    readonly events: {
+        /** Event triggered when a font cannot be found */
+        fontNotFound: EventManager<FontManagerEventArgs>;
+        /** Event triggered when a font is successfully loaded */
+        fontLoaded: EventManager<FontManagerEventArgs>;
+    };
+    private constructor();
+    /**
+     * Gets the singleton instance of the FontManager
+     * @returns The FontManager instance
+     */
+    static get instance(): FontManager;
+    /**
+     * Base URL to load fonts
+     */
+    get baseUrl(): string;
+    set baseUrl(value: string);
+    /**
+     * Sets the font mapping configuration
+     * @param mapping - The font mapping to set
+     */
+    setFontMapping(mapping: FontMapping): void;
+    /**
+     * Sets the font loader
+     * @param fontLoader - The font loader to set
+     */
+    setFontLoader(fontLoader: FontLoader): void;
+    /**
+     * Retrieves information about all available fonts in the system.
+     * Loads font metadata from a CDN if not already loaded.
+     * @returns Promise that resolves to an array of FontInfo objects
+     * @throws {Error} If font metadata cannot be loaded from the CDN
+     */
+    getAvailableFonts(): Promise<FontInfo[]>;
+    /**
+     * Return true if the default font was loaded.
+     * @returns True if the default font was loaded. False otherwise.
+     */
+    isDefaultFontLoaded(): boolean;
+    /**
+     * Loads the default font
+     * @returns Promise that resolves to the font load statuses
+     */
+    loadDefaultFont(): Promise<FontLoadStatus[]>;
+    /**
+     * Loads the specified fonts from font names
+     * @param names - Font names to load.
+     * @returns Promise that resolves to an array of font load statuses
+     */
+    loadFontsByNames(names: string | string[]): Promise<FontLoadStatus[]>;
+    /**
+     * Loads the specified fonts from URLs
+     * @param urls - URLs of font files to load.
+     * @returns Promise that resolves to an array of font load statuses
+     */
+    loadFonts(fonts: FontInfo | FontInfo[]): Promise<FontLoadStatus[]>;
+    /**
+     * Tries to find the specified font. If not found, uses a replacement font and returns its name.
+     * @param fontName - The font name to find
+     * @returns The original font name if found, or the replacement font name if not found
+     */
+    findAndReplaceFont(fontName: string): string;
+    /**
+     * Gets font by font name. Return undefined if not found.
+     * @param fontName - The font name to find
+     * @param recordMissedFonts - Record the font name to property `missedFonts` in this class
+     * if the specified font name not found.
+     * @returns The font with the specified font name, or undefined if not found
+     */
+    getFontByName(fontName: string, recordMissedFonts?: boolean): BaseFont | undefined;
+    /**
+     * Gets the first font which contains the specified character.
+     * @param char - The character to get the shape for
+     * @returns The text shape for the character, or undefined if not found
+     */
+    getFontByChar(char: string): BaseFont | undefined;
+    /**
+     * Gets the text shape for a specific character with the specified font and size
+     * @param char - The character to get the shape for
+     * @param fontName - The name of the font to use
+     * @param size - The size of the character
+     * @returns The text shape for the character, or undefined if not found
+     */
+    getCharShape(char: string, fontName: string, size: number): BaseTextShape | undefined;
+    /**
+     * Gets the scale factor for a specific font
+     * @param fontName - The name of the font
+     * @returns The scale factor for the font, or 1 if the font is not found
+     */
+    getFontScaleFactor(fontName: string): number;
+    /**
+     * Gets type of the specific font
+     * @param fontName - The name of the font
+     * @returns The type of the font. If the specified font can't be found, `undefined` is returned
+     */
+    getFontType(fontName: string): FontType | undefined;
+    /**
+     * Gets the shape to display when a character is not found
+     * @param size - The size of the shape
+     * @returns The shape for the not found indicator, or undefined if not available
+     */
+    getNotFoundTextShape(size: number): BaseTextShape | undefined;
+    /**
+     * Checks if a font is already loaded in the system
+     * @param fontName - The name of the font to check
+     * @returns True if the font is loaded, false otherwise
+     */
+    isFontLoaded(fontName: string): boolean;
+    /**
+     * Records a font that was requested but not found
+     * @param fontName - The name of the font that was not found
+     */
+    private recordMissedFonts;
+    /**
+     * Loads a single font
+     * @param fontInfo - The matadata of the font to be loaded
+     */
+    private loadFont;
+    private fontInfoToFontData;
+    /**
+     * Loads all fonts from the cache
+     */
+    getAllFontsFromCache(): Promise<void>;
+    /**
+     * Gets a record of all unsupported characters across all loaded fonts
+     * @returns A record mapping unsupported characters to their occurrence count
+     */
+    getUnsupportedChar(): Record<string, number>;
+    /**
+     * Releases loaded fonts from memory.
+     *
+     * - If no argument is provided, all loaded fonts are released and the font map is cleared.
+     * - If a font name is provided, only that specific font is released from the font map.
+     *
+     * This is useful for freeing up memory, especially when working with large font files (e.g., Chinese mesh fonts).
+     * Notes: Based on testing, one Chinese mesh font file may take 40M memory.
+     *
+     * @param fontToRelease - (Optional) The name of the font to release. If omitted, all fonts are released.
+     * @returns `true` if the operation succeeded (all fonts released or the specified font was found and deleted), `false` if the specified font was not found.
+     */
+    release(fontToRelease?: string): boolean;
+}

package/lib/font/index.d.ts

@@ -0,0 +1,7 @@
+export * from './baseFont';
+export * from './baseTextShape';
+export * from './defaultFontLoader';
+export * from './font';
+export * from './fontFactory';
+export * from './fontLoader';
+export * from './fontManager';