@open-xchange/vite-plugin-icon-sprite 1.1.1 → 1.3.0

package/dist/helper.js

@@ -1,56 +0,0 @@
-import { dictEntries } from "@open-xchange/vite-helper/utils";
-import { resolvePath } from "@open-xchange/vite-helper/file";
-import { PluginHelper } from "@open-xchange/vite-helper";
-// class SpritePluginHelper ===================================================
-/**
- * Plugin helper for all icon file formats.
- *
- * @template OptionsT
- *  Exact type of the options interface.
- */
-export class SpritePluginHelper extends PluginHelper {
-    /** Resolved configuration options. */
-    options;
-    // constructor ------------------------------------------------------------
-    constructor(config, options) {
-        super({
-            ...config,
-            virtualPrefix: options.format,
-            loggerPrefix: options.format,
-            logLevelEnvVar: "PLUGIN_ICON_SPRITE_LOGLEVEL",
-            cacheSrcFiles: [options.imagesPath + "/**/*." + options.format, options.mappingPath],
-        });
-        this.options = options;
-    }
-    // protected methods ------------------------------------------------------
-    /**
-     * Reads an icon mapping configuration file, and returns the entries as
-     * array.
-     *
-     * @param path
-     *  The path to the icon mapping configuration file to be read.
-     *
-     * @returns
-     *  The entries of the configuration file.
-     */
-    async readIconMapping() {
-        const schemaPath = resolvePath("./mapping-schema.json", import.meta.url);
-        const mappingDict = await this.readConfig(this.options.mappingPath, { schema: schemaPath });
-        // convert to array of `IconMappingEntry`
-        const iconMapping = [];
-        for (const [iconId, entry] of dictEntries(mappingDict)) {
-            const iconDict = (typeof entry === "string") ? { "*": entry } : entry;
-            for (const [languages, iconPath] of dictEntries(iconDict)) {
-                for (const iconLang of languages.split(",")) {
-                    if (iconLang === "*") {
-                        iconMapping.push({ iconId, iconPath });
-                    }
-                    else {
-                        iconMapping.push({ iconId, iconPath, iconLang });
-                    }
-                }
-            }
-        }
-        return iconMapping;
-    }
-}

package/dist/index.d.ts

@@ -1,19 +0,0 @@
-import type { Plugin } from "vite";
-import { type SvgSpritePluginOptions } from "./plugin-svg.js";
-import { type PngSpritePluginOptions } from "./plugin-png.js";
-/**
- * Configuration options for generating icon sprites from SVG or PNG source
- * images.
- */
-export type IconSpritePluginOptions = SvgSpritePluginOptions | PngSpritePluginOptions;
-/**
- * A plugin for Vite to generate an icon sprite file from multiple SVG or PNG
- * source files.
- *
- * @param options
- *  Plugin configuration options.
- *
- * @returns
- *  The plugin instance.
- */
-export default function iconSpritePlugin(options: IconSpritePluginOptions): Plugin;

package/dist/index.js

@@ -1,19 +0,0 @@
-import { svgSpritePlugin } from "./plugin-svg.js";
-import { pngSpritePlugin } from "./plugin-png.js";
-// plugin =====================================================================
-/**
- * A plugin for Vite to generate an icon sprite file from multiple SVG or PNG
- * source files.
- *
- * @param options
- *  Plugin configuration options.
- *
- * @returns
- *  The plugin instance.
- */
-export default function iconSpritePlugin(options) {
-    switch (options.format) {
-        case "svg": return svgSpritePlugin(import.meta.url, options);
-        case "png": return pngSpritePlugin(import.meta.url, options);
-    }
-}

package/dist/plugin-png.d.ts

@@ -1,97 +0,0 @@
-import type { Plugin } from "vite";
-import { type Dict } from "@open-xchange/vite-helper/utils";
-import { type SpritePluginBaseOptions } from "./helper.js";
-/**
- * Configuration options for generating PNG sprites from PNG source images.
- */
-export interface PngSpritePluginOptions extends SpritePluginBaseOptions<"png"> {
-    /**
-     * Module name for the CSS file (with ".css" extension). The generated CSS
-     * markup can be imported from `"virtual:png/[cssName]"`.
-     */
-    cssName: string;
-    /**
-     * Base size of all icons, in CSS pixels.
-     */
-    cssIconSize: number;
-    /**
-     * Additional padding around all icons to be generated in the sprites, in
-     * CSS pixels.
-     *
-     * @default 0
-     */
-    cssIconPadding?: number;
-    /**
-     * The CSS selector for a PNG icon element to be used in all generated CSS
-     * rules.
-     *
-     * @default "i.png-icon"
-     */
-    cssIconSelector?: string;
-    /**
-     * Name of the root element's attribute containing the locale identifier.
-     * Needed to generate CSS selectors for localized icons.
-     *
-     * @default "lang"
-     */
-    rootLocaleAttr?: string;
-    /**
-     * Specifies how to generate the sprite PNG files.
-     *
-     * - `"source"`: The source PNGs will be copied into the generated sprites
-     *   unmodified. They will contain three color channels and an alpha
-     *   channel.
-     * - `"monochrome"`: The generated sprites will be converted to monochrome.
-     *   They will contain a gray channel and an alpha channel.
-     * - `"alpha"`: Only the alpha channels of the source PNGs will be copied
-     *   into the generated sprites. They will contain a single gray channel
-     *   representing the original alpha channels.
-     *
-     * @default "source"
-     */
-    spriteColorType?: "source" | "monochrome" | "alpha";
-    /**
-     * Specifies how the sprites are supposed to be used in CSS rules.
-     *
-     * - `"background"`: The sprites will be attached via "background-image".
-     * - `"mask"`: The sprites will be attached via "mask-image".
-     *
-     * All related CSS properties (e.g. "(background|mask)-position" etc.) will
-     * be generated accordingly.
-     *
-     * @default "background"
-     */
-    spriteFillType?: "background" | "mask";
-    /**
-     * List of all icon sprites to be generated.
-     *
-     * - The keys of the dictionary are the module names of the PNG sprites
-     *   (with ".png" extension). The generated sprite PNG file can be imported
-     *   from `"virtual:png/[key]"`.
-     * - "factor" is the scaling factor (a multiplier for "cssIconSize"). All
-     *   source PNG files must have the effective pixel size (`cssIconSize *
-     *   factor`).
-     * - "src" specifies the pattern used to build the path of the source PNG
-     *   files. MUST contain the placeholder "[path]" that will be replaced
-     *   with the base paths contained in the icon mapping file referred in the
-     *   option "mappingFile".
-     */
-    sprites: Dict<{
-        factor: number;
-        src: string;
-    }>;
-}
-/**
- * A plugin for Vite to generate PNG sprite files from multiple PNG source
- * files.
- *
- * @param index
- *  URL of the index source file of this plugin.
- *
- * @param options
- *  Plugin configuration options.
- *
- * @returns
- *  The plugin instance.
- */
-export declare function pngSpritePlugin(index: string, options: PngSpritePluginOptions): Plugin;

package/dist/plugin-png.js

@@ -1,237 +0,0 @@
-import { Jimp, PNGColorType } from "jimp";
-import { onceFn } from "@open-xchange/vite-helper/utils";
-import { Cache } from "@open-xchange/vite-helper/cache";
-import { SpritePluginHelper } from "./helper.js";
-// constants ==================================================================
-const FILL_VENDOR_PREFIXES = {
-    background: [],
-    mask: ["webkit"],
-};
-// functions ==================================================================
-/**
- * Generates a CSS length string in pixels (omits unit for zero).
- *
- * @param value
- *  The length to be emitted.
- *
- * @returns
- *  The passed length with "px" unit.
- */
-function px(value) {
-    return value ? `${value}px` : "0";
-}
-// class PngSpritePluginHelper ================================================
-class PngSpritePluginHelper extends SpritePluginHelper {
-    #parseMappingOnce;
-    // constructor ------------------------------------------------------------
-    constructor(index, options) {
-        super({
-            pluginIndex: index,
-            virtualModules: [options.cssName, ...Object.keys(options.sprites)],
-        }, {
-            cssIconPadding: 0,
-            cssIconSelector: "i.png-icon",
-            rootLocaleAttr: "lang",
-            spriteColorType: "source",
-            spriteFillType: "background",
-            ...options,
-        });
-        this.#parseMappingOnce = onceFn(() => this.#parseMapping());
-    }
-    // public methods ---------------------------------------------------------
-    /**
-     * Generates an ES source module with CSS markup code for all icons.
-     *
-     * @returns
-     *  The source module with CSS markup for all icons.
-     */
-    async generateCssMarkupModule() {
-        // shortcuts to plugin options
-        const { cssName } = this.options;
-        // try to resolve cached version of generated file
-        return await this.generateModule(cssName, async () => {
-            this.info("generating CSS markup %f", cssName);
-            // parse mapping file which collects icon paths, CSS selectors, and entry positions
-            const cssMarkup = (await this.#parseMappingOnce()).cssMarkup;
-            this.info("CSS markup %f generated successfully", cssName);
-            return cssMarkup;
-        });
-    }
-    /**
-     * Generates the ES source module for a PNG sprite with a specific scaling
-     * factor.
-     *
-     * @param spriteName
-     *  The name of the sprite.
-     *
-     * @param factor
-     *  The scaling factor.
-     *
-     * @param srcPattern
-     *  The pattern for the source PNG images.
-     *
-     * @returns
-     *  The source module exporting the PNG sprite as base-64 encoded data URL.
-     */
-    async generateSpriteModule(spriteName, factor, srcPattern) {
-        // shortcuts to plugin options
-        const { imagesPath, cssIconSize, cssIconPadding, spriteColorType } = this.options;
-        // check configuration
-        this.ensure(factor > 0, "invalid scaling factor in configuration for sprite %f", spriteName);
-        this.ensure(srcPattern.includes("[path]"), "placeholder [path] expected in configuration for sprite %f", spriteName);
-        // try to resolve cached version of generated file
-        return await this.generateModule(spriteName, async () => {
-            this.info("generating sprite %f", spriteName);
-            // parse mapping file which collects icon paths, CSS selectors, and entry positions
-            const { cssSpriteWidth, cssSpriteHeight, entries } = await this.#parseMappingOnce();
-            // new image data is not clean out-of-the-box, explicitly fill with zeros
-            const sprite = new Jimp({ width: cssSpriteWidth * factor, height: cssSpriteHeight * factor, color: 0 });
-            // process all entries in the mapping configuration
-            for (const { iconPath, x, y } of entries) {
-                // expected pixel size for the current scaling factor
-                const size = cssIconSize * factor;
-                // load and parse the source image file
-                const path = imagesPath + "/" + srcPattern.replace("[path]", iconPath);
-                const buffer = await this.readBuffer(path);
-                const image = await Jimp.fromBuffer(buffer);
-                // validate the image size
-                const { width, height } = image.bitmap;
-                this.ensure((width === size) && (height === size), "wrong image width in %f (expected %s but got %s)", path, `${size}x${size}`, `${width}x${height}`);
-                // insert source image into the sprite
-                sprite.blit({ src: image, x: (x + cssIconPadding) * factor, y: (y + cssIconPadding) * factor });
-            }
-            // copy alpha of all pixels to RGB channels (alpha channel will be exported as greyscale without alpha)
-            if (spriteColorType === "alpha") {
-                for (let d = sprite.bitmap.data, i = 0, l = d.length; i < l; i += 4) {
-                    d.fill(d[i + 3], i, i + 3); // copy A to RGB
-                    d[i + 3] = 255; // set A to full opacity
-                }
-            }
-            // generate the binary PNG data (no preset constants for PNG color types in Jimp)
-            const colorType = {
-                source: PNGColorType.COLOR_ALPHA,
-                monochrome: PNGColorType.GRAYSCALE_ALPHA,
-                alpha: PNGColorType.GRAYSCALE,
-            }[spriteColorType];
-            const spriteBuffer = await sprite.getBuffer("image/png", { colorType });
-            // convert to base64 encoded data URL
-            const spriteDataUrl = `data:image/png;base64,${spriteBuffer.toString("base64")}`;
-            const moduleSource = `export default ${JSON.stringify(spriteDataUrl)};`;
-            this.info("sprite %f generated successfully", spriteName);
-            return moduleSource;
-        });
-    }
-    // private methods --------------------------------------------------------
-    // parses the mapping file once, generates a map from short icon paths to `SpriteEntry` descriptor objects
-    async #parseMapping() {
-        // shortcuts to plugin options
-        const { cssIconSize, cssIconPadding, cssIconSelector, rootLocaleAttr, spriteFillType } = this.options;
-        // CSS selectors for all sprite entries, mapped by short icon path (different icons may refer to the same source PNG)
-        const selectorMap = new Cache();
-        // process all entries in the mapping configuration, collect CSS selectors for each entry in the sprite
-        for (const { iconId, iconPath, iconLang } of await this.readIconMapping()) {
-            const selectors = selectorMap.upsert(iconPath, () => []);
-            const selector = `${cssIconSelector}[data-icon-id="${iconId}"]`;
-            if (iconLang) {
-                selectors.push(`:root[${rootLocaleAttr}="${iconLang}"] ${selector}`);
-                selectors.push(`:root[${rootLocaleAttr}^="${iconLang}_"] ${selector}`);
-            }
-            else {
-                selectors.push(selector);
-            }
-        }
-        // the size of one icon occupied in the sprite including padding, for scaling factor 1
-        const cssTileSize = cssIconSize + 2 * cssIconPadding;
-        // number of distinct icons in the sprites
-        const iconCount = selectorMap.size;
-        // generate a square-shaped sprite
-        const rowLength = Math.ceil(Math.sqrt(iconCount));
-        // the resulting size of a sprite, for scaling factor 1
-        const cssSpriteWidth = cssTileSize * rowLength;
-        const cssSpriteHeight = cssTileSize * Math.ceil(iconCount / rowLength);
-        // additional vendor prefixes for background/fill attributes
-        const prefixes = FILL_VENDOR_PREFIXES[spriteFillType];
-        // generates a background/mask CSS property definition with correct vendor prefixes
-        const fillProp = (name, value) => {
-            const prop = `${spriteFillType}-${name}: ${value};`;
-            return prefixes.map(prefix => `-${prefix}-${prop} `).join("") + prop;
-        };
-        // the contents of the resulting CSS file with icon definitions
-        const cssLines = [
-            `${cssIconSelector} {`,
-            "  display: inline-block;",
-            `  width: ${px(cssTileSize)};`,
-            `  height: ${px(cssTileSize)};`,
-            "  flex: 0 0 auto;",
-            `  ${fillProp("size", `${px(cssSpriteWidth)} ${px(cssSpriteHeight)}`)}`,
-            `  ${fillProp("origin", "content-box")}`,
-            "}",
-            `${cssIconSelector}[data-icon-id="none"] { visibility: hidden; }`,
-        ];
-        // generate all sprite entries as an array
-        const entries = Array.from(selectorMap, ([iconPath, selectors], index) => {
-            const x = cssTileSize * (index % rowLength);
-            const y = cssTileSize * Math.floor(index / rowLength);
-            const prop = fillProp("position", `${px(-x)} ${px(-y)}`);
-            for (const selector of selectors) {
-                cssLines.push(`${selector} { ${prop} }`);
-            }
-            return { iconPath, x, y };
-        });
-        // create the resulting CSS markup as string
-        const cssMarkup = cssLines.join("\n") + "\n";
-        return { cssMarkup, cssSpriteWidth, cssSpriteHeight, entries };
-    }
-}
-// plugin =====================================================================
-/**
- * A plugin for Vite to generate PNG sprite files from multiple PNG source
- * files.
- *
- * @param index
- *  URL of the index source file of this plugin.
- *
- * @param options
- *  Plugin configuration options.
- *
- * @returns
- *  The plugin instance.
- */
-export function pngSpritePlugin(index, options) {
-    // resolved configuration options
-    const { cssName, sprites } = options;
-    // helper instance for file system access, logging, etc.
-    const helper = new PngSpritePluginHelper(index, options);
-    // create and return the plugin object
-    return {
-        name: "@open-xchange/vite-plugin-icon-sprite/png",
-        // initialize file system cache for generated modules
-        async configResolved(viteConfig) {
-            await helper.initializeCache(viteConfig);
-        },
-        // pick matching imports
-        resolveId(source) {
-            return helper.resolveVirtualModuleId(source);
-        },
-        // load the PNG icon files, generate final PNG sprites and CSS file
-        async load(moduleId) {
-            // only handle the target modules specified in "resolveId"
-            const target = helper.matchVirtualModuleId(moduleId);
-            if (!target) {
-                return;
-            }
-            // generate the CSS markup
-            if (target === cssName) {
-                return await helper.generateCssMarkupModule();
-            }
-            // generate a PNG sprite (export binary data as plain Base64 encoded)
-            if (target in sprites) {
-                const { factor, src } = sprites[target];
-                return await helper.generateSpriteModule(target, factor, src);
-            }
-            // invalid module identifier
-            helper.fail("unknown output file %f", target);
-            return undefined;
-        },
-    };
-}

package/dist/plugin-svg.d.ts

@@ -1,32 +0,0 @@
-import type { Plugin } from "vite";
-import { type SpritePluginBaseOptions } from "./helper.js";
-/**
- * Configuration options for generating an SVG sprite from SVG source images.
- */
-export interface SvgSpritePluginOptions extends SpritePluginBaseOptions<"svg"> {
-    /**
-     * Module name of the SVG sprite to be generated (with ".svg" extension).
-     * The SVG markup of the sprite can be imported from the virtual module
-     * path `"virtual:svg/[spriteName]"`.
-     */
-    spriteName: string;
-    /**
-     * A prefix to be added to all icon identifiers declared in the mapping
-     * file. By default, no prefix will be added.
-     */
-    idPrefix?: string;
-}
-/**
- * A plugin for Vite to generate an SVG sprite file from multiple SVG source
- * files.
- *
- * @param index
- *  URL of the index source file of this plugin.
- *
- * @param options
- *  Plugin configuration options.
- *
- * @returns
- *  The plugin instance.
- */
-export declare function svgSpritePlugin(index: string, options: SvgSpritePluginOptions): Plugin;

package/dist/plugin-svg.js

@@ -1,119 +0,0 @@
-import { basename } from "node:path";
-import SVGSprite from "svg-sprite";
-import { SpritePluginHelper } from "./helper.js";
-// class SvgSpritePluginHelper ================================================
-class SvgSpritePluginHelper extends SpritePluginHelper {
-    constructor(index, options) {
-        super({
-            pluginIndex: index,
-            virtualModules: options.spriteName,
-        }, {
-            idPrefix: "",
-            ...options,
-        });
-    }
-    // public methods ---------------------------------------------------------
-    /**
-     * Generates the ES source module for an SVG sprite.
-     *
-     * @returns
-     *  The source module containing the SVG markup of the sprite.
-     */
-    async generateSpriteModule() {
-        // shortcuts to plugin options
-        const { imagesPath, idPrefix, spriteName } = this.options;
-        // try to resolve cached version of generated file
-        return await this.generateModule(spriteName, async () => {
-            this.info("compiling sprite %f", spriteName);
-            // create a reverse map from icon filenames to icon identifiers
-            const iconIdMap = new Map();
-            // create the core SVG spriter
-            const spriter = new SVGSprite({
-                shape: {
-                    id: {
-                        generator: name => iconIdMap.get(name) ?? "",
-                    },
-                    spacing: {
-                        box: "icon",
-                    },
-                    dimension: {
-                        maxWidth: 16,
-                        maxHeight: 16,
-                    },
-                },
-                svg: {
-                    xmlDeclaration: false,
-                    // - remove all <style> elements declaring a class with fill color
-                    // - remove all class attribute referring to the class from <style>
-                    // - add "fill" attribute to all <symbol> elements
-                    transform: markup => markup
-                        .replace(/<style>.*?<\/style>/g, "")
-                        .replace(/class=".*?" ?/g, "")
-                        .replace(/<symbol /g, '<symbol fill="currentColor" '),
-                },
-                mode: {
-                    inline: true,
-                    symbol: {
-                        sprite: spriteName,
-                        render: { less: false },
-                    },
-                },
-            });
-            // load all source SVG images
-            for (const { iconId, iconPath, iconLang } of await this.readIconMapping()) {
-                const path = `${imagesPath}/${iconPath}.svg`;
-                // icon identifier with configured prefix and language suffix
-                const idSuffix = iconLang ? `;${iconLang}` : "";
-                iconIdMap.set(basename(path), idPrefix + iconId + idSuffix);
-                // read SVG source image, insert into spriter instance
-                const markup = await this.readText(path);
-                spriter.add(path, null, markup);
-            }
-            // compile the SVG sprite
-            const result = (await spriter.compileAsync()).result;
-            const spriteMarkup = result.symbol.sprite.contents.toString("utf8");
-            const moduleCode = `export default ${JSON.stringify(spriteMarkup)};`;
-            this.info("sprite %f generated successfully", spriteName);
-            return moduleCode;
-        });
-    }
-}
-// plugin =====================================================================
-/**
- * A plugin for Vite to generate an SVG sprite file from multiple SVG source
- * files.
- *
- * @param index
- *  URL of the index source file of this plugin.
- *
- * @param options
- *  Plugin configuration options.
- *
- * @returns
- *  The plugin instance.
- */
-export function svgSpritePlugin(index, options) {
-    // helper instance for file system access, logging, etc.
-    const helper = new SvgSpritePluginHelper(index, options);
-    // create and return the plugin object
-    return {
-        name: "@open-xchange/vite-plugin-icon-sprite/svg",
-        // initialize file system cache for generated modules
-        async configResolved(viteConfig) {
-            await helper.initializeCache(viteConfig);
-        },
-        // pick matching imports
-        resolveId(source) {
-            return helper.resolveVirtualModuleId(source);
-        },
-        // load the SVG icon files, generate final SVG sprite
-        async load(moduleId) {
-            // only handle the output file specified in "resolveId"
-            if (!helper.matchVirtualModuleId(moduleId)) {
-                return null;
-            }
-            // create an ES module that exports the SVG markup of the sprite
-            return await helper.generateSpriteModule();
-        },
-    };
-}

package/dist/tsconfig.json

@@ -1,7 +0,0 @@
-{
-    "$schema": "https://json.schemastore.org/tsconfig",
-    "extends": "../../../tsconfig.shared.json",
-    "compilerOptions": {
-        "outDir": "../dist"
-    }
-}