chore:updated AST Parser, added tests

Austin1serb · Austin1serb · commit a535aaa0d96d · 2025-07-11T00:03:34.000-07:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -7,14 +7,14 @@ Use these tips when working with the codebase or generating examples.
 
 ## How React Zero-UI works
 
-1. `useUI()` writes to `document.body.dataset` using keys you specify.
+1. `useUI()` writes to `document.body.dataset` using keys you specify. 
 
 ```tsx
 const [staleValue, setValue] = useUI<'open' | 'closed'>('sidebar', 'closed');
 ```
 
 - `key` → becomes `data-{key}` on `<body>` (e.g., `sidebar` → `data-sidebar="closed"`).
-- `defaultValue` → used for SSR to avoid FOUC.
+- `defaultValue` → used for SSR to avoid FOUC. Added to the body as a data-attribute. at build time.
 - The first value is **always stale** — do NOT rely on it for reactive updates.
 
 2. Consumption is done strictly with tailwind variant classNames:
@@ -56,10 +56,22 @@ const [, setTheme] = useUI<'light' | 'dark'>('theme', 'light');
 <div className="theme-light:bg-white theme-dark:bg-black" />
 ```
 
+## Example: Scoping Styles
+
+```tsx
+const [, setTheme] = useUI<'light' | 'dark'>('theme', 'light');
+// Simply pass a ref to the element
+<div ref={setTheme.ref} className="theme-light:bg-white theme-dark:bg-black" />
+
+```
+
+Now the data-* will flip on that element, and the styles will be scoped to that element, or its children.
+
 ---
 
 ## What NOT to do
 
+- ❌ Do not pass anything to the StateKey or InitialValue that is not a string or does not resolve to a string.
 - ❌ Don't use `useUI()` for business logic or data fetching
 - ❌ Don't rely on the first tuple value for reactivity
 - ❌ Don't use camelCase keys (will break variant generation)
diff --git a/packages/core/src/postcss/ast-parsing.cts b/packages/core/src/postcss/ast-parsing.cts
@@ -186,7 +186,7 @@ export function extractVariants(filePath: string): VariantData[] {
 
 		// console.log(`[CACHE] MISS: ${filePath} (parsing...)`);
 		// Parse the file
-		const ast = parse(source, { sourceType: 'module', plugins: ['jsx', 'typescript', 'decorators-legacy'], sourceFilename: filePath });
+		const ast = parse(source, { sourceType: 'module', plugins: ['jsx', 'typescript', 'decorators-legacy', 'topLevelAwait'], sourceFilename: filePath });
 
 		// Collect useUI setters
 		const setters = collectUseUISetters(ast, source);
@@ -209,7 +209,7 @@ export function extractVariants(filePath: string): VariantData[] {
 		}
 
 		// Parse and cache...
-		const ast = parse(source, { sourceType: 'module', plugins: ['jsx', 'typescript', 'decorators-legacy'], sourceFilename: filePath });
+		const ast = parse(source, { sourceType: 'module', plugins: ['jsx', 'typescript', 'decorators-legacy', 'topLevelAwait'], sourceFilename: filePath });
 		const setters = collectUseUISetters(ast, source);
 		if (!setters.length) return [];
 
diff --git a/packages/core/src/postcss/index.cts b/packages/core/src/postcss/index.cts
@@ -6,6 +6,8 @@ import { processVariants, buildCss, generateAttributesFile, isZeroUiInitialized
 import { runZeroUiInit } from '../cli/postInstall.cjs';
 import type { Result, Root } from 'postcss';
 
+const DEV = process.env.NODE_ENV !== 'production';
+
 const plugin = (): { postcssPlugin: string; Once: (root: Root, { result }: { result: Result }) => Promise<void> } => {
 	return {
 		postcssPlugin: 'postcss-react-zero-ui',
@@ -36,9 +38,25 @@ const plugin = (): { postcssPlugin: string; Once: (root: Root, { result }: { res
 
 				// Generate body attributes file and TypeScript definitions
 				await generateAttributesFile(finalVariants, initialValues);
-			} catch (error: unknown) {
-				const errorMessage = error instanceof Error ? error.message : String(error);
-				throw new Error(`[Zero-UI] PostCSS plugin error: ${errorMessage}`);
+			} catch (err: unknown) {
+				const msg = err instanceof Error ? err.message : String(err);
+
+				// ⏩ 1. Always surface the real stack in the dev console
+				if (DEV) console.error(err);
+
+				// ⏩ 2. Warn (dev) or throw (prod)
+				if (DEV) {
+					result.warn(`[Zero-UI] ${msg}`, { plugin: 'postcss-react-zero-ui' });
+				} else {
+					throw new Error(`[Zero-UI] PostCSS plugin error: ${msg}`);
+				}
+				const e = err as { loc?: { file?: string } } & Error;
+				// ⏩ 3. Keep the file hot-watched so a save un-bricks the build
+				if (e?.loc?.file) {
+					result.messages.push({ type: 'dependency', plugin: 'postcss-react-zero-ui', file: e.loc.file, parent: result.opts.from });
+				}
+
+				return; // bail out without killing dev-server
 			}
 		},
 	};
