Merge pull request #414 (css)

feat(css)!: drop processCSSRuleChain and improve processCSSSelectors

Author: amery

packages/@poupe-css/README.md

@@ -464,90 +464,63 @@ expandSelectorAlias('print', customAliases); // '@media print'
 expandSelectorAlias('.my-class'); // '.my-class'
 ```
 
-#### `processCSSRuleChain(selectors: string[], addStarVariants?: boolean): string | string[] | undefined`
+#### `processCSSSelectors(selectors: string | string[], options?: ProcessCSSSelectorOptions): string[] | undefined`
 
-Processes an array of CSS selectors and at-rules, merging consecutive
-selectors with OR and adding * variants, while keeping at-rules stacked
-separately. Returns `undefined` if no valid selectors are found.
-
-```typescript
-import { processCSSRuleChain } from '@poupe/css';
-
-// Merge consecutive selectors with star variants
-processCSSRuleChain(['.dark', '.custom']);
-// Result: '.dark, .dark *, .custom, .custom *'
-
-// At-rules are kept separate
-processCSSRuleChain([
-  '.dark',
-  '@media (max-width: 768px)',
-  '.mobile'
-]);
-// Result: [
-//   '.dark, .dark *',
-//   '@media (max-width: 768px)',
-//   '.mobile, .mobile *'
-// ]
-
-// Disable star variants
-processCSSRuleChain(['.test1', '.test2'], false);
-// Result: '.test1, .test2'
-
-// Uses alias expansion
-processCSSRuleChain(['.test', 'media']);
-// Result: [
-//   '.test, .test *',
-//   '@media (prefers-color-scheme: dark)'
-// ]
-
-// Returns undefined for empty arrays
-processCSSRuleChain([]); // undefined
-```
-
-#### `processCSSSelectors(selectors: string | string[], options?: ProcessCSSSelectorOptions): string | string[] | undefined`
-
-Generic function to process CSS selector arrays with support for alias
-expansion and various formatting options. Returns `undefined` if no valid
-selectors are found.
+Processes CSS selectors and at-rules, handling both strings and arrays.
+Merges consecutive selectors with OR and adds * variants, while keeping
+at-rules stacked separately. Returns `undefined` if no valid selectors are
+found.
 
 ```typescript
 import { processCSSSelectors } from '@poupe/css';
 
 // Single string selector
 processCSSSelectors('.test');
-// Result: '.test, .test *'
+// Result: ['.test, .test *']
 
 // Array of selectors
 processCSSSelectors(['.dark', '.custom']);
-// Result: '.dark, .dark *, .custom, .custom *'
+// Result: ['.dark, .dark *, .custom, .custom *']
 
 // Comma-separated selectors pass through (when allowCommaPassthrough is true)
 processCSSSelectors('.test, .other');
-// Result: '.test, .other'
+// Result: ['.test, .other']
 
 // Disable star variants
 processCSSSelectors(['.test1', '.test2'], { addStarVariants: false });
-// Result: '.test1, .test2'
+// Result: ['.test1, .test2']
 
 // Use custom aliases
 const customAliases = { 'custom': '@media (min-width: 1200px)' };
 processCSSSelectors('custom', { aliases: customAliases });
-// Result: '@media (min-width: 1200px), @media (min-width: 1200px) *'
+// Result: ['@media (min-width: 1200px), @media (min-width: 1200px) *']
 
 // Mixed selectors and aliases
 processCSSSelectors(['.test', 'mobile'], { addStarVariants: false });
 // Result: ['.test', '@media (max-width: 768px)']
 
+// At-rules are kept separate
+processCSSSelectors([
+  '.dark',
+  '@media (max-width: 768px)',
+  '.mobile'
+]);
+// Result: [
+//   '.dark, .dark *',
+//   '@media (max-width: 768px)',
+//   '.mobile, .mobile *'
+// ]
+
 // Returns undefined for empty arrays
 processCSSSelectors([]); // undefined
 
 // Alias expansion with single string
 processCSSSelectors('media');
-// Result: '@media (prefers-color-scheme: dark), @media (prefers-color-scheme: dark) *'
+// Result: ['@media (prefers-color-scheme: dark), @media (prefers-color-scheme: dark) *']
 
-// Disable comma passthrough
+// Disable comma pass-through
 processCSSSelectors('.test, .other', { allowCommaPassthrough: false });
-// Result: '.test, .other, .test, .other *'
+// Result: ['.test, .other, .test, .other *']
 ```
 
 ### Utility Functions

packages/@poupe-css/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poupe/css",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "type": "module",
   "description": "A TypeScript utility library for CSS property manipulation, formatting, and CSS-in-JS operations",
   "author": "Alejandro Mery <amery@apptly.co>",

packages/@poupe-css/src/__tests__/selectors.test.ts

@@ -1,7 +1,6 @@
 import { describe, it, expect } from 'vitest';
 
 import {
-  processCSSRuleChain,
   processCSSSelectors,
   expandSelectorAlias,
 } from '../selectors';
@@ -42,14 +41,32 @@ describe('expandSelectorAlias', () => {
   });
 });
 
-describe('processCSSRuleChain', () => {
+describe('processCSSSelectors', () => {
+  it('should handle single string selectors', () => {
+    expect(processCSSSelectors('.test')).toEqual(['.test, .test *']);
+  });
+
+  it('should handle single string with commas when allowCommaPassthrough is true', () => {
+    expect(processCSSSelectors('.test, .other')).toEqual(['.test, .other']);
+  });
+
+  it('should add star variants when allowCommaPassthrough is false', () => {
+    expect(processCSSSelectors('.test, .other', { allowCommaPassthrough: false }))
+      .toEqual(['.test, .other, .test, .other *']);
+  });
+
+  it('should handle arrays with consecutive selectors', () => {
+    const result = processCSSSelectors(['.test1', '.test2']);
+    expect(result).toEqual(['.test1, .test1 *, .test2, .test2 *']);
+  });
+
   it('should merge consecutive selectors with star variants', () => {
-    const result = processCSSRuleChain(['.test1', '.test2']);
-    expect(result).toBe('.test1, .test1 *, .test2, .test2 *');
+    const result = processCSSSelectors(['.test1', '.test2']);
+    expect(result).toEqual(['.test1, .test1 *, .test2, .test2 *']);
   });
 
   it('should stack at-rules separately', () => {
-    const result = processCSSRuleChain([
+    const result = processCSSSelectors([
       '@media (prefers-color-scheme: dark)',
       '@media (max-width: 768px)',
     ]);
@@ -60,7 +77,7 @@ describe('processCSSRuleChain', () => {
   });
 
   it('should handle mixed selectors and at-rules', () => {
-    const result = processCSSRuleChain([
+    const result = processCSSSelectors([
       '.dark',
       '@media (prefers-color-scheme: dark)',
       '.custom',
@@ -73,55 +90,35 @@ describe('processCSSRuleChain', () => {
   });
 
   it('should disable star variants when addStarVariants is false', () => {
-    const result = processCSSRuleChain(['.test1', '.test2'], false);
-    expect(result).toBe('.test1, .test2');
+    const result = processCSSSelectors(['.test1', '.test2'], { addStarVariants: false });
+    expect(result).toEqual(['.test1, .test2']);
   });
 
   it('should return undefined for empty array', () => {
-    expect(processCSSRuleChain([])).toBeUndefined();
+    expect(processCSSSelectors([])).toBeUndefined();
   });
 
   it('should expand selector aliases', () => {
-    const result = processCSSRuleChain(['.test', 'media']);
+    const result = processCSSSelectors(['.test', 'media']);
     expect(result).toEqual([
       '.test, .test *',
       '@media (prefers-color-scheme: dark)',
     ]);
   });
-});
-
-describe('processCSSSelectors', () => {
-  it('should handle single string selectors', () => {
-    expect(processCSSSelectors('.test')).toBe('.test, .test *');
-  });
-
-  it('should handle single string with commas when allowCommaPassthrough is true', () => {
-    expect(processCSSSelectors('.test, .other')).toBe('.test, .other');
-  });
-
-  it('should add star variants when allowCommaPassthrough is false', () => {
-    expect(processCSSSelectors('.test, .other', { allowCommaPassthrough: false }))
-      .toBe('.test, .other, .test, .other *');
-  });
-
-  it('should handle arrays with consecutive selectors', () => {
-    const result = processCSSSelectors(['.test1', '.test2']);
-    expect(result).toBe('.test1, .test1 *, .test2, .test2 *');
-  });
 
   it('should return undefined for empty arrays', () => {
     expect(processCSSSelectors([])).toBeUndefined();
   });
 
   it('should expand aliases in single strings', () => {
     expect(processCSSSelectors('media'))
-      .toBe('@media (prefers-color-scheme: dark), @media (prefers-color-scheme: dark) *');
+      .toEqual(['@media (prefers-color-scheme: dark)']);
   });
 
   it('should use custom aliases when provided', () => {
     const customAliases = { custom: '@media (min-width: 1200px)' };
     const result = processCSSSelectors('custom', { aliases: customAliases });
-    expect(result).toBe('@media (min-width: 1200px), @media (min-width: 1200px) *');
+    expect(result).toEqual(['@media (min-width: 1200px)']);
   });
 
   it('should expand aliases in arrays', () => {

packages/@poupe-css/src/selectors.ts

@@ -24,19 +24,43 @@ export function expandSelectorAlias(
   return aliases[trimmed] || trimmed;
 }
 
+export interface ProcessCSSSelectorOptions {
+  /** Whether to add "selector *" variants to each selector */
+  addStarVariants?: boolean
+  /** Whether to allow comma-separated selectors to pass through */
+  allowCommaPassthrough?: boolean
+  /** Custom selector aliases to use for expansion */
+  aliases?: Record<string, string>
+}
+
 /**
- * Processes an array of CSS selectors and at-rules, merging consecutive
- * selectors with OR and adding * variants, while keeping at-rules stacked
- * separately.
+ * Processes CSS selectors and at-rules, handling both strings and arrays.
+ * Merges consecutive selectors with OR and adds * variants,
+ * while keeping at-rules stacked separately.
  *
- * @param selectors - Array of CSS selectors and at-rules
- * @param addStarVariants - Whether to add "selector *" variants
- * @returns Single string, array of strings, or undefined
+ * @param selectors - CSS selector(s) and at-rules
+ * @param options - Processing options
+ * @returns Array of processed selector strings or undefined
  */
-export function processCSSRuleChain(
-  selectors: string[],
-  addStarVariants: boolean = true,
-): string | string[] | undefined {
+export function processCSSSelectors(
+  selectors: string | string[],
+  options: ProcessCSSSelectorOptions = {},
+): string[] | undefined {
+  const {
+    addStarVariants = true,
+    allowCommaPassthrough = true,
+    aliases = DEFAULT_SELECTOR_ALIASES,
+  } = options;
+
+  // Convert string to array for unified processing
+  const selectorArray = Array.isArray(selectors) ? selectors : [selectors];
+
+  // Handle comma passthrough for single strings
+  if (!Array.isArray(selectors) && allowCommaPassthrough && selectors.includes(',')) {
+    const expanded = expandSelectorAlias(selectors, aliases);
+    return [expanded];
+  }
+
   const result: string[] = [];
   const currentSelectors: string[] = [];
 
@@ -55,8 +79,8 @@ export function processCSSRuleChain(
     }
   };
 
-  for (const s of selectors) {
-    const expanded = expandSelectorAlias(s);
+  for (const s of selectorArray) {
+    const expanded = expandSelectorAlias(s, aliases);
     const trimmed = expanded.trim();
     if (!trimmed) continue;
 
@@ -73,47 +97,5 @@ export function processCSSRuleChain(
   // Flush any remaining selectors
   flushSelectors();
 
-  if (result.length === 0) {
-    return undefined;
-  }
-  return result.length === 1 ? result[0] : result;
-}
-
-export interface ProcessCSSSelectorOptions {
-  /** Whether to add "selector *" variants to each selector */
-  addStarVariants?: boolean
-  /** Whether to allow comma-separated selectors to pass through */
-  allowCommaPassthrough?: boolean
-  /** Custom selector aliases to use for expansion */
-  aliases?: Record<string, string>
-}
-
-/**
- * Generic function to process CSS selector arrays for any theme mode
- * @param selectors - Array of CSS selectors and at-rules
- * @param options - Processing options
- * @returns Processed selector string(s) or undefined
- */
-export function processCSSSelectors(
-  selectors: string | string[],
-  options: ProcessCSSSelectorOptions = {},
-): string | string[] | undefined {
-  const {
-    addStarVariants = true,
-    allowCommaPassthrough = true,
-    aliases,
-  } = options;
-
-  if (!Array.isArray(selectors)) {
-    const expanded = expandSelectorAlias(selectors, aliases);
-
-    if (allowCommaPassthrough && expanded.includes(',')) {
-      return expanded;
-    }
-    return addStarVariants
-      ? `${expanded}, ${expanded} *`
-      : expanded;
-  }
-
-  return processCSSRuleChain(selectors, addStarVariants);
+  return result.length === 0 ? undefined : result;
 }