feat: new syntax for custom properties with a fallback (#747)

Co-authored-by: Copilot <[email protected]>

Author: tenphi

.changeset/flat-bags-laugh.md

@@ -0,0 +1,5 @@
+---
+"@cube-dev/ui-kit": minor
+---
+
+New syntax for custom properties with fallback: `($prop-name, <fallback_value>)`.

src/components/form/FieldWrapper/FieldWrapper.tsx

@@ -19,7 +19,7 @@ const FieldElement = tasty({
     width: 'auto',
     gridColumns: {
       '': 'minmax(0, 1fr)',
-      'has-sider': '$(full-label-width, auto) minmax(0, 1fr)',
+      'has-sider': '($full-label-width, auto) minmax(0, 1fr)',
     },
     gap: 0,
     placeItems: 'baseline stretch',

src/stories/Tasty.docs.mdx

@@ -606,7 +606,7 @@ const Component = tasty({
     // Use custom properties
     padding: '$local-spacing',
     color: '$theme-color',
-    margin: '$(custom-margin, 1x)', // With fallback
+    margin: '($custom-margin, 1x)', // With fallback
   },
 });
 ```

src/tasty/parser/classify.ts

@@ -71,16 +71,7 @@ export function classify(
 
   // 2. Custom property
   if (token[0] === '@' || token[0] === '$') {
-    const match = token.match(/^[$@]\(([a-z0-9-_]+)\s*,\s*(.*)\)$/);
-    if (match) {
-      const [, name, fallback] = match;
-      const processedFallback = recurse(fallback).output;
-      return {
-        bucket: Bucket.Value,
-        processed: `var(--${name}, ${processedFallback})`,
-      };
-    }
-    const identMatch = token.match(/^[$@]([a-z0-9-_]+)$/);
+    const identMatch = token.match(/^[$@]([a-z_][a-z0-9-_]*)$/);
     if (identMatch) {
       const name = identMatch[1];
       const processed = `var(--${name})`;
@@ -147,14 +138,28 @@ export function classify(
     return { bucket: Bucket.Value, processed: `${fname}(${argProcessed})` };
   }
 
-  // 6. Auto-calc group
+  // 6. Custom property with fallback syntax: (${prop}, fallback)
+  if (token.startsWith('(') && token.endsWith(')')) {
+    const inner = token.slice(1, -1);
+    const match = inner.match(/^[$@]([a-z_][a-z0-9-_]*)\s*,\s*(.*)$/);
+    if (match) {
+      const [, name, fallback] = match;
+      const processedFallback = recurse(fallback).output;
+      return {
+        bucket: Bucket.Value,
+        processed: `var(--${name}, ${processedFallback})`,
+      };
+    }
+  }
+
+  // 7. Auto-calc group
   if (token[0] === '(' && token[token.length - 1] === ')') {
     const inner = token.slice(1, -1);
     const innerProcessed = recurse(inner).output;
     return { bucket: Bucket.Value, processed: `calc(${innerProcessed})` };
   }
 
-  // 7. Unit number
+  // 8. Unit number
   const um = token.match(RE_UNIT_NUM);
   if (um) {
     const unit = um[1];
@@ -182,27 +187,27 @@ export function classify(
     }
   }
 
-  // 7b. Unknown numeric+unit → treat as literal value (e.g., 1fr)
+  // 8b. Unknown numeric+unit → treat as literal value (e.g., 1fr)
   if (/^[+-]?(?:\d*\.\d+|\d+)[a-z%]+$/.test(token)) {
     return { bucket: Bucket.Value, processed: token };
   }
 
-  // 7c. Plain unit-less numbers should be treated as value tokens so that
+  // 8c. Plain unit-less numbers should be treated as value tokens so that
   // code such as `scrollbar={10}` resolves correctly.
   if (RE_NUMBER.test(token)) {
     return { bucket: Bucket.Value, processed: token };
   }
 
-  // 8. Literal value keywords
+  // 9. Literal value keywords
   if (VALUE_KEYWORDS.has(token)) {
     return { bucket: Bucket.Value, processed: token };
   }
 
-  // 8b. Special keyword colors
+  // 9b. Special keyword colors
   if (token === 'transparent' || token === 'currentcolor') {
     return { bucket: Bucket.Color, processed: token };
   }
 
-  // 9. Fallback modifier
+  // 10. Fallback modifier
   return { bucket: Bucket.Mod, processed: token };
 }

src/tasty/parser/parser.md

@@ -133,7 +133,7 @@ Each `StyleParser` instance maintains its own LRU cache.
 | Order | Rule                                                                                       | Bucket   |
 |-------|--------------------------------------------------------------------------------------------|----------|
 | 1     | URL – `url(` opens `inUrl`; everything to its `)` is a single token.                       | value    |
-| 2     | Custom property – `$ident` → `var(--ident)`; `$(ident,fallback)` → `var(--ident, <processed fallback>)`. Only first `$` per token counts. | value    |
+| 2     | Custom property – `$ident` → `var(--ident)`; `($ident,fallback)` → `var(--ident, <processed fallback>)`. Must start with letter or underscore, followed by letters, numbers, hyphens, or underscores. | value    |
 | 3     | Hash token – `#xxxxxx` if valid hex → `var(--xxxxxx-color, #xxxxxx)`; otherwise `var(--name-color)`. | color    |
 | 4     | Color function – name in list §12.2 followed by `(` (balanced).                            | color    |
 | 5     | User / other function – `ident(` not in color list; parse args recursively, hand off to `funcs[name]` if provided; else rebuild with processed args. | value    |
@@ -152,7 +152,7 @@ Each processed string is inserted into its bucket and into `all` in source order
 |--------------------------|---------------------------------------------------------------------------------------------|
 | Custom unit (`2x`, `.75r`, `-3cr`) | `units[unit]`: • string → `calc(n * replacement)` • function → `calc(handler(numeric))`<br> `0u` stays `calc(0 * …)` (unit info preserved). |
 | Auto-calc parentheses    | Applies anywhere, nesting allowed.<br>Trigger = `(` whose previous non-space char is not `[a-z0-9_-]` and not `l` in `url(`.<br>Algorithm:<br>1. Strip outer parens.<br>2. Recursively parse inner text (so `2r`, `#fff`, nested auto-calc, etc., all expand).<br>3. Wrap in `calc( … )`. |
-| Custom property          | As in §5-2.                                                                                 |
+| Custom property          | `$ident` → `var(--ident)` \| `($ident,fallback)` → `var(--ident, <processed fallback>)` |
 | Hash colors              | As in §5-3.                                                                                 |
 | Color functions          | Arguments are parsed, inner colors re-expanded; function name retained.                     |
 | User functions           | If `funcs[name]` exists → call with parsed arg-`StyleDetails[]`, use return string.<br>Else rebuild `ident(<processed args>)`. |
@@ -233,6 +233,8 @@ rgb rgba hsl hsla hwb lab lch oklab oklch color device-cmyk gray color-mix color
 | `1bw top #purple, 1ow right #dark-05` | Two groups; colors processed; positions as modifiers.                  |
 | Comments `/*…*/2x`             | `calc(2 * var(--gap))`.                                                         |
 | `#+not-hash`                   | Modifier (fails hex test).                                                      |
+| `($custom-gap, 1x)`           | `var(--custom-gap, var(--gap))` (new custom property syntax).                  |
+| `($123invalid, fallback)`     | `calc($123invalid, fallback)` (invalid name → auto-calc).                      |
 | Excess spaces/newlines         | Collapsed in output.                                                            |
 | `+2r, 1e3x`                    | Invalid → modifiers.                                                            |
 | Unicode identifiers            | Modifiers (parser supports only kebab-case ASCII idents).                       |

src/tasty/parser/parser.test.ts

@@ -47,7 +47,7 @@ describe('StyleProcessor', () => {
   });
 
   test('parses custom properties', () => {
-    const result = parser.process('$my-gap $(my-gap, 2x)');
+    const result = parser.process('$my-gap ($my-gap, 2x)');
     expect(result.groups[0].values).toEqual([
       'var(--my-gap)',
       'var(--my-gap, calc(2 * var(--gap)))',
@@ -195,6 +195,174 @@ describe('StyleProcessor', () => {
     ]);
   });
 
+  test('parses new custom property with fallback syntax', () => {
+    const result = parser.process(
+      '($custom-margin, 1x) ($theme-color, #purple)',
+    );
+    expect(result.groups[0].values).toEqual([
+      'var(--custom-margin, var(--gap))',
+      'var(--theme-color, var(--purple-color))',
+    ]);
+  });
+
+  test('parses new custom property syntax in complex expressions', () => {
+    const result = parser.process('(100% - (2 * ($custom-gap, 1x)))');
+    expect(result.groups[0].values).toEqual([
+      'calc(100% - calc(2 * var(--custom-gap, var(--gap))))',
+    ]);
+  });
+
+  test('distinguishes between functions and custom property fallbacks', () => {
+    // Test function with custom property as first argument
+    const result1 = parser.process('sum($my-prop, 2x)');
+    expect(result1.groups[0].values).toEqual([
+      'calc(var(--my-prop) + calc(2 * var(--gap)))',
+    ]);
+
+    // Test custom property with fallback
+    const result2 = parser.process('($my-prop, 2x)');
+    expect(result2.groups[0].values).toEqual([
+      'var(--my-prop, calc(2 * var(--gap)))',
+    ]);
+
+    // Test multiple scenarios in one expression
+    const result3 = parser.process('sum($a, $b) ($fallback-prop, 1x)');
+    expect(result3.groups[0].values).toEqual([
+      'calc(var(--a) + var(--b))',
+      'var(--fallback-prop, var(--gap))',
+    ]);
+
+    // Test edge case: function with custom property fallback as argument
+    const result4 = parser.process('sum(($prop-a, 1x), ($prop-b, 2x))');
+    expect(result4.groups[0].values).toEqual([
+      'calc(var(--prop-a, var(--gap)) + var(--prop-b, calc(2 * var(--gap))))',
+    ]);
+
+    // Test color functions with custom properties
+    const result5 = parser.process('rgb($red, $green, $blue)');
+    expect(result5.groups[0].colors).toEqual([
+      'rgb(var(--red),var(--green),var(--blue))',
+    ]);
+
+    // Test generic function (not user-defined)
+    const result6 = parser.process('min($width, 100%)');
+    expect(result6.groups[0].values).toEqual(['min(var(--width), 100%)']);
+
+    // Test critical edge case: ensure no ambiguity in parsing order
+    // Function name 'sum' vs custom property fallback starting with 'sum'
+    const result7 = parser.process('sum($a, $b) ($sum, fallback)');
+    expect(result7.groups[0].values).toEqual([
+      'calc(var(--a) + var(--b))', // Function call
+      'var(--sum, fallback)', // Custom property fallback (not a function)
+    ]);
+  });
+
+  test('validates CSS custom property names correctly', () => {
+    // Valid names
+    const result1 = parser.process(
+      '$valid-name $_underscore $hyphen-ok $abc123',
+    );
+    expect(result1.groups[0].values).toEqual([
+      'var(--valid-name)',
+      'var(--_underscore)',
+      'var(--hyphen-ok)',
+      'var(--abc123)',
+    ]);
+
+    // Invalid names (should become modifiers)
+    const result2 = parser.process('$123invalid $-123invalid $0test $-');
+    expect(result2.groups[0].mods).toEqual([
+      '$123invalid',
+      '$-123invalid',
+      '$0test',
+      '$-',
+    ]);
+
+    // Edge case: single character names
+    const result3 = parser.process('$a $_ $1');
+    expect(result3.groups[0].values).toEqual(['var(--a)', 'var(--_)']);
+    expect(result3.groups[0].mods).toEqual(['$1']);
+  });
+
+  test('comprehensive collision testing for edge cases', () => {
+    // Test 1: Auto-calc vs custom property fallback - similar patterns
+    const result1 = parser.process('(100% - 2x) ($gap, 1x)');
+    expect(result1.groups[0].values).toEqual([
+      'calc(100% - calc(2 * var(--gap)))', // Auto-calc
+      'var(--gap, var(--gap))', // Custom property fallback
+    ]);
+
+    // Test 2: URL with comma vs custom property fallback
+    // NOTE: URLs merge with following tokens for background layers
+    const result2 = parser.process(
+      'url("img,with,comma.png") ($fallback, auto)',
+    );
+    expect(result2.groups[0].values).toEqual([
+      'url("img,with,comma.png") var(--fallback, auto)', // URL merges with following token
+    ]);
+
+    // Test 3: Quoted strings that look like custom properties
+    const result3 = parser.process(
+      '"($not-a-prop, value)" ($real-prop, fallback)',
+    );
+    expect(result3.groups[0].values).toEqual([
+      '"($not-a-prop, value)"', // Quoted string (not processed)
+      'var(--real-prop, fallback)', // Custom property fallback
+    ]);
+
+    // Test 4: Color function with similar pattern
+    const result4 = parser.process(
+      'rgb($red, $green, $blue) ($color-fallback, #fff)',
+    );
+    expect(result4.groups[0].colors).toEqual([
+      'rgb(var(--red),var(--green),var(--blue))',
+    ]);
+    expect(result4.groups[0].values).toEqual([
+      'var(--color-fallback, var(--fff-color, #fff))',
+    ]);
+
+    // Test 5: Nested parentheses with custom properties
+    const result5 = parser.process('(($outer, 10px) + ($inner, 5px))');
+    expect(result5.groups[0].values).toEqual([
+      'calc(var(--outer, 10px) + var(--inner, 5px))',
+    ]);
+
+    // Test 6: Invalid custom property patterns (should not match)
+    const result6 = parser.process(
+      '(not-a-prop, value) (@invalid-syntax, bad)',
+    );
+    expect(result6.groups[0].values).toEqual([
+      'calc(not-a-prop, value)', // Auto-calc (no $ prefix)
+      'var(--invalid-syntax, bad)', // @ is valid custom property prefix
+    ]);
+
+    // Test 7: Edge case with spaces and special characters
+    // NOTE: Extra spaces cause the pattern to not match, falling back to auto-calc
+    const result7 = parser.process('( $spaced , fallback ) ($compact,nospace)');
+    expect(result7.groups[0].values).toEqual([
+      'calc(var(--spaced), fallback)', // Extra spaces -> auto-calc, not custom property
+      'var(--compact, nospace)', // No spaces are fine
+    ]);
+
+    // Test 8: Edge cases with regex boundaries
+    // Now properly validates CSS custom property names
+    const result8 = parser.process(
+      '($123invalid, fallback) ($valid-name, fallback) ($_underscore, fallback) ($hyphen-ok, fallback)',
+    );
+    expect(result8.groups[0].values).toEqual([
+      'calc($123invalid, fallback)', // Invalid (starts with number) -> auto-calc
+      'var(--valid-name, fallback)', // Valid
+      'var(--_underscore, fallback)', // Valid (underscore allowed)
+      'var(--hyphen-ok, fallback)', // Valid (letter followed by hyphen)
+    ]);
+
+    // Test 9: Comma separation in complex scenarios
+    const result9 = parser.process('($prop1, fallback), ($prop2, fallback)');
+    expect(result9.groups.length).toBe(2); // Should create two groups
+    expect(result9.groups[0].values).toEqual(['var(--prop1, fallback)']);
+    expect(result9.groups[1].values).toEqual(['var(--prop2, fallback)']);
+  });
+
   test('skips invalid functions while parsing (for example missing closing parenthesis)', () => {
     const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});