@tenphi/tasty 0.0.0-snapshot.056b911

package/docs/configuration.md

@@ -0,0 +1,389 @@
+# Configuration
+
+Configure the Tasty style system before your app renders using the `configure()` function. Configuration must be done **before any styles are generated** (before first render). For a higher-level docs map, see the [Docs Hub](README.md).
+
+```jsx
+import { configure } from '@tenphi/tasty';
+
+configure({
+  // CSP nonce for style elements
+  nonce: 'abc123',
+
+  // Global state aliases
+  states: {
+    '@mobile': '@media(w < 768px)',
+    '@tablet': '@media(768px <= w < 1024px)',
+    '@dark': '@root(schema=dark)',
+  },
+
+  // Parser configuration
+  parserCacheSize: 2000, // LRU cache size (default: 1000)
+
+  // Custom units (merged with built-in units)
+  units: {
+    vh: 'vh',
+    vw: 'vw',
+    custom: (n) => `${n * 10}px`, // Function-based unit
+  },
+
+  // Custom functions for the parser
+  funcs: {
+    double: (groups) => {
+      const value = parseFloat(groups[0]?.output || '0');
+      return `${value * 2}px`;
+    },
+  },
+});
+```
+
+These docs use `data-schema="dark"` in examples. If your app already standardizes on a different attribute such as `data-theme`, keep the same pattern and swap the attribute name consistently everywhere you define root-state aliases.
+
+---
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `nonce` | `string` | - | CSP nonce for style elements |
+| `states` | `Record<string, string>` | - | Global state aliases for advanced state mapping |
+| `parserCacheSize` | `number` | `1000` | Parser LRU cache size |
+| `units` | `Record<string, string \| Function>` | Built-in | Custom units (merged with built-in). See [built-in units](dsl.md#built-in-units) |
+| `funcs` | `Record<string, Function>` | - | Custom parser functions (merged with existing) |
+| `handlers` | `Record<string, StyleHandlerDefinition>` | Built-in | Custom style handlers (replace built-in) |
+| `tokens` | `Record<string, value \| stateMap>` | - | Design tokens injected as `:root` CSS custom properties |
+| `replaceTokens` | `Record<string, string \| number>` | - | Parse-time token substitution (inline replacement) |
+| `keyframes` | `Record<string, KeyframesSteps>` | - | Global keyframes for animations |
+| `properties` | `Record<string, PropertyDefinition>` | - | Global CSS @property definitions |
+| `fontFace` | `Record<string, FontFaceInput>` | - | Global @font-face definitions |
+| `counterStyle` | `Record<string, CounterStyleDescriptors>` | - | Global @counter-style definitions |
+| `autoPropertyTypes` | `boolean` | `true` | Auto-infer and register `@property` types from values |
+| `recipes` | `Record<string, RecipeStyles>` | - | Predefined style recipes (named style bundles) |
+| `presets` | `Record<string, TypographyPreset>` | - | Typography presets — shorthand for `generateTypographyTokens()` |
+| `bodyStyles` | `Styles` | - | Tasty styles applied to the `body` tag |
+| `colorSpace` | `'rgb' \| 'hsl' \| 'oklch'` | `'oklch'` | Color space for decomposed color token companion variables |
+
+---
+
+## Color Space
+
+Controls the CSS color space used for decomposed color token companion variables. When you define `#name` color tokens, tasty generates both `--name-color` (full color) and `--name-color-{suffix}` (decomposed components for alpha composition).
+
+```jsx
+configure({
+  colorSpace: 'oklch', // default
+});
+```
+
+| Color Space | Suffix | Components Format | Alpha Syntax |
+|---|---|---|---|
+| `rgb` | `-rgb` | `255 128 0` | `rgb(var(--name-color-rgb) / .5)` |
+| `hsl` | `-hsl` | `300 100% 25%` | `hsl(var(--name-color-hsl) / .5)` |
+| `oklch` | `-oklch` | `0.42 0.16 328` | `oklch(var(--name-color-oklch) / .5)` |
+
+The `oklch` color space is the default because it provides perceptually uniform color manipulation — alpha fading and color mixing produce more natural-looking results.
+
+---
+
+## Design Tokens
+
+Design tokens define CSS custom properties on `:root`. They are injected automatically when the first style is rendered. Values are parsed through the Tasty DSL, so you can use units, color syntax, and other DSL features.
+
+Tokens support state maps for responsive or theme-aware values:
+
+```jsx
+configure({
+  tokens: {
+    '$gap': '4px',
+    '$radius': '6px',
+    '#primary': {
+      '': '#purple',
+      '@dark': '#light-purple',
+    },
+    '$font-size': {
+      '': '14px',
+      '@mobile': '12px',
+    },
+  },
+});
+```
+
+- `$name` keys become `--name` CSS custom properties
+- `#name` keys become `--name-color` and `--name-color-{colorSpace}` properties (suffix depends on `colorSpace`, default `oklch`)
+
+Tokens are automatically emitted in all rendering modes: runtime (client), SSR, and zero-runtime (Babel plugin).
+
+---
+
+## Replace Tokens (Parse-Time Substitution)
+
+Replace tokens are **substituted inline at parse time** — they are baked into the generated CSS, not resolved via CSS custom properties at runtime. This makes them ideal for value aliases and shorthand references.
+
+Use `$name` for value tokens and `#name` for color token aliases:
+
+```jsx
+configure({
+  replaceTokens: {
+    $spacing: '2x',
+    '$card-padding': '4x',
+    '#accent': '#purple',
+    '#surface-hover': '#gray.05',
+  },
+});
+```
+
+When a component uses `padding: '$card-padding'`, the parser replaces it with `'4x'` before generating CSS. When a component uses `fill: '#accent'`, it is replaced with `'#purple'`, which in turn resolves to `var(--purple-color)`.
+
+See [Replace Tokens](dsl.md#replace-tokens) in the Style DSL reference.
+
+---
+
+## Font Face
+
+Register custom fonts globally so every component can reference them by family name. Values are descriptor objects or arrays (for multiple weights/styles). Rules are injected eagerly when styles are first generated.
+
+```ts
+configure({
+  fontFace: {
+    'Brand Sans': [
+      {
+        src: 'url("/fonts/brand-regular.woff2") format("woff2")',
+        fontWeight: 400,
+        fontDisplay: 'swap',
+      },
+      {
+        src: 'url("/fonts/brand-bold.woff2") format("woff2")',
+        fontWeight: 700,
+        fontDisplay: 'swap',
+      },
+    ],
+    Icons: {
+      src: 'url("/fonts/icons.woff2") format("woff2")',
+      fontDisplay: 'block',
+    },
+  },
+});
+```
+
+Now any component can use `fontFamily: '"Brand Sans", sans-serif'` and the browser will already have the `@font-face` rules in the stylesheet.
+
+See [Font Face (`@fontFace`)](dsl.md#font-face-fontface) for inline usage inside component styles and the full list of supported descriptors.
+
+---
+
+## Counter Style
+
+Define custom list-marker algorithms globally. Rules are injected eagerly when styles are first generated.
+
+```ts
+configure({
+  counterStyle: {
+    thumbs: {
+      system: 'cyclic',
+      symbols: '"👍"',
+      suffix: '" "',
+    },
+    'lower-roman-parens': {
+      system: 'extends lower-roman',
+      suffix: '") "',
+    },
+  },
+});
+```
+
+Components can then reference `listStyleType: 'thumbs'` directly.
+
+See [Counter Style (`@counterStyle`)](dsl.md#counter-style-counterstyle) for inline usage inside component styles and the full list of supported descriptors.
+
+---
+
+## Recipes
+
+Recipes are predefined, named style bundles. Define them globally via `configure()`:
+
+```jsx
+configure({
+  recipes: {
+    card: {
+      padding: '4x',
+      fill: '#surface',
+      radius: '1r',
+      border: true,
+    },
+    elevated: {
+      shadow: '2x 2x 4x #shadow',
+    },
+  },
+});
+```
+
+Recipe values are flat tasty styles (no sub-element keys). They may contain base styles, tokens, local states, `@keyframes`, and `@properties`. Recipes cannot reference other recipes.
+
+For how to apply, compose, and override recipes in components, see [Recipes](dsl.md#recipes) in the Style DSL reference.
+
+---
+
+## Typography Presets
+
+Typography presets are a shorthand for `generateTypographyTokens()`. Instead of calling the function manually and spreading the result into `tokens`, pass the presets directly:
+
+```jsx
+configure({
+  presets: {
+    h1: { fontSize: '32px', lineHeight: '1.2', fontWeight: '700' },
+    t2: { fontSize: '16px', lineHeight: '1.5', fontWeight: '400' },
+    tag: {
+      fontSize: '10px',
+      lineHeight: '1.4',
+      letterSpacing: '0.04em',
+      fontWeight: '600',
+    },
+  },
+});
+```
+
+Each preset generates `$name-font-size`, `$name-line-height`, `$name-letter-spacing`, `$name-font-weight`, and optional `$name-bold-font-weight`, `$name-icon-size`, `$name-text-transform`, `$name-font-family`, `$name-font-style` tokens.
+
+Preset values support state maps for responsive or theme-aware typography:
+
+```jsx
+configure({
+  presets: {
+    t2: {
+      fontSize: '16px',
+      lineHeight: '1.5',
+      fontWeight: { '': '400', '@dark': '300' },
+    },
+  },
+});
+```
+
+The generated tokens are merged **under** explicit `tokens` — if both `presets` and `tokens` define `$t2-font-weight`, the `tokens` value wins. Plugins can also provide `presets`; plugin presets are merged first, then config presets, then explicit tokens on top.
+
+---
+
+## Body Styles
+
+Apply Tasty styles to the `body` element via configuration, without needing `useGlobalStyles('body', ...)` at runtime:
+
+```jsx
+configure({
+  bodyStyles: {
+    fill: '#surface',
+    color: '#text',
+    preset: 't2',
+    margin: 0,
+    fontFamily: 'system-ui, sans-serif',
+  },
+});
+```
+
+Body styles support the full Tasty style syntax including style properties, tokens, state maps, `@keyframes`, `@fontFace`, and sub-element selectors. They are injected alongside `:root` tokens when the first style is rendered.
+
+Body styles are automatically emitted in all rendering modes: runtime (client), SSR, and zero-runtime (Babel plugin). Plugins can also provide `bodyStyles`; they are merged with config body styles (config wins on conflict).
+
+---
+
+## Auto Property Types
+
+CSS cannot transition or animate custom properties unless their type is declared via [`@property`](https://developer.mozilla.org/en-US/docs/Web/CSS/@property). Tasty handles this automatically — when a custom property is assigned a concrete value (e.g. `'$scale': 1`, `'$gap': '10px'`, `'#accent': 'purple'`), the type is inferred and a `@property` rule is registered.
+
+This works across all declaration contexts: component styles, `@keyframes`, global config, and the zero-runtime Babel plugin. It also resolves `var()` chains — if `$a` references `var(--b)`, the type propagates once `--b` is resolved.
+
+Supported types:
+
+| Detection | Inferred syntax |
+|-----------|-----------------|
+| `1`, `0.5`, `-3` (bare numbers) | `<number>` |
+| `10px`, `2rem`, `100vw` (length units) | `<length>` |
+| `50%` | `<percentage>` |
+| `45deg`, `0.5turn` (angle units) | `<angle>` |
+| `300ms`, `1s` (time units) | `<time>` |
+| `#name` tokens (by naming convention) | `<color>` |
+
+Auto-inferred properties use `inherits: true` (the CSS default). Use explicit `@properties` when you need different settings:
+
+```jsx
+// In component styles
+styles: {
+  '@properties': {
+    '$scale': { syntax: '<number>', inherits: false, initialValue: 1 },
+  },
+}
+
+// Or globally
+configure({
+  properties: {
+    '$scale': { syntax: '<number>', inherits: false, initialValue: 1 },
+  },
+});
+```
+
+To disable auto-inference entirely (only explicit `@properties` will be used):
+
+```jsx
+configure({ autoPropertyTypes: false });
+```
+
+---
+
+## Custom Style Handlers
+
+Override or extend the built-in style property handlers. A handler definition can take three forms:
+
+| Form | Syntax | Description |
+|------|--------|-------------|
+| Function only | `handler` | Triggered by its key name; receives only that property |
+| Single dep | `['styleName', handler]` | Triggered by the specified style property |
+| Multi dep | `[['dep1', 'dep2', ...], handler]` | Triggered by any of the listed properties; receives all of them |
+
+The multi-dep form is useful when output depends on several style properties together (e.g., `gap` needs to know `display` and `flow` to decide the CSS strategy).
+
+```jsx
+import { configure, styleHandlers } from '@tenphi/tasty';
+
+configure({
+  handlers: {
+    // Function only — overrides built-in fill handler
+    fill: ({ fill }) => {
+      if (fill?.startsWith('gradient:')) {
+        return { background: fill.slice(9) };
+      }
+      return styleHandlers.fill({ fill });
+    },
+
+    // Function only — new single-prop handler
+    elevation: ({ elevation }) => {
+      const level = parseInt(elevation) || 1;
+      return {
+        'box-shadow': `0 ${level * 2}px ${level * 4}px rgba(0,0,0,0.1)`,
+        'z-index': String(level * 100),
+      };
+    },
+
+    // Multi dep — handler reads multiple style properties
+    gap: [['display', 'flow', 'gap'], ({ display, flow, gap }) => {
+      if (!gap) return;
+      const isGrid = display?.includes('grid');
+      return { gap: isGrid ? gap : `/* custom logic for ${flow} */` };
+    }],
+  },
+});
+```
+
+---
+
+## Extending Style Types (TypeScript)
+
+Use module augmentation to extend the `StylesInterface`:
+
+```tsx
+// tasty.d.ts
+declare module '@tenphi/tasty' {
+  interface StylesInterface {
+    elevation?: string;
+    gradient?: string;
+  }
+}
+```
+
+See [Style DSL](dsl.md) for state maps, tokens, units, and extending semantics, and [React API](react-api.md) for `tasty()`, style functions, and component props.

package/docs/debug.md

@@ -0,0 +1,318 @@
+# Tasty Debug Utilities
+
+Runtime CSS inspection and diagnostics for the Tasty styling system. Inspect injected styles, measure cache performance, analyze style chunks, and troubleshoot CSS issues — all from the browser console.
+
+---
+
+## Overview
+
+`tastyDebug` is a diagnostic object that exposes Tasty's runtime CSS state. It is designed for development use but can be manually installed in production for debugging.
+
+In development mode (`isDevEnv()` returns `true`), `tastyDebug` is automatically installed on `window.tastyDebug`. In production, install it manually when needed.
+
+All methods **log to the console by default**. Pass `{ raw: true }` to suppress logging and only return data.
+
+---
+
+## Quick Start
+
+```typescript
+// Auto-installed in dev mode. Otherwise:
+import { tastyDebug } from '@tenphi/tasty';
+tastyDebug.install();
+
+// Print a quick-start guide
+tastyDebug.help();
+
+// Get a comprehensive overview (logged automatically)
+tastyDebug.summary();
+
+// See all active CSS
+tastyDebug.css('active');
+
+// Inspect a specific element
+tastyDebug.inspect('.my-button');
+
+// Silent mode — return data only, no console output
+const data = tastyDebug.summary({ raw: true });
+```
+
+---
+
+## Options
+
+All methods accept a shared options object:
+
+```typescript
+interface DebugOptions {
+  root?: Document | ShadowRoot; // Target root (default: document)
+  raw?: boolean;                // Suppress console logging (default: false)
+}
+```
+
+When `raw` is `false` (the default), results are logged to the console **and** returned. When `raw` is `true`, results are returned silently.
+
+---
+
+## API Reference
+
+### `css(target, opts?): string`
+
+Retrieves CSS text for a given target. Logs the result with rule count and size.
+
+**Targets:**
+
+| Target | Description |
+|---|---|
+| `'all'` | All tasty CSS (component + global + raw) |
+| `'active'` | CSS for classes currently in the DOM |
+| `'unused'` | CSS with refCount = 0 (cached but not used) |
+| `'global'` | Only global CSS (from `injectGlobal`) |
+| `'page'` | All CSS on the page (including non-tasty) |
+| `'t42'` | CSS for a specific tasty class |
+| `['t0', 't5']` | CSS for multiple tasty classes |
+| `'.my-button'` | CSS affecting a DOM element (by selector) |
+| `element` | CSS affecting a DOM element (by reference) |
+
+**Extra options:**
+
+```typescript
+interface CssOptions extends DebugOptions {
+  prettify?: boolean; // Format output (default: true)
+  source?: boolean;   // Read original CSS instead of live CSSOM (default: false, dev-mode only)
+}
+```
+
+```typescript
+// Active CSS with stats
+tastyDebug.css('active');
+
+// Specific class, silent
+const css = tastyDebug.css('t42', { raw: true });
+
+// Compare original vs browser-parsed CSS (dev mode only)
+tastyDebug.css('t42');                    // live CSSOM
+tastyDebug.css('t42', { source: true }); // original output
+
+// Shadow DOM
+tastyDebug.css('all', { root: shadowRoot });
+```
+
+The `source` option reads from `RuleInfo.cssText`, which is only populated when `devMode` is active (development environment or `localStorage.TASTY_DEBUG = 'true'`). In production without debug mode, it falls back to the live CSSOM with a warning.
+
+---
+
+### `inspect(target, opts?): InspectResult`
+
+Inspects a DOM element and returns detailed information about its tasty styles, including chunk assignments.
+
+```typescript
+interface InspectResult {
+  element?: Element | null;
+  classes: string[];    // Tasty classes on the element
+  chunks: ChunkInfo[];  // Chunk assignment per class
+  css: string;          // Prettified CSS
+  size: number;         // CSS size in characters
+  rules: number;        // Number of CSS rule blocks
+}
+
+interface ChunkInfo {
+  className: string;
+  chunkName: string | null; // e.g., 'appearance', 'font', 'dimension'
+}
+```
+
+```typescript
+tastyDebug.inspect('.my-card');
+// Logs: inspect div — 3 classes, 5 rules, 1.2KB
+//       Chunks: t3→appearance, t7→font, t12→dimension
+
+// Silent
+const result = tastyDebug.inspect('.my-card', { raw: true });
+console.log(result.classes);  // ['t3', 't7', 't12']
+console.log(result.rules);    // 5
+```
+
+---
+
+### `summary(opts?): Summary`
+
+One-shot overview of the entire Tasty CSS state. Logs a compact report.
+
+```typescript
+interface Summary {
+  activeClasses: string[];
+  unusedClasses: string[];
+  totalStyledClasses: string[];
+
+  activeCSSSize: number;
+  unusedCSSSize: number;
+  globalCSSSize: number;
+  rawCSSSize: number;
+  keyframesCSSSize: number;
+  propertyCSSSize: number;
+  totalCSSSize: number;
+
+  activeRuleCount: number;
+  unusedRuleCount: number;
+  globalRuleCount: number;
+  rawRuleCount: number;
+  keyframesRuleCount: number;
+  propertyRuleCount: number;
+  totalRuleCount: number;
+
+  metrics: CacheMetrics | null;
+  definedProperties: string[];
+  definedKeyframes: { name: string; refCount: number }[];
+  chunkBreakdown: ChunkBreakdown;
+}
+```
+
+```typescript
+// Logged automatically
+tastyDebug.summary();
+// Output:
+//   Active:   42 classes, 186 rules, 12.4KB
+//   Unused:   3 classes, 8 rules, 0.5KB
+//   Global:   12 rules, 1.1KB
+//   Total:    45 classes, 206 rules, 14.0KB
+//   Cache:    94.2% hit rate (312 lookups)
+
+// Silent
+const s = tastyDebug.summary({ raw: true });
+console.log(s.totalRuleCount); // 206
+```
+
+---
+
+### `chunks(opts?): ChunkBreakdown`
+
+Breakdown of styles by chunk type.
+
+```typescript
+interface ChunkBreakdown {
+  byChunk: Record<string, {
+    classes: string[];
+    cssSize: number;
+    ruleCount: number;
+  }>;
+  totalChunkTypes: number;
+  totalClasses: number;
+}
+```
+
+```typescript
+tastyDebug.chunks();
+// Output:
+//   appearance: 24 cls, 48 rules, 3.2KB
+//   font: 18 cls, 18 rules, 1.1KB
+//   dimension: 31 cls, 45 rules, 2.4KB
+```
+
+Chunk types: `combined`, `appearance`, `font`, `dimension`, `display`, `layout`, `position`, `misc`, `subcomponents`.
+
+---
+
+### `cache(opts?): CacheStatus`
+
+Cache state and performance metrics.
+
+```typescript
+interface CacheStatus {
+  classes: {
+    active: string[];
+    unused: string[];
+    all: string[];
+  };
+  metrics: CacheMetrics | null;
+}
+```
+
+```typescript
+tastyDebug.cache();
+// Output:
+//   Active: 42, Unused: 3
+//   Hits: 294, Misses: 18, Rate: 94.2%
+```
+
+---
+
+### `cleanup(opts?): void`
+
+Forces immediate cleanup of all unused styles (those with `refCount = 0`).
+
+```typescript
+tastyDebug.cleanup();
+tastyDebug.cleanup({ root: shadowRoot });
+```
+
+---
+
+### `help(): void`
+
+Prints a quick-start guide to the console.
+
+```typescript
+tastyDebug.help();
+```
+
+---
+
+### `install(): void`
+
+Attaches `tastyDebug` to `window.tastyDebug`. Called automatically in development mode.
+
+```typescript
+import { tastyDebug } from '@tenphi/tasty';
+tastyDebug.install();
+```
+
+---
+
+## Shadow DOM Support
+
+All methods accept a `root` option to target a Shadow DOM:
+
+```typescript
+const shadowRoot = host.shadowRoot;
+tastyDebug.css('all', { root: shadowRoot });
+tastyDebug.inspect('.shadow-component', { root: shadowRoot });
+tastyDebug.summary({ root: shadowRoot });
+```
+
+---
+
+## Common Workflows
+
+### Debugging a component's styles
+
+```typescript
+// 1. Inspect the element
+tastyDebug.inspect('.my-button');
+
+// 2. See CSS for a specific class
+tastyDebug.css('t3');
+
+// 3. Compare original vs browser-parsed (dev mode)
+tastyDebug.css('t3', { source: true });
+```
+
+### Checking cache efficiency
+
+```typescript
+const { metrics } = tastyDebug.cache({ raw: true });
+if (metrics) {
+  const total = metrics.hits + metrics.misses;
+  const rate = total > 0 ? ((metrics.hits / total) * 100).toFixed(1) : 0;
+  console.log(`Cache hit rate: ${rate}%`);
+}
+```
+
+### Monitoring CSS growth
+
+```typescript
+const s = tastyDebug.summary({ raw: true });
+console.log(`Total: ${s.totalRuleCount} rules, ${(s.totalCSSSize / 1024).toFixed(1)}KB`);
+console.log(`Active: ${s.activeRuleCount} rules`);
+console.log(`Unused: ${s.unusedRuleCount} rules`);
+```