@tenphi/tasty 0.10.1 → 0.12.0

package/docs/runtime.md

@@ -0,0 +1,291 @@
+# Runtime API
+
+The React-specific `tasty()` component factory, component props, and hooks. For the shared style language (state maps, tokens, units, extending semantics), see [Style DSL](dsl.md). For global configuration, see [Configuration](configuration.md).
+
+---
+
+## Component Creation
+
+### Create a new component
+
+```jsx
+import { tasty } from '@tenphi/tasty';
+
+const Card = tasty({
+  as: 'div',
+  styles: {
+    padding: '4x',
+    fill: '#white',
+    border: true,
+    radius: true,
+  },
+  styleProps: ['padding', 'fill'],
+});
+
+<Card>Hello World</Card>
+<Card padding="6x" fill="#gray.05">Custom Card</Card>
+```
+
+### Extend an existing component
+
+```jsx
+const PrimaryButton = tasty(Button, {
+  styles: {
+    fill: '#purple',
+    color: '#white',
+    padding: '2x 4x',
+  },
+});
+```
+
+Style maps merge intelligently — see [Style DSL — Extending vs. Replacing State Maps](dsl.md#extending-vs-replacing-state-maps) for extend mode, replace mode, `@inherit`, `null`, and `false` tombstones.
+
+---
+
+## 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>
+```
+
+Style props accept state maps, so responsive values work through the same API:
+
+```jsx
+<FlexibleBox
+  gap={{ '': '2x', '@tablet': '4x' }}
+  fill={{ '': '#surface', '@dark': '#surface-dark' }}
+>
+```
+
+For predefined style prop lists (`FLOW_STYLES`, `POSITION_STYLES`, `DIMENSION_STYLES`, etc.) and guidance on which props to expose per component category, see [Methodology — styleProps as the public API](methodology.md#styleprops-as-the-public-api).
+
+---
+
+## Variants
+
+Define named style variations. Only CSS for variants actually used at runtime is injected:
+
+```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',
+    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.
+
+> 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',
+  },
+});
+
+<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 }
+```
+
+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).
+
+---
+
+## Hooks
+
+### useStyles
+
+Generate a className from a style object:
+
+```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
+
+Inject global styles for a CSS selector:
+
+```tsx
+import { useGlobalStyles } from '@tenphi/tasty';
+
+function ThemeStyles() {
+  useGlobalStyles('.card', {
+    padding: '4x',
+    fill: '#surface',
+    radius: '1r',
+  });
+
+  return null;
+}
+```
+
+### useRawCSS
+
+Inject raw CSS strings:
+
+```tsx
+import { useRawCSS } from '@tenphi/tasty';
+
+function GlobalReset() {
+  useRawCSS(`
+    body { margin: 0; padding: 0; }
+  `);
+
+  return null;
+}
+```
+
+### useMergeStyles
+
+Merge multiple style objects for compound component prop forwarding:
+
+```tsx
+import { useMergeStyles } from '@tenphi/tasty';
+
+function MyTabs({ styles, tabListStyles, prefixStyles }) {
+  const mergedStyles = useMergeStyles(styles, {
+    TabList: tabListStyles,
+    Prefix: prefixStyles,
+  });
+
+  return <TabsElement styles={mergedStyles} />;
+}
+```
+
+---
+
+## Learn more
+
+- **[Style DSL](dsl.md)** — State maps, tokens, units, extending semantics, keyframes, @property
+- **[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
+- **[Server-Side Rendering](ssr.md)** — SSR setup for Next.js, Astro, and generic frameworks

package/docs/ssr.md

@@ -2,7 +2,17 @@
 
 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.
 
-**Requires React 19+.**
+---
+
+## Requirements
+
+| Dependency | Version | Required for |
+|---|---|---|
+| `react` | >= 18 | All SSR entry points (peer dependency of `@tenphi/tasty`) |
+| `next` | >= 13 | Next.js integration (`@tenphi/tasty/ssr/next`) — App Router with `useServerInsertedHTML` |
+| Node.js | >= 20 | Generic / streaming SSR (`@tenphi/tasty/ssr`) — uses `node:async_hooks` for `AsyncLocalStorage` |
+
+The Astro integration (`@tenphi/tasty/ssr/astro`) has no additional dependencies beyond `react`.
 
 ---
 

package/docs/styles.md

@@ -344,7 +344,7 @@ Box shadow. Supports multiple shadows comma-separated.
 
 | Value | Effect |
 |-------|--------|
-| `true` | Default shadow (from `$shadow` token) |
+| `true` | Default shadow (uses `var(--shadow)` — define a `$shadow` token in your design system) |
 | `"1x .5x .5x #dark.50"` | Custom shadow with Tasty units/colors |
 | `"0 1x 2x #dark.20"` | Standard shadow |
 | `"inset 0 1x 2x #dark.10"` | Inset shadow |
@@ -511,7 +511,7 @@ Scrollbar styling using CSS standard properties (`scrollbar-width`, `scrollbar-c
 
 **Colors:** Up to 2 color values for thumb and track (optional), applied via `scrollbar-color`.
 
-**Defaults:** When no colors are specified, the thumb color comes from the `#scrollbar-thumb` token (`#text.5`) and the track color from the `#scrollbar-track` token (`#dark-bg`). These tokens are provided by the base token set. If the base tokens are not loaded, the track falls back to `transparent` via a CSS fallback, while the thumb has no CSS-level fallback — the browser treats the entire `scrollbar-color` declaration as invalid and reverts to the platform-default scrollbar appearance.
+**Defaults:** When no colors are specified, the thumb color comes from `var(--scrollbar-thumb-color)` and the track color from `var(--scrollbar-track-color, transparent)`. These are not built-in — your design system should define `#scrollbar-thumb` and `#scrollbar-track` tokens (e.g. `'#text.5'` and `'#dark-bg'`). If neither token is defined, the track falls back to `transparent` via a CSS fallback, while the thumb has no CSS-level fallback — the browser treats the entire `scrollbar-color` declaration as invalid and reverts to the platform-default scrollbar appearance.
 
 **Note:** `none` takes precedence over all other modifiers and colors. Combining `none` with other tokens (e.g., `"none always #red"`) produces a warning, and only `scrollbar-width: none` is applied.
 

package/docs/tasty-static.md

@@ -11,9 +11,30 @@
 - **Performance-critical pages** — Zero runtime overhead for styling
 - **Landing pages** — Minimal bundle size with pre-generated CSS
 
-## Quick Start
+## Requirements
+
+The zero-runtime mode is part of the main `@tenphi/tasty` package but requires additional peer dependencies depending on your setup:
+
+| Dependency | Version | Required for |
+|---|---|---|
+| `@babel/core` | >= 7.24 | Babel plugin (`@tenphi/tasty/babel-plugin`) |
+| `@babel/helper-plugin-utils` | >= 7.24 | Babel plugin |
+| `@babel/types` | >= 7.24 | Babel plugin |
+| `jiti` | >= 2.6 | Next.js wrapper (`@tenphi/tasty/next`) when using `configFile` option |
+
+All of these are declared as optional peer dependencies of `@tenphi/tasty`. Install only what your setup requires:
+
+```bash
+# For any Babel-based setup (Vite, custom Babel config, etc.)
+pnpm add -D @babel/core @babel/helper-plugin-utils @babel/types
+
+# For Next.js with TypeScript config file
+pnpm add -D @babel/core @babel/helper-plugin-utils @babel/types jiti
+```
+
+---
 
-The zero-runtime mode is part of the main `@tenphi/tasty` package. No additional packages required.
+## Quick Start
 
 ### Basic Usage
 
@@ -134,6 +155,9 @@ module.exports = {
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `output` | `string` | `'tasty.css'` | Path for generated CSS file |
+| `configFile` | `string` | — | Absolute path to a TS/JS module that default-exports a `TastyZeroConfig` object. JSON-serializable alternative to `config` — required for Turbopack. |
+| `config` | `TastyZeroConfig \| () => TastyZeroConfig` | `{}` | Inline config object or factory function. Takes precedence over `configFile`. |
+| `configDeps` | `string[]` | `[]` | Absolute file paths that affect config (for cache invalidation) |
 | `config.states` | `Record<string, string>` | `{}` | Predefined state aliases |
 | `config.devMode` | `boolean` | `false` | Add source comments to CSS |
 | `config.recipes` | `Record<string, RecipeStyles>` | `{}` | Predefined style recipes |
@@ -176,23 +200,43 @@ const card = tastyStatic({
 
 ## Next.js Integration
 
-```javascript
-// next.config.js
-const { withTastyZero } = require('@tenphi/tasty/next');
+The `withTastyZero` wrapper configures both **webpack** and **Turbopack** automatically. No `--webpack` flag is needed — it works with whichever bundler Next.js uses.
+
+```typescript
+// next.config.ts
+import { withTastyZero } from '@tenphi/tasty/next';
 
-module.exports = withTastyZero({
+export default withTastyZero({
   output: 'public/tasty.css',
-  config: {
-    states: {
-      '@mobile': '@media(w < 768px)',
-    },
-    devMode: process.env.NODE_ENV === 'development',
-  },
+  configFile: './app/tasty-zero.config.ts',
+  configDeps: ['./app/theme.ts'],
 })({
   reactStrictMode: true,
 });
 ```
 
+### `withTastyZero` Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `output` | `string` | `'public/tasty.css'` | Output path for CSS relative to project root |
+| `enabled` | `boolean` | `true` | Enable/disable the plugin |
+| `configFile` | `string` | — | Path to a TS/JS module that default-exports `TastyZeroConfig`. Recommended for Turbopack compatibility. |
+| `config` | `TastyZeroConfig` | — | Inline config object. For static configs that don't change during dev. |
+| `configDeps` | `string[]` | `[]` | Extra files the config depends on (for cache invalidation) |
+
+### Turbopack Support
+
+Starting with Next.js 16, Turbopack is the default bundler. `withTastyZero` supports it out of the box by injecting `turbopack.rules` with `babel-loader` and JSON-serializable options.
+
+The `configFile` option is key for Turbopack — it passes a file path (JSON-serializable) instead of a function, and the Babel plugin loads the config internally via jiti.
+
+**Requirements**: `babel-loader` must be installed in your project:
+
+```bash
+pnpm add babel-loader
+```
+
 ### Including the CSS
 
 ```tsx
@@ -372,5 +416,6 @@ const card = tastyStatic({
 
 ## Related
 
-- [Usage Guide](usage.md) — Runtime styling: component creation, state mappings, sub-elements, variants, and hooks
+- [Style DSL](dsl.md) — State maps, tokens, units, extending semantics (shared by runtime and static)
+- [Runtime API](runtime.md) — Runtime styling: `tasty()` factory, component props, variants, sub-elements, hooks
 - [Configuration](configuration.md) — Global configuration: tokens, recipes, custom units, and style handlers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/tasty",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "A design-system-integrated styling system and DSL for concise, state-aware UI styling",
   "type": "module",
   "main": "./dist/index.js",
@@ -92,7 +92,8 @@
     "@babel/core": "^7.24.0",
     "@babel/helper-plugin-utils": "^7.24.0",
     "@babel/types": "^7.24.0",
-    "react": "^18.0.0 || ^19.0.0"
+    "react": "^18.0.0 || ^19.0.0",
+    "jiti": "^2.6.1"
   },
   "peerDependenciesMeta": {
     "@babel/core": {
@@ -106,11 +107,13 @@
     },
     "react": {
       "optional": true
+    },
+    "jiti": {
+      "optional": true
     }
   },
   "dependencies": {
-    "csstype": "^3.1.0",
-    "jiti": "^2.6.1"
+    "csstype": "^3.1.0"
   },
   "devDependencies": {
     "@babel/core": "^7.24.0",
@@ -176,7 +179,7 @@
         "path",
         "crypto"
       ],
-      "limit": "37 kB"
+      "limit": "38 kB"
     }
   ],
   "scripts": {

package/dist/tokens/typography.d.ts

@@ -1,19 +0,0 @@
-//#region src/tokens/typography.d.ts
-/**
- * Typography preset configuration.
- * Each preset defines font properties that get expanded into CSS custom properties.
- */
-interface TypographyPreset {
-  fontSize: string;
-  lineHeight: string;
-  letterSpacing?: string;
-  fontWeight: string | number;
-  boldFontWeight?: string | number;
-  iconSize?: string;
-  textTransform?: string;
-  fontFamily?: string;
-  fontStyle?: string;
-}
-//#endregion
-export { TypographyPreset };
-//# sourceMappingURL=typography.d.ts.map