feat: add parseValue to api

Alias the postcss-value-parser package under the api as parseValue for transforming values

Author: skovy

README.md

@@ -109,6 +109,7 @@ The second argument passed to the `transform` function.
 It's an object with helpers provided by `css-codemod` to perform transformations.
 
 - `parse`: parse a raw CSS string into an AST. This returns the root node of the underlying abstract syntax tree. Transformations can be made by making direct mutations to the underlying node. This is performed with [PostCSS](https://postcss.org/) so the returned node is a PostCSS [Root](https://postcss.org/api/#root) node. Refer to the [PostCSS API documentation](https://postcss.org/api/) for documentation on nodes and various helpers.
+- `parseValue`: parse a CSS string [declaration value](https://postcss.org/api/#declaration-value) into a "mini" AST. This returns a result with all the nodes representing the string value. This is an alias for the [`postcss-value-parser`](https://github.com/TrySound/postcss-value-parser) package. PostCSS itself doesn't parse values and working with complex string values can be challenging. Converting these string values into nodes when necessary can be useful. There are additional parsers for things like selectors, dimensions, media queries, etc. provided in the [PostCSS documentation for plugins](https://github.com/postcss/postcss/blob/main/docs/writing-a-plugin.md#step-3-find-nodes).
 
 ### `parser`
 

package.json

@@ -71,6 +71,7 @@
     "esbuild": "^0.14.14",
     "fs-extra": "^10.0.0",
     "glob": "^7.2.0",
-    "postcss": "^8.4.5"
+    "postcss": "^8.4.5",
+    "postcss-value-parser": "^4.2.0"
   }
 }

recipes/rename-css-property/input/a.css

@@ -0,0 +1,9 @@
+.a {
+  --old-color: #fafafa;
+  --other-color: magenta;
+
+  color: var(--old-color);
+  background: orange;
+  box-shadow: 0 0 0 2px var(--other-color);
+  border: 2px solid var(--old-color);
+}

recipes/rename-css-property/output/a.css

@@ -0,0 +1,9 @@
+.a {
+  --new-color: #fafafa;
+  --other-color: magenta;
+
+  color: var(--new-color);
+  background: orange;
+  box-shadow: 0 0 0 2px var(--other-color);
+  border: 2px solid var(--new-color);
+}

recipes/rename-css-property/transform.ts

@@ -0,0 +1,30 @@
+import { Transform } from '../../src';
+
+const OLD_VAR = '--old-color';
+const NEW_VAR = '--new-color';
+
+export const transform: Transform = (fileInfo, api) => {
+  const root = api.parse(fileInfo.source);
+
+  root.walkDecls(decl => {
+    if (decl.prop === OLD_VAR) {
+      // Replace any custom property declarations.
+      //   eg: `--custom-prop: #fff`
+      decl.prop = NEW_VAR;
+    } else {
+      // Replace any uses of the custom property in values.
+      //  eg: `border: 2px solid var(--custom-prop);`
+      const result = api.parseValue(decl.value);
+
+      result.walk(value => {
+        if (value.type === 'word' && value.value === OLD_VAR) {
+          value.value = NEW_VAR;
+        }
+      });
+
+      decl.value = result.toString();
+    }
+  });
+
+  return root.toString();
+};

src/api.ts

@@ -1,10 +1,16 @@
 import postcss, { Root, Parser, AcceptedPlugin } from 'postcss';
+import parseValue from 'postcss-value-parser';
 
 export interface TransformAPI {
   /**
    * Parse a raw CSS string into an abstract syntax tree and return a PostCSS `Root` node.
    */
   parse(source: string): Root;
+
+  /**
+   * Parse a CSS value string into a series of nodes to operate on.
+   */
+  parseValue(value: string): parseValue.ParsedValue;
 }
 
 const createAPIParse = ({
@@ -47,6 +53,7 @@ export const createAPI = ({
 }: { parser?: Parser; plugins?: AcceptedPlugin[] } = {}): TransformAPI => {
   const api: TransformAPI = {
     parse: createAPIParse({ parser, plugins }),
+    parseValue,
   };
 
   return api;

test/api.test.ts

@@ -1,4 +1,5 @@
 import { Declaration, Rule } from 'postcss';
+import { FunctionNode } from 'postcss-value-parser';
 import { createAPI } from '../src/api';
 
 describe('api', () => {
@@ -9,16 +10,45 @@ describe('api', () => {
       const root = api.parse(`.class { color: orange; }`);
 
       expect(root.type).toEqual('root');
-      expect(root.nodes.length).toEqual(1);
+      expect(root.nodes).toHaveLength(1);
 
       const rule = root.nodes[0] as Rule;
       expect(rule.type).toEqual('rule');
-      expect(rule.nodes.length).toEqual(1);
+      expect(rule.nodes).toHaveLength(1);
 
       const declaration = rule.nodes[0] as Declaration;
       expect(declaration.type).toEqual('decl');
       expect(declaration.prop).toEqual('color');
       expect(declaration.value).toEqual('orange');
     });
   });
+
+  describe('#parseValue', () => {
+    it('should return the value nodes', () => {
+      const { nodes } = api.parseValue(`1px solid var(--custom-prop)`);
+      expect(nodes).toHaveLength(5);
+
+      let [word1, space1, word2, space2, func1] = nodes;
+
+      expect(word1.type).toBe('word');
+      expect(word1.value).toBe('1px');
+
+      expect(space1.type).toBe('space');
+      expect(space1.value).toBe(' ');
+
+      expect(word2.type).toBe('word');
+      expect(word2.value).toBe('solid');
+
+      expect(space2.type).toBe('space');
+      expect(space2.value).toBe(' ');
+
+      func1 = func1 as FunctionNode;
+      expect(func1.type).toBe('function');
+      expect(func1.value).toBe('var');
+      expect(func1.nodes).toHaveLength(1);
+      const [word3] = func1.nodes;
+      expect(word3.type).toBe('word');
+      expect(word3.value).toBe('--custom-prop');
+    });
+  });
 });

test/cli.test.ts

@@ -32,7 +32,8 @@ const run = (recipe: string, { ext = 'css' }: RunOptions = {}) => {
     'transform.ts'
   );
   const inputGlob = path.join(inputDest, '**', fileGlob);
-  const { stderr } = execa.sync(bin, ['-t', transform, inputGlob]);
+  const { stdout, stderr } = execa.sync(bin, ['-t', transform, inputGlob]);
+  expect(stdout).toEqual('');
   expect(stderr).toEqual('');
 
   // Compare results

yarn.lock

@@ -5150,7 +5150,7 @@ postcss-selector-parser@^6.0.2:
     cssesc "^3.0.0"
     util-deprecate "^1.0.2"
 
-postcss-value-parser@^4.0.2:
+postcss-value-parser@^4.0.2, postcss-value-parser@^4.2.0:
   version "4.2.0"
   resolved "https://registry.yarnpkg.com/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz#723c09920836ba6d3e5af019f92bc0971c02e514"
   integrity sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==