Merge pull request #415 (css)

feat: refactor selector handling in `@poupe/theme-builder` and `@poupe/tailwindcss`

Author: amery

packages/@poupe-tailwindcss/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poupe/tailwindcss",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "type": "module",
   "description": "TailwindCSS v4 plugin for Poupe UI framework with theme customization support",
   "author": "Alejandro Mery <amery@apptly.co>",

packages/@poupe-tailwindcss/src/theme/theme.ts

@@ -307,6 +307,7 @@ export function makeThemeBases(
         darkSuffix: theme.options.darkSuffix,
         lightSuffix: theme.options.lightSuffix,
         stringify: stringify || hslString,
+        addStarVariantsToDark: false,
       },
     );
 

packages/@poupe-tailwindcss/src/theme/variants.ts

@@ -1,4 +1,5 @@
 import {
+  processCSSSelectors,
   type CSSRuleObject,
 } from '@poupe/css';
 
@@ -94,11 +95,8 @@ export function getDarkMode(darkMode: DarkModeStrategy = 'class'): string[] {
         const [mode, value] = darkMode;
         switch (mode) {
           case 'class':
-          case 'selector': {
-            const v = makeDarkModeSelector(value);
-            if (v.length > 0)
-              return v;
-          }
+          case 'selector':
+            return processCSSSelectors(value) ?? [defaultDarkSelector];
         }
 
         // TODO: variant modes
@@ -109,21 +107,4 @@ export function getDarkMode(darkMode: DarkModeStrategy = 'class'): string[] {
   }
 }
 
-function makeDarkModeSelector(value: string | string[]): string[] {
-  if (Array.isArray(value)) {
-    const sanitized: string[] = [];
-
-    // remove empty slots
-    for (const v of value) {
-      const trimmed = v.trim();
-      if (trimmed != '') sanitized.push(trimmed);
-    }
-
-    return sanitized.length > 0 ? sanitized : [defaultDarkSelector];
-  }
-
-  const trimmed = value.trim();
-  return trimmed == '' ? [defaultDarkSelector] : [trimmed];
-}
-
 const defaultDarkSelector = '.dark, .dark *';

packages/@poupe-theme-builder/README.md

@@ -85,7 +85,20 @@ const cssTheme = makeCSSTheme({
   scheme: 'content',
   contrastLevel: 0.5,
   prefix: 'md-',
-  darkMode: '.dark',
+  darkMode: ['.dark', 'media'],    // Multiple selectors with aliases
+  lightMode: '.light',
+})
+
+// Built-in responsive aliases
+makeCSSTheme(colors, { 
+  darkMode: ['dark', 'mobile'],    // Uses media queries
+  lightMode: ['light', 'desktop']  // Now supports arrays too
+})
+
+// Advanced selector configuration
+const advancedTheme = makeCSSTheme(colors, {
+  darkMode: ['mobile', '.dark-mode'],   // Mobile screens + custom class
+  lightMode: ['desktop', '.light-mode'], // Desktop + custom class
 })
 
 // Use generated CSS variables
@@ -254,15 +267,24 @@ cssTheme.styles                   // CSS rule objects
 
 ## Dark Mode
 
-Built-in dark mode support with flexible selectors:
+Built-in dark mode support with flexible selectors and aliases:
 
 ```typescript
 // Class-based dark mode (default)
 makeCSSTheme(colors, { darkMode: '.dark' })
 
-// Media query dark mode
+// Media query dark mode using built-in alias
 makeCSSTheme(colors, { darkMode: 'media' })
 
+// Multiple selectors
+makeCSSTheme(colors, { darkMode: ['.dark', '.theme-dark'] })
+
+// Built-in responsive aliases
+makeCSSTheme(colors, { 
+  darkMode: ['dark', 'mobile'],  // Uses media queries
+  lightMode: 'light'
+})
+
 // Custom selectors
 makeCSSTheme(colors, {
   darkMode: '[data-theme="dark"]',
@@ -273,6 +295,24 @@ makeCSSTheme(colors, {
 makeCSSTheme(colors, { darkMode: false })
 ```
 
+### Built-in Selector Aliases
+
+The theme builder includes convenient aliases for common media queries:
+
+- `'media'` or `'dark'` → `'@media (prefers-color-scheme: dark)'`
+- `'light'` → `'@media (prefers-color-scheme: light)'`
+- `'mobile'` → `'@media (max-width: 768px)'`
+- `'tablet'` → `'@media (min-width: 769px) and (max-width: 1024px)'`
+- `'desktop'` → `'@media (min-width: 1025px)'`
+
+```typescript
+// Using aliases for responsive theming
+const cssTheme = makeCSSTheme(colors, {
+  darkMode: ['dark', 'tablet'],     // Dark mode + tablet screens
+  lightMode: ['light', 'desktop'],  // Light mode + desktop screens
+})
+```
+
 ## Integration with Poupe Ecosystem
 
 - [@poupe/css](../@poupe-css) - CSS utility library

packages/@poupe-theme-builder/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poupe/theme-builder",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "type": "module",
   "description": "Design token management and theme generation system for Poupe UI framework",
   "author": "Alejandro Mery <amery@apptly.co>",

packages/@poupe-theme-builder/src/css/__tests__/css.test.ts

@@ -60,27 +60,27 @@ describe('defaultCSSThemeOptions', () => {
 
 describe('defaultDarkSelector', () => {
   it('should return .dark for true or .dark', () => {
-    expect(defaultDarkSelector({ darkMode: true })).toBe('.dark, .dark *');
-    expect(defaultDarkSelector({ darkMode: '.dark' })).toBe('.dark, .dark *');
+    expect(defaultDarkSelector({ darkMode: true })).toEqual(['.dark, .dark *']);
+    expect(defaultDarkSelector({ darkMode: '.dark' })).toEqual(['.dark, .dark *']);
   });
 
   it('should return media query for false, empty string, or media', () => {
-    const mediaQuery = '@media not print and (prefers-color-scheme: dark)';
-    expect(defaultDarkSelector({ darkMode: false })).toBe(mediaQuery);
-    expect(defaultDarkSelector({ darkMode: '' })).toBe(mediaQuery);
-    expect(defaultDarkSelector({ darkMode: 'media' })).toBe(mediaQuery);
+    const mediaQuery = '@media (prefers-color-scheme: dark)';
+    expect(defaultDarkSelector({ darkMode: false })).toEqual([mediaQuery]);
+    expect(defaultDarkSelector({ darkMode: '' })).toEqual([mediaQuery]);
+    expect(defaultDarkSelector({ darkMode: 'media' })).toEqual([mediaQuery]);
   });
 
   it('should return custom selector when provided', () => {
     const custom = '.custom-dark-mode';
-    expect(defaultDarkSelector({ darkMode: custom })).toBe(`${custom}, ${custom} *`);
+    expect(defaultDarkSelector({ darkMode: custom })).toEqual([`${custom}, ${custom} *`]);
   });
 });
 
 describe('defaultLightSelector', () => {
   it('should return .light for true or .light', () => {
-    expect(defaultLightSelector({ lightMode: true })).toBe('.light, .light *');
-    expect(defaultLightSelector({ lightMode: '.light' })).toBe('.light, .light *');
+    expect(defaultLightSelector({ lightMode: true })).toEqual(['.light, .light *']);
+    expect(defaultLightSelector({ lightMode: '.light' })).toEqual(['.light, .light *']);
   });
 
   it('should return undefined for false or empty string', () => {
@@ -90,7 +90,7 @@ describe('defaultLightSelector', () => {
 
   it('should return custom selector when provided', () => {
     const custom = '.custom-light-mode';
-    expect(defaultLightSelector({ lightMode: custom })).toBe(`${custom}, ${custom} *`);
+    expect(defaultLightSelector({ lightMode: custom })).toEqual([`${custom}, ${custom} *`]);
   });
 });
 
@@ -416,20 +416,18 @@ describe('deduplication in generateCSSColorVariables', () => {
 });
 
 describe('defaultRootLightSelector', () => {
-  if (typeof defaultRootLightSelector === 'function') {
-    it('should return :root when lightMode is false or empty', () => {
-      expect(defaultRootLightSelector({ lightMode: false })).toBe(':root');
-      expect(defaultRootLightSelector({ lightMode: '' })).toBe(':root');
-    });
+  it('should return :root when lightMode is false or empty', () => {
+    expect(defaultRootLightSelector({ lightMode: false })).toEqual([':root']);
+    expect(defaultRootLightSelector({ lightMode: '' })).toEqual([':root']);
+  });
 
-    it('should combine :root with light selector when lightMode is defined', () => {
-      const selector = defaultRootLightSelector({ lightMode: '.light-theme' });
-      expect(selector).toBe(':root, .light-theme, .light-theme *');
+  it('should combine :root with light selector when lightMode is defined', () => {
+    const selector = defaultRootLightSelector({ lightMode: '.light-theme' });
+    expect(selector).toEqual([':root, .light-theme, .light-theme *']);
 
-      const defaultSelector = defaultRootLightSelector({});
-      expect(defaultSelector).toBe(':root, .light, .light *');
-    });
-  }
+    const defaultSelector = defaultRootLightSelector({});
+    expect(defaultSelector).toEqual([':root, .light, .light *']);
+  });
 });
 
 describe('assembleCSSRules', () => {
@@ -448,6 +446,7 @@ describe('assembleCSSRules', () => {
       expect(result[0][':root']).toEqual(root);
       expect(result[1]).toHaveProperty(':root, .light, .light *');
       expect(result[1][':root, .light, .light *']).toEqual(light);
+      expect(result[1]).toHaveProperty('.dark, .dark *');
       expect(result[1]['.dark, .dark *']).toEqual(dark);
     });
 

packages/@poupe-theme-builder/src/css/css.ts

@@ -6,6 +6,7 @@ import {
   type CSSRuleObject,
   unsafeKeys,
   setDeepRule,
+  processCSSSelectors,
 } from '@poupe/css';
 
 import {
@@ -26,7 +27,7 @@ export interface CSSThemeOptions {
   /** @defaultValue `'.dark'` */
   darkMode: boolean | string | string[]
   /** @defaultValue `'.light'` */
-  lightMode: boolean | string
+  lightMode: boolean | string | string[]
   /** @defaultValue `'md-'` */
   prefix: string
   /** @defaultValue `'-dark'` */
@@ -35,6 +36,10 @@ export interface CSSThemeOptions {
   lightSuffix: string
   /** @defaultValue `rgb('{r} {g} {b}')` */
   stringify: (c: Hct) => string
+  /** @defaultValue `true` */
+  addStarVariantsToDark?: boolean
+  /** @defaultValue `true` */
+  addStarVariantsToLight?: boolean
 };
 
 /** apply defaults to {@link CSSThemeOptions} */
@@ -50,44 +55,54 @@ export function defaultCSSThemeOptions(options: Partial<CSSThemeOptions> = {}):
 }
 
 /** @returns the dark mode selector or media rule */
-export function defaultDarkSelector(options: Partial<CSSThemeOptions>) {
-  const { darkMode = true } = options;
-  if (darkMode === true || darkMode === '.dark')
-    return '.dark, .dark *';
-  else if (darkMode === false || darkMode === '' || darkMode === 'media')
-    return '@media not print and (prefers-color-scheme: dark)';
-  else if (!Array.isArray(darkMode)) {
-    return darkMode.includes(',') ? darkMode : `${darkMode}, ${darkMode} *`;
-  }
+export function defaultDarkSelector(options: Partial<CSSThemeOptions>): string[] {
+  const { addStarVariantsToDark = true } = options;
+  let { darkMode = true } = options;
 
-  const selectors: string[] = [];
-  for (const s of darkMode) {
-    const trimmed = s.trim();
-    if (trimmed)
-      selectors.push(trimmed);
-  }
+  if (darkMode === true)
+    darkMode = '.dark';
+  else if (darkMode === false || darkMode === '')
+    darkMode = 'media';
 
-  if (selectors.length === 0) return '.dark, .dark *';
-  return selectors;
+  const result = processCSSSelectors(darkMode, {
+    addStarVariants: addStarVariantsToDark,
+  });
+  return result ?? ['.dark, .dark *'];
 }
 
 /** @returns the light mode selector, or undefined if disabled */
-export function defaultLightSelector(options: Partial<CSSThemeOptions>) {
-  const { lightMode = true } = options;
-  if (lightMode === true || lightMode === '.light')
-    return '.light, .light *';
+export function defaultLightSelector(options: Partial<CSSThemeOptions>): string[] | undefined {
+  const { addStarVariantsToLight = true } = options;
+  let { lightMode = true } = options;
+
+  if (lightMode === true)
+    lightMode = '.light';
   else if (lightMode === false || lightMode === '')
     return undefined;
-  else
-    return lightMode.includes(',') ? lightMode : `${lightMode}, ${lightMode} *`;
+
+  const result = processCSSSelectors(lightMode, {
+    addStarVariants: addStarVariantsToLight,
+  });
+  return result ?? ['.light, .light *'];
 }
 
-export function defaultRootLightSelector(options: Partial<CSSThemeOptions>) {
-  const rootSelector = ':root';
+export function defaultRootLightSelector(options: Partial<CSSThemeOptions>): string[] {
+  const rootSelector = [':root'];
   const lightSelector = defaultLightSelector(options);
+
   if (lightSelector) {
-    return `${rootSelector}, ${lightSelector}`;
+    const combined = processCSSSelectors([
+      ...rootSelector,
+      ...lightSelector,
+    ], {
+      addStarVariants: false, // already added.
+    });
+
+    if (combined) { // always true
+      return combined;
+    }
   }
+
   return rootSelector;
 }
 
@@ -110,23 +125,17 @@ export function assembleCSSRules(root: CSSRuleObject | undefined,
     });
   }
 
-  styles.push({
-    ...makeDeepRule(rootLightSelector, light),
-    ...makeDeepRule(darkSelector, dark),
-  });
+  const combinedRules: CSSRuleObject = {};
 
-  return styles;
-}
+  // Set light mode rules
+  setDeepRule(combinedRules, rootLightSelector, light);
 
-/**
- * Creates a nested CSS rule object from a selector path and a CSS rule object
- * @param path - Selector path (string or array of strings)
- * @param object - CSS rule object to be nested
- * @returns A CSSRuleObject with the nested structure
- */
-function makeDeepRule(path: string | string[], object: CSSRuleObject): CSSRuleObject {
-  const out: CSSRuleObject = {};
-  return setDeepRule(out, path, object);
+  // Set dark mode rules
+  setDeepRule(combinedRules, darkSelector, dark);
+
+  styles.push(combinedRules);
+
+  return styles;
 }
 
 export function generateCSSColorVariables<K extends string>(dark: ColorMap<K>, light: ColorMap<K>, options: CSSThemeOptions) {