@tenphi/tasty 0.14.2 → 0.15.1

package/docs/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:

package/docs/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": "@tenphi/tasty",
-  "version": "0.14.2",
+  "version": "0.15.1",
   "description": "A design-system-integrated styling system and DSL for concise, state-aware UI styling",
   "type": "module",
   "main": "./dist/index.js",