@tenphi/tasty 0.0.0-snapshot.37c3068 → 0.0.0-snapshot.61865f6

package/README.md

@@ -24,9 +24,10 @@ On top of that foundation, Tasty gives you a concise, CSS-like DSL with design t
 ## Why Tasty
 
 - **Deterministic at any scale** — Exclusive selector generation eliminates the entire class of cascade/specificity bugs. Every state combination resolves to exactly one CSS rule per property. Refactor freely.
+- **AI-friendly by design** — Style definitions are declarative, self-contained, and structurally consistent. AI tools can read, understand, and refactor even advanced state bindings as confidently as a human — because there's no hidden cascade logic or implicit ordering to second-guess.
 - **DSL that feels like CSS** — Property names you already know (`padding`, `color`, `display`) with syntax sugar that removes boilerplate. Learn the DSL in minutes, not days.
 - **Design-system native** — Color tokens (`#primary`), spacing units (`2x`), typography presets (`h1`, `t2`), border radius (`1r`), and recipes are first-class primitives, not afterthoughts.
-- **Full modern CSS coverage** — Media queries, container queries, `@supports`, `:has()`, `@starting-style`, `@property`, keyframes, boolean state logic with `&`, `|`, `!` operators. If CSS can do it, Tasty can express it — concisely.
+- **Near-complete modern CSS coverage** — Media queries, container queries, `@supports`, `:has()`, `@starting-style`, `@property`, `@keyframes`, etc. Some features that don't fit Tasty's component model (such as `@layer` and `!important`) are intentionally omitted, but real-world use cases are covered almost completely.
 - **Runtime or zero-runtime — your call** — Use `tasty()` for dynamic React components with runtime injection, or `tastyStatic()` with the Babel plugin for zero-runtime CSS extraction. Same DSL, same tokens, same output.
 - **Only generate what is used** — In runtime mode, Tasty injects CSS on demand for mounted components/variants, so your app avoids shipping style rules for UI states that are never rendered.
 - **Runtime performance that holds at scale** — The runtime path is tested against enterprise-scale applications and tuned with multi-level caching, chunk-level style reuse, style garbage collection, and a dedicated injector.
@@ -133,9 +134,13 @@ Predefined states turn complex selector logic into single tokens. Use `@mobile`
 
 This is the core idea that makes everything else possible.
 
-Traditional CSS uses the cascade to resolve conflicts: when multiple selectors match, the one with the highest specificity wins, or — if specificity is equal — the last one in source order wins. This makes styles inherently fragile. Reordering imports, adding a new media query, or composing components from different libraries can silently break styling.
+Traditional CSS has two structural problems.
 
-Tasty takes a fundamentally different approach: **every state mapping compiles into selectors that are guaranteed to never overlap.**
+First, the **cascade** resolves conflicts by specificity and source order: when multiple selectors match, the one with the highest specificity wins, or — if specificity is equal — the last one in source order wins. That makes styles inherently fragile. Reordering imports, adding a media query, or composing components from different libraries can silently break styling.
+
+Second, **authoring selectors that capture real-world state logic is fundamentally hard.** A single state like "dark mode" may depend on a root attribute, an OS preference, or both — each branch needing its own selector, proper negation of competing branches, and correct `@media` nesting. The example below shows the CSS you'd write by hand for just *one* property with *one* state. Scale that across dozens of properties, then add breakpoints and container queries, and the selector logic quickly becomes unmanageable.
+
+Tasty solves both problems at once: **every state mapping compiles into mutually exclusive selectors.**
 
 ```tsx
 const Text = tasty({
@@ -180,7 +185,9 @@ If `@dark` expands to `@root(schema=dark) | (!@root(schema) & @media(prefers-col
 }
 ```
 
-Every rule is guarded by the negation of all higher-priority rules. No two rules can ever match simultaneously. No specificity arithmetic. No source-order dependence. Components compose and extend without ever colliding.
+Every rule is guarded by the negation of higher-priority rules. No two rules can match at the same time. No specificity arithmetic. No source-order dependence. Components compose and extend without collisions.
+
+By absorbing selector complexity, Tasty makes advanced CSS patterns practical again — nested container queries, multi-condition `@supports` gates, and combined root-state/media branches. You stay in pure CSS instead of relying on JavaScript workarounds, so the browser can optimize layout, painting, and transitions natively. Tasty doesn't limit CSS; it unlocks its full potential by removing the complexity that held teams back.
 
 ## Capabilities
 
@@ -412,11 +419,12 @@ If you choose the runtime approach, performance is usually a non-issue in practi
 
 | Import | Description | Platform |
 |--------|-------------|----------|
-| `@tenphi/tasty` | Runtime style engine | Browser |
-| `@tenphi/tasty/static` | Zero-runtime static styles | Browser |
-| `@tenphi/tasty/babel-plugin` | Babel plugin for CSS extraction | Node |
+| `@tenphi/tasty` | Runtime style engine (`tasty`, hooks, `configure`) | Browser |
+| `@tenphi/tasty/static` | Zero-runtime static styles (`tastyStatic`) | Browser |
+| `@tenphi/tasty/core` | Lower-level internals (config, parser, pipeline, injector, style handlers) for tooling and advanced use | Browser / Node |
+| `@tenphi/tasty/babel-plugin` | Babel plugin for zero-runtime CSS extraction | Node |
 | `@tenphi/tasty/zero` | Programmatic extraction API | Node |
-| `@tenphi/tasty/next` | Next.js integration | Node |
+| `@tenphi/tasty/next` | Next.js integration wrapper | Node |
 
 ## Ecosystem
 
@@ -455,14 +463,21 @@ const tokens = theme.tasty(); // Ready-to-use Tasty tokens
 
 Syntax highlighting for Tasty styles in TypeScript, TSX, JavaScript, and JSX. Highlights color tokens, custom units, state keys, presets, and style properties inside `tasty()`, `tastyStatic()`, and related APIs.
 
+<p align="center">
+  <img src="assets/tasty-vscode-highlight.png" width="512" alt="Tasty VS Code syntax highlighting example">
+</p>
+
 ### [Cube UI Kit](https://github.com/cube-js/cube-ui-kit)
 
 Open-source React UI kit built on Tasty + React Aria. 100+ production components proving Tasty works at design-system scale. A reference implementation and a ready-to-use component library.
 
 ## Documentation
 
-- **[Runtime API (tasty)](docs/tasty.md)** — Full runtime styling documentation: component creation, state mappings, sub-elements, variants, hooks, configuration, and style property reference
+- **[Runtime API (tasty)](docs/tasty.md)** — Full runtime styling documentation: component creation, state mappings, sub-elements, variants, hooks, and configuration
+- **[Style Properties](docs/styles.md)** — Complete reference for all enhanced style properties: syntax, values, modifiers, and recommendations
 - **[Zero Runtime (tastyStatic)](docs/tasty-static.md)** — Build-time static styling: Babel plugin setup, Next.js integration, and static style patterns
+- **[Style Injector](docs/injector.md)** — Internal CSS injection engine: `inject()`, `injectGlobal()`, `injectRawCSS()`, `keyframes()`, deduplication, reference counting, cleanup, SSR support, and Shadow DOM
+- **[Debug Utilities](docs/debug.md)** — Runtime CSS inspection via `tastyDebug`: CSS extraction, element inspection, cache metrics, chunk breakdown, and performance monitoring
 
 ## License
 

package/dist/pipeline/materialize.js

@@ -1,4 +1,5 @@
 import { Lru } from "../parser/lru.js";
+import { not } from "./conditions.js";
 
 //#region src/pipeline/materialize.ts
 /**
@@ -68,27 +69,43 @@ function stateToCSS(state) {
 		case "root": return innerConditionToVariants(state.innerCondition, state.negated ?? false, "rootConditions");
 		case "parent": return parentConditionToVariants(state.innerCondition, state.negated ?? false, state.direct);
 		case "own": return innerConditionToVariants(state.innerCondition, state.negated ?? false, "ownConditions");
-		default: {
-			const variant = emptyVariant();
-			switch (state.type) {
-				case "modifier":
-					variant.modifierConditions.push(modifierToParsed(state));
-					break;
-				case "pseudo":
-					variant.pseudoConditions.push(pseudoToParsed(state));
-					break;
-				case "container":
-					variant.containerConditions.push(containerToParsed(state));
-					break;
-				case "supports":
-					variant.supportsConditions.push(supportsToParsed(state));
-					break;
-				case "starting":
-					variant.startingStyle = !state.negated;
-					break;
-			}
+		case "modifier": {
+			const v = emptyVariant();
+			v.modifierConditions.push(modifierToParsed(state));
 			return {
-				variants: [variant],
+				variants: [v],
+				isImpossible: false
+			};
+		}
+		case "pseudo": {
+			const v = emptyVariant();
+			v.pseudoConditions.push(pseudoToParsed(state));
+			return {
+				variants: [v],
+				isImpossible: false
+			};
+		}
+		case "container": {
+			const v = emptyVariant();
+			v.containerConditions.push(containerToParsed(state));
+			return {
+				variants: [v],
+				isImpossible: false
+			};
+		}
+		case "supports": {
+			const v = emptyVariant();
+			v.supportsConditions.push(supportsToParsed(state));
+			return {
+				variants: [v],
+				isImpossible: false
+			};
+		}
+		case "starting": {
+			const v = emptyVariant();
+			v.startingStyle = !state.negated;
+			return {
+				variants: [v],
 				isImpossible: false
 			};
 		}
@@ -227,35 +244,46 @@ function supportsToParsed(state) {
 	};
 }
 /**
+* Collect all modifier and pseudo conditions from a variant as a flat array.
+*/
+function collectSelectorConditions(variant) {
+	return [...variant.modifierConditions, ...variant.pseudoConditions];
+}
+/**
 * Convert an inner condition tree into SelectorVariants.
 * Each inner OR branch becomes a separate variant, preserving disjunction.
 * Shared by @root() and @own().
 */
 function innerConditionToVariants(innerCondition, negated, target) {
-	const innerCSS = conditionToCSS(innerCondition);
+	const innerCSS = conditionToCSS(negated ? not(innerCondition) : innerCondition);
 	if (innerCSS.isImpossible || innerCSS.variants.length === 0) return {
 		variants: [],
 		isImpossible: true
 	};
-	return {
-		variants: innerCSS.variants.map((innerVariant) => {
+	const variants = [];
+	for (const innerVariant of innerCSS.variants) {
+		const conditions = collectSelectorConditions(innerVariant);
+		if (conditions.length > 0) {
 			const v = emptyVariant();
-			for (const mod of innerVariant.modifierConditions) v[target].push({
-				...mod,
-				negated: negated ? !mod.negated : mod.negated
-			});
-			for (const pseudo of innerVariant.pseudoConditions) v[target].push({
-				...pseudo,
-				negated: negated ? !pseudo.negated : pseudo.negated
-			});
-			return v;
-		}),
+			v[target].push(...conditions);
+			variants.push(v);
+		}
+	}
+	if (variants.length === 0) return {
+		variants: [emptyVariant()],
+		isImpossible: false
+	};
+	return {
+		variants,
 		isImpossible: false
 	};
 }
 /**
 * Convert a @parent() inner condition into SelectorVariants with ParentGroups.
-* Each inner OR branch becomes a separate variant, each containing one ParentGroup.
+*
+* Positive: each inner OR branch becomes a separate variant with one :is() group.
+* Negated: !(A | B) = !A & !B — all branches become :not() groups collected
+* into a single variant so they produce :not([a] *):not([b] *) on one element.
 */
 function parentConditionToVariants(innerCondition, negated, direct) {
 	const innerCSS = conditionToCSS(innerCondition);
@@ -263,19 +291,44 @@ function parentConditionToVariants(innerCondition, negated, direct) {
 		variants: [],
 		isImpossible: true
 	};
-	return {
-		variants: innerCSS.variants.map((innerVariant) => {
+	if (negated) {
+		const v = emptyVariant();
+		for (const innerVariant of innerCSS.variants) {
+			const conditions = collectSelectorConditions(innerVariant);
+			if (conditions.length > 0) v.parentGroups.push({
+				conditions,
+				direct,
+				negated: true
+			});
+		}
+		if (v.parentGroups.length === 0) return {
+			variants: [emptyVariant()],
+			isImpossible: false
+		};
+		return {
+			variants: [v],
+			isImpossible: false
+		};
+	}
+	const variants = [];
+	for (const innerVariant of innerCSS.variants) {
+		const conditions = collectSelectorConditions(innerVariant);
+		if (conditions.length > 0) {
 			const v = emptyVariant();
-			const group = {
-				conditions: [],
+			v.parentGroups.push({
+				conditions,
 				direct,
-				negated
-			};
-			for (const mod of innerVariant.modifierConditions) group.conditions.push(mod);
-			for (const pseudo of innerVariant.pseudoConditions) group.conditions.push(pseudo);
-			v.parentGroups.push(group);
-			return v;
-		}),
+				negated: false
+			});
+			variants.push(v);
+		}
+	}
+	if (variants.length === 0) return {
+		variants: [emptyVariant()],
+		isImpossible: false
+	};
+	return {
+		variants,
 		isImpossible: false
 	};
 }
@@ -330,36 +383,6 @@ function getSelectorConditionKey(cond) {
 	return "attribute" in cond ? `mod:${getModifierKey(cond)}` : `pseudo:${getPseudoKey(cond)}`;
 }
 /**
-* Deduplicate modifier conditions
-*/
-function dedupeModifierConditions(conditions) {
-	const seen = /* @__PURE__ */ new Set();
-	const result = [];
-	for (const c of conditions) {
-		const key = getModifierKey(c);
-		if (!seen.has(key)) {
-			seen.add(key);
-			result.push(c);
-		}
-	}
-	return result;
-}
-/**
-* Deduplicate pseudo conditions
-*/
-function dedupePseudoConditions(conditions) {
-	const seen = /* @__PURE__ */ new Set();
-	const result = [];
-	for (const c of conditions) {
-		const key = getPseudoKey(c);
-		if (!seen.has(key)) {
-			seen.add(key);
-			result.push(c);
-		}
-	}
-	return result;
-}
-/**
 * Deduplicate selector conditions (modifiers or pseudos).
 * Shared by root, parent, and own conditions.
 */
@@ -374,15 +397,16 @@ function dedupeSelectorConditions(conditions) {
 		}
 	}
 	const negatedBooleanAttrs = /* @__PURE__ */ new Set();
-	const positiveValuesByAttr = /* @__PURE__ */ new Map();
+	const positiveExactValuesByAttr = /* @__PURE__ */ new Map();
 	for (const c of result) {
 		if (!("attribute" in c)) continue;
 		if (c.negated && c.value === void 0) negatedBooleanAttrs.add(c.attribute);
-		if (!c.negated && c.value !== void 0) {
-			let values = positiveValuesByAttr.get(c.attribute);
+		const op = c.operator ?? "=";
+		if (!c.negated && c.value !== void 0 && op === "=") {
+			let values = positiveExactValuesByAttr.get(c.attribute);
 			if (!values) {
 				values = /* @__PURE__ */ new Set();
-				positiveValuesByAttr.set(c.attribute, values);
+				positiveExactValuesByAttr.set(c.attribute, values);
 			}
 			values.add(c.value);
 		}
@@ -390,7 +414,8 @@ function dedupeSelectorConditions(conditions) {
 	result = result.filter((c) => {
 		if (!("attribute" in c) || !c.negated || c.value === void 0) return true;
 		if (negatedBooleanAttrs.has(c.attribute)) return false;
-		const positiveValues = positiveValuesByAttr.get(c.attribute);
+		if ((c.operator ?? "=") !== "=") return true;
+		const positiveValues = positiveExactValuesByAttr.get(c.attribute);
 		if (positiveValues !== void 0 && positiveValues.size === 1 && !positiveValues.has(c.value)) return false;
 		return true;
 	});
@@ -433,6 +458,21 @@ function hasSelectorConditionContradiction(conditions) {
 	return hasModifierContradiction(modifiers) || hasPseudoContradiction(pseudos);
 }
 /**
+* Check for parent group contradiction: same target (direct + conditions)
+* with opposite negation. E.g. :not([data-hovered] *) and :is([data-hovered] *)
+* in the same variant is impossible.
+*/
+function hasParentGroupContradiction(groups) {
+	const byBaseKey = /* @__PURE__ */ new Map();
+	for (const g of groups) {
+		const baseKey = `${g.direct ? ">" : ""}(${g.conditions.map(getSelectorConditionKey).sort().join(",")})`;
+		const existing = byBaseKey.get(baseKey);
+		if (existing !== void 0 && existing !== !g.negated) return true;
+		byBaseKey.set(baseKey, !g.negated);
+	}
+	return false;
+}
+/**
 * Merge two selector variants (AND operation)
 * Deduplicates conditions and checks for contradictions
 */
@@ -441,11 +481,11 @@ function mergeVariants(a, b) {
 	if (hasMediaContradiction(mergedMedia)) return null;
 	const mergedRoots = dedupeSelectorConditions([...a.rootConditions, ...b.rootConditions]);
 	if (hasSelectorConditionContradiction(mergedRoots)) return null;
-	const mergedModifiers = dedupeModifierConditions([...a.modifierConditions, ...b.modifierConditions]);
-	if (hasModifierContradiction(mergedModifiers)) return null;
-	const mergedPseudos = dedupePseudoConditions([...a.pseudoConditions, ...b.pseudoConditions]);
-	if (hasPseudoContradiction(mergedPseudos)) return null;
+	const mergedModifiers = dedupeSelectorConditions([...a.modifierConditions, ...b.modifierConditions]);
+	const mergedPseudos = dedupeSelectorConditions([...a.pseudoConditions, ...b.pseudoConditions]);
+	if (hasSelectorConditionContradiction([...mergedModifiers, ...mergedPseudos])) return null;
 	const mergedParentGroups = [...a.parentGroups, ...b.parentGroups];
+	if (hasParentGroupContradiction(mergedParentGroups)) return null;
 	const mergedOwn = dedupeSelectorConditions([...a.ownConditions, ...b.ownConditions]);
 	if (hasSelectorConditionContradiction(mergedOwn)) return null;
 	const mergedContainers = dedupeContainerConditions([...a.containerConditions, ...b.containerConditions]);
@@ -620,7 +660,7 @@ function getVariantKey(v) {
 		containerKey,
 		v.supportsConditions.map((c) => `${c.subtype}:${c.negated ? "!" : ""}${c.condition}`).sort().join("|"),
 		v.rootConditions.map(getSelectorConditionKey).sort().join("|"),
-		v.parentGroups.map((g) => `${g.direct ? ">" : ""}(${g.conditions.map(getSelectorConditionKey).sort().join(",")})`).sort().join("|"),
+		v.parentGroups.map(getParentGroupKey).sort().join("|"),
 		v.startingStyle ? "1" : "0"
 	].join("###");
 }