[feat] Add defineMarker() API for custom markers for combinator selectors

nmn · nmn · commit 7ddc5b79a484 · 2025-10-12T22:05:35.000-07:00
diff --git a/packages/@stylexjs/babel-plugin/__tests__/transform-stylex-defineMarker-test.js b/packages/@stylexjs/babel-plugin/__tests__/transform-stylex-defineMarker-test.js
@@ -0,0 +1,75 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+jest.autoMockOff();
+
+import { transformSync } from '@babel/core';
+import stylexPlugin from '../src/index';
+
+function transform(source, opts = {}) {
+  const { code, metadata } = transformSync(source, {
+    filename: opts.filename || '/stylex/packages/vars.stylex.js',
+    parserOpts: {
+      flow: 'all',
+    },
+    babelrc: false,
+    plugins: [
+      [
+        stylexPlugin,
+        {
+          unstable_moduleResolution: {
+            rootDir: '/stylex/packages/',
+            type: 'commonJS',
+          },
+          ...opts,
+        },
+      ],
+    ],
+  });
+  return { code, metadata };
+}
+
+describe('@stylexjs/babel-plugin', () => {
+  describe('[transform] stylex.defineMarker()', () => {
+    test('member call', () => {
+      const { code, metadata } = transform(`
+        import * as stylex from '@stylexjs/stylex';
+        export const fooBar = stylex.defineMarker();
+      `);
+
+      expect(code).toMatchInlineSnapshot(`
+        "import * as stylex from '@stylexjs/stylex';
+        export const fooBar = {
+          x1jdyizh: "x1jdyizh",
+          $$css: true
+        };"
+      `);
+      expect(metadata).toMatchInlineSnapshot(`
+        {
+          "stylex": [],
+        }
+      `);
+    });
+
+    test('named import call', () => {
+      const { code } = transform(`
+        import { defineMarker } from '@stylexjs/stylex';
+        export const baz = defineMarker();
+      `);
+
+      expect(code).toMatchInlineSnapshot(`
+        "import { defineMarker } from '@stylexjs/stylex';
+        export const baz = {
+          x1i61hkd: "x1i61hkd",
+          $$css: true
+        };"
+      `);
+    });
+  });
+});
diff --git a/packages/@stylexjs/babel-plugin/__tests__/transform-stylex-when-test.js b/packages/@stylexjs/babel-plugin/__tests__/transform-stylex-when-test.js
@@ -19,7 +19,16 @@ function transform(source, opts = {}) {
       flow: 'all',
     },
     babelrc: false,
-    plugins: [[stylexPlugin, { ...opts }]],
+    plugins: [
+      [
+        stylexPlugin,
+        {
+          treeshakeCompensation: true,
+          unstable_moduleResolution: { type: 'haste' },
+          ...opts,
+        },
+      ],
+    ],
   });
 
   return result;
@@ -336,4 +345,42 @@ describe('@stylexjs/babel-plugin', () => {
       `);
     });
   });
+
+  describe.only('[transform] using custom markers', () => {
+    test.only('named import', () => {
+      const { code } = transform(
+        `
+        import * as stylex from '@stylexjs/stylex';
+        import {customMarker} from 'custom-marker.stylex';
+
+        const styles = stylex.create({
+          foo: {
+            backgroundColor: {
+              default: 'blue',
+              [stylex.when.ancestor(':hover', customMarker)]: 'red',
+            },
+          },
+        });
+        
+        const container = stylex.props(customMarker);
+        const classNames = stylex.props(styles.foo);
+      `,
+        { runtimeInjection: true },
+      );
+
+      expect(code).toMatchInlineSnapshot(`
+        "import _inject from "@stylexjs/stylex/lib/stylex-inject";
+        var _inject2 = _inject;
+        import * as stylex from '@stylexjs/stylex';
+        import 'custom-marker.stylex';
+        import { customMarker } from 'custom-marker.stylex';
+        _inject2(".x1t391ir{background-color:blue}", 3000);
+        _inject2(".x7rpj1w:where(.x1lc2aw:hover *){background-color:red}", 3011.3);
+        const container = stylex.props(customMarker);
+        const classNames = {
+          className: "x1t391ir x7rpj1w"
+        };"
+      `);
+    });
+  });
 });
diff --git a/packages/@stylexjs/babel-plugin/__tests__/validation-stylex-defineMarker-test.js b/packages/@stylexjs/babel-plugin/__tests__/validation-stylex-defineMarker-test.js
@@ -0,0 +1,59 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+jest.autoMockOff();
+
+import { transformSync } from '@babel/core';
+import stylexPlugin from '../src/index';
+import * as messages from '../src/shared/messages';
+
+function transform(source, opts = {}) {
+  const { code, metadata } = transformSync(source, {
+    filename: opts.filename || '/stylex/packages/vars.stylex.js',
+    parserOpts: {
+      flow: 'all',
+    },
+    babelrc: false,
+    plugins: [
+      [
+        stylexPlugin,
+        {
+          unstable_moduleResolution: {
+            rootDir: '/stylex/packages/',
+            type: 'commonJS',
+          },
+          ...opts,
+        },
+      ],
+    ],
+  });
+  return { code, metadata };
+}
+
+describe('@stylexjs/babel-plugin', () => {
+  describe('[validation] stylex.defineMarker()', () => {
+    test('must be bound to a named export', () => {
+      expect(() => {
+        transform(`
+          import * as stylex from '@stylexjs/stylex';
+          const marker = stylex.defineMarker();
+        `);
+      }).toThrow(messages.nonExportNamedDeclaration('defineMarker'));
+    });
+
+    test('no arguments allowed', () => {
+      expect(() => {
+        transform(`
+          import * as stylex from '@stylexjs/stylex';
+          export const marker = stylex.defineMarker(1);
+        `);
+      }).toThrow(messages.illegalArgumentLength('defineMarker', 0));
+    });
+  });
+});
diff --git a/packages/@stylexjs/babel-plugin/src/index.js b/packages/@stylexjs/babel-plugin/src/index.js
@@ -33,6 +33,7 @@ import transformStylexProps from './visitors/stylex-props';
 import { skipStylexPropsChildren } from './visitors/stylex-props';
 import transformStyleXViewTransitionClass from './visitors/stylex-view-transition-class';
 import transformStyleXDefaultMarker from './visitors/stylex-default-marker';
+import transformStyleXDefineMarker from './visitors/stylex-define-marker';
 
 const NAME = 'stylex';
 
@@ -306,6 +307,7 @@ function styleXTransform(): PluginObj<> {
         }
 
         transformStyleXDefaultMarker(path, state);
+        transformStyleXDefineMarker(path, state);
         transformStyleXDefineVars(path, state);
         transformStyleXDefineConsts(path, state);
         transformStyleXCreateTheme(path, state);
diff --git a/packages/@stylexjs/babel-plugin/src/shared/when/when.js b/packages/@stylexjs/babel-plugin/src/shared/when/when.js
@@ -11,9 +11,24 @@ import type { StyleXOptions } from '../common-types';
 
 import { defaultOptions } from '../utils/default-options';
 
+function isProxy(value: mixed): boolean {
+  if (
+    typeof value === 'object' &&
+    value != null &&
+    value.__IS_PROXY === true &&
+    typeof value.toString === 'function'
+  ) {
+    return true;
+  }
+  return false;
+}
+
 function getDefaultMarkerClassName(
   options: StyleXOptions = defaultOptions,
 ): string {
+  if (isProxy(options)) {
+    return options.toString();
+  }
   const prefix =
     options.classNamePrefix != null ? `${options.classNamePrefix}-` : '';
   return `${prefix}default-marker`;
diff --git a/packages/@stylexjs/babel-plugin/src/utils/evaluate-path.js b/packages/@stylexjs/babel-plugin/src/utils/evaluate-path.js
@@ -204,6 +204,11 @@ function evaluateThemeRef(
         if (key === '__IS_PROXY') {
           return true;
         }
+        if (key === 'toString') {
+          return () =>
+            state.traversalState.options.classNamePrefix +
+            utils.hash(utils.genFileBasedIdentifier({ fileName, exportName }));
+        }
         return resolveKey(key);
       },
       set(_, key: string, value: string) {
diff --git a/packages/@stylexjs/babel-plugin/src/utils/state-manager.js b/packages/@stylexjs/babel-plugin/src/utils/state-manager.js
@@ -132,6 +132,7 @@ export default class StateManager {
   +stylexKeyframesImport: Set<string> = new Set();
   +stylexPositionTryImport: Set<string> = new Set();
   +stylexDefineVarsImport: Set<string> = new Set();
+  +stylexDefineMarkerImport: Set<string> = new Set();
   +stylexDefineConstsImport: Set<string> = new Set();
   +stylexCreateThemeImport: Set<string> = new Set();
   +stylexTypesImport: Set<string> = new Set();
diff --git a/packages/@stylexjs/babel-plugin/src/visitors/imports.js b/packages/@stylexjs/babel-plugin/src/visitors/imports.js
@@ -79,6 +79,9 @@ export function readImportDeclarations(
             if (importedName === 'defineVars') {
               state.stylexDefineVarsImport.add(localName);
             }
+            if (importedName === 'defineMarker') {
+              state.stylexDefineMarkerImport.add(localName);
+            }
             if (importedName === 'defineConsts') {
               state.stylexDefineConstsImport.add(localName);
             }
@@ -158,6 +161,9 @@ export function readRequires(
           if (prop.key.name === 'defineVars') {
             state.stylexDefineVarsImport.add(value.name);
           }
+          if (prop.key.name === 'defineMarker') {
+            state.stylexDefineMarkerImport.add(value.name);
+          }
           if (prop.key.name === 'defineConsts') {
             state.stylexDefineConstsImport.add(value.name);
           }
diff --git a/packages/@stylexjs/babel-plugin/src/visitors/stylex-define-marker.js b/packages/@stylexjs/babel-plugin/src/visitors/stylex-define-marker.js
@@ -0,0 +1,110 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ */
+
+import type { NodePath } from '@babel/traverse';
+
+import * as t from '@babel/types';
+import StateManager from '../utils/state-manager';
+import * as messages from '../shared/messages';
+import { utils } from '../shared';
+import { convertObjectToAST } from '../utils/js-to-ast';
+
+/**
+ * Transforms calls to `stylex.defineMarker()` (or imported `defineMarker()`)
+ * into an object: { $$css: true, [hash]: hash } where `hash` is generated from
+ * the file path and the export name.
+ */
+export default function transformStyleXDefineMarker(
+  path: NodePath<t.CallExpression>,
+  state: StateManager,
+): void {
+  const { node } = path;
+
+  if (node.type !== 'CallExpression') {
+    return;
+  }
+
+  const isDefineMarkerCall =
+    (node.callee.type === 'Identifier' &&
+      state.stylexDefineMarkerImport.has(node.callee.name)) ||
+    (node.callee.type === 'MemberExpression' &&
+      node.callee.object.type === 'Identifier' &&
+      node.callee.property.type === 'Identifier' &&
+      node.callee.property.name === 'defineMarker' &&
+      state.stylexImport.has(node.callee.object.name));
+
+  if (!isDefineMarkerCall) {
+    return;
+  }
+
+  // Validate call shape and location: must be bound to an exported const
+  validateStyleXDefineMarker(path);
+
+  // We know the parent is a VariableDeclarator
+  const variableDeclaratorPath = path.parentPath;
+  if (!variableDeclaratorPath.isVariableDeclarator()) {
+    return;
+  }
+  const variableDeclaratorNode = variableDeclaratorPath.node;
+  if (variableDeclaratorNode.id.type !== 'Identifier') {
+    return;
+  }
+
+  // No arguments allowed
+  if (node.arguments.length !== 0) {
+    throw path.buildCodeFrameError(
+      messages.illegalArgumentLength('defineMarker', 0),
+      SyntaxError,
+    );
+  }
+
+  const fileName = state.fileNameForHashing;
+  if (fileName == null) {
+    throw new Error(messages.cannotGenerateHash('defineMarker'));
+  }
+
+  const exportName = variableDeclaratorNode.id.name;
+  const exportId = utils.genFileBasedIdentifier({ fileName, exportName });
+  const id = state.options.classNamePrefix + utils.hash(exportId);
+
+  const markerObj = {
+    [id]: id,
+    $$css: true,
+  };
+
+  path.replaceWith(convertObjectToAST(markerObj));
+}
+
+function validateStyleXDefineMarker(path: NodePath<t.CallExpression>) {
+  const variableDeclaratorPath: any = path.parentPath;
+  const exportNamedDeclarationPath =
+    variableDeclaratorPath.parentPath?.parentPath;
+
+  if (
+    variableDeclaratorPath == null ||
+    variableDeclaratorPath.isExpressionStatement() ||
+    !variableDeclaratorPath.isVariableDeclarator() ||
+    variableDeclaratorPath.node.id.type !== 'Identifier'
+  ) {
+    throw path.buildCodeFrameError(
+      messages.unboundCallValue('defineMarker'),
+      SyntaxError,
+    );
+  }
+
+  if (
+    exportNamedDeclarationPath == null ||
+    !exportNamedDeclarationPath.isExportNamedDeclaration()
+  ) {
+    throw path.buildCodeFrameError(
+      messages.nonExportNamedDeclaration('defineMarker'),
+      SyntaxError,
+    );
+  }
+}
diff --git a/packages/@stylexjs/babel-plugin/src/visitors/stylex-props.js b/packages/@stylexjs/babel-plugin/src/visitors/stylex-props.js
diff --git a/packages/@stylexjs/stylex/__tests__/stylex-test.js b/packages/@stylexjs/stylex/__tests__/stylex-test.js
diff --git a/packages/@stylexjs/stylex/src/stylex.js b/packages/@stylexjs/stylex/src/stylex.js

Original file line number	Diff line number	Diff line change
`@@ -79,6 +79,9 @@ export function readImportDeclarations(`
`79`	`79`	`if (importedName === 'defineVars') {`
`80`	`80`	`state.stylexDefineVarsImport.add(localName);`
`81`	`81`	`}`
	`82`	`+ if (importedName === 'defineMarker') {`
	`83`	`+ state.stylexDefineMarkerImport.add(localName);`
	`84`	`+ }`
`82`	`85`	`if (importedName === 'defineConsts') {`
`83`	`86`	`state.stylexDefineConstsImport.add(localName);`
`84`	`87`	`}`
`@@ -158,6 +161,9 @@ export function readRequires(`
`158`	`161`	`if (prop.key.name === 'defineVars') {`
`159`	`162`	`state.stylexDefineVarsImport.add(value.name);`
`160`	`163`	`}`
	`164`	`+ if (prop.key.name === 'defineMarker') {`
	`165`	`+ state.stylexDefineMarkerImport.add(value.name);`
	`166`	`+ }`
`161`	`167`	`if (prop.key.name === 'defineConsts') {`
`162`	`168`	`state.stylexDefineConstsImport.add(value.name);`
`163`	`169`	`}`