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

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## `1.3.0` – 2026-Apr-09
+
+- chore: switch to `tsdown` for building packages
+
+## `1.2.0` – 2026-Mar-13
+
+- added: support for Vite 8
+
 ## `1.1.1` – 2025-Sep-09
 
 - chore: bump dependencies

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Open-Xchange 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

@@ -16,7 +16,7 @@ Common configuration options for SVG sprites and PNG sprites.
 
 #### Option `format`
 
-- Type: `"svg" | "png"`
+- 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).
@@ -44,16 +44,16 @@ Example how to consume the SVG sprite in source code:
 ```ts
 // path/to/source.ts
 
-import svgSprite from "virtual:svg/my-icons.svg"
+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
+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")
+  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
 }
@@ -64,9 +64,9 @@ function createIcon(id: string): SVGElement {
 - Type: `string`
 - _required_
 
-The module name of the SVG sprite to be generated (with ".svg" extension).
+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]"`.
+The SVG markup of the sprite can be imported from the virtual module path `'virtual:svg/[spriteName]'`.
 
 #### Option `idPrefix`
 
@@ -80,17 +80,17 @@ A prefix to be added to all icon identifiers declared in the mapping file. By de
 ```ts
 // vite.config.ts
 
-import { defineConfig } from "vite" // or "vitest/config"
-import spritePlugin from "@open-xchange/vite-plugin-icon-sprite"
+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-",
+      format: 'svg',
+      imagesPath: 'src/icons/images',
+      mappingPath: 'src/icons/svg-mapping.yaml',
+      spriteName: 'icons.svg',
+      idPrefix: 'svg-',
     }),
   ],
 })
@@ -98,8 +98,8 @@ export default defineConfig(() => {
 
 - 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.
+- 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
 
@@ -110,7 +110,7 @@ The plugin collects multiple PNG files, and generates a virtual imports for one
 - Type: `string`
 - _required_
 
-The module name for the CSS file (with ".css" extension). The generated CSS markup can be imported from `"virtual:png/[cssName]"`.
+The module name for the CSS file (with '.css' extension). The generated CSS markup can be imported from `'virtual:png/[cssName]'`.
 
 #### Option `cssIconSize`
 
@@ -129,40 +129,41 @@ Additional padding around all icons to be generated in the sprites, in CSS pixel
 #### Option `cssIconSelector`
 
 - Type: `string`
-- Default: `"i.png-icon"`
+- 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"`
+- 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"`
+- 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. |
+| `'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"`
+- 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". |
+| - | - |
+| `'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.
 
@@ -173,7 +174,7 @@ All related CSS properties (e.g. `background-position` vs. `mask-position` etc.)
 
 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 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:
 
@@ -187,25 +188,25 @@ List of all icon sprites with different icon sizes to be generated.
 ```ts
 // vite.config.ts
 
-import { defineConfig } from "vite" // or "vitest/config"
-import spritePlugin from "@open-xchange/vite-plugin-icon-sprite"
+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",
+      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",
+      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" },
+        'icons1.png': { factor: 1, src: '[path]_16.png' },
+        'icons2.png': { factor: 2, src: '[path]_32.png' },
       },
     }),
   ]
@@ -214,10 +215,10 @@ export default defineConfig(() => {
 
 - 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"`.
+- 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 `: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).
 
@@ -235,7 +236,7 @@ The plugin expects an icon mapping file (plugin option `mappingPath`) which is a
 
 - 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.
+- 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
 
@@ -253,7 +254,7 @@ my-icon: commons/icon1
 other-icon: commons/icon2
 ```
 
-In source code, the icons can be used with the identifiers `"my-icon"` and `"other-icon"`.
+In source code, the icons can be used with the identifiers `'my-icon'` and `'other-icon'`.
 
 ##### Example 2: Simple PNG Icons
 
@@ -281,7 +282,7 @@ other-icon: commons/icon2
 # svg-mapping.yaml
 
 my-icon:
-  "*": commons/icon1
+  '*': commons/icon1
   de,fr: commons/icon2
   sv: commons/icon3
 ```
@@ -294,7 +295,7 @@ 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:
+Add the path to the schema file as property `'$schema'` to the mapping file:
 
 ```json
 // mapping.json
@@ -325,4 +326,4 @@ In VS Code, the plugin [redhat.vscode-yaml](https://marketplace.visualstudio.com
 
 ### Logging
 
-By default, warning messages and error messages will be logged to the shell. The environment variable `PLUGIN_REPLACE_ICON_SPRITE` can be used to change the log level of this plugin. Possible values are `info`, `warn`, `error`, and `silent`.
+By default, warning messages and error messages will be logged to the shell. The environment variable `PLUGIN_ICON_SPRITE_LOGLEVEL` can be used to change the log level of this plugin. Possible values are `info`, `warn`, `error`, and `silent`.

package/dist/index.d.mts

@@ -0,0 +1,147 @@
+import { Dict } from "@open-xchange/vite-helper/utils";
+import { PluginHelper } from "@open-xchange/vite-helper";
+import { Plugin } from "vite";
+
+//#region src/helper.d.ts
+/**
+ * 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.
+ */
+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;
+}
+//#endregion
+//#region src/plugin-svg.d.ts
+/**
+ * Configuration options for generating an SVG sprite from SVG source images.
+ */
+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;
+}
+//#endregion
+//#region src/plugin-png.d.ts
+/**
+ * Configuration options for generating PNG sprites from PNG source images.
+ */
+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;
+  }>;
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * Configuration options for generating icon sprites from SVG or PNG source
+ * images.
+ */
+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.
+ */
+declare function iconSpritePlugin(options: IconSpritePluginOptions): Plugin;
+//#endregion
+export { IconSpritePluginOptions, iconSpritePlugin as default };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/helper.ts","../src/plugin-svg.ts","../src/plugin-png.ts","../src/index.ts"],"mappings":";;;;;;;;;AAcA;;;UAAiB,uBAAA;EAAwB;;;EAKvC,MAAA,EAAQ,OAAA;EAWR;;;EANA,UAAA;;;ACRF;;EDcE,WAAA;AAAA;;;;;;UCde,sBAAA,SAA+B,uBAAA;EDFR;;;;;ECStC,UAAA;EDCA;;;;ECKA,QAAA;AAAA;;;;;ADfF;UECiB,sBAAA,SAA+B,uBAAA;EFDR;;;;EEOtC,OAAA;EFGA;;;EEEA,WAAA;;;;ADVF;;;ECkBE,cAAA;EDlB8C;;;;;;EC0B9C,eAAA;;AA3BF;;;;;EAmCE,cAAA;EAxBA;;;;;;;;;;;;;EAuCA,eAAA;;ACrDF;;;;;AAAqF;;;;;EDkEnF,cAAA;ECpD0E;;;;;;;;;;;;;;EDoE1E,OAAA,EAAS,IAAA;IAAO,MAAA;IAAgB,GAAA;EAAA;AAAA;;;;;AFhFlC;;KGFY,uBAAA,GAA0B,sBAAA,GAAyB,sBAAA;;;;;;;;;;;iBAcvC,gBAAA,CAAiB,OAAA,EAAS,uBAAA,GAA0B,MAAA"}