docs: fix CJS guidance for Node >=20.19 (use require), align Parser signature, and convert remaining Stringify examples to ESM

Author: CharlieHelps

README.md

@@ -33,6 +33,7 @@ Note: This package is ESM‑only. Use `import` in Node.js. In CommonJS on Node.j
 // CommonJS (Node >= 20.19.0)
 const { parse } = require('postcss-values-parser');
 ```
+```
 
 ## Benefits
 

docs/Parser.md

@@ -2,9 +2,9 @@
 
 The parser converts CSS value strings into an Abstract Syntax Tree (AST). It uses [css-tree](https://github.com/csstree/csstree) under the hood, then maps css-tree nodes to this package’s node classes.
 
-## parse(css)
+## parse(css, options?)
 
-Converts a CSS value string into an AST with a `Root` node.
+Converts a CSS value string into an AST with a `Root` node. The optional `options` argument is accepted for forward‑compatibility in v7 but is currently ignored.
 
 ### Parameters
 
@@ -13,6 +13,7 @@ Converts a CSS value string into an AST with a `Root` node.
 Type: `string` (required)
 
 Any valid CSS value string, such as:
+
 - `10px solid red`
 - `calc(100% - 20px)`
 - `rgba(255, 0, 0, 0.5)`
@@ -68,12 +69,14 @@ Unknown or unrecognized node types are parsed as `Word` nodes to ensure the pars
 #### Source mapping
 
 The parser preserves source locations from the original CSS string, including:
+
 - Line and column positions
 - Start and end offsets
 - Original source text
 
 ```js
 import { parse } from 'postcss-values-parser';
+
 const root = parse('calc(100px + 20%)');
 // Each node maintains source position information
 ```
@@ -103,7 +106,7 @@ try {
 Thrown when the parsed AST is invalid or empty:
 
 ```js
-import { parse, AstError } from 'postcss-values-parser';
+import { AstError, parse } from 'postcss-values-parser';
 
 try {
   const root = parse('');
@@ -122,9 +125,9 @@ The parser creates nodes using the NodeOptions interface:
 
 ```typescript
 interface NodeOptions {
-  node?: CssNode;    // Original css-tree node
-  value?: string;    // String value
-  parent?: any;      // Parent node
+  node?: CssNode; // Original css-tree node
+  value?: string; // String value
+  parent?: any; // Parent node
 }
 ```
 
@@ -157,6 +160,7 @@ console.log(calcFunc.nodes.length); // Contains parsed parameters
 ## Browser and Environment Support
 
 The parser works in all environments where css-tree is supported:
+
 - Node.js (all supported versions)
 - Modern browsers (ES2015+)
 - Webpack/Rollup bundled applications
@@ -168,7 +172,7 @@ The parser works in all environments where css-tree is supported:
 
 ```js
 const root = parse('10px solid red');
-console.log(root.nodes.map(n => n.type)); // ['numeric', 'word', 'word']
+console.log(root.nodes.map((n) => n.type)); // ['numeric', 'word', 'word']
 ```
 
 ### Function Parsing
@@ -184,7 +188,7 @@ console.log(func.isColor); // true
 
 ```js
 const root = parse('calc(100% - 20px) url("bg.jpg") center/cover');
-root.walkFuncs(func => {
+root.walkFuncs((func) => {
   console.log(`Function: ${func.name}`);
 });
 ```

docs/README.md

@@ -16,7 +16,21 @@ Please see the [Exports](./Exports.md) documentation for further information.
 
 Parsing is powered by [css-tree](https://github.com/csstree/csstree). Nodes in this package extend PostCSS `Node`/`Container`/`Root` so the API feels familiar, but there is no PostCSS parser involved.
 
-> Note: This package is ESM‑only. Use `import` syntax in Node.js. If you must use CommonJS, load it via dynamic import: `const mod = await import('postcss-values-parser')`.
+> Note: This package is ESM‑only. Prefer `import` in Node.js. For CommonJS on Node >= 20.19.0 you can use:
+>
+> ```js
+> // CommonJS (Node >= 20.19.0)
+> const { parse } = require('postcss-values-parser');
+> ```
+>
+> On older Node versions, use dynamic import instead.
+>
+> ```js
+> // CommonJS (older Node)
+> (async () => {
+>   const { parse } = await import('postcss-values-parser');
+> })();
+> ```
 
 ## Nodes
 

docs/Stringify.md

@@ -82,7 +82,7 @@ The string representation of the node.
 ### Example Usage
 
 ```js
-import { parse, nodeToString } from 'postcss-values-parser';
+import { nodeToString, parse } from 'postcss-values-parser';
 
 const root = parse('10px solid red');
 const numericNode = root.nodes[0];
@@ -103,7 +103,7 @@ interface Stringifier {
 ### Example Custom Stringifier
 
 ```js
-const { parse } = require('postcss-values-parser');
+import { parse } from 'postcss-values-parser';
 
 // Custom stringifier that uppercases all word values
 const upperCaseStringifier = (node, builder) => {
@@ -113,7 +113,7 @@ const upperCaseStringifier = (node, builder) => {
     builder(node.value + node.unit);
   } else if (node.nodes) {
     // Handle container nodes
-    node.nodes.forEach(child => {
+    node.nodes.forEach((child) => {
       upperCaseStringifier(child, builder);
     });
   } else {
@@ -131,7 +131,7 @@ console.log(root.toString(upperCaseStringifier)); // '10pxSOLIDRED'
 All nodes have a `toString()` method that accepts an optional stringifier parameter:
 
 ```js
-const { parse } = require('postcss-values-parser');
+import { parse } from 'postcss-values-parser';
 
 const root = parse('calc(100px + 20%)');
 
@@ -149,7 +149,7 @@ console.log(root.toString(customStringifier));
 The stringify function can preserve original formatting and spacing when nodes maintain source mapping information:
 
 ```js
-const { parse } = require('postcss-values-parser');
+import { parse } from 'postcss-values-parser';
 
 const root = parse('calc( 100px + 20% )'); // Note the extra spaces
 console.log(root.toString()); // Preserves original spacing
@@ -160,7 +160,7 @@ console.log(root.toString()); // Preserves original spacing
 When nodes have source mapping information, the stringify function can utilize this information to maintain accurate positioning:
 
 ```js
-const { parse } = require('postcss-values-parser');
+import { parse } from 'postcss-values-parser';
 
 const root = parse('calc(100px + 20%)');
 // Source mapping information is preserved during stringification
@@ -171,7 +171,7 @@ const root = parse('calc(100px + 20%)');
 The builder function can be used to create complex string manipulations:
 
 ```js
-const { parse, stringify } = require('postcss-values-parser');
+import { parse, stringify } from 'postcss-values-parser';
 
 const root = parse('10px solid red');
 const parts = [];