feat: support multiple scopes in CSS variable registration (#245)

* feat: support multiple scopes in CSS variable registration

Allow the `scope` option to accept an array of strings, enabling CSS variables to be scoped to multiple classes simultaneously. This generates comma-separated selectors when multiple scopes are provided.

Changes:
- Update type definitions to support `string | string[]` for scope parameter
- Refactor selector generation logic in `serializeCSSVar` to handle multiple scopes
- Add test coverage for multiple scope functionality

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: filter empty scopes in CSS variable registration

- Add filter(Boolean) to remove empty strings from scope array
- Use @@ as separator for array scope in cache key

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: simplify scope handling in css variables

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: zombieJ

src/hooks/useCSSVarRegister.ts

@@ -28,21 +28,22 @@ const useCSSVarRegister = <V, T extends Record<string, V>>(
     prefix?: string;
     unitless?: Record<string, boolean>;
     ignore?: Record<string, boolean>;
-    scope?: string;
+    scope?: string | string[];
     token: any;
     hashId?: string;
   },
   fn: () => T,
 ) => {
-  const { key, prefix, unitless, ignore, token, hashId, scope = '' } = config;
+  const { key, prefix, unitless, ignore, token, hashId, scope } = config;
   const {
     cache: { instanceId },
     container,
     hashPriority,
   } = useContext(StyleContext);
   const { _tokenKey: tokenKey } = token;
 
-  const stylePath = [...config.path, key, scope, tokenKey];
+  const scopeKey = Array.isArray(scope) ? scope.join('@@') : scope;
+  const stylePath = [...config.path, key, scopeKey, tokenKey];
 
   const cache = useGlobalCache<CSSVarCacheValue<V, T>>(
     CSS_VAR_PREFIX,

src/util/css-variables.ts

@@ -13,18 +13,23 @@ export const serializeCSSVar = <T extends Record<string, any>>(
   cssVars: T,
   hashId: string,
   options?: {
-    scope?: string;
+    scope?: string | string[];
     hashCls?: string;
     hashPriority?: HashPriority;
   },
 ) => {
-  const { hashCls, hashPriority = 'low' } = options || {};
+  const { hashCls, hashPriority = 'low', scope } = options || {};
   if (!Object.keys(cssVars).length) {
     return '';
   }
-  return `${where({ hashCls, hashPriority })}.${hashId}${
-    options?.scope ? `.${options.scope}` : ''
-  }{${Object.entries(cssVars)
+
+  const baseSelector = `${where({ hashCls, hashPriority })}.${hashId}`;
+  const scopes = [scope].flat().filter(Boolean);
+  const selector = scopes.length
+    ? scopes.map((s) => `${baseSelector}.${s}`).join(', ')
+    : baseSelector;
+
+  return `${selector}{${Object.entries(cssVars)
     .map(([key, value]) => `${key}:${value};`)
     .join('')}}`;
 };
@@ -53,7 +58,7 @@ export const transformToken = <
     preserve?: {
       [key in keyof T]?: boolean;
     };
-    scope?: string;
+    scope?: string | string[];
     hashCls?: string;
     hashPriority?: HashPriority;
   },

tests/css-variables.spec.tsx

@@ -406,4 +406,178 @@ describe('CSS Variables', () => {
     expect(styleStyle).toContain('line-height:var(--rc-line-height)');
     expect(styleStyle).not.toContain('--rc-line-height:1.5;');
   });
+
+  it('support multiple scope', () => {
+    const cache = createCache();
+    const BoxWithMultipleScopes = (props: { className?: string }) => {
+      const [token, hashId, cssVarKey, realToken] = useToken();
+
+      const getComponentToken = () => ({ boxColor: '#5c21ff' });
+
+      const [cssVarToken] = useCSSVarRegister(
+        {
+          path: ['Box'],
+          key: cssVarKey,
+          token: realToken,
+          prefix: 'rc-box',
+          unitless: {
+            lineHeight: true,
+          },
+          ignore: {
+            lineHeightBase: true,
+          },
+          scope: ['box', 'container'],
+        },
+        cssVarKey ? getComponentToken : () => ({}),
+      ) as [{ boxColor?: string }, string, string, string];
+
+      useStyleRegister(
+        {
+          theme,
+          token,
+          hashId,
+          path: ['BoxMultipleScope'],
+        },
+        () => {
+          const mergedToken = {
+            ...token,
+            ...cssVarToken,
+            boxColor: cssVarToken?.boxColor || '#5c21ff',
+          } as DerivativeToken & { boxColor: string };
+
+          return {
+            '.box': {
+              lineHeight: mergedToken.lineHeight,
+              color: mergedToken.boxColor,
+              backgroundColor: mergedToken.primaryColor,
+            },
+          };
+        },
+      );
+
+      return (
+        <div
+          className={clsx(
+            hashId,
+            cssVarKey ? cssVarKey : '',
+            'box',
+            props.className,
+          )}
+        />
+      );
+    };
+
+    render(
+      <StyleProvider cache={cache}>
+        <DesignTokenProvider
+          theme={{
+            cssVar: {
+              key: 'apple',
+            },
+          }}
+        >
+          <BoxWithMultipleScopes className="target" />
+        </DesignTokenProvider>
+      </StyleProvider>,
+    );
+
+    const styles = Array.from(document.head.querySelectorAll('style'));
+    expect(styles.length).toBe(3);
+
+    // Check that the CSS variable style includes both scopes
+    const cssVarStyle = styles.find((style) =>
+      style.textContent?.includes('--rc-box-box-color'),
+    );
+    expect(cssVarStyle).toBeDefined();
+    expect(cssVarStyle?.textContent).toContain('--rc-box-box-color:#5c21ff');
+    // Should generate: .apple.box, .apple.container { ... }
+    expect(cssVarStyle?.textContent).toMatch(
+      /\.apple\.box,\s*\.apple\.container\{/,
+    );
+  });
+
+  it('should filter empty scopes', () => {
+    const BoxWithEmptyScope = (props: { className?: string }) => {
+      const [token, hashId, cssVarKey, realToken] = useToken();
+
+      const getComponentToken = () => ({ boxColor: '#5c21ff' });
+
+      const [cssVarToken] = useCSSVarRegister(
+        {
+          path: ['Box'],
+          key: cssVarKey,
+          token: realToken,
+          prefix: 'rc-box',
+          unitless: {
+            lineHeight: true,
+          },
+          ignore: {
+            lineHeightBase: true,
+          },
+          scope: ['box', '', 'container'],
+        },
+        cssVarKey ? getComponentToken : () => ({}),
+      ) as [{ boxColor?: string }, string, string, string];
+
+      useStyleRegister(
+        {
+          theme,
+          token,
+          hashId,
+          path: ['BoxEmptyScope'],
+        },
+        () => {
+          const mergedToken = {
+            ...token,
+            ...cssVarToken,
+            boxColor: cssVarToken?.boxColor || '#5c21ff',
+          } as DerivativeToken & { boxColor: string };
+
+          return {
+            '.box': {
+              lineHeight: mergedToken.lineHeight,
+              color: mergedToken.boxColor,
+            },
+          };
+        },
+      );
+
+      return (
+        <div
+          className={clsx(
+            hashId,
+            cssVarKey ? cssVarKey : '',
+            'box',
+            props.className,
+          )}
+        />
+      );
+    };
+
+    render(
+      <StyleProvider cache={createCache()}>
+        <DesignTokenProvider
+          theme={{
+            cssVar: {
+              key: 'orange',
+            },
+          }}
+        >
+          <BoxWithEmptyScope className="target" />
+        </DesignTokenProvider>
+      </StyleProvider>,
+    );
+
+    const styles = Array.from(document.head.querySelectorAll('style'));
+    const cssVarStyle = styles.find((style) =>
+      style.textContent?.includes('--rc-box-box-color'),
+    );
+    expect(cssVarStyle).toBeDefined();
+    // Should NOT contain empty scope selector like .orange.
+    expect(cssVarStyle?.textContent).not.toMatch(/\.orange\.\{/);
+    // Should only contain valid scopes: .orange.box and .orange.container
+    expect(cssVarStyle?.textContent).toMatch(
+      /\.orange\.box,\s*\.orange\.container\{/,
+    );
+  });
 });