@tenphi/tasty 2.6.5 → 2.8.0

package/docs/dsl.md

@@ -41,6 +41,20 @@ fill: {
 }
 ```
 
+#### Default State Ordering
+
+Key order sets priority — later keys win and turn off earlier ones via negation. The bare default (`''`) is the lowest-priority state, so it **must be the first key**. If it appears after other states, Tasty moves it to the front and emits a dev warning (`MISPLACED_DEFAULT_STATE`); otherwise it would override every state above it.
+
+```jsx
+// Correct — default first
+color: { '': '#text', hovered: '#accent' }
+
+// Auto-corrected with a warning — '' moved to the front
+color: { hovered: '#accent', '': '#text' }
+```
+
+The bare `''` default still **receives negation** (it is turned off when a higher-priority state matches). For a value that must always apply as a guaranteed floor — even where a query is *unknown* — use the [`_` fallback floor](#_--fallback-floor) instead. The two can coexist: `''` is the negated default, `_` is the always-on floor. If a map contains only `_` and `''` (no other states), the `''` default is redundant — Tasty keeps the `_` value and drops `''` with a `REDUNDANT_DEFAULT_STATE` warning.
+
 ### Sub-element
 
 Element styled using a capitalized key. Identified by `data-element` attribute:
@@ -288,11 +302,21 @@ const SimpleButton = tasty(Button, {
 | `@parent` | Parent/ancestor element states | `@parent(hovered)` |
 | `@own` | Sub-element's own state | `@own(hovered)` |
 | `@starting` | Entry animation | `@starting` |
+| `_` | Fallback floor (always-on, never negated) | `_` |
 | `:is()` | CSS `:is()` structural pseudo-class | `:is(fieldset > label)` |
 | `:has()` | CSS `:has()` relational pseudo-class | `:has(> Icon)` |
 | `:not()` | CSS `:not()` negation (prefer `!:is()`) | `:not(:first-child)` |
 | `:where()` | CSS `:where()` (zero specificity) | `:where(Section)` |
 
+> **Specificity.** All state selectors Tasty generates (modifiers, pseudo-classes,
+> `:is()`/`:not()` groups, and `@root` / `@parent` context) are wrapped in
+> `:where(...)` so they carry **zero specificity**. The only specificity anchors
+> are the doubled component class (`.t0.t0`) and sub-element `[data-element]`
+> attributes. This means overlapping rules (e.g. a `_` fallback floor and the
+> states layered over it) resolve purely by **source order** — Tasty emits
+> lower-priority states first and higher-priority states last so the cascade
+> produces the intended winner.
+
 ### `@media(...)` — Media Queries
 
 Media queries support dimension shorthands and custom unit expansion:
@@ -374,6 +398,91 @@ display: {
 }
 ```
 
+### `_` — Fallback Floor
+
+By default Tasty makes states **mutually exclusive**: a higher-priority state
+turns the lower-priority ones off via negation, so exactly one branch applies.
+This relies on `A | !A` always being true. CSS feature/container queries break
+that assumption: `@supports(...)` and `@(...)` queries can be **unknown** (not
+just true/false), and `not(unknown)` is also unknown — so a negated default
+branch silently never applies. The classic case is `scroll-state`: a browser can
+support `container-type: scroll-state` while a specific `scroll-state(...)` query
+is unknown, leaving *no* branch active.
+
+The `_` fallback floor solves this. Use `_` as a **standalone key** and its value
+**always applies** as a guaranteed floor: it never receives negation, and
+higher-priority states simply layer over it via the cascade.
+
+```jsx
+inset: {
+  _: '0 top',
+  '@supports(container-type: scroll-state) & @(scroll-state(scrolled: block-end))':
+    '-80x top',
+}
+```
+
+```css
+.t0.t0 { inset: 0 ...; }
+@container scroll-state(scrolled: block-end) {
+  @supports (container-type: scroll-state) {
+    .t0.t0 { inset: -80px ...; }
+  }
+}
+```
+
+The floor is emitted as a bare rule (no negated `@supports` / container branches),
+so it always applies. When the override matches it wins because it is emitted
+later and all state selectors share the same specificity (see the note on
+`:where()` below).
+
+Notes:
+
+- `_` is a **standalone key only** — it defines a single map-wide floor and
+  cannot be combined with state logic. Keys like `_ & hovered` or `_ | focused`
+  are ignored with an `INVALID_FALLBACK_KEY` dev warning.
+- `_` can coexist with the bare `''` default when other states exist: `''` is the
+  negated default, `_` is the always-on floor. With only `_` and `''` (no other
+  states) the `''` default is redundant — Tasty keeps the `_` value and drops
+  `''` with a `REDUNDANT_DEFAULT_STATE` warning.
+- `_` is position-independent: it is always placed at the lowest priority
+  regardless of where it appears in the map.
+
+#### `_` vs the `''` default
+
+In simple maps where every other state is a plain modifier (always cleanly
+on/off), `_` and `''` produce the **same visible result** — the base value shows
+whenever no other state wins. They diverge in three situations, and the root
+cause is always the same: **`''` is mutually exclusive (turned off by negation),
+while `_` is always on (layered underneath).**
+
+- **Unknown / invalid branches.** If a higher-priority branch sits behind a query
+  that can be *unknown* (`@supports`, container, `scroll-state`) or uses a
+  selector the browser drops, the negated `''` default disappears along with it
+  (`not(unknown) = unknown`), leaving the property with no rule. The `_` floor
+  survives because it is an unconditional bare rule. This is the case `_` exists
+  for.
+
+- **Empty / "unset" states.** A state can intentionally produce *no* output (an
+  empty value) to leave a property unset while that state is active. With `''`
+  this works — the default is negated away and nothing replaces it, so the
+  property unsets. With `_` the floor can never be turned off, so its value keeps
+  applying and the "unset on this state" intent is lost.
+
+  ```jsx
+  // '' : color unsets while loading.  '_' : color stays #text while loading.
+  color: { '': '#text', loading: '' }
+  ```
+
+- **States with different output shapes.** Because `_` layers additively, when
+  different states emit *different sets* of declarations, the floor's
+  declarations bleed through wherever the winning state does not override the
+  same property — which can produce inconsistent combinations. A `''` default is
+  swapped out cleanly by its mutually-exclusive condition.
+
+Rule of thumb: **use `''` for the normal default** (clean mutual exclusivity,
+supports unsetting), and reach for `_` only when a value must survive an
+*unknown* higher-priority branch.
+
 ### `@root(...)` — Root Element States
 
 Root states generate selectors on the `:root` element. They are useful for theme modes, feature flags, and other page-level conditions:
@@ -565,7 +674,7 @@ CSS cannot transition or animate custom properties unless the browser knows thei
 const AnimatedGradient = tasty({
   styles: {
     '$gradient-angle': '0deg',
-    '#theme': 'okhsl(280 80% 50%)',
+    '#theme': 'okhst(280 80% 50%)',
     background: 'linear-gradient($gradient-angle, #theme, transparent)',
     transition: '$$gradient-angle 0.3s, ##theme 0.3s',
   },

package/docs/pipeline.md

@@ -76,7 +76,7 @@ Output: CSSRule[]
 
 **Simplification** (`simplifyCondition` in `simplify.ts`) is not a separate numbered stage. It runs inside OR expansion, exclusive building, `expandExclusiveOrs` branch cleanup, combination ANDs, merge-by-value ORs, and materialization. Every call is cached by condition unique-id, so the repetition is cheap.
 
-**Post-pass:** After `processStyles` collects rules from every handler, `runPipeline` (`index.ts:188`) filters duplicates using a key of `selector|declarations|atRules|rootPrefix|startingStyle` and then reorders rules so every `@starting-style` rule is emitted **after** all normal rules. This ordering is cascade-critical: `@starting-style` rules share specificity with their normal counterparts, and source order decides which value wins.
+**Post-pass:** After `processStyles` collects rules from every handler, `runPipeline` (`index.ts`) filters duplicates using a key of `selector|declarations|atRules|rootPrefix|startingStyle`, then **stable-sorts rules by their cascade `order` hint (ascending source priority)** so lower-priority rules come first and higher-priority rules win, and finally emits every `@starting-style` rule **after** all normal rules. The `order` hint is the highest source priority among the entries that produced each rule (threaded `ComputedRule → CSSRule`). This ordering is cascade-critical because Stage 7 equalizes specificity with `:where()`: once every state selector carries zero specificity, source order alone decides which of two overlapping rules wins — most importantly the `_` fallback floor (low order, emitted first) versus the states layered over it, and `@starting-style` versus its normal counterpart. Mutually-exclusive rules are unaffected by ordering (they never both match), so reordering them is safe.
 
 ---
 
@@ -120,6 +120,8 @@ Removing don't-care dimensions before parsing prevents combinatorial blowup in l
 
 Converts each state key in a style value map (like `'hovered & !disabled'`, `'@media(w < 768px)'`) into `ConditionNode` trees. `parseStyleEntries` walks the object keys in source order and assigns priorities; `parseStateKey` parses a single key string.
 
+`parseStyleEntries` also handles the bare `''` default and the standalone `_` fallback floor before the priority order is finalized. The bare `''` default only behaves correctly as the lowest-priority state, so a misplaced one is moved to the front (`MISPLACED_DEFAULT_STATE` warning). The `_` key is pulled out as a separate floor entry (`floor: true`, `TrueCondition`) and always assigned the lowest priority. If a map defines only `_` and a bare `''` (no other states), the `''` default is redundant — it is dropped in favor of the `_` value (`REDUNDANT_DEFAULT_STATE` warning). A `_` combined with state logic (`_ & hovered`, `_ | x`) is ignored (`INVALID_FALLBACK_KEY` warning).
+
 ### How It Works
 
 1. **Tokenization**: The state key is split into tokens using a regex pattern that recognizes:
@@ -293,6 +295,32 @@ C: C & !A & !B          (applies only when neither A nor B)
 
 Each exclusive condition is passed through `simplifyCondition`. Entries that simplify to `FALSE` (impossible) are filtered out. The default state (`''` → `TrueCondition`) is not added to the “prior” list for negation (see `buildExclusiveConditions`).
 
+### `_` fallback floor
+
+An entry flagged `floor: true` (from the standalone `_` key) is the one
+exception to the negation cascade above. `buildExclusiveConditions` **pulls the
+floor entries out** before the negation pass, builds the remaining entries with a
+plain unconditional negation loop, then re-appends each floor with its own
+(`TRUE`) condition as the exclusive condition. So the floor **always applies**,
+never receives `!prior`, and never negates lower-priority entries. Because its
+condition is `TRUE`, Stage 1 `mergeEntriesByValue` already leaves it untouched
+(same guard as the bare `''` default), so no floor-specific merge handling is
+needed.
+
+This exists to fix the *unknown-query hole*: CSS three-valued logic makes
+`not(unknown) = unknown`, so a negated `@supports(...)` / container-query default
+branch silently never applies. A `_` floor sidesteps negation entirely and lets
+the positive override layer on top via the cascade (see Stage 7's `:where()`
+equalization and the ascending-priority post-pass).
+
+Because the floor is **additive** (always emitted, never negated) rather than
+mutually exclusive, it differs observably from the `''` default in two ways
+beyond the unknown-query fix: an "empty" higher-priority state (one that emits no
+declarations) cannot unset the property — the floor still applies — and when
+states emit different declaration sets, the floor's declarations bleed through
+wherever a winning state does not override the same property. The `''` default,
+being negated, swaps out cleanly. See the DSL guide's "`_` vs the `''` default".
+
 ### Why
 
 This eliminates CSS specificity wars. Instead of relying on cascade order, each CSS rule matches in exactly one scenario. Benefits:
@@ -477,7 +505,15 @@ Converts condition trees into actual CSS selectors and at-rules.
 
 3. **Contradiction detection**: During variant merging, impossible combinations are dropped (e.g. conflicting media, root, or modifier negations).
 
-4. **`materializeComputedRule`**: Groups variants by sorted at-rules plus root-prefix key; within each group, `mergeVariantsIntoSelectorGroups` merges variants that differ only in flat modifier/pseudo parts; builds selector strings and emits one or more `CSSRule` objects.
+4. **`materializeComputedRule`**: Groups variants by sorted at-rules plus root-prefix key; within each group, `mergeVariantsIntoSelectorGroups` merges variants that differ only in flat modifier/pseudo parts; builds selector strings and emits one or more `CSSRule` objects. The rule's `order` hint (cascade priority) is propagated here for the post-pass sort.
+
+5. **`:where()` specificity equalization**: Every stateful part of the selector is wrapped in `:where(...)` so it contributes **zero specificity**:
+   - the flat root modifiers + pseudos and the root element's `:is()`/`:not()` groups are combined into one `:where(...)` (`buildSelectorFromVariant`);
+   - the sub-element (`@own`) groups are wrapped in a **separate** `:where(...)` so the sub-element's structural `[data-element="X"]` specificity is preserved while its states are zeroed;
+   - `@parent` ancestors (`parentGroupsToCSS`) become `:where(... *)` / `:where(:not(... *))`;
+   - the `@root` context prefix (`rootGroupsToCSS`) becomes `:where(:root...)` (zeroing the `:root` pseudo too).
+
+   The only specificity anchors that remain are the doubled component class (`.tXX.tXX`, added by the injector) and sub-element `[data-element]` attributes. Because Stage 2b already makes ordinary rules mutually exclusive, zeroing specificity never changes *which* rule matches — it only makes additive layering (`_` fallback floor, `@starting-style`) resolve deterministically by source order (see the post-pass). Canonical sorting/dedup/subsumption still run first; `:where()` is only the final wrapper, and both output paths (injector and direct-selector / SSR) consume the same wrapped fragments.
 
 ### Why
 
@@ -498,6 +534,8 @@ interface CSSRule {
   declarations: string; // CSS declarations (e.g. 'color: red;')
   atRules?: string[]; // Wrapping at-rules
   rootPrefix?: string; // Root state prefix
+  startingStyle?: boolean; // Wrap declarations in @starting-style
+  order?: number; // Internal cascade order hint (ascending source priority); stripped before injection
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/tasty",
-  "version": "2.6.5",
+  "version": "2.8.0",
   "description": "A design-system-integrated styling system and DSL for concise, state-aware UI styling",
   "type": "module",
   "main": "./dist/index.js",
@@ -165,13 +165,13 @@
       "name": "main (import *)",
       "path": "dist/index.js",
       "import": "*",
-      "limit": "52 kB"
+      "limit": "53 kB"
     },
     {
       "name": "core (import *)",
       "path": "dist/core/index.js",
       "import": "*",
-      "limit": "49.5 kB"
+      "limit": "50.5 kB"
     },
     {
       "name": "static",
@@ -188,7 +188,7 @@
         "path",
         "crypto"
       ],
-      "limit": "31 kB"
+      "limit": "32 kB"
     },
     {
       "name": "babel-plugin",
@@ -199,7 +199,7 @@
         "path",
         "crypto"
       ],
-      "limit": "45.65 kB"
+      "limit": "46.65 kB"
     }
   ],
   "scripts": {