feat(core): scoped styles, new variant parser & string-only UI keys (BREAKING CHANGE)

[Austin1serb]

Summary

@react-zero-ui/core v0.2.0

This PR lands the first scoped-style system and overhauls the parser stack.
Code Shipped to production now down to 258 bytes.

• Element-scoped variants
  Call the setter with a ref and the library injects a data-ui attribute on that element only; every descendant can opt-in with Tailwind-style classes.

  import { useUI } from '@react-zero-ui/core';
  
  // 1. Consume UI state – string keys only
  const [, setTheme] = useUI('theme', 'light'); // <== kebab-case strings
  
  // 2. Attach the provided ref
  return (
    <div ref={setTheme.ref} className="profile-card theme-light:bg-white theme-dark:bg-black">
      ...
      {/* Somewhere deeper */}
      <button onClick={() => setTheme('dark')}>Dark mode</button>
    </div>
  );

and the data-* will flip on that element, all styles applied in that subtree will be scoped

• String-only UI variablts (breaking)
  stateKey and initial value must now be kebab-case strings.
  Deterministic CSS, zero coercion surprises.

• Tailwind-style variant discovery

  • Babel first resolves every stateKey (string literal or locally-bound const).

  • It then scans the repo (like tailwind) for class names matching the pattern

    stateKey-value:utility
    

    e.g. theme-dark:bg-black, accordion-open:max-h-0.

  • Every new value encountered is registered as a Tailwind custom variant;

  • quick-glob + quick-lru → 4× faster parse on a 10 k-LOC repo.

• Static CSS generator
  Emits .profile-card\:theme-dark:bg-black via a PostCSS 8 plugin—no runtime cost.

• Partial TypeScript migration
  Core is now .ts; Babel helpers remain .cts until Phase 2.

---

Type of Change

• ✨ New feature
• 🐛 Bug fix
• 🛠 Refactor
• 🧪 Test improvement
• 📝 Docs update
• ⚙️ CI/tooling

---

Breaking Changes

What	Old behaviour	New rule	Migration pain
stateKey & initial value types	Any serialisable value	String only, kebab-case, no spaces
Variable resolution	Imported constants allowed	Must resolve inside the same file. Re-assign imported constants locally.	Medium

BREAKING CHANGE: stateKey and initial value must be kebab-case strings. Non-string values or imported constants without local reassignment will fail lint + build.

---

Migration Guide

- import { DARK } from './constants'
- const [theme, setTheme] = useUI(DARK)          // ❌ now invalid

+ import { DARK } from './constants'
+ const LOCAL_DARK = DARK                        // ✅ local alias
+ const [theme, setTheme] = useUI(LOCAL_DARK)

Attach ref={setTheme.ref} to isolate the scope if needed.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
react-zero-ui	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 8, 2025 11:01pm