phosphor-icons-tailwindcss - npm Package Compare versions

Comparing version 1.0.3 to 1.1.0

package.json

 {
   "name": "phosphor-icons-tailwindcss",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Tailwind plugin for Phoshor icon set in pure CSS",
@@ -5,0 +5,0 @@ "type": "module",

README.md

@@ -45,4 +45,4 @@ <img src="/meta/phosphor-mark-tight-yellow.png" width="128" align="right" />
 
-1. the base `ph` class,
-2. a class with the syntax: `ph-[<name><--weight>]`, corresponding to your desired icon.
+1. the **base** `ph` class,
+2. an **specifier** class with the syntax: `ph-[<name><--weight>]`, corresponding to your desired icon.
 
@@ -68,18 +68,22 @@ > [!NOTE]
 ```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... */
 ```
@@ -100,2 +104,3 @@
 		prefix: 'ph', // for the icon classes
+		layer: 'icons', // for the CSS layer
 		customProperty: '--ph-url',
@@ -112,2 +117,3 @@ })],
 	prefix: ph;
+	layer: icons;
 	custom-property: --ph-url; /* use the kebab-case alias to avoid auto-format by stylelint / prettier */
@@ -121,2 +127,56 @@ }
 
+## 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
+to reuse the icon source in other CSS.
+
+In the following example, `@apply [ph-bell]` makes `--ph-url` available for use:
+
+```css
+/* notification.css */
+.notification {
+	&::before {
+		@apply [ph-bell];
+
+		mask-image: var(--ph-url);
+		mask-size: 100% 100%;
+		mask-repeat: no-repeat;
+		background-color: currentcolor;
+	}
+}
+```
+
+> [!NOTE]
+> Note that you should only apply a specifier class, **NOT** the base class.
+
 ## Acknowledgements
@@ -123,0 +183,0 @@

src/plugin.d.ts

@@ -11,2 +11,10 @@ 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;
 	/*
@@ -13,0 +21,0 @@ * CSS custom property for icon URL.

src/plugin.js

@@ -14,22 +14,33 @@ import { readFileSync, existsSync } from 'fs';
 		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',
+			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',
+				'&: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) => {
@@ -56,5 +67,13 @@ // syntax: <name>[--weight]
 
-					return {
+					const declarations = {
 						[customProperty]: url,
 					};
+
+					if (layer) {
+						return {
+							[`@layer ${layer}`]: declarations,
+						};
+					}
+
+					return declarations;
 				},
@@ -61,0 +80,0 @@ });

No alert changes

Improved metrics

Total package byte prevSize

11299

23.85%

Lines of code

103

32.05%

Number of lines in readme file

191

45.8%

No dependency changes