feat: Create utils package to share logic across runtime and bundler (#345)

Co-authored-by: Brijesh Bittu <[email protected]>

Author: brijeshb42

.codesandbox/ci.json

@@ -3,9 +3,11 @@
   "installCommand": "install:codesandbox",
   "node": "18",
   "packages": [
+    "packages/pigment-css-nextjs-plugin",
     "packages/pigment-css-react",
+    "packages/pigment-css-theme",
     "packages/pigment-css-unplugin",
-    "packages/pigment-css-nextjs-plugin",
+    "packages/pigment-css-utils",
     "packages/pigment-css-vite-plugin"
   ],
   "sandboxes": [

.gitignore

@@ -30,3 +30,4 @@ docs/public/static/blog/feed/*
 # vale downloaded config
 .github/styles/
 .nx/cache
+packages/**/LICENSE

packages/eslint-plugin-material-ui/package.json

@@ -9,8 +9,5 @@
     "@typescript-eslint/experimental-utils": "^5.62.0",
     "@typescript-eslint/parser": "^7.5.0"
   },
-  "scripts": {
-    "test": "cd ../../ && cross-env NODE_ENV=test mocha 'packages/eslint-plugin-material-ui/**/*.test.js' --timeout 3000"
-  },
   "license": "MIT"
 }

packages/pigment-css-nextjs-plugin/package.json

@@ -25,7 +25,7 @@
     "watch": "tsup --watch --tsconfig tsconfig.build.json",
     "copy-license": "node ../../scripts/pigment-license.mjs",
     "build": "tsup --tsconfig tsconfig.build.json",
-    "typecheck": "tsc --noEmit -p ."
+    "typescript": "tsc --noEmit -p ."
   },
   "dependencies": {
     "@pigment-css/unplugin": "workspace:^"

packages/pigment-css-nextjs-plugin/tsconfig.json

@@ -1,8 +1,7 @@
 {
   "extends": "../../tsconfig.json",
   "compilerOptions": {
-    "resolveJsonModule": true,
-    "target": "ES2015"
+    "skipLibCheck": true
   },
   "include": ["src/**/*.ts"],
   "exclude": ["./tsup.config.ts"]

packages/pigment-css-react/package.json

@@ -35,7 +35,7 @@
     "@babel/helper-module-imports": "^7.25.9",
     "@babel/helper-plugin-utils": "^7.25.9",
     "@babel/parser": "^7.26.2",
-    "@babel/types": "^7.26.0",
+    "@babel/types": "^7.26.5",
     "@emotion/css": "^11.13.4",
     "@emotion/is-prop-valid": "^1.3.1",
     "@emotion/react": "^11.13.3",

packages/pigment-css-theme/LICENSE

@@ -1,21 +1,5 @@
 {
   "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "target": "ES2015",
-    "allowJs": true,
-    "lib": ["ES2017", "ES2021.String", "DOM"],
-    "composite": true,
-    "noEmit": false,
-    "resolveJsonModule": true,
-    "types": ["node", "mocha"],
-    "jsx": "react-jsx"
-  },
-  "include": [
-    "src/**/*.tsx",
-    "src/**/*.js",
-    "src/**/*.ts",
-    "tests/**/*.spec.ts",
-    "tests/**/*.spec.tsx"
-  ],
+  "include": ["src/**/*.js", "src/**/*.ts", "tests/**/*.spec.ts"],
   "exclude": ["./tsup.config.ts"]
 }

packages/pigment-css-theme/tsconfig.json

@@ -25,7 +25,7 @@
     "watch": "tsup --watch --tsconfig tsconfig.build.json",
     "copy-license": "node ../../scripts/pigment-license.mjs",
     "build": "tsup --tsconfig tsconfig.build.json",
-    "typecheck": "tsc --noEmit -p .",
+    "typescript": "tsc --noEmit -p .",
     "test": "cd ../../ && cross-env NODE_ENV=test mocha 'packages/pigment-css-unplugin/**/*.test.{js,ts,tsx}'",
     "test:ci": "cd ../../ && cross-env NODE_ENV=test BABEL_ENV=coverage nyc --reporter=lcov --report-dir=./coverage/pigment-css-unplugin mocha 'packages/pigment-css-unplugin/**/*.test.{js,ts,tsx}'"
   },

packages/pigment-css-unplugin/package.json

@@ -1,9 +1,6 @@
 {
   "extends": "./tsconfig.json",
   "compilerOptions": {
-    "composite": false,
-    "paths": {
-      "@babel/core": ["./node_modules/@babel/core"]
-    }
+    "composite": false
   }
 }

packages/pigment-css-unplugin/tsconfig.build.json

@@ -1,15 +1,7 @@
 {
   "extends": "../../tsconfig.json",
   "compilerOptions": {
-    "resolveJsonModule": true,
-    "target": "ES2022",
-    "lib": ["ES2021", "DOM"],
-    "paths": {
-      "@babel/core": ["./node_modules/@babel/core"],
-      "@pigment-css/react": ["./packages/pigment-css-react/src"],
-      "@pigment-css/react/*": ["./packages/pigment-css-react/src/*"]
-    },
-    "types": ["node", "mocha", "chai"]
+    "skipLibCheck": true
   },
   "include": ["src/**/*.ts"],
   "exclude": ["./tsup.config.ts"]

packages/pigment-css-unplugin/tsconfig.json

@@ -0,0 +1,101 @@
+{
+  "name": "@pigment-css/utils",
+  "version": "0.0.28",
+  "main": "build/index.js",
+  "module": "build/index.mjs",
+  "types": "build/index.d.ts",
+  "author": "MUI Team",
+  "description": "Utilities to be used internally across different Pigment CSS packages.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mui/pigment-css.git",
+    "directory": "packages/pigment-css-utils"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/mui/pigment-css/issues"
+  },
+  "homepage": "https://github.com/mui/pigment-css/tree/master/README.md",
+  "funding": {
+    "type": "opencollective",
+    "url": "https://opencollective.com/mui-org"
+  },
+  "scripts": {
+    "clean": "rimraf build types processors utils",
+    "watch": "tsup --watch --clean false",
+    "copy-license": "node ../../scripts/pigment-license.mjs",
+    "build": "tsup",
+    "test": "cd ../../ && cross-env NODE_ENV=test BABEL_ENV=coverage nyc --reporter=text mocha 'packages/pigment-css-utils/**/*.test.{js,ts,tsx}'",
+    "test:update": "cd ../../ && cross-env NODE_ENV=test UPDATE_FIXTURES=true mocha 'packages/pigment-css-utils/**/*.test.{js,ts,tsx}'",
+    "test:ci": "cd ../../ && cross-env NODE_ENV=test BABEL_ENV=coverage nyc --reporter=lcov --report-dir=./coverage/pigment-css-utils mocha 'packages/pigment-css-utils/**/*.test.{js,ts,tsx}'",
+    "typescript": "tsc --noEmit -p ."
+  },
+  "dependencies": {
+    "@babel/types": "^7.26.5",
+    "@babel/parser": "^7.26.5",
+    "@emotion/unitless": "0.10.0",
+    "@emotion/serialize": "^1.3.3",
+    "@pigment-css/theme": "workspace:*",
+    "@wyw-in-js/processor-utils": "^0.5.5",
+    "@wyw-in-js/shared": "^0.5.5",
+    "@wyw-in-js/transform": "^0.5.5",
+    "cssesc": "^3.0.0",
+    "lodash": "4.17.21"
+  },
+  "devDependencies": {
+    "@types/cssesc": "3.0.2",
+    "chai": "^4.4.1"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "build",
+    "package.json",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "import": {
+        "types": "./build/index.d.mts",
+        "default": "./build/index.mjs"
+      },
+      "require": "./build/index.js",
+      "default": "./build/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "nx": {
+    "targets": {
+      "test": {
+        "cache": false,
+        "dependsOn": [
+          "build"
+        ]
+      },
+      "test:update": {
+        "cache": false,
+        "dependsOn": [
+          "build"
+        ]
+      },
+      "test:ci": {
+        "cache": false,
+        "dependsOn": [
+          "build"
+        ]
+      },
+      "build": {
+        "outputs": [
+          "{projectRoot}/build"
+        ],
+        "dependsOn": [
+          "^build"
+        ]
+      }
+    }
+  }
+}

packages/pigment-css-utils/package.json

@@ -0,0 +1,7 @@
+import { BaseProcessor as WywBaseProcessor } from '@wyw-in-js/processor-utils';
+
+/**
+ * This is going to be expanded when the react package comes into picture.
+ * Right now, it only has the bare mimimum.
+ */
+export default abstract class BaseProcessor extends WywBaseProcessor {}

packages/pigment-css-utils/src/base-processor.ts

@@ -0,0 +1,102 @@
+import { Theme } from '@pigment-css/theme';
+import { PluginOptions } from '@wyw-in-js/transform';
+
+export type GenerateClassData<M, E> = {
+  /**
+   * Original classname that would be used if not customized.
+   */
+  slug: string;
+  /**
+   * The metadata argument that you passed to the function call, usually as the 2nd argument.
+   *
+   * ```js
+   * const className = css(cssObject, metadata);
+   */
+  metadata: M;
+  /**
+   * The variable name that the function call's return value is assigned to.
+   */
+  displayName: string;
+  /**
+   * The name of the function that is being called, ie, `css`, `styled`, etc
+   */
+  functionName: string;
+  /**
+   * All the extra data specific to the above `functionName` call.
+   */
+  extraData: E;
+};
+
+/**
+ * Feature flags that user can choose to enable/disable to control the output
+ */
+type PigmentFeatures = {
+  useLayer?: boolean;
+};
+
+/**
+ * This is the base Pigment Config that'll be used by bundler package with some extra bundler specific options.
+ */
+export type PigmentConfig = Omit<Partial<PluginOptions>, 'features'> & {
+  wywFeatures?: PluginOptions['features'];
+  features?: PigmentFeatures;
+  themeArgs?: {
+    theme: Theme;
+  };
+  /**
+   *
+   * @param {string} tag The function that was imported
+   * @param {string} source The path that the function was imported from
+   *
+   * If returning a string, this will be used as the import path in the final transform.
+   *
+   * @example
+   *
+   * __Input Code__
+   *
+   * ```js
+   * import { css } from '@pigment-css/core';
+   *
+   * const cls1 = css({});
+   * ```
+   * __config__
+   * ```js
+   * {
+   *   runtimeReplacementPath(tag, source) {
+   *     if (tag === 'css') {
+   *       return `@my-lib/runtime/css`;
+   *     }
+   *     return null;
+   *   }
+   * }
+   *```
+   * __Output__
+   *
+   * ```js
+   * import { css } from '@my-lib/runtime/css';
+   *
+   * const cls1 = css({});
+   * ```
+   */
+  runtimeReplacementPath?: (tag: string, source: string) => string | null;
+};
+
+/**
+ * @internal
+ */
+export type TransformedInternalConfig = Omit<PigmentConfig, 'wywFeatures' | 'features'> & {
+  feautres?: PluginOptions['features'];
+  pigmentFeatures?: PigmentFeatures;
+};
+
+/**
+ * Internal utility to convert Pigment CSS configuration object to be usable by WyW
+ */
+export function transformPigmentConfig(config?: PigmentConfig): TransformedInternalConfig {
+  const { features, wywFeatures, ...rest } = config ?? {};
+  return {
+    ...rest,
+    pigmentFeatures: features,
+    feautres: wywFeatures,
+  };
+}

packages/pigment-css-utils/src/config.ts

@@ -0,0 +1,3 @@
+export { default as BaseProcessor } from './base-processor';
+export * from './config';
+export * from './utils';

packages/pigment-css-utils/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Slightly unsafe but way faster way to evaluate JS code than using babel transforms.
+ *
+ * @param expressionString The JS code expression to evaluate
+ */
+export function evaluateClassNameArg<T>(expressionString: string): T {
+  // Create sandbox context
+  const context = Object.create(null);
+  const safeEval = new Function('context', `with(context) { return ${expressionString}; }`);
+  return safeEval(context);
+}

packages/pigment-css-utils/src/utils/evaluateExpresions.ts

@@ -0,0 +1,4 @@
+export * from './processStyle';
+export * from './valueToLiteral';
+export * from './parseExpressions';
+export * from './evaluateExpresions';

packages/pigment-css-utils/src/utils/index.ts

@@ -0,0 +1,16 @@
+import { parseExpression, ParserOptions } from '@babel/parser';
+import { ArrayExpression } from '@babel/types';
+
+/**
+ * Parses array expression string to AST for locating sourcemap points.
+ */
+export function parseArray(
+  expressionStr: string,
+  opts: Pick<ParserOptions, 'startColumn' | 'startIndex' | 'startLine'>,
+): ArrayExpression | null {
+  const expr = parseExpression(expressionStr, opts);
+  if (expr.type === 'ArrayExpression') {
+    return expr;
+  }
+  return null;
+}