@tenphi/tasty 3.0.2 → 3.2.0

package/docs/dsl.md

@@ -111,7 +111,7 @@ const List = tasty({
 Named color prefixed with `#` that maps to CSS custom properties. Supports opacity with `.N` suffix:
 
 ```jsx
-fill: '#purple.5'  // → var(--purple-color) with 50% opacity
+fill: '#purple.5'  // → oklch(from var(--purple-color) l c h / .5)
 ```
 
 ### Modifier
@@ -133,11 +133,108 @@ Modifiers can also be exposed as top-level component props via `modProps` — se
 color: '#purple',           // Full opacity
 color: '#purple.5',         // 50% opacity
 color: '#purple.05',        // 5% opacity
+color: '#purple.$fade',     // Opacity from a custom property
 fill: '#current',           // → currentcolor
-fill: '#current.5',         // → color-mix(in oklab, currentcolor 50%, transparent)
 color: '(#primary, #secondary)',  // Fallback syntax
 ```
 
+The suffix sets the alpha on the token's color with CSS relative color syntax:
+
+```jsx
+fill: '#purple.5';
+// → oklch(from var(--purple-color) l c h / .5)
+```
+
+The channels are copied over and the alpha slot is written, which asks nothing of
+the color beyond *being* a color. That means the suffix works on every one of
+these:
+
+- a token holding a `color-mix()`, a `light-dark()`, or a `color()` in a space
+  Tasty cannot convert — none of which have channels to decompose
+- `#current`, which resolves to `currentcolor`
+- a `--name-color` variable declared in your own CSS, with no Tasty token
+  definition and no companion variable behind it
+
+Two properties follow from writing the alpha slot rather than compositing:
+
+- **Alpha is replaced, not multiplied.** A token holding `rgb(255 0 0 / .8)`
+  faded to `.5` is alpha `.5`, not `.4`.
+- **The alpha may be a number or a percentage.** `#purple.$fade` emits
+  `/ var(--fade)` unchanged, so it works whether `$fade` holds `.5` or `50%` —
+  which is what `--*-opacity` properties are registered to accept.
+
+### `#current` composes instead
+
+`#current` is the one exception, and the difference is deliberate. A token *names*
+a color, so fading it sets its alpha. `currentcolor` is the color an element
+**inherits**, which an ancestor may already have faded — `#current.4` means "40%
+of what reaches me":
+
+```jsx
+fill: '#current.4';
+// → color-mix(in oklab, currentcolor 40%, transparent)
+```
+
+So a `#current` fade nested inside another one composes: a label at `#current.4`
+with a fill of `#current.18` under it lands at `.072`. Color ramps built on
+`#current` depend on that — replacing would double the opacity of every nested
+step. Because a `color-mix()` percentage cannot be a `<number>`, an opacity
+custom property used as `#current.$fade` must hold a unitless number; a token
+accepts either form.
+
+The space is always `oklch`, whatever [`colorSpace`](configuration.md#color-space)
+is set to: it is unbounded, so a wide-gamut color survives a round trip that a
+gamut-limited space would clamp.
+
+---
+
+## CSS Color Functions
+
+Every CSS color function is recognized as a color, so it lands in the color slot
+of whichever style property you use it in — and tokens inside it are expanded:
+
+```jsx
+fill: 'color-mix(in oklab, #primary 50%, #surface)',
+color: 'light-dark(#dark, #light)',
+color: 'contrast-color(#primary)',
+fill: 'color(display-p3 1 .5 0)',
+border: '1bw solid oklch(from #primary l c h / 50%)',  // relative color syntax
+shadow: '0 0 1x color-mix(in oklab, #dark 20%, transparent)',
+```
+
+`light-dark()` is the one exception to "always a color": CSS lets it pick between
+values of any type, so it is treated as a color only when its arguments are
+colors. `padding: 'light-dark(1x, 2x)'` still reaches the padding slot.
+
+A color token defined as one of these functions takes the
+[opacity suffix](#color-tokens--opacity) like any other:
+
+```jsx
+const Card = tasty({
+  styles: {
+    '#brand': 'color-mix(in oklab, #primary 50%, #surface)',
+    fill: '#brand.5',
+  },
+});
+```
+
+A [replace token](configuration.md#replace-tokens-parse-time-substitution) is
+substituted while parsing, so its color is right there to fade in place. A
+channel function takes the alpha after a slash; a derived function has no alpha
+channel, so it gets wrapped:
+
+```jsx
+configure({
+  replaceTokens: {
+    '#solid': 'hsl(220 90% 50%)',
+    '#adaptive': 'light-dark(#dark, #light)',
+  },
+});
+
+fill: '#solid.5';     // → hsl(220 90% 50% / .5)
+fill: '#adaptive.5';  // → oklch(from light-dark(…) l c h / .5)
+```
+
 ---
 
 ## Built-in Units

package/docs/injector.md

@@ -300,6 +300,17 @@ const styleRule: StyleResult = {
 };
 ```
 
+### Batched Injection
+
+`configure({ batchInjection: true })` queues every sheet write — component
+rules, global rules, raw CSS and at-rules — into one FIFO and applies them
+together, so the document is style-invalidated once per flush instead of once per
+component. `<TastyBatchProvider>` flushes in `useInsertionEffect`, before any
+layout effect, so a queued write can never be observed by a measurement. See
+[Batched injection](configuration.md#batched-injection) for the modes and the
+ordering guarantee. `flushStyles()` applies pending writes on demand; every read
+API here calls it for you.
+
 ### Deduplication & Performance
 
 ```typescript

package/docs/styles.md

@@ -254,6 +254,7 @@ Background color with design token support. Preferred over `backgroundColor` and
 | `"#purple.10"` | Token color at 10% opacity |
 | `"#surface #primary.10"` | Background `#surface` with `#primary.10` overlay (two colors enable smooth transitions between both) |
 | `"rgb(255 128 0)"` | CSS color value |
+| `"color-mix(in oklab, #primary 50%, #surface)"` | CSS color function — see [CSS Color Functions](dsl.md#css-color-functions) |
 | `true` | Default fill color |
 
 When two colors are provided, the first sets the background color and the second is applied as an overlay gradient layer. This enables independent CSS transitions on each color. The overlay is only applied when no explicit `image` or `backgroundImage` is set.
@@ -286,9 +287,10 @@ Text color with design token support.
 | `"#current"` | Current inherited color |
 | `"#current.5"` | Current inherited color at 50% opacity |
 | `"(#primary, #secondary)"` | Fallback: use `#primary`, fall back to `#secondary` |
+| `"light-dark(#dark, #light)"` | CSS color function — see [CSS Color Functions](dsl.md#css-color-functions) |
 | `true` | `currentColor` |
 
-When set to a named color token, also sets `$current-color` and `$current-color-{colorSpace}` custom properties for downstream use (suffix depends on the configured `colorSpace`, default `oklch`).
+When set to a named color token, also sets `$current-color` and `$current-color-{colorSpace}` custom properties for downstream use (suffix depends on the configured `colorSpace`, default `oklch`). An opacity suffix does not move the companion: `color="#purple.5"` still reports `#purple`'s channels, since components carry no alpha.
 
 ### `svgFill`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/tasty",
-  "version": "3.0.2",
+  "version": "3.2.0",
   "description": "A design-system-integrated styling system and DSL for concise, state-aware UI styling",
   "type": "module",
   "main": "./dist/index.js",
@@ -178,19 +178,19 @@
       "name": "main (import *)",
       "path": "dist/index.js",
       "import": "*",
-      "limit": "57.5 kB"
+      "limit": "59 kB"
     },
     {
       "name": "core (import *)",
       "path": "dist/core/index.js",
       "import": "*",
-      "limit": "54.5 kB"
+      "limit": "55.75 kB"
     },
     {
       "name": "static",
       "path": "dist/static/index.js",
       "import": "*",
-      "limit": "18.75 kB"
+      "limit": "19.25 kB"
     },
     {
       "name": "zero",
@@ -201,7 +201,7 @@
         "path",
         "crypto"
       ],
-      "limit": "33.25 kB"
+      "limit": "33.75 kB"
     },
     {
       "name": "babel-plugin",
@@ -212,7 +212,7 @@
         "path",
         "crypto"
       ],
-      "limit": "50.75 kB"
+      "limit": "52 kB"
     }
   ],
   "scripts": {