@tenphi/tasty 0.10.1 → 0.12.0

package/docs/{usage.md → dsl.md}

@@ -1,155 +1,8 @@
-# Usage Guide
+# Style DSL Reference
 
-`tasty` is a powerful utility for creating styled React components with a declarative, design-system-integrated API. It combines the flexibility of CSS-in-JS with the consistency of a design system, enabling you to build maintainable, themeable components quickly.
+This is the Tasty style language reference — the value syntax, state mappings, tokens, units, extending semantics, and special declarations that apply to both runtime `tasty()` and build-time `tastyStatic()`.
 
-For global configuration (tokens, recipes, custom units, handlers), see **[Configuration](configuration.md)**.
-
----
-
-## Quick Start
-
-### Creating Your First Component
-
-```jsx
-import { tasty } from '@tenphi/tasty';
-
-// Basic styled component
-const Card = tasty({
-  as: 'div',
-  styles: {
-    padding: '4x',
-    fill: '#white',
-    border: true,
-    radius: true,
-  },
-  styleProps: ['padding', 'fill'], // Expose styles as props
-});
-
-// Usage
-<Card>Hello World</Card>
-<Card padding="6x" fill="#gray.05">Custom Card</Card>
-```
-
-### Extending Existing Components
-
-> **Best Practice:** Always prefer creating styled wrappers over using the `styles` prop directly.
-
-```jsx
-// Recommended
-const PrimaryButton = tasty(Button, {
-  styles: {
-    fill: '#purple',
-    color: '#white',
-    padding: '2x 4x',
-  },
-});
-
-// Avoid
-<Button styles={{ fill: '#purple' }}>Click me</Button>
-```
-
-#### Extending vs. Replacing State Maps
-
-When a style property uses a state map, the merge behavior depends on whether the child provides a `''` (default) key:
-
-- **No `''` key** — extend mode: parent states are preserved, child adds/overrides
-- **Has `''` key** — replace mode: child defines everything from scratch
-
-```jsx
-// Parent has: fill: { '': '#white', hovered: '#blue', disabled: '#gray' }
-
-// Extend — no '' key, parent states preserved
-const MyButton = tasty(Button, {
-  styles: {
-    fill: {
-      'loading': '#yellow',      // append new state
-      'disabled': '#gray.20',    // override existing state in place
-    },
-  },
-});
-
-// Replace — has '' key, parent states dropped
-const MyButton = tasty(Button, {
-  styles: {
-    fill: {
-      '': '#red',
-      'hovered': '#blue',
-    },
-  },
-});
-```
-
-Use `'@inherit'` to pull a parent state value. In extend mode it repositions the state; in replace mode it cherry-picks it:
-
-```jsx
-// Extend mode: reposition disabled to end (highest CSS priority)
-fill: {
-  'loading': '#yellow',
-  disabled: '@inherit',
-}
-
-// Replace mode: cherry-pick disabled from parent
-fill: {
-  '': '#red',
-  disabled: '@inherit',
-}
-```
-
-Use `null` inside a state map to remove a state, or `false` to block it entirely (tombstone):
-
-```jsx
-fill: { pressed: null }   // removes pressed from the result
-fill: { disabled: false } // tombstone — no CSS for disabled, blocks recipe too
-```
-
-#### Resetting Properties with `null` and `false`
-
-```jsx
-const SimpleButton = tasty(Button, {
-  styles: {
-    fill: null,    // discard parent's fill, let recipe fill in
-    border: false, // no border at all (tombstone — blocks recipe too)
-  },
-});
-```
-
-| Value | Meaning | Recipe fills in? |
-|-------|---------|-----------------|
-| `undefined` | Not provided — parent preserved | N/A |
-| `null` | Intentional unset — parent discarded | Yes |
-| `false` | Tombstone — blocks everything | No |
-
-### Essential Patterns
-
-```jsx
-// State-based styling
-const InteractiveCard = tasty({
-  styles: {
-    fill: {
-      '': '#white',
-      'hovered': '#gray.05',
-      'pressed': '#gray.10',
-    },
-  },
-});
-
-// Using design tokens
-const TokenCard = tasty({
-  styles: {
-    fill: '#surface',      // Color token
-    color: '#text',        // Color token
-    padding: '2x',         // Custom unit (gap × 2)
-    radius: '1r',          // Custom unit (border-radius)
-    border: '1bw solid #border', // Border width token
-  },
-});
-```
-
----
-
-## Configuration
-
-For tokens, recipes, custom units, style handlers, and other global settings, see **[Configuration](configuration.md)**.
+For the runtime React API (`tasty()`, hooks, component props), see [Runtime API](runtime.md). For all enhanced style properties, see [Style Properties](styles.md). For global configuration, see [Configuration](configuration.md).
 
 ---
 
@@ -202,43 +55,7 @@ mods={{ hovered: true, theme: 'danger' }}
 
 ---
 
-## Core Concepts
-
-### Component Creation
-
-```jsx
-// Create new element
-const Box = tasty({
-  as: 'div',
-  styles: { /* styles */ },
-});
-
-// Extend existing component
-const StyledButton = tasty(Button, {
-  styles: { /* additional styles */ },
-});
-```
-
-### Style Props
-
-Use `styleProps` to expose style properties as direct component props:
-
-```jsx
-const FlexibleBox = tasty({
-  as: 'div',
-  styles: {
-    display: 'flex',
-    padding: '2x',
-  },
-  styleProps: ['gap', 'align', 'placeContent', 'fill'],
-});
-
-<FlexibleBox gap="2x" align="center" fill="#surface">
-  Content
-</FlexibleBox>
-```
-
-### Color Tokens & Opacity
+## Color Tokens & Opacity
 
 ```jsx
 color: '#purple',           // Full opacity
@@ -249,7 +66,9 @@ fill: '#current.5',         // → color-mix(in oklab, currentcolor 50%, transpa
 color: '(#primary, #secondary)',  // Fallback syntax
 ```
 
-### Built-in Units
+---
+
+## Built-in Units
 
 | Unit | Description | Example | CSS Output |
 |------|-------------|---------|------------|
@@ -264,9 +83,11 @@ color: '(#primary, #secondary)',  // Fallback syntax
 
 You can register additional custom units via [`configure()`](configuration.md#options).
 
-### Predefined Tokens
+---
+
+## Replace Tokens
 
-Tokens defined via [`configure({ tokens })`](configuration.md#predefined-tokens) are replaced at parse time and baked into the generated CSS:
+Tokens defined via [`configure({ replaceTokens })`](configuration.md#replace-tokens-parse-time-substitution) are replaced at parse time and baked into the generated CSS:
 
 ```jsx
 const Card = tasty({
@@ -278,7 +99,9 @@ const Card = tasty({
 });
 ```
 
-### Recipes
+---
+
+## Recipes
 
 Apply predefined style bundles (defined via [`configure({ recipes })`](configuration.md#recipes)) using the `recipe` style property:
 
@@ -323,7 +146,82 @@ const Custom = tasty({
 });
 ```
 
-### Advanced States (`@` prefix)
+---
+
+## Extending vs. Replacing State Maps
+
+When a style property uses a state map, the merge behavior depends on whether the child provides a `''` (default) key:
+
+- **No `''` key** — extend mode: parent states are preserved, child adds/overrides
+- **Has `''` key** — replace mode: child defines everything from scratch
+
+```jsx
+// Parent has: fill: { '': '#white', hovered: '#blue', disabled: '#gray' }
+
+// Extend — no '' key, parent states preserved
+const MyButton = tasty(Button, {
+  styles: {
+    fill: {
+      'loading': '#yellow',      // append new state
+      'disabled': '#gray.20',    // override existing state in place
+    },
+  },
+});
+
+// Replace — has '' key, parent states dropped
+const MyButton = tasty(Button, {
+  styles: {
+    fill: {
+      '': '#red',
+      'hovered': '#blue',
+    },
+  },
+});
+```
+
+Use `'@inherit'` to pull a parent state value. In extend mode it repositions the state; in replace mode it cherry-picks it:
+
+```jsx
+// Extend mode: reposition disabled to end (highest CSS priority)
+fill: {
+  'loading': '#yellow',
+  disabled: '@inherit',
+}
+
+// Replace mode: cherry-pick disabled from parent
+fill: {
+  '': '#red',
+  disabled: '@inherit',
+}
+```
+
+Use `null` inside a state map to remove a state, or `false` to block it entirely (tombstone):
+
+```jsx
+fill: { pressed: null }   // removes pressed from the result
+fill: { disabled: false } // tombstone — no CSS for disabled, blocks recipe too
+```
+
+### Resetting Properties with `null` and `false`
+
+```jsx
+const SimpleButton = tasty(Button, {
+  styles: {
+    fill: null,    // discard parent's fill, let recipe fill in
+    border: false, // no border at all (tombstone — blocks recipe too)
+  },
+});
+```
+
+| Value | Meaning | Recipe fills in? |
+|-------|---------|-----------------|
+| `undefined` | Not provided — parent preserved | N/A |
+| `null` | Intentional unset — parent discarded | Yes |
+| `false` | Tombstone — blocks everything | No |
+
+---
+
+## Advanced States (`@` prefix)
 
 | Prefix | Purpose | Example |
 |--------|---------|---------|
@@ -339,7 +237,156 @@ const Custom = tasty({
 | `:not()` | CSS `:not()` negation (prefer `!:is()`) | `:not(:first-child)` |
 | `:where()` | CSS `:where()` (zero specificity) | `:where(Section)` |
 
-#### `@parent(...)` — Parent Element States
+### `@media(...)` — Media Queries
+
+Media queries support dimension shorthands and custom unit expansion:
+
+| Shorthand | Expands to |
+|-----------|------------|
+| `w` | `width` |
+| `h` | `height` |
+
+```jsx
+fill: {
+  '': '#surface',
+  '@media(w < 768px)': '#surface-mobile',
+  '@media(600px <= w < 1200px)': '#surface-tablet',
+  '@media(prefers-color-scheme: dark)': '#surface-dark',
+}
+```
+
+| Tasty syntax | CSS output |
+|--------------|------------|
+| `@media(w < 768px)` | `@media (width < 768px)` |
+| `@media(600px <= w < 1200px)` | `@media (600px <= width < 1200px)` |
+| `@media:print` | `@media print` |
+| `@media:screen` | `@media screen` |
+| `@media(prefers-color-scheme: dark)` | `@media (prefers-color-scheme: dark)` |
+| `@media(prefers-reduced-motion)` | `@media (prefers-reduced-motion)` |
+
+Custom units work inside media queries: `@media(w < 40x)` → `@media (width < calc(var(--gap) * 40))`.
+
+In practice, define state aliases via `configure({ states })` and use `@mobile` instead of writing the full query in every component.
+
+### `@(...)` — Container Queries
+
+Container queries use the syntax `@(name, condition)` for named containers or `@(condition)` for the nearest ancestor container. Dimension shorthands (`w`, `h`, `is`, `bs`) are expanded the same way as `@media`.
+
+| Shorthand | Expands to |
+|-----------|------------|
+| `w` | `width` |
+| `h` | `height` |
+| `is` | `inline-size` |
+| `bs` | `block-size` |
+
+```jsx
+const Panel = tasty({
+  styles: {
+    flow: {
+      '': 'column',
+      '@(layout, w >= 600px)': 'row',
+    },
+  },
+});
+```
+
+| Tasty syntax | CSS output |
+|--------------|------------|
+| `@(layout, w < 600px)` | `@container layout (width < 600px)` |
+| `@(w < 600px)` | `@container (width < 600px)` |
+| `@(layout, $variant=danger)` | `@container layout style(--variant: "danger")` |
+| `@(layout, $compact)` | `@container layout style(--compact)` |
+| `@(scroll-state(stuck: top))` | `@container scroll-state(stuck: top)` |
+| `@(nav, scroll-state(stuck: top))` | `@container nav scroll-state(stuck: top)` |
+
+Container style queries use `$prop` (boolean) or `$prop=value` syntax, which maps to CSS `style(--prop)` or `style(--prop: "value")`.
+
+### `@supports(...)` — Feature Queries
+
+Feature queries test CSS property support. Use `$` as the first argument to test selector support:
+
+| Tasty syntax | CSS output |
+|--------------|------------|
+| `@supports(display: grid)` | `@supports (display: grid)` |
+| `@supports($, :has(*))` | `@supports selector(:has(*))` |
+| `!@supports(display: grid)` | `@supports (not (display: grid))` |
+
+```jsx
+display: {
+  '': 'flex',
+  '@supports(display: grid)': 'grid',
+}
+```
+
+### `@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:
+
+```jsx
+color: {
+  '': '#text',
+  '@root(schema=dark)': '#text-on-dark',
+  '@root(.premium-user)': '#gold',
+}
+```
+
+| Tasty syntax | CSS selector |
+|--------------|-------------|
+| `@root(schema=dark)` | `:root[data-schema="dark"]` |
+| `@root(hovered)` | `:root[data-hovered]` |
+| `@root(.premium-user)` | `:root.premium-user` |
+| `@root([lang="en"])` | `:root[lang="en"]` |
+| `!@root(schema=dark)` | `:root:not([data-schema="dark"])` |
+
+Root conditions are prepended to the component selector: `:root[data-schema="dark"] .t0.t0 { ... }`.
+
+### `@own(...)` — Sub-element's Own State
+
+By default, state keys in sub-element styles refer to the root component's state context. Use `@own(...)` when the sub-element should react to its own state:
+
+```jsx
+const Nav = tasty({
+  styles: {
+    NavItem: {
+      color: {
+        '': '#text',
+        '@own(:hover)': '#primary',
+        '@own(:focus-visible)': '#primary',
+        'selected': '#primary',       // root-level modifier
+      },
+    },
+  },
+  elements: { NavItem: 'a' },
+});
+```
+
+| Tasty syntax (inside sub-element) | CSS output |
+|-----------------------------------|------------|
+| `@own(:hover)` | `:hover` on the sub-element selector |
+| `@own(hovered)` | `[data-hovered]` on the sub-element selector |
+| `@own(theme=dark)` | `[data-theme="dark"]` on the sub-element selector |
+
+`@own()` is only valid inside sub-element styles. Using it on root styles emits a warning and is treated as a regular modifier.
+
+### `@starting` — Entry Animation
+
+Wraps the rule in `@starting-style`, enabling CSS entry animations for elements as they appear in the DOM:
+
+```jsx
+const FadeIn = tasty({
+  styles: {
+    opacity: { '': '1', '@starting': '0' },
+    transform: { '': 'scale(1)', '@starting': 'scale(0.95)' },
+    transition: 'opacity 0.3s, translate 0.3s',
+  },
+});
+```
+
+| Tasty syntax | CSS output |
+|--------------|------------|
+| `@starting` | `@starting-style { .t0.t0 { ... } }` |
+
+### `@parent(...)` — Parent Element States
 
 Style based on ancestor element attributes. Uses `:is([selector] *)` / `:not([selector] *)` for symmetric, composable parent checks. Boolean logic (`&`, `|`, `!`) is supported inside `@parent()`.
 
@@ -381,7 +428,7 @@ const Card = tasty({
 // → .t0.t0:is([data-hovered] *) [data-element="Label"]
 ```
 
-#### `:is()`, `:has()` — CSS Structural Pseudo-classes
+### `:is()`, `:has()` — CSS Structural Pseudo-classes
 
 Use CSS structural pseudo-classes directly in state keys. Capitalized words become `[data-element="..."]` selectors; lowercase words are HTML tags. A trailing combinator (`>`, `+`, `~`) is auto-completed with `*`.
 
@@ -431,15 +478,9 @@ Combine with other states using boolean logic:
 
 ---
 
-## Style Properties
-
-For a complete reference of all enhanced style properties — syntax, values, modifiers, and recommendations — see **[Style Properties Reference](styles.md)**.
+## Keyframes
 
----
-
-## Advanced Features
-
-### Keyframes
+Define animations inline using the `@keyframes` key in styles:
 
 ```jsx
 const Pulse = tasty({
@@ -455,7 +496,9 @@ const Pulse = tasty({
 });
 ```
 
-### Properties (`@property`)
+---
+
+## Properties (`@property`)
 
 CSS cannot transition or animate custom properties unless the browser knows their type. Tasty solves this automatically — when you assign a concrete value to a custom property, the type is inferred and a CSS `@property` rule is registered behind the scenes:
 
@@ -480,216 +523,18 @@ Use explicit `@properties` when you need non-default settings like `inherits: fa
 },
 ```
 
-### Variants & Theming
-
-```jsx
-const Button = tasty({
-  styles: {
-    padding: '2x 4x',
-    border: true,
-  },
-  variants: {
-    default: { fill: '#blue', color: '#white' },
-    danger: { fill: '#red', color: '#white' },
-    outline: { fill: 'transparent', color: '#blue', border: '1bw solid #blue' },
-  },
-});
-
-<Button variant="danger">Delete</Button>
-```
-
-#### Extending Variants with Base State Maps
-
-When base `styles` contain an extend-mode state map (an object **without** a `''` key), it is applied **after** the variant merge. This lets you add or override states across all variants without repeating yourself:
-
-```jsx
-const Badge = tasty({
-  styles: {
-    padding: '1x 2x',
-    // No '' key → extend mode: appended to every variant's border
-    border: {
-      'type=primary': '#clear',
-    },
-  },
-  variants: {
-    primary: {
-      border: { '': '#white.2', pressed: '#primary-text', disabled: '#clear' },
-      fill: { '': '#white #primary', hovered: '#white #primary-text' },
-    },
-    secondary: {
-      border: { '': '#primary.15', pressed: '#primary.3' },
-      fill: '#primary.10',
-    },
-  },
-});
-
-// Both variants get 'type=primary': '#clear' appended to their border map
-```
-
-Properties that are **not** extend-mode (simple values, state maps with `''`, `null`, `false`, selectors, sub-elements) merge with variants as before — the variant can fully replace them.
-
-### Sub-element Styling
-
-Sub-elements are inner parts of a compound component, styled via capitalized keys in `styles` and identified by `data-element` attributes in the DOM.
-
-> **Best Practice:** Use the `elements` prop to declare sub-element components. This gives you typed, reusable sub-components (`Card.Title`, `Card.Content`) instead of manually writing `data-element` attributes.
-
-```jsx
-const Card = tasty({
-  styles: {
-    padding: '4x',
-    Title: { preset: 'h3', color: '#primary' },
-    Content: { color: '#text' },
-  },
-  elements: {
-    Title: 'h3',
-    Content: 'div',
-  },
-});
-
-// Sub-components automatically get data-element attributes
-<Card>
-  <Card.Title>Card Title</Card.Title>
-  <Card.Content>Card content</Card.Content>
-</Card>
-```
-
-Each entry in `elements` can be a tag name string or a config object:
-
-```jsx
-elements: {
-  Title: 'h3',                          // shorthand: tag name only
-  Icon: { as: 'span', qa: 'card-icon' }, // full form: tag + QA attribute
-}
-```
-
-The sub-components produced by `elements` support `mods`, `tokens`, `isDisabled`, `isHidden`, and `isChecked` props — the same modifier interface as the root component.
-
-If you don't need sub-components (e.g., the inner elements are already rendered by a third-party library), you can still style them by key alone — just omit `elements` and apply `data-element` manually:
-
-```jsx
-const Card = tasty({
-  styles: {
-    padding: '4x',
-    Title: { preset: 'h3', color: '#primary' },
-  },
-});
-
-<Card>
-  <div data-element="Title">Card Title</div>
-</Card>
-```
-
-#### Selector Affix (`$`)
-
-Control how a sub-element selector attaches to the root selector using the `$` property inside the sub-element's styles:
-
-| Pattern | Result | Description |
-|---------|--------|-------------|
-| *(none)* | ` [el]` | Descendant (default) |
-| `>` | `> [el]` | Direct child |
-| `>Body>Row>` | `> [Body] > [Row] > [el]` | Chained elements |
-| `::before` | `::before` | Root pseudo (no key) |
-| `@::before` | `[el]::before` | Pseudo on the sub-element |
-| `>@:hover` | `> [el]:hover` | Pseudo-class on the sub-element |
-| `>@.active` | `> [el].active` | Class on the sub-element |
-
-The `@` placeholder marks exactly where the `[data-element="..."]` selector is injected, allowing you to attach pseudo-classes, pseudo-elements, or class selectors directly to the sub-element instead of the root:
-
-```jsx
-const List = tasty({
-  styles: {
-    Item: {
-      $: '>@:last-child',
-      border: 'none',
-    },
-  },
-});
-// → .t0 > [data-element="Item"]:last-child { border: none }
-```
-
 ---
 
-## Hooks
-
-### useStyles
-
-```tsx
-import { useStyles } from '@tenphi/tasty';
-
-function MyComponent() {
-  const { className } = useStyles({
-    padding: '2x',
-    fill: '#surface',
-    radius: '1r',
-  });
-
-  return <div className={className}>Styled content</div>;
-}
-```
-
-### useGlobalStyles
-
-```tsx
-import { useGlobalStyles } from '@tenphi/tasty';
-
-function ThemeStyles() {
-  useGlobalStyles('.card', {
-    padding: '4x',
-    fill: '#surface',
-    radius: '1r',
-  });
-
-  return null;
-}
-```
-
-### useRawCSS
-
-```tsx
-import { useRawCSS } from '@tenphi/tasty';
-
-function GlobalReset() {
-  useRawCSS(`
-    body { margin: 0; padding: 0; }
-  `);
-
-  return null;
-}
-```
-
-### useMergeStyles
-
-```tsx
-import { useMergeStyles } from '@tenphi/tasty';
-
-function MyTabs({ styles, tabListStyles, prefixStyles }) {
-  const mergedStyles = useMergeStyles(styles, {
-    TabList: tabListStyles,
-    Prefix: prefixStyles,
-  });
+## Style Properties
 
-  return <TabsElement styles={mergedStyles} />;
-}
-```
+For a complete reference of all enhanced style properties — syntax, values, modifiers, and recommendations — see **[Style Properties Reference](styles.md)**.
 
 ---
 
-## Best Practices
-
-### Do's
-
-- Use styled wrappers instead of `styles` prop directly
-- Use design tokens and custom units (`#text`, `2x`, `1r`)
-- Use semantic transition names (`theme 0.3s`)
-- Use `elements` prop to declare typed sub-components for compound components
-- Use `styleProps` for component APIs
-- Use `tokens` prop for dynamic values
-
-### Don'ts
+## Learn more
 
-- Don't use `styles` prop directly on components
-- Don't use raw CSS values when tokens exist
-- Don't use CSS property names when Tasty alternatives exist — see [recommended props](styles.md#recommended-props)
-- Don't change `styles` prop at runtime (use modifiers or tokens instead)
-- Don't use `style` prop for custom styling (only for third-party library integration)
+- **[Runtime API](runtime.md)** — `tasty()` factory, component props, variants, sub-elements, hooks
+- **[Methodology](methodology.md)** — Recommended patterns: root + sub-elements, styleProps, tokens, wrapping
+- **[Configuration](configuration.md)** — Tokens, recipes, custom units, style handlers, TypeScript extensions
+- **[Style Properties](styles.md)** — Complete reference for all enhanced style properties
+- **[Zero Runtime (tastyStatic)](tasty-static.md)** — Build-time static styling with Babel plugin