@pikacss/plugin-icons 0.0.47 → 0.0.48

package/README.md

@@ -0,0 +1,37 @@
+# @pikacss/plugin-icons
+
+Iconify icons plugin for PikaCSS. Renders icons from Iconify collections as CSS mask-image or background-image.
+
+## Installation
+
+```bash
+pnpm add -D @pikacss/plugin-icons
+```
+
+## Usage
+
+```ts
+import { defineEngineConfig } from '@pikacss/core'
+import { icons } from '@pikacss/plugin-icons'
+
+export default defineEngineConfig({
+  plugins: [icons()],
+  icons: {
+    autoInstall: true,
+  },
+})
+```
+
+Then use in templates:
+
+```vue
+<div :class="pika('i-mdi:home')" />
+```
+
+## Documentation
+
+See the [full documentation](https://pikacss.com/guide/plugins/icons).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -10,72 +10,154 @@ interface IconMeta {
   mode?: IconsConfig['mode'];
 }
 type IconSource = 'custom' | 'local' | 'cdn';
+/**
+ * Configuration options for the PikaCSS icons plugin.
+ *
+ * @remarks Controls how icon utilities are resolved, loaded, and rendered as CSS.
+ * Icons are loaded from custom collections first, then from locally installed
+ * Iconify packages, and finally from a CDN if configured.
+ *
+ * @example
+ * ```ts
+ * import { defineEngineConfig } from '@pikacss/core'
+ * import { icons } from '@pikacss/plugin-icons'
+ *
+ * export default defineEngineConfig({
+ *   plugins: [icons()],
+ *   icons: {
+ *     prefix: 'i-',
+ *     mode: 'auto',
+ *     scale: 1,
+ *     cdn: 'https://esm.sh/@iconify-json/{collection}/icons.json',
+ *   },
+ * })
+ * ```
+ */
 interface IconsConfig {
   /**
-   * Class name prefix for icon shortcuts.
+   * One or more prefixes used to match icon utility names. When a utility
+   * matches `<prefix><collection>:<name>`, it resolves to an icon style.
    *
-   * @default 'i-'
+   * @default `'i-'`
    */
   prefix?: string | string[];
   /**
-   * Default rendering mode.
+   * Rendering strategy for icon SVGs. `'mask'` uses a CSS mask with
+   * `currentColor` as the fill, allowing color inheritance. `'bg'` renders
+   * the SVG as a background image with its original colors. `'auto'`
+   * chooses `'mask'` when the SVG contains `currentColor`, otherwise `'bg'`.
    *
-   * @default 'auto'
+   * @default `'auto'`
    */
   mode?: 'auto' | 'mask' | 'bg';
   /**
-   * Scale icons against 1em.
+   * Multiplier applied to the icon's intrinsic width and height.
+   * Combined with `unit` to produce the final CSS dimensions.
    *
-   * @default 1
+   * @default `1`
    */
   scale?: number;
   /**
-   * Native Iconify custom collections.
+   * Custom icon collections keyed by collection name. Each entry maps
+   * icon names to SVG strings or async loaders, checked before local
+   * packages and the CDN.
+   *
+   * @default `undefined`
    */
   collections?: CustomCollections;
   /**
-   * Native Iconify SVG customizations.
+   * Iconify customization hooks applied when loading icons. Allows
+   * transforming SVG attributes, trimming whitespace, and running
+   * per-icon logic via `iconCustomizer`.
+   *
+   * @default `{}`
    */
   customizations?: IconCustomizations;
   /**
-   * Auto install missing Iconify JSON packages when supported by the runtime.
+   * When enabled, automatically installs missing `@iconify-json/*`
+   * packages on demand during local icon resolution.
    *
-   * @default false
+   * @default `false`
    */
   autoInstall?: IconifyLoaderOptions['autoInstall'];
   /**
-   * Current working directory used to resolve local Iconify JSON packages.
+   * Working directory used by the Iconify node loader when resolving
+   * locally installed icon packages.
    *
-   * @default process.cwd()
+   * @default `undefined`
    */
   cwd?: IconifyLoaderOptions['cwd'];
   /**
-   * Optional CDN base URL or URL template for collection JSON.
-   * Use `{collection}` as a placeholder to fully control the final URL.
+   * CDN URL template for fetching remote icon sets. Use `{collection}`
+   * as a placeholder for the collection name, or provide a base URL
+   * and the collection name will be appended as `<url>/<collection>.json`.
+   *
+   * @default `undefined`
    */
   cdn?: string;
   /**
-   * CSS unit used when width or height need to be synthesized.
+   * CSS unit appended to the icon's width and height (e.g. `'em'`, `'rem'`).
+   * When set, produces explicit dimension values like `1em` based on `scale`.
+   * When omitted, dimensions are left to the SVG's intrinsic size.
+   *
+   * @default `undefined`
    */
   unit?: string;
   /**
-   * Additional CSS properties applied to every resolved icon.
+   * Additional CSS properties merged into every generated icon style item.
+   * Useful for adding `display`, `vertical-align`, or other layout properties.
+   *
+   * @default `{}`
    */
   extraProperties?: Record<string, string>;
   /**
-   * Processor for the CSS object before stringify
+   * Post-processing callback invoked on each generated icon style item before
+   * it is returned. Receives the mutable style item and resolved icon metadata,
+   * allowing custom property injection or conditional transformations.
+   *
+   * @default `undefined`
    */
   processor?: (styleItem: StyleItem, meta: Required<IconMeta>) => void;
   /**
-   * Specify the icons for auto-completion.
+   * Explicit list of icon identifiers (e.g. `'mdi:home'`) to include in
+   * editor autocomplete suggestions. Each entry is combined with every
+   * configured prefix.
+   *
+   * @default `undefined`
    */
   autocomplete?: string[];
 }
 declare module '@pikacss/core' {
   interface EngineConfig {
+    /**
+     * Configuration for the icons plugin. Requires the `icons()` plugin
+     * to be registered in `plugins` for this configuration to take effect.
+     *
+     * @default `undefined`
+     */
     icons?: IconsConfig;
   }
 }
+/**
+ * Creates the PikaCSS icons engine plugin.
+ *
+ * @returns An engine plugin that registers icon shortcut rules and autocomplete entries.
+ *
+ * @remarks Resolves icon SVGs from custom collections, locally installed
+ * `@iconify-json/*` packages, or a remote CDN. Each matched utility is
+ * expanded into a CSS style item using either mask or background rendering.
+ * Configure behavior through the `icons` key in your engine config.
+ *
+ * @example
+ * ```ts
+ * import { icons } from '@pikacss/plugin-icons'
+ *
+ * export default defineEngineConfig({
+ *   plugins: [icons()],
+ *   icons: { prefix: 'i-', mode: 'auto' },
+ * })
+ * ```
+ */
 declare function icons(): EnginePlugin;
 //#endregion
 export { IconsConfig, icons };

package/dist/index.mjs

@@ -3,7 +3,6 @@ import { encodeSvgForCss, loadIcon, quicklyValidateIconSet, searchForIcon, strin
 import { loadNodeIcon } from "@iconify/utils/lib/loader/node-loader";
 import { defineEnginePlugin, log } from "@pikacss/core";
 import { $fetch } from "ofetch";
-
 //#region src/index.ts
 /**
 * Environment flags helper function to detect the current runtime environment.
@@ -16,17 +15,41 @@ function getEnvFlags() {
 		isESLint: isNode && !!process.env.ESLINT
 	};
 }
+const RE_ESCAPE_REGEXP = /[|\\{}()[\]^$+*?.-]/g;
+const RE_CAMEL_CASE_ICON_BOUNDARY = /([a-z])([A-Z])/g;
+const RE_DIGIT_ICON_BOUNDARY = /([a-z])(\d+)/g;
+const RE_TRAILING_SLASH = /\/$/;
+/**
+* Creates the PikaCSS icons engine plugin.
+*
+* @returns An engine plugin that registers icon shortcut rules and autocomplete entries.
+*
+* @remarks Resolves icon SVGs from custom collections, locally installed
+* `@iconify-json/*` packages, or a remote CDN. Each matched utility is
+* expanded into a CSS style item using either mask or background rendering.
+* Configure behavior through the `icons` key in your engine config.
+*
+* @example
+* ```ts
+* import { icons } from '@pikacss/plugin-icons'
+*
+* export default defineEngineConfig({
+*   plugins: [icons()],
+*   icons: { prefix: 'i-', mode: 'auto' },
+* })
+* ```
+*/
 function icons() {
 	return createIconsPlugin();
 }
 const globalColonRE = /:/g;
 const currentColorRE = /currentColor/;
 function normalizePrefixes(prefix) {
-	const prefixes = [prefix ?? "i-"].flat().filter(Boolean);
+	const prefixes = [prefix].flat().filter(Boolean);
 	return [...new Set(prefixes)];
 }
 function escapeRegExp(value) {
-	return value.replace(/[|\\{}()[\]^$+*?.-]/g, "\\$&");
+	return value.replace(RE_ESCAPE_REGEXP, "\\$&");
 }
 function createShortcutRegExp(prefixes) {
 	return new RegExp(`^(?:${prefixes.map(escapeRegExp).join("|")})([\\w:-]+)(?:\\?(mask|bg|auto))?$`);
@@ -34,8 +57,8 @@ function createShortcutRegExp(prefixes) {
 function getPossibleIconNames(iconName) {
 	return [
 		iconName,
-		iconName.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase(),
-		iconName.replace(/([a-z])(\d+)/g, "$1-$2")
+		iconName.replace(RE_CAMEL_CASE_ICON_BOUNDARY, "$1-$2").toLowerCase(),
+		iconName.replace(RE_DIGIT_ICON_BOUNDARY, "$1-$2")
 	];
 }
 function createAutocomplete(prefixes, autocomplete = []) {
@@ -52,7 +75,7 @@ function createAutocompletePatterns(prefixes) {
 }
 function resolveCdnCollectionUrl(cdn, collection) {
 	if (cdn.includes("{collection}")) return cdn.replaceAll("{collection}", collection);
-	return `${cdn.replace(/\/$/, "")}/${collection}.json`;
+	return `${cdn.replace(RE_TRAILING_SLASH, "")}/${collection}.json`;
 }
 function createLoaderOptions(config, usedProps) {
 	const { scale = 1, collections, autoInstall = false, cwd, unit, extraProperties = {}, customizations = {} } = config;
@@ -73,10 +96,9 @@ function createLoaderOptions(config, usedProps) {
 			trimCustomSvg: customizations.trimCustomSvg ?? true,
 			async iconCustomizer(collection, icon, props) {
 				await iconCustomizer?.(collection, icon, props);
-				if (unit) {
-					if (!props.width) props.width = `${scale}${unit}`;
-					if (!props.height) props.height = `${scale}${unit}`;
-				}
+				if (!unit) return;
+				if (!props.width) props.width = `${scale}${unit}`;
+				if (!props.height) props.height = `${scale}${unit}`;
 			}
 		}
 	};
@@ -147,7 +169,7 @@ function createIconsPlugin() {
 	return defineEnginePlugin({
 		name: "icons",
 		configureRawConfig: async (config) => {
-			iconsConfig = config.icons || {};
+			iconsConfig = config.icons ?? {};
 		},
 		configureEngine: async (_engine) => {
 			engine = _engine;
@@ -155,7 +177,7 @@ function createIconsPlugin() {
 			const prefixes = normalizePrefixes(prefix);
 			const autocomplete = createAutocomplete(prefixes, _autocomplete);
 			const autocompletePatterns = createAutocompletePatterns(prefixes);
-			engine.appendAutocomplete({ patterns: { styleItemStrings: autocompletePatterns } });
+			engine.appendAutocomplete({ patterns: { shortcuts: autocompletePatterns } });
 			engine.shortcuts.add({
 				shortcut: createShortcutRegExp(prefixes),
 				value: async (match) => {
@@ -212,6 +234,5 @@ function createIconsPlugin() {
 		}
 	});
 }
-
 //#endregion
-export { icons };
+export { icons };

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@pikacss/plugin-icons",
   "type": "module",
-  "version": "0.0.47",
+  "version": "0.0.48",
   "author": "DevilTea <ch19980814@gmail.com>",
   "license": "MIT",
+  "homepage": "https://pikacss.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/pikacss/pikacss.git",
+    "url": "git+https://github.com/pikacss/pikacss.git",
     "directory": "packages/plugin-icons"
   },
   "bugs": {
@@ -20,6 +21,7 @@
     "pikacss-plugin",
     "icons"
   ],
+  "sideEffects": false,
   "exports": {
     ".": {
       "import": {
@@ -36,23 +38,26 @@
   "files": [
     "dist"
   ],
+  "engines": {
+    "node": ">=22"
+  },
   "peerDependencies": {
-    "@pikacss/core": "0.0.47"
+    "@pikacss/core": "0.0.48"
   },
   "dependencies": {
     "@iconify/utils": "^3.1.0",
     "ofetch": "^1.5.1"
   },
   "devDependencies": {
-    "@pikacss/core": "0.0.47"
+    "@pikacss/core": "0.0.48"
   },
   "scripts": {
-    "build": "tsdown && pnpm exec publint",
+    "build": "tsdown",
     "build:watch": "tsdown --watch",
     "typecheck": "pnpm typecheck:package && pnpm typecheck:test",
     "typecheck:package": "tsc --project ./tsconfig.package.json --noEmit",
     "typecheck:test": "tsc --project ./tsconfig.tests.json --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "test": "vitest run --config ./vitest.config.ts",
+    "test:watch": "vitest --config ./vitest.config.ts"
   }
 }