chore: add warnings about selectors

Author: tenphi

.changeset/has-selector-element-transformation.md

@@ -3,4 +3,3 @@
 ---
 
 Add support for `:has(Item)` syntax in style mappings. Capitalized element names inside `:has()` pseudo-class selectors are now automatically transformed to `data-element` attribute selectors (`:has(Item)` → `:has([data-element="Item"])`).
-

.size-limit.cjs

@@ -27,13 +27,13 @@ module.exports = [
     path: './dist/es/index.js',
     webpack: true,
     import: '{ Button }',
-    limit: '33 kB',
+    limit: '34 kB',
   },
   {
     name: 'Tree shaking (just an Icon)',
     path: './dist/es/index.js',
     webpack: true,
     import: '{ AiIcon }',
-    limit: '20 kB',
+    limit: '21 kB',
   },
 ];

src/stories/Tasty.docs.mdx

@@ -101,6 +101,8 @@ fill: { '': '#white', hovered: '#gray.05', 'theme=danger': '#red' }
 
 Element styled using a capitalized key. Identified by `data-element` attribute. Capitalized words in selectors (`:has(Item)`, `> Body > Row`) transform to `[data-element="..."]`.
 
+**Important:** Combinators (`>`, `+`, `~`) must have spaces around them: `:has(Body > Row)` ✅, not `:has(Body>Row)` ❌. This is a design choice for parser performance.
+
 ```jsx
 styles: { Title: { preset: 'h3' } }
 // Targets: <div data-element="Title">
@@ -715,8 +717,11 @@ const Table = tasty({
     },
 
     // Chained selectors (auto-transforms capitalized words)
+    // ⚠️ Important: Spaces required around combinators for parsing
     Cell: {
-      $: '> Body > Row >',        // .table > [data-element="Body"] > [data-element="Row"] > [data-element="Cell"]
+      $: '> Body > Row >',        // ✅ Correct: spaces around > 
+                                  // ❌ Wrong: '>Body>Row>' (parser can't split)
+                                  // → .table > [data-element="Body"] > [data-element="Row"] > [data-element="Cell"]
       border: '1bw solid #border',
     },
 
@@ -728,6 +733,33 @@ const Table = tasty({
 });
 ```
 
+> **⚠️ Space Requirements:** Combinators (`>`, `+`, `~`) in selector affixes **must have spaces** around them when used with capitalized element names. Use `$: '> Body > Row'` ✅, not `$: '>Body>Row'` ❌. This is a performance consideration—the parser uses simple whitespace splitting to identify element names.
+
+#### `:has()` Selector with Sub-elements
+
+Style components based on their children using the `:has()` pseudo-class:
+
+```jsx
+const List = tasty({
+  styles: {
+    border: {
+      '': 'none',
+      // ⚠️ Spaces required around combinators (>, +, ~)
+      ':has(Body > Row)': '1bw solid #border',  // ✅ Correct
+      // ':has(Body>Row)': ...                   // ❌ Wrong: parser can't split
+    },
+    
+    padding: {
+      '': '2x',
+      ':has(Item)': '4x',                       // Single element, no combinator
+      'hovered & :has(Item)': '6x',             // Combining with other modifiers
+    },
+  },
+});
+```
+
+> **⚠️ Space Requirements:** Combinators (`>`, `+`, `~`) **must have spaces** around them when used with capitalized element names. Use `:has(Body > Row)` ✅, not `:has(Body>Row)` ❌. This is a performance consideration—the parser uses whitespace splitting to identify element names. A console error will warn if spaces are missing.
+
 ### Variants & Theming
 
 Create themed component variations:

src/tasty/tasty.test.tsx

@@ -1230,6 +1230,53 @@ describe('tastyGlobal() API', () => {
     );
   });
 
+  it('should warn when combinator lacks spaces in selector affix ($)', () => {
+    const consoleErrorSpy = jest
+      .spyOn(console, 'error')
+      .mockImplementation(() => {});
+
+    const Component = tasty({
+      styles: {
+        Item: {
+          $: '>Body>Row',
+          color: '#primary',
+        },
+      },
+    });
+
+    render(<Component />);
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('[Tasty] Invalid selector affix ($) syntax'),
+    );
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('>Body>Row'),
+    );
+
+    consoleErrorSpy.mockRestore();
+  });
+
+  it('should not warn when combinator has proper spaces in selector affix ($)', () => {
+    const consoleErrorSpy = jest
+      .spyOn(console, 'error')
+      .mockImplementation(() => {});
+
+    const Component = tasty({
+      styles: {
+        Item: {
+          $: '> Body > Row',
+          color: '#primary',
+        },
+      },
+    });
+
+    render(<Component />);
+
+    expect(consoleErrorSpy).not.toHaveBeenCalled();
+
+    consoleErrorSpy.mockRestore();
+  });
+
   it('should support multiple global style components with different selectors', () => {
     const GlobalHeading = tasty('h1.special', {
       preset: 'h1',

src/tasty/utils/renderStyles.ts

@@ -85,6 +85,18 @@ function transformSelectorAffix(affix: string): string {
   const trimmed = affix.trim();
   if (!trimmed) return ' ';
 
+  // Validate that combinators have spaces around them
+  // Check for capitalized words adjacent to combinators without spaces
+  const invalidPattern = /[A-Z][a-z]*[>+~]|[>+~][A-Z][a-z]*/;
+  if (invalidPattern.test(trimmed)) {
+    console.error(
+      `[Tasty] Invalid selector affix ($) syntax: "${affix}"\n` +
+        `Combinators (>, +, ~) must have spaces around them when used with element names.\n` +
+        `Example: Use "$: '> Body > Row'" instead of "$: '>Body>Row'"\n` +
+        `This is a design choice: the parser uses simple whitespace splitting for performance.`,
+    );
+  }
+
   const tokens = trimmed.split(/\s+/);
   const transformed = tokens.map((token) =>
     /^[A-Z]/.test(token) ? `[data-element="${token}"]` : token,

src/tasty/utils/styles.ts

@@ -143,6 +143,18 @@ export function getModSelector(modName: string): string {
       // Check if it contains :has() with capitalized element names
       if (modName.includes(':has(')) {
         selector = modName.replace(/:has\(([^)]+)\)/g, (match, content) => {
+          // Validate that combinators have spaces around them
+          // Check for capitalized words adjacent to combinators without spaces
+          const invalidPattern = /[A-Z][a-z]*[>+~]|[>+~][A-Z][a-z]*/;
+          if (invalidPattern.test(content)) {
+            console.error(
+              `[Tasty] Invalid :has() selector syntax: "${modName}"\n` +
+                `Combinators (>, +, ~) must have spaces around them when used with element names.\n` +
+                `Example: Use ":has(Body > Row)" instead of ":has(Body>Row)"\n` +
+                `This is a design choice: the parser uses simple whitespace splitting for performance.`,
+            );
+          }
+
           // Transform capitalized words to [data-element="..."] selectors
           const tokens = content.split(/\s+/);
           const transformed = tokens.map((token: string) =>

src/tasty/value-mods.test.tsx

@@ -446,6 +446,52 @@ describe('Value Mods', () => {
           ':has([data-element="Body"] [data-element="Item"] [data-element="Row"])',
         );
       });
+
+      it('should warn when combinator lacks spaces in :has()', () => {
+        const consoleErrorSpy = jest
+          .spyOn(console, 'error')
+          .mockImplementation(() => {});
+
+        // Test various invalid patterns
+        getModSelector(':has(Body>Row)');
+        expect(consoleErrorSpy).toHaveBeenCalledWith(
+          expect.stringContaining('[Tasty] Invalid :has() selector syntax'),
+        );
+        expect(consoleErrorSpy).toHaveBeenCalledWith(
+          expect.stringContaining(':has(Body>Row)'),
+        );
+
+        consoleErrorSpy.mockClear();
+
+        getModSelector(':has(Header+Content)');
+        expect(consoleErrorSpy).toHaveBeenCalledWith(
+          expect.stringContaining('[Tasty] Invalid :has() selector syntax'),
+        );
+
+        consoleErrorSpy.mockClear();
+
+        getModSelector(':has(List~Item)');
+        expect(consoleErrorSpy).toHaveBeenCalledWith(
+          expect.stringContaining('[Tasty] Invalid :has() selector syntax'),
+        );
+
+        consoleErrorSpy.mockRestore();
+      });
+
+      it('should not warn when combinator has proper spaces in :has()', () => {
+        const consoleErrorSpy = jest
+          .spyOn(console, 'error')
+          .mockImplementation(() => {});
+
+        getModSelector(':has(Body > Row)');
+        getModSelector(':has(Header + Content)');
+        getModSelector(':has(List ~ Item)');
+        getModSelector(':has(> Item)');
+
+        expect(consoleErrorSpy).not.toHaveBeenCalled();
+
+        consoleErrorSpy.mockRestore();
+      });
     });
 
     it('should transform :has(Item) to :has([data-element="Item"]) in component', () => {