favium/dist/index.d.ts

Favium is a lightweight package that allows you to create ICO and PNG formatted favicons from a canvas element.

interface ImageBundleOptions {
    /** Data URL for the ICO image */
    ico: string;
    /** Data URL for the 16x16 PNG image */
    png16: string;
    /** Data URL for the 32x32 PNG image */
    png32: string;
    /** Data URL for the 150x150 PNG image */
    png150: string;
    /** Data URL for the 180x180 PNG image */
    png180: string;
    /** Data URL for the 192x192 PNG image */
    png192: string;
    /** Data URL for the 512x512 PNG image */
    png512: string;
}
interface TextIconGeneratorOptions {
    /** Canvas width in pixels (default: 128) */
    width?: number;
    /** Canvas height in pixels (default: 128) */
    height?: number;
    /** Text to display, or null for no text (default: null) */
    text?: string | null;
    /** Text color (CSS color value, default: "white") */
    fontColor?: string;
    /** Font family (CSS font-family value, default: "Helvetica") */
    fontFamily?: string;
    /** Font size in pixels (default: 64) */
    fontSize?: number;
    /** Font weight (CSS font-weight value, default: "400") */
    fontWeight?: string;
    /** Font style (CSS font-style value, default: "normal") */
    fontStyle?: string;
    /** Corner radius in pixels (0 = square, >= min(width, height)/2 = circle, default: 0) */
    cornerRadius?: number;
    /** Background color (CSS color value, default: "black") */
    backgroundColor?: string;
}

declare class Bundle {
    private readonly canvas;
    constructor(canvas: HTMLCanvasElement);
    /**
     * Generates a bundle of various image formats and sizes
     * @returns Object containing ICO and PNG data URLs
     */
    generate(): ImageBundleOptions;
}

declare class TextIconGenerator {
    private readonly canvas;
    constructor(canvas: HTMLCanvasElement);
    /**
     * Generates an icon on the provided canvas with customizable corner radius and text.
     * @param options - Configuration options for the icon
     * @returns The generated canvas element
     * @throws {Error} If canvas context is unavailable or options are invalid
     */
    generate(options?: TextIconGeneratorOptions): HTMLCanvasElement;
    /**
     * Draws the background with a specified corner radius.
     * @param ctx - Canvas 2D rendering context
     * @param width - Canvas width in logical pixels
     * @param height - Canvas height in logical pixels
     * @param cornerRadius - Corner radius in pixels (clamped to fit within bounds)
     * @param backgroundColor - Background fill color
     */
    private drawBackground;
    /**
     * Measures text offsets for precise centering by analyzing pixel data.
     * @param ctx - Canvas 2D rendering context with font settings applied
     * @param text - Text to measure
     * @param fontSize - Font size in pixels
     * @returns Vertical and horizontal offsets for centering
     * @throws {Error} If temporary canvas context is unavailable
     */
    private measureOffsets;
    /**
     * Static method to create and generate an icon on a new canvas.
     * @param options - Configuration options for the icon
     * @returns The generated canvas element
     */
    static generate(options?: TextIconGeneratorOptions): HTMLCanvasElement;
}

declare class FaviconComposer {
    private readonly canvas;
    constructor(canvas: HTMLCanvasElement);
    /**
     * Generates a complete bundle of favicon images
     * @returns Bundle containing ICO and various PNG sizes
     */
    bundle(): ImageBundleOptions;
    /**
     * Generates an ICO file with specified sizes
     * @param sizes - Array of sizes in pixels
     * @returns Data URL of ICO image
     */
    ico(sizes?: number[]): string;
    /**
     * Generates a PNG image of specified size
     * @param size - Size in pixels (width and height)
     * @returns Data URL of PNG image
     */
    png(size: number): string;
    /**
     * Resizes the canvas to specified dimensions
     * @param size - Size in pixels (width and height)
     * @returns Resized canvas element
     */
    resize(size: number): HTMLCanvasElement;
}

/**
 * Generates ICO files from a canvas element, supporting multiple sizes.
 */
declare class Ico {
    private readonly canvas;
    /**
     * Creates an instance of Ico.
     * @param canvas - The source canvas element to generate ICO from.
     * @throws {TypeError} If the parameter is not an HTMLCanvasElement.
     */
    constructor(canvas: HTMLCanvasElement);
    /**
     * Generates an ICO file as a data URL with specified sizes.
     * @param sizes - Array of sizes (in pixels) for the ICO images (default: [16, 32, 48]).
     * @returns A data URL representing the ICO file.
     * @throws {RangeError} If any size is not a positive integer between 1 and 256.
     * @throws {Error} If the canvas context is unavailable.
     */
    generate(sizes?: number[]): string;
    /**
     * Creates the icon directory header.
     * @param numImages - Number of images in the ICO file.
     * @returns Binary string for the header.
     */
    private createIconDirHeader;
    /**
     * Creates an icon directory entry.
     * @param size - Image size (width and height).
     * @param bitmapSize - Size of the bitmap data.
     * @param offset - Offset to the bitmap data.
     * @returns Binary string for the entry.
     */
    private createIconDirEntry;
    /**
     * Creates the bitmap info header.
     * @param size - Image size (width and height).
     * @returns Binary string for the header.
     */
    private createBitmapInfoHeader;
    /**
     * Creates bitmap image data from a canvas.
     * @param canvas - The canvas to extract data from.
     * @returns Binary string of bitmap data.
     * @throws {Error} If the canvas context is unavailable.
     */
    private createBitmapImageData;
}

declare class Png {
    private readonly canvas;
    constructor(canvas: HTMLCanvasElement);
    /**
     * Generates a PNG image of specified size
     * @param size - Size in pixels (width and height)
     * @returns Data URL of PNG image
     */
    generate(size: number): string;
}

declare class Resize {
    private canvas;
    /**
     * Creates an instance of Resize.
     * @param canvas - The source canvas element to resize.
     * @throws {TypeError} If the parameter is not an HTMLCanvasElement.
     */
    constructor(canvas: HTMLCanvasElement);
    /**
     * Generates a resized canvas element with specified dimensions.
     * @param width - The desired width of the canvas.
     * @param height - The desired height of the canvas.
     * @returns The resized canvas element.
     * @throws {RangeError} If width or height is not a positive integer.
     */
    resize(width: number, height: number): HTMLCanvasElement;
    /**
     * Simple resize of a canvas element.
     */
    private _resize;
}

export { Resize as CanvasResize, FaviconComposer, Ico as IcoGenerator, Bundle as ImageBundleGenerator, type ImageBundleOptions, Png as PngGenerator, TextIconGenerator, type TextIconGeneratorOptions };