@cube-dev/ui-kit 0.124.0 → 0.124.2

package/docs/tasty/dsl.md

@@ -36,6 +36,46 @@ styles: { Title: { preset: 'h3' } }
 // Targets: <div data-element="Title">
 ```
 
+#### 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 |
+| `h1` | ` h1` | Tag selector (no key injection) |
+| `h1 >` | ` h1 > [el]` | Key is direct child of tag |
+| `h1 *` | ` h1 *` | Any descendant of tag |
+| `*` | ` *` | All descendants |
+| `::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 |
+
+Rules for key injection (`[data-element="..."]`):
+
+- **Trailing combinator** (`>`, `+`, `~`) — key is injected after it
+- **Uppercase element name** (`Body`, `Row`) — key is injected as descendant
+- **HTML tag** (`h1`, `a`, `span`) — no key injection; the tag IS the selector
+- **Universal selector** (`*`) — no key injection
+- **Pseudo / class / attribute** — no key injection
+
+The `@` placeholder marks exactly where `[data-element="..."]` 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 }
+```
+
 ### Color Token
 
 Named color prefixed with `#` that maps to CSS custom properties. Supports opacity with `.N` suffix:
@@ -53,6 +93,8 @@ mods={{ hovered: true, theme: 'danger' }}
 // → data-hovered="" data-theme="danger"
 ```
 
+Modifiers can also be exposed as top-level component props via `modProps` — see [Runtime — Mod Props](runtime.md#mod-props).
+
 ---
 
 ## Color Tokens & Opacity

package/docs/tasty/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-This guide walks you from zero to a working Tasty component, then through the optional shared configuration and tooling layers. For a feature overview, see the [README](../README.md). For the full style language reference, see the [Style DSL](dsl.md). For the React API, see the [Runtime API](runtime.md). For the rest of the docs by role or task, see the [Docs Hub](README.md).
+This guide walks you from zero to a working Tasty component, then through the optional shared configuration and tooling layers. It is the right starting point when you already want to try Tasty in code. If you are still deciding whether Tasty fits your team, start with [Comparison](comparison.md) and [Adoption Guide](adoption.md) first. For a feature overview, see the [README](../README.md). For the full style language reference, see the [Style DSL](dsl.md). For the React API, see the [Runtime API](runtime.md). For the rest of the docs by role or task, see the [Docs Hub](README.md).
 
 ---
 
@@ -10,6 +10,8 @@ This guide walks you from zero to a working Tasty component, then through the op
 - **React** >= 18 (peer dependency)
 - **Package manager**: pnpm, npm, or yarn
 
+Tasty can be used immediately in a React app, but it is most compelling for teams building reusable components with intersecting states, variants, tokens, and design-system conventions.
+
 ---
 
 ## Install
@@ -177,25 +179,25 @@ export default [
 
 ## Choosing a rendering mode
 
-Tasty supports three rendering modes. Pick the one that fits your use case:
+Tasty has two styling approaches. Pick the one that fits your use case, then decide whether your runtime setup also needs server rendering support:
 
-| Mode | Entry point | Best for | Trade-off |
+| Approach | Entry point | Best for | Trade-off |
 |------|-------------|----------|-----------|
-| **Runtime** | `tasty()` from `@tenphi/tasty` | Interactive apps, design systems | CSS generated at runtime; full feature set (styleProps, sub-elements, variants) |
+| **Runtime** | `tasty()` from `@tenphi/tasty` | Interactive apps with reusable stateful components, design systems | CSS generated at runtime; full feature set (styleProps, sub-elements, variants) |
 | **Zero-runtime** | `tastyStatic()` from `@tenphi/tasty/static` | Static sites, landing pages, SSG | Zero JS overhead; requires Babel plugin; no dynamic props |
-| **SSR** | `@tenphi/tasty/ssr/next` or `@tenphi/tasty/ssr/astro` | Next.js, Astro, streaming SSR | Runtime `tasty()` with server-rendered CSS and zero-cost hydration |
 
-All three share the same DSL, tokens, units, and state mappings.
+Both share the same DSL, tokens, units, and state mappings.
 
 - Runtime is the default and requires no extra setup beyond `@tenphi/tasty`.
+- If your framework can execute runtime code during server rendering, add SSR support on top of runtime with `@tenphi/tasty/ssr/next`, `@tenphi/tasty/ssr/astro`, or the core SSR API. This still uses `tasty()`; it just collects CSS on the server and hydrates the cache on the client.
 - Zero-runtime requires the Babel plugin and additional peer dependencies. See [Zero Runtime (tastyStatic)](tasty-static.md).
-- SSR works with existing `tasty()` components — wrap your app with a registry or middleware. See [Server-Side Rendering](ssr.md).
+- SSR works with existing `tasty()` components — wrap your app with a registry, middleware, or collector. See [Server-Side Rendering](ssr.md).
 
 ---
 
 ## Next steps
 
-- **[Docs Hub](README.md)** — Pick the next guide by role, rendering mode, or task
+- **[Docs Hub](README.md)** — Pick the next guide by role, styling approach, or task
 - **[Methodology](methodology.md)** — The recommended patterns for structuring Tasty components: sub-elements, styleProps, tokens, extension
 - **[Style DSL](dsl.md)** — State maps, tokens, units, extending semantics, keyframes, @property
 - **[Runtime API](runtime.md)** — `tasty()` factory, component props, variants, sub-elements, hooks
@@ -212,4 +214,4 @@ All three share the same DSL, tokens, units, and state mappings.
 
 - Styles are missing on first render: make sure the file that calls `configure()` is imported before any `tasty()` component renders.
 - Token or unit values are not what you expect: check your `configure({ tokens, units })` setup, then inspect the generated CSS variables with [Debug Utilities](debug.md).
-- You need zero-runtime or SSR instead of the default runtime path: use [Zero Runtime (tastyStatic)](tasty-static.md) or [Server-Side Rendering](ssr.md) rather than trying to retrofit the runtime setup later.
+- You need build-time extraction or server-rendered CSS delivery: use [Zero Runtime (tastyStatic)](tasty-static.md) for extraction, or add [Server-Side Rendering](ssr.md) on top of runtime `tasty()` when your framework renders on the server.

package/docs/tasty/methodology.md

@@ -1,11 +1,13 @@
 # Methodology
 
-Tasty has opinions about how components should be structured. The patterns described here are not mandatory — Tasty works without them — but following them gets the most out of the engine: better state resolution, cleaner component APIs, simpler overrides, and fewer surprises as the system grows.
+Tasty has opinions about how components should be structured. The patterns described here are not mandatory — Tasty works without them — but following them gets the most out of the engine: deterministic state resolution, cleaner component APIs, simpler overrides, and fewer surprises as the system grows.
 
 ---
 
 ## Component architecture: root + sub-elements
 
+This model matters most for design-system authors and platform teams building reusable, stateful components. It turns Tasty's selector guarantees into a component architecture that stays predictable as states, variants, and compound parts accumulate.
+
 ### The model
 
 Every Tasty component has a **root element** and zero or more **sub-elements**. The root owns the state context. Sub-elements participate in the same context by default.
@@ -161,6 +163,61 @@ Exposing every CSS property as a prop defeats the purpose of a design system. Th
 
 ---
 
+## modProps and mods
+
+`modProps` expose modifier keys as top-level component props — the modifier equivalent of `styleProps`. Use them when a component has a fixed set of known state modifiers.
+
+```tsx
+const Card = tasty({
+  modProps: {
+    isLoading: Boolean,
+    isSelected: Boolean,
+  },
+  styles: {
+    fill: { '': '#surface', isLoading: '#surface.5' },
+    border: { '': '1bw solid #outline', isSelected: '2bw solid #primary' },
+  },
+});
+
+// Clean prop API — no mods object needed
+<Card isLoading isSelected>Content</Card>
+```
+
+### When to use which
+
+| Pattern | Use when |
+|---|---|
+| `modProps` | The component has a fixed set of known boolean/string states that drive styles. Provides TypeScript autocomplete and a cleaner JSX API. |
+| `mods` prop | The component needs arbitrary or dynamic modifiers that aren't known at definition time. |
+| Both | Combine `modProps` for the known states and `mods` for ad-hoc overrides. Mod props take precedence. |
+| `styleProps` | Exposing CSS properties (layout, sizing) for customization — different from modifiers. |
+
+### Typed modProps vs array form
+
+The object form gives precise TypeScript types using JS constructors (`Boolean`, `String`, `Number`) or enum arrays:
+
+```tsx
+const Button = tasty({
+  modProps: {
+    isLoading: Boolean,
+    size: ['small', 'medium', 'large'] as const,
+  },
+  // ...
+});
+
+// TypeScript knows: isLoading?: boolean, size?: 'small' | 'medium' | 'large'
+```
+
+The array form is simpler but types all values as `ModValue`:
+
+```tsx
+modProps: ['isLoading', 'isSelected'] as const,
+```
+
+For the full API reference, see [Runtime — Mod Props](runtime.md#mod-props).
+
+---
+
 ## tokens prop for dynamic values
 
 Every Tasty component accepts a `tokens` prop that renders as inline CSS custom properties on the element. This is the mechanism for per-instance dynamic values.
@@ -400,8 +457,9 @@ See [Configuration](configuration.md) for the full `configure()` API.
 - **Use semantic transition names** (`transition: 'theme 0.3s'`) instead of listing CSS properties
 - **Use `elements` prop** to declare typed sub-components for compound components
 - **Use `styleProps`** to define what product engineers can customize
+- **Use `modProps`** to expose known modifier states as clean component props
 - **Use `tokens` prop** for per-instance dynamic values (progress, user color)
-- **Use modifiers** (`mods`) for state-driven style changes instead of runtime `styles` prop changes
+- **Use modifiers** (`mods` or `modProps`) for state-driven style changes instead of runtime `styles` prop changes
 
 ### Avoid
 
@@ -439,11 +497,19 @@ Tasty's enhanced properties provide concise syntax, better composability, and si
 // Bad: styles object changes every render
 <Card styles={{ padding: isCompact ? '2x' : '4x' }} />
 
-// Good: use modifiers
-<Card mods={{ compact: isCompact }} />
+// Good: use modifiers via modProps
+<Card isCompact={isCompact} />
+
+// Or via mods object
+<Card mods={{ isCompact }} />
 
 // In the component definition:
-padding: { '': '4x', compact: '2x' },
+const Card = tasty({
+  modProps: ['isCompact'] as const,
+  styles: {
+    padding: { '': '4x', isCompact: '2x' },
+  },
+});
 ```
 
 Modifiers are compiled into exclusive selectors once. Changing `styles` at runtime forces Tasty to regenerate and re-inject CSS.

package/docs/tasty/runtime.md

@@ -74,6 +74,86 @@ For predefined style prop lists (`FLOW_STYLES`, `POSITION_STYLES`, `DIMENSION_ST
 
 ---
 
+## Mod Props
+
+Use `modProps` to expose modifier keys as direct component props instead of requiring the `mods` object:
+
+```jsx
+// Before: mods object
+<Button mods={{ isLoading: true, size: 'large' }}>Submit</Button>
+
+// After: mod props
+<Button isLoading size="large">Submit</Button>
+```
+
+### Array form
+
+List modifier key names. Types default to `ModValue` (`boolean | string | number | undefined | null`):
+
+```jsx
+const Button = tasty({
+  modProps: ['isLoading', 'isSelected'] as const,
+  styles: {
+    fill: { '': '#surface', isLoading: '#surface.5' },
+    border: { '': '1bw solid #outline', isSelected: '2bw solid #primary' },
+  },
+});
+
+<Button isLoading isSelected>Submit</Button>
+// Renders: <button data-is-loading="" data-is-selected="">Submit</button>
+```
+
+### Object form (typed)
+
+Map modifier names to type descriptors for precise TypeScript types:
+
+```tsx
+const Button = tasty({
+  modProps: {
+    isLoading: Boolean,   // isLoading?: boolean
+    isSelected: Boolean,  // isSelected?: boolean
+    size: ['small', 'medium', 'large'] as const,  // size?: 'small' | 'medium' | 'large'
+  },
+  styles: {
+    padding: { '': '2x 4x', 'size=small': '1x 2x', 'size=large': '3x 6x' },
+    fill: { '': '#surface', isLoading: '#surface.5' },
+  },
+});
+
+<Button isLoading size="large">Submit</Button>
+// Renders: <button data-is-loading="" data-size="large">Submit</button>
+```
+
+Available type descriptors:
+
+| Descriptor | TypeScript type | Example |
+|---|---|---|
+| `Boolean` | `boolean` | `isLoading: Boolean` |
+| `String` | `string` | `label: String` |
+| `Number` | `number` | `count: Number` |
+| `['a', 'b'] as const` | `'a' \| 'b'` | `size: ['sm', 'md', 'lg'] as const` |
+
+### Merge with `mods`
+
+Mod props and the `mods` object can be used together. Mod props take precedence:
+
+```jsx
+<Button mods={{ isLoading: false, extra: true }} isLoading>
+// isLoading=true wins (from mod prop), extra=true preserved from mods
+```
+
+### When to use `modProps` vs `mods`
+
+| Use case | Recommendation |
+|---|---|
+| Component has a fixed set of known modifiers | `modProps` — cleaner API, better TypeScript autocomplete |
+| Component needs arbitrary/dynamic modifiers | `mods` — open-ended `Record<string, ModValue>` |
+| Both fixed and dynamic | Combine: `modProps` for known keys, `mods` for ad-hoc |
+
+For architecture guidance on when to use modifiers vs `styleProps`, see [Methodology — modProps and mods](methodology.md#modprops-and-mods).
+
+---
+
 ## Variants
 
 Define named style variations. Only CSS for variants actually used at runtime is injected:
@@ -178,31 +258,7 @@ const Card = tasty({
 
 ### 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 }
-```
+The `$` property inside a sub-element's styles controls how its selector attaches to the root selector — combinators, HTML tags, pseudo-elements, the `@` placeholder, and more. For the full reference table and injection rules, see [DSL — Selector Affix](dsl.md#selector-affix-).
 
 For the mental model behind sub-elements — how they share root state context and how this differs from BEM — see [Methodology — Component architecture](methodology.md#component-architecture-root--sub-elements).
 

package/docs/tasty/ssr.md

@@ -1,6 +1,6 @@
 # Server-Side Rendering (SSR)
 
-Tasty supports server-side rendering with zero-cost client hydration. Your existing `tasty()` components work unchanged -- SSR is opt-in and requires no per-component modifications. For the broader docs map, see the [Docs Hub](README.md).
+Tasty supports server-side rendering with zero-cost client hydration. This does **not** introduce a separate styling engine: SSR uses the same runtime `tasty()` pipeline you already use on the client, then adds server-side CSS collection and client-side cache hydration. Your existing `tasty()` components work unchanged, and SSR remains opt-in with no per-component modifications. For the broader docs map, see the [Docs Hub](README.md).
 
 ---
 
@@ -18,7 +18,7 @@ The Astro integration (`@tenphi/tasty/ssr/astro`) has no additional dependencies
 
 ## How It Works
 
-During server rendering, `useStyles()` detects a `ServerStyleCollector` and collects CSS into it instead of trying to access the DOM. The collector accumulates all styles, serializes them as `<style>` tags and a cache state script in the HTML. On the client, `hydrateTastyCache()` pre-populates the injector cache so that `useStyles()` skips the rendering pipeline entirely during hydration.
+When the environment can execute runtime React code during server rendering, the same `tasty()` and `useStyles()` calls can run there too. In Next.js, generic React SSR, and Astro islands, Tasty simply changes where that runtime-generated CSS goes: `useStyles()` detects a `ServerStyleCollector` and collects CSS into it instead of trying to access the DOM. The collector accumulates all styles, serializes them as `<style>` tags and a cache state script in the HTML. On the client, `hydrateTastyCache()` pre-populates the injector cache so that `useStyles()` skips the rendering pipeline entirely during hydration.
 
 ```
 Server                         Client

package/docs/tasty/styles.md

@@ -146,37 +146,39 @@ Individual props `marginTop`, `marginRight`, `marginBottom`, `marginLeft`, `marg
 
 ### `width`
 
-Element width with min/max control.
+Element width with min/max control. One, two, or three values set `min-width`, `width`, and `max-width` together.
 
-**Syntax:** `[value]` | `[min max]` | `[min value max]` | `[modifier value]`
+**Positional syntax:**
 
-**Modifiers:** `min`, `max`, `fixed`
+| Value | min-width | width | max-width |
+|-------|-----------|-------|-----------|
+| `"10x"` | initial | `10x` | initial |
+| `"1x 10x"` | `1x` | auto | `10x` |
+| `"1x 5x 10x"` | `1x` | `5x` | `10x` |
+| `"0 100% 800px"` | `0` | `100%` | `800px` |
+| `"initial 100% 1400px"` | initial | `100%` | `1400px` |
+
+**Modifier syntax:**
+
+| Value | min-width | width | max-width |
+|-------|-----------|-------|-----------|
+| `"min 2x"` | `2x` | auto | initial |
+| `"max 100%"` | initial | auto | `100%` |
+| `"fixed 200px"` | `200px` | `200px` | `200px` |
 
 **Keywords:** `stretch`, `max-content`, `min-content`, `fit-content`
 
 | Value | Effect |
 |-------|--------|
-| `"10x"` | Width `10x`, min `initial`, max `initial` |
-| `"1x 10x"` | Width `auto`, min `1x`, max `10x` |
-| `"1x 5x 10x"` | Min `1x`, width `5x`, max `10x` |
-| `"min 2x"` | Min-width `2x`, width `auto`, max `initial` |
-| `"max 100%"` | Max-width `100%`, width `auto`, min `initial` |
-| `"fixed 200px"` | Min, width, and max all set to `200px` |
 | `"stretch"` | Fill available space (cross-browser) |
-| `true` | Width `auto`, min `initial`, max `initial` |
+| `true` | Reset to `auto` / `initial` / `initial` |
 | Number | Converted to `px` |
 
 Separate `minWidth` and `maxWidth` props are supported and override values from the `width` syntax.
 
 ### `height`
 
-Element height. Same syntax and modifiers as `width`.
-
-**Syntax:** `[value]` | `[min max]` | `[min value max]` | `[modifier value]`
-
-**Modifiers:** `min`, `max`, `fixed`
-
-**Keywords:** `max-content`, `min-content`, `fit-content`
+Element height. Same syntax, modifiers, and positional patterns as `width`.
 
 Separate `minHeight` and `maxHeight` props are supported and override values from the `height` syntax.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.124.0",
+  "version": "0.124.2",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {
@@ -45,7 +45,7 @@
     "@react-types/shared": "^3.32.1",
     "@tabler/icons-react": "^3.31.0",
     "@tanstack/react-virtual": "^3.13.12",
-    "@tenphi/tasty": "0.14.0",
+    "@tenphi/tasty": "0.15.2",
     "clipboard-copy": "^4.0.1",
     "clsx": "^1.1.1",
     "diff": "^8.0.3",