Merge remote-tracking branch 'origin/main' into postcss-bundler--sinc…

…ere-bolognese-dog-7bd235cc5f

plugins/postcss-rebase-url/README.md

@@ -4,12 +4,16 @@
 
 [PostCSS Rebase URL] rebases `url()` functions when transforming CSS.
 
-This plugin is only intended to help with bundling CSS and only in a way that you author CSS as if there was no bundling or url rebasing.
+When bundling CSS, the location of the final stylesheet file will be different than the individual source files.  
+[PostCSS Rebase URL] rewrites the contents of `url()` functions so that relative paths continue to work.
 
-If you need something with more knobs and dials, please checkout [`postcss-url`](https://www.npmjs.com/package/postcss-url)
+Instead of manually mapping where the files will be in the final output you can use this plugin  
+and simply use the relative paths to each source file.
+
+_If you need something with more knobs and dials, please checkout [`postcss-url`](https://www.npmjs.com/package/postcss-url)_
 
 ```pcss
-/* when used with a bundler like `postcs-import` */
+/* when used with a bundler like `postcss-import` */
 
 /* test/examples/example.css */
 @import url("imports/basic.css");

plugins/postcss-rebase-url/dist/normalized-dir.d.ts

@@ -1 +1,7 @@
+/**
+ * Returns a posix path for the directory of the given file path.
+ *
+ * @param {string} x The file path to normalize.
+ * @returns {string} The normalized directory path.
+ */
 export declare function normalizedDir(x: string): string;

plugins/postcss-rebase-url/dist/serialize-string.d.ts

@@ -1 +1,9 @@
+/**
+ * Serialize a string as a quoted CSS string.
+ *
+ * @param {string} str The contents for the string value.
+ * @returns {string} The quoted CSS string.
+ *
+ * @see https://www.w3.org/TR/cssom-1/#common-serializing-idioms
+ */
 export declare function serializeString(str: string): string;

plugins/postcss-rebase-url/docs/README.md

@@ -18,12 +18,16 @@
 
 [<humanReadableName>] rebases `url()` functions when transforming CSS.
 
-This plugin is only intended to help with bundling CSS and only in a way that you author CSS as if there was no bundling or url rebasing.
+When bundling CSS, the location of the final stylesheet file will be different than the individual source files.  
+[<humanReadableName>] rewrites the contents of `url()` functions so that relative paths continue to work.
 
-If you need something with more knobs and dials, please checkout [`postcss-url`](https://www.npmjs.com/package/postcss-url)
+Instead of manually mapping where the files will be in the final output you can use this plugin  
+and simply use the relative paths to each source file.
+
+_If you need something with more knobs and dials, please checkout [`postcss-url`](https://www.npmjs.com/package/postcss-url)_
 
 ```pcss
-/* when used with a bundler like `postcs-import` */
+/* when used with a bundler like `postcss-import` */
 
 /* test/examples/example.css */
 <example.css>

plugins/postcss-rebase-url/src/normalized-dir.ts

@@ -1,5 +1,18 @@
 import path from 'path';
 
+/**
+ * Returns a posix path for the directory of the given file path.
+ *
+ * @param {string} x The file path to normalize.
+ * @returns {string} The normalized directory path.
+ */
 export function normalizedDir(x: string): string {
-	return path.parse(path.resolve(x.trim())).dir.split(path.sep).join(path.posix.sep);
+	// Resolve the path to eliminate any relative path components.
+	const dir = path.parse(path.resolve(x.trim())).dir;
+	// Split the path by the native path separator
+	const dirPathComponents = dir.split(path.sep);
+	// Join the path components with the posix path separator
+	const posixDir = dirPathComponents.join(path.posix.sep);
+
+	return posixDir;
 }

plugins/postcss-rebase-url/src/serialize-string.ts

@@ -1,4 +1,11 @@
-// https://www.w3.org/TR/cssom-1/#common-serializing-idioms
+/**
+ * Serialize a string as a quoted CSS string.
+ *
+ * @param {string} str The contents for the string value.
+ * @returns {string} The quoted CSS string.
+ *
+ * @see https://www.w3.org/TR/cssom-1/#common-serializing-idioms
+ */
 export function serializeString(str: string): string {
 	let out = '';