[feat] Add defineMarker() for custom markers for selector combinators (#1238)

* Add stylex.defaultTarget

* Rename defaultTarget to defaultMarker

* Add stylex.defaultTarget

* Rename defaultTarget to defaultMarker

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

* Fix flow/ts types for custom markers

Author: nmn

examples/example-nextjs/components/Card.tsx

@@ -8,8 +8,13 @@
  */
 
 import * as stylex from '@stylexjs/stylex';
-import { globalTokens as $, spacing, text, colors } from '@/app/globalTokens.stylex';
-import { tokens } from '@/app/CardTokens.stylex';
+import {
+  globalTokens as $,
+  spacing,
+  text,
+  colors,
+} from '@/app/globalTokens.stylex';
+import { cardMarker, headingMarker } from './CardTokens.stylex';
 
 type Props = Readonly<{
   title: string;
@@ -20,12 +25,12 @@ type Props = Readonly<{
 export default function Card({ title, body, href }: Props) {
   return (
     <a
-      {...stylex.props(styles.link)}
+      {...stylex.props(styles.link, cardMarker)}
       href={href}
       rel="noopener noreferrer"
       target="_blank"
     >
-      <h2 {...stylex.props(styles.h2)}>
+      <h2 {...stylex.props(styles.h2, headingMarker)}>
         {title} <span {...stylex.props(styles.span)}>→</span>
       </h2>
       <p {...stylex.props(styles.p)}>{body}</p>
@@ -67,10 +72,6 @@ const styles = stylex.create({
     transitionDuration: '400ms',
     textAlign: 'center',
     textDecoration: 'none',
-    [tokens.arrowTransform]: {
-      default: 'translateX(0)',
-      ':hover': 'translateX(4px)',
-    },
   },
   h2: {
     color: colors.blue3,
@@ -84,7 +85,11 @@ const styles = stylex.create({
   span: {
     display: 'inline-block',
     transitionProperty: 'transform',
-    transform: tokens.arrowTransform,
+    transform: {
+      default: null,
+      [stylex.when.ancestor(':hover', cardMarker)]: 'translateX(10px)',
+      [stylex.when.ancestor(':hover', headingMarker)]: 'translateX(4px)',
+    },
     transitionDuration: {
       default: '200ms',
       [REDUCE_MOTION]: '0s',

examples/example-nextjs/app/CardTokens.stylex.ts renamed to examples/example-nextjs/components/CardTokens.stylex.ts

@@ -9,6 +9,5 @@
 
 import * as stylex from '@stylexjs/stylex';
 
-export const tokens = stylex.defineVars({
-  arrowTransform: 'translateX(0)',
-});
+export const cardMarker = stylex.defineMarker();
+export const headingMarker = stylex.defineMarker();

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
+        };"
+      `);
+    });
+  });
+});

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;
@@ -334,4 +343,42 @@ describe('@stylexjs/babel-plugin', () => {
       `);
     });
   });
+
+  describe('[transform] using custom markers', () => {
+    test('named import of custom marker', () => {
+      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"
+        };"
+      `);
+    });
+  });
 });

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));
+    });
+  });
+});

packages/@stylexjs/babel-plugin/src/index.js

@@ -37,6 +37,7 @@ import {
   LOGICAL_FLOAT_START_VAR,
   LOGICAL_FLOAT_END_VAR,
 } from './shared/preprocess-rules/legacy-expand-shorthands';
+import transformStyleXDefineMarker from './visitors/stylex-define-marker';
 
 const NAME = 'stylex';
 
@@ -310,6 +311,7 @@ function styleXTransform(): PluginObj<> {
         }
 
         transformStyleXDefaultMarker(path, state);
+        transformStyleXDefineMarker(path, state);
         transformStyleXDefineVars(path, state);
         transformStyleXDefineConsts(path, state);
         transformStyleXCreateTheme(path, state);

packages/@stylexjs/babel-plugin/src/shared/when/when.js

@@ -11,9 +11,36 @@ import type { StyleXOptions } from '../common-types';
 
 import { defaultOptions } from '../utils/default-options';
 
+function fromProxy(value: mixed): ?string {
+  if (
+    typeof value === 'object' &&
+    value != null &&
+    value.__IS_PROXY === true &&
+    typeof value.toString === 'function'
+  ) {
+    return value.toString();
+  }
+  return null;
+}
+
+function fromStyleXStyle(value: mixed): ?string {
+  if (typeof value === 'object' && value != null && value.$$css === true) {
+    return Object.keys(value).find((key) => key !== '$$css');
+  }
+  return null;
+}
+
 function getDefaultMarkerClassName(
   options: StyleXOptions = defaultOptions,
 ): string {
+  const valueFromProxy = fromProxy(options);
+  if (valueFromProxy != null) {
+    return valueFromProxy;
+  }
+  const valueFromStyleXStyle = fromStyleXStyle(options);
+  if (valueFromStyleXStyle != null) {
+    return valueFromStyleXStyle;
+  }
   const prefix =
     options.classNamePrefix != null ? `${options.classNamePrefix}-` : '';
   return `${prefix}default-marker`;

packages/@stylexjs/babel-plugin/src/utils/evaluate-path.js

@@ -205,6 +205,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) {

packages/@stylexjs/babel-plugin/src/utils/state-manager.js

@@ -155,6 +155,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();

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);
           }