@open-xchange/vite-plugin-icon-sprite 0.0.1

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "typescript.tsdk": "node_modules/typescript/lib"
+}

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [0.0.1] - 2024-07-30
+
+- initial release

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 OX Software GmbH, Germany <info@open-xchange.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,324 @@
+# @open-xchange/vite-plugin-icon-sprite
+
+A Vite plugin that builds icon sprites from multiple SVG or PNG icon files.
+
+## Usage
+
+This plugin collects multiple SVG or PNG image files, assembles them into a single icon sprite file, and provides virtual modules that can be imported in source code.
+
+In Vite server mode, the icon sprite files will be generated on demand. When bundling the project, all icon sprite files referenced in source code will be generated and bundled.
+
+It is possible to instantiate this plugin repeatedly, e.g. in order to generate an SVG sprite and a PNG sprite in the same project.
+
+### Common Options
+
+Common configuration options for SVG sprites and PNG sprites.
+
+#### Option `format`
+
+- Type: `"svg" | "png"`
+- _required_
+
+The file format specifier of the icon sprite, and the source images. Depending on the value of this option, the plugin expects various file-format specific options (see below).
+
+#### Option `imagesPath`
+
+- Type: `string`
+- _required_
+
+Path to root directory with all image resource files to be processed.
+
+#### Option `mappingPath`
+
+- Type: `string`
+- _required_
+
+Path to the JSON or YAML configuration file containing the mapping between icon identifiers and SVG source file names (see below).
+
+### SVG Sprites
+
+The plugin collects multiple SVG files, and generates a virtual import for an SVG sprite file with multiple `<symbol>` elements that can be imported from source code.
+
+Example how to consume the SVG sprite in source code:
+
+```ts
+// path/to/source.ts
+
+import svgSprite from "virtual:svg/my-icons.svg"
+
+// insert the SVG sprite into the DOM to be able to refer to the <symbol> elements
+document.createElement("div").innerHTML = svgSprite
+
+// create an SVG element referring to an icon in the sprite
+function createIcon(id: string): SVGElement {
+  const useEl = document.createElementNS("http://www.w3.org/2000/svg", "use")
+  useEl.setAttribute("href", "#my-icon")
+  const iconEl = document.createElementNS("http://www.w3.org/2000/svg", "svg")
+  iconEl.append(useEl)
+  return iconEl
+}
+```
+
+#### Option `spriteName`
+
+- Type: `string`
+- _required_
+
+The 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]"`.
+
+#### Option `idPrefix`
+
+- Type: `string`
+- _optional_
+
+A prefix to be added to all icon identifiers declared in the mapping file. By default, no prefix will be added.
+
+#### SVG Sprite Example
+
+```ts
+// vite.config.ts
+
+import { defineConfig } from "vite" // or "vitest/config"
+import spritePlugin from "@open-xchange/vite-plugin-icon-sprite"
+
+export default defineConfig(() => {
+  plugins: [
+    spritePlugin({
+      format: "svg",
+      imagesPath: "src/icons/images",
+      mappingPath: "src/icons/svg-mapping.yaml",
+      spriteName: "icons.svg",
+      idPrefix: "svg-",
+    }),
+  ],
+})
+```
+
+- Collects all SVG files in the directory `src/icons/images`.
+- Uses the icon mapping in `src/icons/svg-mapping.yaml`.
+- Creates a virtual import `"virtual:svg/icons.svg"`.
+- Prefixes all icon identifiers with `svg-`, e.g. the icon key `my-icon` in the mapping file will result in the icon identifier `"svg-my-icon"` in source code.
+
+### PNG Sprites
+
+The plugin collects multiple PNG files, and generates a virtual imports for one or more sprite files with different icon sizes and a CSS file that can be imported from source code.
+
+#### Option `cssName`
+
+- Type: `string`
+- _required_
+
+The module name for the CSS file (with ".css" extension). The generated CSS markup can be imported from `"virtual:png/[cssName]"`.
+
+#### Option `cssIconSize`
+
+- Type: `number`
+- _required_
+
+Base size of all icons, in CSS pixels.
+
+#### Option `cssIconPadding`
+
+- Type: `number`
+- Default: `0`
+
+Additional padding around all icons to be generated in the sprites, in CSS pixels.
+
+#### Option `cssIconSelector`
+
+- Type: `string`
+- Default: `"i.png-icon"`
+
+The CSS selector for a PNG icon element to be used in all generated CSS rules.
+
+#### Option `rootLocaleAttr`
+
+- Type: `string`
+- Default: `"lang"`
+
+Name of the root element's attribute containing the locale identifier. Needed to generate CSS selectors for localized icons.
+
+#### Option `spriteColorType`
+
+- Type: `"source" | "monochrome" | "alpha"`
+- Default: `"source"`
+
+Specifies how to generate the sprite PNG files.
+
+| Value | Description |
+| - | - |
+| `"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. |
+
+#### Option `spriteFillType`
+
+- Type: `"background" | "mask"`
+- Default: `"background"`
+
+Specifies how the sprites are supposed to be used in CSS rules.
+
+| Value | Description |
+| `"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-position` vs. `mask-position` etc.) will be generated accordingly.
+
+#### Option `sprites`
+
+- Type: `Record<string, { factor: number; src: string }>`
+- _required_
+
+List of all icon sprites with different icon sizes to be generated.
+
+- The keys of the dictionary are the module names of the PNG sprites (with ".png" extension). The generated PNG sprite can be imported from `"virtual:png/[key]"`.
+
+- The values of the dictionary contain configuration options for the PNG sprite:
+
+  | Option | Type | Default | Description |
+  | - | - | - | - |
+  | `factor` | `number` | _required_ | Icon scaling factor (a multiplier for plugin option `cssIconSize`). All source PNG files must have the effective pixel size (`cssIconSize * factor`). |
+  | `src` | `string` | _required_ | 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. |
+
+#### PNG Sprite Example
+
+```ts
+// vite.config.ts
+
+import { defineConfig } from "vite" // or "vitest/config"
+import spritePlugin from "@open-xchange/vite-plugin-icon-sprite"
+
+export default defineConfig(() => {
+  plugins: [
+    spritePlugin({
+      format: "png",
+      imagesPath: "src/icons/images",
+      mappingPath: "src/icons/png-mapping.yaml",
+      cssName: "icons.css",
+      cssIconSize: 16,
+      cssIconPadding: 1,
+      cssIconSelector: "i.my-icon",
+      rootLocaleAttr: "data-icon-locale",
+      spriteColorType: "alpha",
+      spriteFillType: "mask",
+      sprites: {
+        "icons1.png": { factor: 1, src: "[path]_16.png" },
+        "icons2.png": { factor: 2, src: "[path]_32.png" },
+      },
+    }),
+  ]
+})
+```
+
+- Collects all PNG files in the directory `src/icons/images`. The images must exist in two sizes (16px and 32px), their file names must end with `_16.png` and `_32.png` respectively (according to the options `cssIconSize` and `sprites->factor`).
+- Uses the icon mapping in `src/icons/png-mapping.yaml`.
+- Creates the virtual imports `"virtual:svg/icons.css"`, `"virtual:svg/icons1.png"`, and `"virtual:svg/icons2.png"`.
+- Adds one pixel padding around all icons in the PNG sprites.
+- Generates CSS selectors for `<i>` elements with CSS class `my-icon`.
+- Generates `:root[data-icon-locale]` CSS selectors for localized icons (i.e., the UI locale code must be stored in the root element's attribute "data-icon-locale").
+- Generates PNG sprites consisting of an 8-bit alpha channel only.
+- Generates CSS rules using CSS mask (instead of background).
+
+### Icon Mapping File
+
+The plugin expects an icon mapping file (plugin option `mappingPath`) which is a JSON or YAML configuration file containing a mapping from arbitrary icon identifiers to the paths of the source images. The icon identifiers can be used later in source code to refer to a specific icon in the generated sprite.
+
+- The name of the configuration file can be chosen freely.
+
+- The configuration file must consist of a single object map.
+
+- Each entry maps a unique icon identifier (used in source code) to a source image to be used for that icon.
+
+- The source image file can be specified directly as string, or as dictionary for localized icons (more details below).
+
+- Only the base name of the source image file must be specified relative to the configured root directory of the image files. It must not contain the image size suffix (_PNG only_), nor a file extension (`.svg` or `.png`). See examples below.
+
+- Localized icons will be described by a dictionary mapping the ISO language identifiers (as comma-separated strings) to the image base names (as described above). The special locale code `"*"` is mandatory, and defines a default icon for unlisted locales. See examples below.
+
+#### Icon Mapping Examples
+
+In all examples, the configured image root directory (plugin option `imagesPath`) shall be `path/to/images`.
+
+##### Example 1: Simple SVG Icons
+
+- Assign the icon with the identifier `my-icon` to the SVG image `path/to/images/commons/icon1.svg`.
+- Assign the icon with the identifier `other-icon` to the SVG image `path/to/images/commons/icon2.svg`.
+
+```YAML
+# svg-mapping.yaml
+
+my-icon: commons/icon1
+other-icon: commons/icon2
+```
+
+In source code, the icons can be used with the identifiers `"my-icon"` and `"other-icon"`.
+
+##### Example 2: Simple PNG Icons
+
+Assuming that the plugin will generate PNG sprites for icons with sizes of 16px and 32px.
+
+- Assign the icon with the identifier `my-icon` to the PNG images `path/to/images/commons/icon1_16.png` (16x16 pixels) and `path/to/images/commons/icon1_32.png` (32x32 pixels).
+- Respectively, assign an icon with the identifier `other-icon` to the PNG images `path/to/images/commons/icon2_*.png`.
+
+The resulting mapping file looks exactly as the former mapping file for SVG icons:
+
+```YAML
+# png-mapping.yaml
+
+my-icon: commons/icon1
+other-icon: commons/icon2
+```
+
+##### Example 3: Localized Icons
+
+- Assign the icon with the identifier `my-icon` to the SVG image `path/to/images/commons/icon1.svg` by default.
+- Use the SVG image `path/to/images/commons/icon2.svg` in German and French UI instead.
+- Use the SVG image `path/to/images/commons/icon3.svg` in Swedish UI instead.
+
+```YAML
+# svg-mapping.yaml
+
+my-icon:
+  "*": commons/icon1
+  de,fr: commons/icon2
+  sv: commons/icon3
+```
+
+The same applies to PNG icons as well.
+
+#### Schema Validation
+
+This package provides a JSON schema that can be used for validation in editors.
+
+##### JSON Mapping File
+
+Add the path to the schema file as property `"$schema"` to the mapping file:
+
+```json
+// mapping.json
+
+{
+  "$schema": "../../node_modules/@open-xchange/vite-plugin-icon-sprite/dist/mapping-schema.json",
+  // ...
+}
+```
+
+Adjust the number of parent path fragments according to the location of the mapping file in the project.
+
+##### YAML Mapping File
+
+Add the path to the schema file in a `yaml-language-server` directive to the mapping file:
+
+```yaml
+# mapping.yaml
+
+# yaml-language-server: $schema=../../node_modules/@open-xchange/vite-plugin-icon-sprite/dist/mapping-schema.json
+
+# ...
+```
+
+Adjust the number of parent path fragments according to the location of the mapping file in the project.
+
+In VS Code, the plugin [redhat.vscode-yaml](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) needs to be installed to support this directive.

package/dist/helper.d.ts

@@ -0,0 +1,62 @@
+import { type PluginHelperConfig, PluginHelper } from "@open-xchange/vite-helper";
+/**
+ * Common configuration options (independent from the icon file format) for the
+ * plugin "@open-xchange/vite-plugin-icon-sprite".
+ *
+ * @template FormatT
+ *  The file format specifier of the icon sprite, and the source images.
+ */
+export interface SpritePluginBaseOptions<FormatT extends string> {
+    /**
+     * The file format specifier of the icon sprite, and the source images.
+     */
+    format: FormatT;
+    /**
+     * Path to root directory with all image resource files to be processed.
+     */
+    imagesPath: string;
+    /**
+     * Path to the JSON or YAML configuration file containing the mapping
+     * between icon identifiers and SVG source file names.
+     */
+    mappingPath: string;
+}
+/**
+ * Internal configuration of a `SpritePluginHelper` instance.
+ */
+export type SpritePluginConfig = Required<Pick<PluginHelperConfig, "pluginIndex" | "virtualModules">>;
+/**
+ * Represents a single entry in an icon mapping configuration file (a mapping
+ * between icon identifier, path to source image, and language code for
+ * localized icons).
+ */
+export interface IconMappingEntry {
+    /** The icon identifier used in source code to select an icon. */
+    iconId: string;
+    /** The path to the source image file to be inserted into the sprite. */
+    iconPath: string;
+    /** Language code for a localized icon. */
+    iconLang?: string;
+}
+/**
+ * Plugin helper for all icon file formats.
+ *
+ * @template OptionsT
+ *  Exact type of the options interface.
+ */
+export declare class SpritePluginHelper<OptionsT extends SpritePluginBaseOptions<string>> extends PluginHelper {
+    /** Resolved configuration options. */
+    readonly options: Required<Readonly<OptionsT>>;
+    protected constructor(config: SpritePluginConfig, options: Required<OptionsT>);
+    /**
+     * 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.
+     */
+    protected readIconMapping(): Promise<IconMappingEntry[]>;
+}

package/dist/helper.js

@@ -0,0 +1,56 @@
+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

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,19 @@
+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/mapping-schema.json

@@ -0,0 +1,32 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema",
+    "title": "Icon mapping for SVG or PNG icon sprites",
+    "description": "A dictionary that maps icon identifiers to source SVG or PNG image files.",
+    "type": "object",
+    "properties": {
+        "$schema": {
+            "type": "string",
+            "format": "uri-reference"
+        }
+    },
+    "patternProperties": {
+        "^[a-z0-9]+(-[a-z0-9]+)*$": {
+            "anyOf": [
+                {
+                    "type": "string"
+                },
+                {
+                    "type": "object",
+                    "patternProperties": {
+                        "^(\\*|[a-z]+(,[a-z]+)*)$": {
+                            "type": "string"
+                        }
+                    },
+                    "required": ["*"],
+                    "additionalProperties": false
+                }
+            ]
+        }
+    },
+    "additionalProperties": false
+}

package/dist/plugin-png.d.ts

@@ -0,0 +1,88 @@
+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 value is 0.
+     */
+    cssIconPadding?: number;
+    /**
+     * The CSS selector for a PNG icon element to be used in all generated CSS
+     * rules. Default value is "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 value is
+     * "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 value is "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 value is "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

@@ -0,0 +1,233 @@
+import Jimp 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(cssSpriteWidth * factor, cssSpriteHeight * factor, 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.read(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(image, (x + cssIconPadding) * factor, (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 pngColorType = { source: 6, monochrome: 4, alpha: 0 }[spriteColorType];
+            const spriteBuffer = await sprite.colorType(pngColorType).getBufferAsync(Jimp.MIME_PNG);
+            // 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

@@ -0,0 +1,32 @@
+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

@@ -0,0 +1,119 @@
+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/package.json

@@ -0,0 +1,45 @@
+{
+    "name": "@open-xchange/vite-plugin-icon-sprite",
+    "version": "0.0.1",
+    "description": "Vite plugin that builds icon sprites from SVG or PNG icon files",
+    "repository": {
+        "url": "https://gitlab.open-xchange.com/fspd/npm-packages/vite-plugin-icon-sprite"
+    },
+    "license": "MIT",
+    "engines": {
+        "node": "18.18.0 || ^20.9.0 || >=21.1.0"
+    },
+    "packageManager": "yarn@4.4.0",
+    "type": "module",
+    "exports": "./dist/index.js",
+    "scripts": {
+        "prepare": "husky",
+        "prepack": "yarn build && yarn lint",
+        "build": "npx --yes rimraf dist && tsc && npx --yes cpy-cli --flat src/*.json dist/",
+        "lint": "eslint ."
+    },
+    "lint-staged": {
+        "*.{js,ts,json}": "yarn lint"
+    },
+    "dependencies": {
+        "@open-xchange/vite-helper": "0.1.0",
+        "jimp": "0.22.12",
+        "svg-sprite": "2.0.4"
+    },
+    "devDependencies": {
+        "@open-xchange/linter-presets": "0.4.3",
+        "@types/node": "22.1.0",
+        "@types/svg-sprite": "0.0.39",
+        "@types/vinyl": "2.0.12",
+        "eslint": "9.8.0",
+        "husky": "9.1.4",
+        "typescript": "5.5.4",
+        "vite": "5.4.0"
+    },
+    "peerDependencies": {
+        "vite": "^5.3"
+    },
+    "resolutions": {
+        "semver": "^7.6.2"
+    }
+}