feat: nest output inside icons layer

Author: vnphanquang

.changeset/famous-trees-carry.md

@@ -0,0 +1,5 @@
+---
+'phosphor-icons-tailwindcss': minor
+---
+
+support adding rules to CSS layer, default to `icons`

README.md

@@ -64,22 +64,26 @@ For all available icon names and weight, visit [phosphoricons.com][phosphor].
 The output CSS look something like this:
 
 ```css
-.ph {
-	--ph-url: none;
-	width: 1em;
-	height: 1em;
-	background-color: currentcolor;
-	color: inherit;
-	mask-image: var(--ph-url);
-	mask-size: 100% 100%;
-	mask-repeat: no-repeat;
+@layer icons.base {
+	.ph {
+		--ph-url: none;
+		width: 1em;
+		height: 1em;
+		background-color: currentcolor;
+		color: inherit;
+		mask-image: var(--ph-url);
+		mask-size: 100% 100%;
+		mask-repeat: no-repeat;
+	}
 }
 
-.ph-\[info\] {
-	url(data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNTYgMjU2IiBmaWxsPSJjdXJyZW50Q29sb3IiPjxwYXRoIGQ9Ik0xMjgsMjRBMTA0LDEwNCwwLDEsMCwyMzIsMTI4LDEwNC4xMSwxMDQuMTEsMCwwLDAsMTI4LDI0Wm0wLDE5MmE4OCw4OCwwLDEsMSw4OC04OEE4OC4xLDg4LjEsMCwwLDEsMTI4LDIxNlptMTYtNDBhOCw4LDAsMCwxLTgsOCwxNiwxNiwwLDAsMS0xNi0xNlYxMjhhOCw4LDAsMCwxLDAtMTYsMTYsMTYsMCwwLDEsMTYsMTZ2NDBBOCw4LDAsMCwxLDE0NCwxNzZaTTExMiw4NGExMiwxMiwwLDEsMSwxMiwxMkExMiwxMiwwLDAsMSwxMTIsODRaIi8+PC9zdmc+);
-}
+@layer icons {
+	.ph-\[info\] {
+		url('data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNTYgMjU2IiBmaWxsPSJjdXJyZW50Q29sb3IiPjxwYXRoIGQ9Ik0xMjgsMjRBMTA0LDEwNCwwLDEsMCwyMzIsMTI4LDEwNC4xMSwxMDQuMTEsMCwwLDAsMTI4LDI0Wm0wLDE5MmE4OCw4OCwwLDEsMSw4OC04OEE4OC4xLDg4LjEsMCwwLDEsMTI4LDIxNlptMTYtNDBhOCw4LDAsMCwxLTgsOCwxNiwxNiwwLDAsMS0xNi0xNlYxMjhhOCw4LDAsMCwxLDAtMTYsMTYsMTYsMCwwLDEsMTYsMTZ2NDBBOCw4LDAsMCwxLDE0NCwxNzZaTTExMiw4NGExMiwxMiwwLDEsMSwxMiwxMkExMiwxMiwwLDAsMSwxMTIsODRaIi8+PC9zdmc+');
+	}
 
-/* ...truncated... */
+	/* ...truncated... */
+}
 ```
 
 ## Configuration
@@ -95,6 +99,7 @@ import phosphorIcons from "phosphor-icons-tailwindcss";
 export default {
 	plugins: [phosphorIcons({
 		prefix: 'ph', // for the icon classes
+		layer: 'icons', // for the CSS layer
 		customProperty: '--ph-url',
 	})],
 };
@@ -106,6 +111,7 @@ Similarly, for Tailwind 4:
 @import 'tailwindcss';
 @plugin 'phosphor-icons-tailwindcss' {
 	prefix: ph;
+	layer: icons;
 	custom-property: --ph-url; /* use the kebab-case alias to avoid auto-format by stylelint / prettier */
 }
 ```
@@ -114,6 +120,36 @@ Similarly, for Tailwind 4:
 
 You may notice this library utilizes Tailwind's support for [arbitrary value](https://tailwindcss.com/docs/adding-custom-styles#using-arbitrary-values), i.e `ph-[info]` instead of `ph-info` to map to the regular info icon. This is to avoid unnecessary parsing during development, especially for [Taliwind language server](https://github.com/tailwindlabs/tailwindcss-intellisense). Arbitrary value syntax allows parsing ad-hoc only the icons actually being used. Otherwise, parsing 9000+ icons may cause slow-down that negatively impacts developer experience.
 
+## CSS layer
+
+By default, the plugin generates CSS in the `icons` [layer](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer). This is to ensure the generated CSS is
+isolated and can be easily overridden by other utility classes, or extended upon. You can change the
+layer by specifying `layer` option in the config object, as discussed in [Configuration](#configuration),
+or passing `null` to skip any layering.
+
+### Tailwind 4
+
+Sorting works differently in Tailwind 4, so the generated CSS is nested inside `@layer utilities`, that is:
+
+```css
+@layer utilities {
+	@layer icons.base {
+		.ph {
+			/* truncated base rule */
+		}
+	}
+	@layer icons {
+		.ph-[info] {
+			/* truncated specifier rule */
+		}
+	}
+}
+```
+
+> [!NOTE]
+> Notice the base rule is inside a sub-layer: this is to ensure specifier classes always have higher
+> specificity, no matter if they are declare before or after the base rule in your CSS source.
+
 ## Usage with Tailwind `@apply` directive
 
 You may utilize `@apply` to extend your use case beyond just for icons. This is helpful if you want

src/plugin.d.ts

@@ -8,6 +8,14 @@ export interface Options {
 	 * ```
 	 */
 	prefix: string;
+	/**
+	 * The layer to output CSS rules into.
+	 * Default to `icons`.
+	 * Set to null skip layering.
+	 *
+	 * Note: The base class will be output to the sub-layer `.base`
+	 */
+	layer: string | null;
 	/*
 	 * CSS custom property for icon URL.
 	 * Default to `--ph-url`

src/plugin.js

@@ -11,26 +11,37 @@ export default createPlugin.withOptions(
 	function (options = {}) {
 		const prefix = options.prefix ?? 'ph';
 		const customProperty = options['custom-property'] ?? options['customProperty'] ?? '--ph-url';
+		let layer = options.layer;
+		if (layer === undefined) layer = 'icons';
 
 		return function (api) {
-			api.addComponents({
-				[`.${prefix}`]: {
-					[customProperty]: 'none',
-					width: '1em',
-					height: '1em',
-					backgroundColor: 'currentcolor',
-					color: 'inherit',
-					maskImage: `var(${customProperty})`,
-					maskSize: '100% 100%',
-					maskRepeat: 'no-repeat',
-
-					'&:is(span,i)': {
-						display: 'inline-block',
-					},
+			const declarations = {
+				[customProperty]: 'none',
+				width: '1em',
+				height: '1em',
+				backgroundColor: 'currentcolor',
+				color: 'inherit',
+				maskImage: `var(${customProperty})`,
+				maskSize: '100% 100%',
+				maskRepeat: 'no-repeat',
+
+				'&:is(span,i)': {
+					display: 'inline-block',
 				},
-			});
+			};
+			if (layer) {
+				api.addUtilities({
+					[`.${prefix}`]: {
+						[`@layer ${layer}.base`]: declarations,
+					},
+				});
+			} else {
+				api.addUtilities({
+					[`.${prefix}`]: declarations,
+				});
+			}
 
-			api.matchComponents({
+			api.matchUtilities({
 				[prefix]: (icon) => {
 					// syntax: <name>[--weight]
 					let [name = '', weight = 'regular'] = icon.split('--');
@@ -52,9 +63,17 @@ export default createPlugin.withOptions(
 						}
 					}
 
-					return {
+					const declarations = {
 						[customProperty]: url,
 					};
+
+					if (layer) {
+						return {
+							[`@layer ${layer}`]: declarations,
+						};
+					}
+
+					return declarations;
 				},
 			});
 		};