@pikacss/plugin-icons 0.0.46 → 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

@@ -1,28 +1,163 @@
-import { EnginePlugin, Simplify, StyleItem } from "@pikacss/core";
-import { IconsOptions } from "@unocss/preset-icons";
+import { CustomCollections, IconCustomizations, IconifyLoaderOptions } from "@iconify/utils";
+import { EnginePlugin, StyleItem } from "@pikacss/core";
 
 //#region src/index.d.ts
 interface IconMeta {
   collection: string;
   name: string;
   svg: string;
+  source: IconSource;
   mode?: IconsConfig['mode'];
 }
-type IconsConfig = Simplify<Omit<IconsOptions, 'warn' | 'layer' | 'processor' | 'customFetcher'> & {
+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 {
   /**
-   * Processor for the CSS object before stringify
+   * 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-'`
+   */
+  prefix?: string | string[];
+  /**
+   * 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'`
+   */
+  mode?: 'auto' | 'mask' | 'bg';
+  /**
+   * Multiplier applied to the icon's intrinsic width and height.
+   * Combined with `unit` to produce the final CSS dimensions.
+   *
+   * @default `1`
+   */
+  scale?: number;
+  /**
+   * 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;
+  /**
+   * Iconify customization hooks applied when loading icons. Allows
+   * transforming SVG attributes, trimming whitespace, and running
+   * per-icon logic via `iconCustomizer`.
+   *
+   * @default `{}`
+   */
+  customizations?: IconCustomizations;
+  /**
+   * When enabled, automatically installs missing `@iconify-json/*`
+   * packages on demand during local icon resolution.
+   *
+   * @default `false`
+   */
+  autoInstall?: IconifyLoaderOptions['autoInstall'];
+  /**
+   * Working directory used by the Iconify node loader when resolving
+   * locally installed icon packages.
+   *
+   * @default `undefined`
+   */
+  cwd?: IconifyLoaderOptions['cwd'];
+  /**
+   * 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 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 merged into every generated icon style item.
+   * Useful for adding `display`, `vertical-align`, or other layout properties.
+   *
+   * @default `{}`
+   */
+  extraProperties?: Record<string, string>;
+  /**
+   * 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

@@ -1,18 +1,11 @@
 import process from "node:process";
-import { encodeSvgForCss, loadIcon } from "@iconify/utils";
+import { encodeSvgForCss, loadIcon, quicklyValidateIconSet, searchForIcon, stringToIcon } from "@iconify/utils";
+import { loadNodeIcon } from "@iconify/utils/lib/loader/node-loader";
 import { defineEnginePlugin, log } from "@pikacss/core";
-import { combineLoaders, createCDNFetchLoader, createNodeLoader, parseIconWithLoader } from "@unocss/preset-icons";
 import { $fetch } from "ofetch";
-
 //#region src/index.ts
 /**
 * Environment flags helper function to detect the current runtime environment.
-* This replaces the removed `getEnvFlags` export from `@unocss/preset-icons` v66+.
-*
-* @returns An object containing:
-*  - `isNode`: Whether the code is running in a Node.js environment
-*  - `isVSCode`: Whether the code is running within VS Code (extension host)
-*  - `isESLint`: Whether the code is running within ESLint
 */
 function getEnvFlags() {
 	const isNode = typeof process !== "undefined" && typeof process.versions?.node !== "undefined";
@@ -22,75 +15,183 @@ 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(createIconsLoader);
+	return createIconsPlugin();
+}
+const globalColonRE = /:/g;
+const currentColorRE = /currentColor/;
+function normalizePrefixes(prefix) {
+	const prefixes = [prefix].flat().filter(Boolean);
+	return [...new Set(prefixes)];
+}
+function escapeRegExp(value) {
+	return value.replace(RE_ESCAPE_REGEXP, "\\$&");
+}
+function createShortcutRegExp(prefixes) {
+	return new RegExp(`^(?:${prefixes.map(escapeRegExp).join("|")})([\\w:-]+)(?:\\?(mask|bg|auto))?$`);
+}
+function getPossibleIconNames(iconName) {
+	return [
+		iconName,
+		iconName.replace(RE_CAMEL_CASE_ICON_BOUNDARY, "$1-$2").toLowerCase(),
+		iconName.replace(RE_DIGIT_ICON_BOUNDARY, "$1-$2")
+	];
 }
-function createCDNLoader(cdnBase) {
-	return createCDNFetchLoader($fetch, cdnBase);
+function createAutocomplete(prefixes, autocomplete = []) {
+	const prefixRE = new RegExp(`^(?:${prefixes.map(escapeRegExp).join("|")})`);
+	return [...prefixes, ...prefixes.flatMap((prefix) => autocomplete.map((icon) => `${prefix}${icon.replace(prefixRE, "")}`))];
 }
-async function createIconsLoader(config) {
-	const { cdn } = config;
-	const loaders = [];
-	const { isNode, isVSCode, isESLint } = getEnvFlags();
-	if (isNode && !isVSCode && !isESLint) {
-		const nodeLoader = await createNodeLoader();
-		if (nodeLoader != null) loaders.push(nodeLoader);
+function createAutocompletePatterns(prefixes) {
+	return prefixes.flatMap((prefix) => [
+		`\`${prefix}\${string}:\${string}\``,
+		`\`${prefix}\${string}:\${string}?mask\``,
+		`\`${prefix}\${string}:\${string}?bg\``,
+		`\`${prefix}\${string}:\${string}?auto\``
+	]);
+}
+function resolveCdnCollectionUrl(cdn, collection) {
+	if (cdn.includes("{collection}")) return cdn.replaceAll("{collection}", collection);
+	return `${cdn.replace(RE_TRAILING_SLASH, "")}/${collection}.json`;
+}
+function createLoaderOptions(config, usedProps) {
+	const { scale = 1, collections, autoInstall = false, cwd, unit, extraProperties = {}, customizations = {} } = config;
+	const iconCustomizer = customizations.iconCustomizer;
+	return {
+		addXmlNs: true,
+		scale,
+		customCollections: collections,
+		autoInstall,
+		cwd,
+		usedProps,
+		customizations: {
+			...customizations,
+			additionalProps: {
+				...customizations.additionalProps,
+				...extraProperties
+			},
+			trimCustomSvg: customizations.trimCustomSvg ?? true,
+			async iconCustomizer(collection, icon, props) {
+				await iconCustomizer?.(collection, icon, props);
+				if (!unit) return;
+				if (!props.width) props.width = `${scale}${unit}`;
+				if (!props.height) props.height = `${scale}${unit}`;
+			}
+		}
+	};
+}
+async function loadCollectionFromCdn(cdn, collection, cache) {
+	if (!cache.has(collection)) cache.set(collection, (async () => {
+		try {
+			return quicklyValidateIconSet(await $fetch(resolveCdnCollectionUrl(cdn, collection))) ?? void 0;
+		} catch {
+			return;
+		}
+	})());
+	return cache.get(collection);
+}
+async function resolveIcon(body, config, flags, cdnCollectionCache) {
+	const parsed = stringToIcon(body, true);
+	if (parsed == null || !parsed.prefix) return null;
+	const customProps = {};
+	const customSvg = await loadIcon(parsed.prefix, parsed.name, createLoaderOptions(config, customProps));
+	if (customSvg != null) return {
+		collection: parsed.prefix,
+		name: parsed.name,
+		svg: customSvg,
+		usedProps: customProps,
+		source: "custom"
+	};
+	if (flags.isNode && !flags.isVSCode && !flags.isESLint) {
+		const localProps = {};
+		const localSvg = await loadNodeIcon(parsed.prefix, parsed.name, {
+			...createLoaderOptions(config, localProps),
+			customCollections: void 0
+		});
+		if (localSvg != null) return {
+			collection: parsed.prefix,
+			name: parsed.name,
+			svg: localSvg,
+			usedProps: localProps,
+			source: "local"
+		};
+	}
+	if (config.cdn) {
+		const iconSet = await loadCollectionFromCdn(config.cdn, parsed.prefix, cdnCollectionCache);
+		if (iconSet != null) {
+			const remoteProps = {};
+			const remoteSvg = await searchForIcon(iconSet, parsed.prefix, getPossibleIconNames(parsed.name), createLoaderOptions(config, remoteProps));
+			if (remoteSvg != null) return {
+				collection: parsed.prefix,
+				name: parsed.name,
+				svg: remoteSvg,
+				usedProps: remoteProps,
+				source: "cdn"
+			};
+		}
 	}
-	if (cdn) loaders.push(createCDNLoader(cdn));
-	loaders.push(loadIcon);
-	return combineLoaders(loaders);
+	return {
+		collection: parsed.prefix,
+		name: parsed.name,
+		svg: null,
+		usedProps: {},
+		source: null
+	};
 }
-const globalColonRE = /:/g;
-function createIconsPlugin(lookupIconLoader) {
+function createIconsPlugin() {
 	let engine;
-	let iconsConfig;
+	let iconsConfig = {};
+	const flags = getEnvFlags();
+	const cdnCollectionCache = /* @__PURE__ */ new Map();
 	return defineEnginePlugin({
 		name: "icons",
 		configureRawConfig: async (config) => {
-			iconsConfig = config.icons || {};
+			iconsConfig = config.icons ?? {};
 		},
 		configureEngine: async (_engine) => {
 			engine = _engine;
-			const { scale = 1, mode = "auto", prefix = "i-", iconifyCollectionsNames, collections: customCollections, customizations = {}, autoInstall = false, collectionsNodeResolvePath, unit, extraProperties = {}, processor, autocomplete: _autocomplete } = iconsConfig;
-			const loaderOptions = {
-				addXmlNs: true,
-				scale,
-				customCollections,
-				autoInstall,
-				cwd: collectionsNodeResolvePath,
-				warn: void 0,
-				customizations: {
-					...customizations,
-					additionalProps: { ...extraProperties },
-					trimCustomSvg: true,
-					async iconCustomizer(collection, icon, props) {
-						await customizations.iconCustomizer?.(collection, icon, props);
-						if (unit) {
-							if (!props.width) props.width = `${scale}${unit}`;
-							if (!props.height) props.height = `${scale}${unit}`;
-						}
-					}
-				}
-			};
-			const prefixRE = new RegExp(`^(${[prefix].flat().join("|")})`);
-			const autocompletePrefix = [prefix].flat();
-			const autocomplete = [...autocompletePrefix, ...autocompletePrefix.flatMap((p) => _autocomplete?.map((a) => `${p}${a.replace(prefixRE, "")}`) || [])];
-			let iconLoader;
+			const { mode = "auto", prefix = "i-", processor, autocomplete: _autocomplete } = iconsConfig;
+			const prefixes = normalizePrefixes(prefix);
+			const autocomplete = createAutocomplete(prefixes, _autocomplete);
+			const autocompletePatterns = createAutocompletePatterns(prefixes);
+			engine.appendAutocomplete({ patterns: { shortcuts: autocompletePatterns } });
 			engine.shortcuts.add({
-				shortcut: new RegExp(`^(?:${[prefix].flat().join("|")})([\\w:-]+)(?:\\?(mask|bg|auto))?$`),
+				shortcut: createShortcutRegExp(prefixes),
 				value: async (match) => {
 					let [full, body, _mode = mode] = match;
-					iconLoader = iconLoader || await lookupIconLoader(iconsConfig);
-					const usedProps = {};
-					const parsed = await parseIconWithLoader(body, iconLoader, {
-						...loaderOptions,
-						usedProps
-					}, iconifyCollectionsNames);
-					if (parsed == null) {
+					const resolved = await resolveIcon(body, iconsConfig, flags, cdnCollectionCache);
+					if (resolved == null) {
+						log.warn(`invalid icon name "${full}"`);
+						return {};
+					}
+					if (resolved.svg == null) {
 						log.warn(`failed to load icon "${full}"`);
 						return {};
 					}
-					const url = `url("data:image/svg+xml;utf8,${encodeSvgForCss(parsed.svg)}")`;
+					const url = `url("data:image/svg+xml;utf8,${encodeSvgForCss(resolved.svg)}")`;
 					const varName = `--${engine.config.prefix}svg-icon-${body.replace(globalColonRE, "-")}`;
 					if (engine.variables.store.has(varName) === false) engine.variables.add({ [varName]: {
 						value: url,
@@ -100,7 +201,7 @@ function createIconsPlugin(lookupIconLoader) {
 						},
 						pruneUnused: true
 					} });
-					if (_mode === "auto") _mode = parsed.svg.includes("currentColor") ? "mask" : "bg";
+					if (_mode === "auto") _mode = currentColorRE.test(resolved.svg) ? "mask" : "bg";
 					let styleItem;
 					if (_mode === "mask") styleItem = {
 						"--svg-icon": `var(${varName})`,
@@ -110,17 +211,20 @@ function createIconsPlugin(lookupIconLoader) {
 						"mask-size": "100% 100%",
 						"background-color": "currentColor",
 						"color": "inherit",
-						...usedProps
+						...resolved.usedProps
 					};
 					else styleItem = {
 						"--svg-icon": `var(${varName})`,
 						"background": "var(--svg-icon) no-repeat",
 						"background-size": "100% 100%",
 						"background-color": "transparent",
-						...usedProps
+						...resolved.usedProps
 					};
 					processor?.(styleItem, {
-						...parsed,
+						collection: resolved.collection,
+						name: resolved.name,
+						svg: resolved.svg,
+						source: resolved.source,
 						mode: _mode
 					});
 					return styleItem;
@@ -130,6 +234,5 @@ function createIconsPlugin(lookupIconLoader) {
 		}
 	});
 }
-
 //#endregion
-export { icons };
+export { icons };

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@pikacss/plugin-icons",
   "type": "module",
-  "version": "0.0.46",
+  "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,24 +38,26 @@
   "files": [
     "dist"
   ],
+  "engines": {
+    "node": ">=22"
+  },
   "peerDependencies": {
-    "@pikacss/core": "0.0.46"
+    "@pikacss/core": "0.0.48"
   },
   "dependencies": {
     "@iconify/utils": "^3.1.0",
-    "@unocss/preset-icons": "^66.6.1",
     "ofetch": "^1.5.1"
   },
   "devDependencies": {
-    "@pikacss/core": "0.0.46"
+    "@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"
   }
 }