@tenphi/tasty 0.0.0-snapshot.bbd10c7 → 0.0.0-snapshot.bbfcd75

package/docs/styles.md

@@ -1,6 +1,6 @@
 # Style Properties Reference
 
-All standard CSS properties are supported in Tasty and benefit from its syntax sugar: design tokens (`$name`, `#name`), custom units (`2x`, `1r`, `1bw`), color opacity (`#purple.5`), auto-calc (`(100% - 2x)`), and custom functions. Values are parsed through the Tasty engine automatically.
+All standard CSS properties are supported in Tasty and benefit from its syntax sugar: design tokens (`$name`, `#name`), custom units (`2x`, `1r`, `1bw`), color opacity (`#purple.5`), auto-calc (`(100% - 2x)`), and [custom functions](dsl.md#functions-function) (`$$negative(10px)`). Values are parsed through the Tasty engine automatically.
 
 The properties documented below have **custom handlers** with enhanced syntax. They should be **preferred** over their raw CSS equivalents because they:
 
@@ -20,9 +20,10 @@ Use these instead of their raw CSS counterparts:
 |-----|------------|
 | `fill` | `backgroundColor`, `background` |
 | `image` | `backgroundImage` |
-| `padding` (with direction modifiers) | `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft` |
-| `margin` (with direction modifiers) | `marginTop`, `marginRight`, `marginBottom`, `marginLeft` |
-| `width` (with `min`/`max` modifiers) | `minWidth`, `maxWidth` |
+| `padding` (with physical direction modifiers) | `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft` |
+| `margin` (with physical direction modifiers) | `marginTop`, `marginRight`, `marginBottom`, `marginLeft` |
+| Logical block/inline category styles (with `start`/`end` modifiers) | Native logical axis/edge declarations |
+| `width` / `blockSize` / `inlineSize` (with `min`/`max` modifiers) | Their separate min/max declarations when one state map is sufficient |
 | `height` (with `min`/`max` modifiers) | `minHeight`, `maxHeight` |
 | `border` | `borderColor`, `borderWidth`, `borderStyle` |
 | `radius` | `borderRadius` |
@@ -100,18 +101,23 @@ For flex/grid layouts, outputs native `gap`. For block layouts, emulates gap usi
 
 Element padding with directional modifiers and multi-group support. Use **comma-separated groups** to set a base value and then override specific directions.
 
-**Syntax:** `[value]` | `[top right]` | `[top right bottom left]` | `[value directions...]` — comma-separated for multiple groups
+**Syntax:** `[value]` | `[block inline]` | `[top right bottom left]` | `[value direction...]` — comma-separated for multiple groups
 
 **Direction modifiers:** `top`, `right`, `bottom`, `left`
 
 **Output modifier:** `longhand` — forces output as individual CSS longhand properties (`padding-top`, `padding-right`, `padding-bottom`, `padding-left`) instead of the `padding` shorthand. Useful when children need to selectively inherit individual directions.
 
+**One value per directional group.** A group that names direction modifiers takes **exactly one** value, applied to every direction it names. For different values per side, use comma-separated groups: `padding: '2x top, 4x right'`. Writing `padding: '2x 4x top right'` ignores `4x` and warns in development — the parser keeps values and modifiers in separate buckets, so their interleaving in the source is not recoverable and `'2x 4x top right'`, `'2x top 4x right'` and `'top 2x right 4x'` are all the same input.
+
+A group that names *no* direction keeps plain CSS shorthand order, which is unambiguous and unchanged.
+
 | Value | Effect |
 |-------|--------|
 | `"2x"` | All sides `2x` |
 | `"2x 1x"` | Top/bottom `2x`, left/right `1x` |
 | `"2x top"` | Top `2x`, right/bottom/left `0` |
 | `"1x left right"` | Left and right `1x`, top/bottom `0` |
+| `"2x top, 4x right"` | Top `2x`, right `4x`, bottom/left `0` |
 | `"1x, 2x top"` | All sides `1x`, then top overridden to `2x` |
 | `"1x, 2x top bottom"` | Left/right `1x`, top/bottom `2x` |
 | `"2x longhand"` | All sides `2x`, output as 4 individual `padding-*` properties |
@@ -120,34 +126,33 @@ Element padding with directional modifiers and multi-group support. Use **comma-
 
 Later comma-separated groups override earlier groups for conflicting directions.
 
-Individual props `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft`, `paddingBlock`, `paddingInline` are supported but `padding` with modifiers is recommended.
-
-**Priority:** `padding` < `paddingBlock`/`paddingInline` < `paddingTop`/`paddingRight`/`paddingBottom`/`paddingLeft`
+Individual physical props `paddingTop`, `paddingRight`, `paddingBottom`, and `paddingLeft` are supported, but `padding` with modifiers is recommended. Use `blockPadding` or `inlinePadding` for an enhanced logical-axis shorthand; native declarations such as `paddingInlineStart` remain ordinary CSS properties. See [Logical properties](#logical-properties).
 
 ### `margin`
 
 Element margin. Same syntax, modifiers, and multi-group support as `padding`.
 
-**Syntax:** `[value]` | `[top right]` | `[top right bottom left]` | `[value directions...]` — comma-separated for multiple groups
+**Syntax:** `[value]` | `[block inline]` | `[top right bottom left]` | `[value direction...]` — comma-separated for multiple groups
 
 **Direction modifiers:** `top`, `right`, `bottom`, `left`
 
 **Output modifier:** `longhand` — forces output as individual CSS longhand properties (`margin-top`, etc.) instead of the `margin` shorthand.
 
+The [one-value-per-directional-group rule](#padding) from `padding` applies here too.
+
 | Value | Effect |
 |-------|--------|
 | `"2x"` | All sides `2x` |
 | `"2x 1x"` | Top/bottom `2x`, left/right `1x` |
 | `"2x top"` | Top `2x`, right/bottom/left `0` |
+| `"2x top, 4x right"` | Top `2x`, right `4x`, bottom/left `0` |
 | `"auto left right, 1x top bottom"` | Left/right `auto`, top/bottom `1x` |
 | `true` | All sides `1x` |
 | Number | Converted to `px` |
 
 Later comma-separated groups override earlier groups for conflicting directions.
 
-Individual props `marginTop`, `marginRight`, `marginBottom`, `marginLeft`, `marginBlock`, `marginInline` are supported but `margin` with modifiers is recommended.
-
-**Priority:** `margin` < `marginBlock`/`marginInline` < `marginTop`/`marginRight`/`marginBottom`/`marginLeft`
+Individual physical props `marginTop`, `marginRight`, `marginBottom`, and `marginLeft` are supported, but `margin` with modifiers is recommended. Use `blockMargin` or `inlineMargin` for an enhanced logical-axis shorthand; native declarations such as `marginInlineStart` remain ordinary CSS properties. See [Logical properties](#logical-properties).
 
 ### `width`
 
@@ -191,10 +196,23 @@ Separate `minHeight` and `maxHeight` props are supported and override values fro
 
 Positioning offsets with directional modifiers and multi-group support. Same directional syntax as `padding`.
 
-**Syntax:** `[value]` | `[top right]` | `[top right bottom left]` | `[value directions...]` — comma-separated for multiple groups
+**Syntax:** `[value]` | `[block inline]` | `[top right bottom left]` | `[value direction...]` — comma-separated for multiple groups
 
 **Direction modifiers:** `top`, `right`, `bottom`, `left`
 
+The [one-value-per-directional-group rule](#padding) from `padding` applies here too, with `dock`
+as the single exception.
+
+**`dock` modifier:** pins the named edge and spans its full length, by also applying the value
+to the two perpendicular sides. `inset: 'bottom dock'` gives `inset: auto 0 0 0` — anchored to
+the bottom, full width. Without a direction, `dock` fills every side.
+
+`dock` is the one place a directional group takes **two** values: the first insets the named
+edge, the second the sides it spans. `inset: '2x 4x bottom dock'` pins the bottom at `2x` and
+insets the sides by `4x`. A third value, or a second value without `dock`, is ignored and warns
+in development. With several directions the first value applies to each named edge and the
+second to every side they span.
+
 **Output modifier:** `longhand` — forces output as individual CSS properties (`top`, `right`, `bottom`, `left`) instead of the `inset` shorthand.
 
 | Value | Effect |
@@ -205,12 +223,52 @@ Positioning offsets with directional modifiers and multi-group support. Same dir
 | `"0, 2x top"` | All sides `0`, then top overridden to `2x` |
 | `"0 longhand"` | All sides `0`, output as individual `top`/`right`/`bottom`/`left` |
 | `true` | All sides `0` |
+| `"bottom dock"` | Bottom/left/right `0`, top `auto` — bottom-anchored, full width |
+| `"right dock"` | Right/top/bottom `0`, left `auto` — right-anchored, full height |
+| `"2x bottom dock"` | Bottom/left/right `2x`, top `auto` |
+| `"2x 4x bottom dock"` | Bottom `2x`, left/right `4x`, top `auto` |
+| `"dock"` | All sides `0` |
 
 Later comma-separated groups override earlier groups for conflicting directions.
 
-Individual props `top`, `right`, `bottom`, `left`, `insetBlock`, `insetInline` are supported. When only individual direction props are used (without `inset`), individual CSS properties are output for correct cascade behavior with state overrides.
+Individual physical props `top`, `right`, `bottom`, and `left` are supported. When only those props are used (without `inset`), individual CSS properties are output for correct cascade behavior with state overrides. Use `blockInset` or `inlineInset` for logical axes; native declarations such as `insetInlineStart` remain ordinary CSS properties.
+
+### Logical properties
+
+Tasty provides one enhanced handler for each logical axis/category pair. Each handler emits native logical CSS instead of converting values to `top`, `right`, `bottom`, `left`, `width`, or `height`. The browser therefore resolves `block`, `inline`, `start`, and `end` from the element's `writingMode` and `direction`.
+
+```jsx
+styles: {
+  direction: 'rtl',
+  inlinePadding: '1x start, 2x end',
+  inlineBorder: '1bw solid #accent start',
+  blockInset: '0 end',
+}
+```
+
+An axis handler accepts one value for both edges or two values in logical **start/end** order. Use `start` and `end` modifiers, with comma-separated groups for different edge values. Unspecified padding, margin, and scroll edges reset to `0`; unspecified inset edges reset to `auto`. The `longhand` modifier emits the two native start/end declarations.
+
+| Category | Block axis | Inline axis |
+|----------|------------|-------------|
+| Size | `blockSize` | `inlineSize` |
+| Padding | `blockPadding` | `inlinePadding` |
+| Margin | `blockMargin` | `inlineMargin` |
+| Inset | `blockInset` | `inlineInset` |
+| Scroll margin | `blockScrollMargin` | `inlineScrollMargin` |
+| Scroll padding | `blockScrollPadding` | `inlineScrollPadding` |
+| Border | `blockBorder` | `inlineBorder` |
+
+`blockSize` and `inlineSize` use the same enhanced one/two/three-value and `min`/`max`/`fixed` syntax as `width`. Separate `minBlockSize`, `maxBlockSize`, `minInlineSize`, and `maxInlineSize` declarations override constraints produced by that shorthand.
+
+`blockBorder` and `inlineBorder` use the same width/style/color parsing and defaults as `border`, including `1bw`, color tokens, and `true`. Logical padding, margin, scroll margin, and scroll padding default to `1x` for `true`; logical inset defaults to `0`.
 
-**Priority:** `inset` < `insetBlock`/`insetInline` < `top`/`right`/`bottom`/`left`
+Native logical CSS names—such as `paddingInlineStart`, `borderBlockColor`, and `borderStartStartRadius`—remain available as ordinary CSS properties. They support Tasty tokens and units through the normal value parser, but do not get category defaults or directional shorthand behavior.
+
+The physical `scrollMargin` and `scrollPadding` shorthands support the same values and physical direction modifiers as `padding`. Their logical counterparts stay in separate axis handlers.
+
+`writingMode`, `direction`, and `textOrientation` are standard CSS control properties. They use Tasty's normal value parser and need no special handler.
+
+Avoid setting physical and logical declarations that resolve to the same edge in one style block. Tasty keeps them separate and lets the native CSS cascade resolve the overlap, whose result also depends on writing mode and direction.
 
 ---
 
@@ -228,6 +286,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.
@@ -260,9 +319,17 @@ 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`).
+Also sets `$current-color` to the same color, for anything that needs the
+inherited color as a color rather than as the `currentcolor` keyword. Every color
+publishes it, not just a named token, so a reader below always takes the nearest
+`color` rather than the nearest *token* color. A value that already reads the
+inherited color — `#current` itself, a `#current` fade, a bare `currentColor` —
+is not republished: resolving it a second time one level down would fade it
+twice, and the variable into itself is a self-reference. `#current` does not go
+through it; it is the keyword.
 
 ### `svgFill`
 
@@ -270,7 +337,7 @@ SVG fill color. Same color token syntax as `fill` and `color`. Outputs the nativ
 
 ```jsx
 svgFill="#purple.10"
-svgFill="currentColor"
+svgFill="#current"
 ```
 
 ---
@@ -319,7 +386,11 @@ Border radius with shape presets and directional modifiers.
 | `"backleaf"` | Asymmetric: round, sharp, round, sharp |
 | `"inherit"` | Inherit border-radius from parent |
 
-**Direction modifiers:** `top`, `right`, `bottom`, `left` — rounds only the specified corners.
+**Edge modifiers:** `top`, `right`, `bottom`, `left` — rounds the *pair* of corners along that edge.
+
+**Corner modifiers:** `top-left`, `top-right`, `bottom-right`, `bottom-left` — rounds a single corner.
+Use these when an edge modifier would round one corner too many. Edge and corner modifiers combine
+(`radius: 'top bottom-right'`).
 
 **Output modifier:** `longhand` — forces output as individual CSS longhand properties (`border-top-left-radius`, `border-top-right-radius`, `border-bottom-right-radius`, `border-bottom-left-radius`) instead of the `border-radius` shorthand. Useful when children need to selectively inherit individual corners via `radius: 'inherit left'`.
 
@@ -334,6 +405,9 @@ Border radius with shape presets and directional modifiers.
 | `"1r longhand"` | All corners `1r`, output as 4 individual `border-*-radius` properties |
 | `"inherit"` | All corners inherit from parent (`border-radius: inherit`) |
 | `"inherit right"` | Right corners inherit from parent (uses longhand properties) |
+| `"top-right"` | Top-right corner `1r`, every other corner `0` |
+| `"4px top-left"` | Top-left corner `4px`, every other corner `0` |
+| `"top bottom-right"` | Both top corners and bottom-right `1r`, bottom-left `0` |
 
 ### `outline`
 
@@ -378,11 +452,11 @@ Multiple shadows: `shadow="1x 1x 2x #dark.20, inset 0 0 4x #dark.10"`
 
 Typography preset that sets font-size, line-height, letter-spacing, font-weight, font-style, and text-transform from named design tokens.
 
-**Syntax:** `name`, `name / modifier`, or `modifier` (shorthand)
+**Syntax:** `name`, `name / modifier...`, or `modifier...` (shorthand)
 
 Preset names are project-specific (e.g. `h1`–`h6`, `t1`–`t4`, `p1`–`p4`). Register them for autocomplete by augmenting `TastyPresetNames`.
 
-Use `/` to separate the preset name from a modifier. When a modifier is used alone (without a name), the preset name defaults to `inherit`.
+Use `/` to separate the preset name from one or more space-separated modifiers. When modifiers are used alone (without a name), the preset name defaults to `inherit`. Modifiers can be combined freely because they target different properties.
 
 **Modifiers:**
 
@@ -394,11 +468,13 @@ Use `/` to separate the preset name from a modifier. When a modifier is used alo
 | `tight` | Sets line-height equal to font-size |
 
 ```jsx
-preset="h1"              // heading 1
-preset="h2 / strong"     // bold heading 2
-preset="t3 / italic"     // italic text 3
-preset="t2 / tight"      // text 2 with tight line-height
-preset="bold"             // inherit preset with bold (shorthand for "inherit / bold")
+preset="h1"                    // heading 1
+preset="h2 / strong"           // bold heading 2
+preset="h2 / strong italic"    // bold + italic heading 2
+preset="t3 / italic"           // italic text 3
+preset="t2 / strong tight"     // bold text 2 with tight line-height
+preset="bold"                  // inherit preset with bold (shorthand)
+preset="bold italic"           // inherit preset with bold + italic (shorthand)
 ```
 
 Individual typography props (`fontSize`, `lineHeight`, `letterSpacing`, `fontWeight`, `fontStyle`, `textTransform`) can be used alongside `preset` to override specific values, but using `preset` alone is recommended.
@@ -550,15 +626,20 @@ Scrollbar styling using CSS standard properties (`scrollbar-width`, `scrollbar-c
 
 Gradient-based edge fading using CSS masks. Use **comma-separated groups** to set different widths and colors per direction.
 
-**Syntax:** `[width] [directions...] [#from-color] [#to-color]` — comma-separated for multiple groups
+**Syntax:** `[width] [direction...] [#from-color] [#to-color]` — comma-separated for multiple groups
 
 **Direction modifiers:** `top`, `right`, `bottom`, `left`
 
+A group that names edges takes a **single** width, applied to every edge it names — different
+widths per edge come from comma groups. A group that names no edge covers all four and keeps
+plain CSS shorthand order, like `padding`. See the [`padding` rule](#padding).
+
 | Value | Effect |
 |-------|--------|
 | `"top"` | Fade top edge, default width (`2x`), all other edges unfaded |
 | `"2x left right"` | Fade left and right edges with `2x` width, top/bottom unfaded |
-| `"3x 1x top bottom"` | Fade top with `3x` width, bottom with `1x` width |
+| `"3x 1x"` | All edges faded — top/bottom `3x`, left/right `1x` (CSS shorthand order) |
+| `"3x top, 1x bottom"` | Fade top with `3x` width, bottom with `1x` width |
 | `"2x #transparent #dark"` | All edges faded with `2x` width, from `#transparent` to `#dark` |
 | `"top #a #b, bottom #c #d"` | Top fades from `#a` to `#b`, bottom fades from `#c` to `#d` |