@cube-dev/ui-kit 0.120.1 → 0.121.1

package/docs/tasty/configuration.md

@@ -0,0 +1,211 @@
+# 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).
+
+```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(theme=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`;
+    },
+  },
+});
+```
+
+---
+
+## 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](usage.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, string \| number>` | - | Predefined tokens replaced during parsing |
+| `keyframes` | `Record<string, KeyframesSteps>` | - | Global keyframes for animations |
+| `properties` | `Record<string, PropertyDefinition>` | - | Global CSS @property definitions |
+| `autoPropertyTypes` | `boolean` | `true` | Auto-infer and register `@property` types from values |
+| `recipes` | `Record<string, RecipeStyles>` | - | Predefined style recipes (named style bundles) |
+
+---
+
+## Predefined Tokens
+
+Define reusable tokens that are replaced during style parsing. Unlike component-level `tokens` prop (which renders as inline CSS custom properties), predefined tokens are baked into the generated CSS.
+
+Use `$name` for custom property tokens and `#name` for color tokens:
+
+```jsx
+configure({
+  tokens: {
+    $spacing: '2x',
+    '$card-padding': '4x',
+    '$button-height': '40px',
+    '#accent': '#purple',
+    '#surface': '#white',
+    '#surface-hover': '#gray.05',
+  },
+});
+```
+
+Once defined, tokens can be used in any component's styles — see [Using Predefined Tokens](usage.md#predefined-tokens) in the usage guide.
+
+---
+
+## 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 [Using Recipes](usage.md#recipes) in the usage guide.
+
+---
+
+## 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 [Usage Guide](usage.md) for component creation, state mappings, sub-elements, variants, and hooks.

package/docs/tasty/debug.md

@@ -0,0 +1,505 @@
+# 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 every aspect of Tasty's runtime CSS state. It is designed for development use: inspecting which CSS is active, what's cached, how chunks are distributed, and whether cleanup is working as expected.
+
+In development mode (`isDevEnv()` returns `true`), `tastyDebug` is automatically installed on `window.tastyDebug`. In production, you can install it manually when needed.
+
+> **Note:** This is a development/debugging tool. It does not affect style generation or application behavior.
+
+---
+
+## 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 to the console
+tastyDebug.summary({ log: true });
+
+// See all active CSS (for components currently in the DOM)
+tastyDebug.log('active');
+
+// Inspect a specific element
+tastyDebug.inspect('.my-button');
+
+// Check cache hit rates
+tastyDebug.metrics();
+```
+
+---
+
+## Core Types
+
+### `CSSTarget`
+
+The `target` parameter accepted by `css()`, `log()`, and related methods:
+
+```typescript
+type CSSTarget =
+  | 'all'       // All tasty CSS (component + global + raw)
+  | 'global'    // Only global CSS (from injectGlobal)
+  | 'active'    // CSS for classes currently present in the DOM
+  | 'unused'    // CSS with refCount = 0 (cached but not actively used)
+  | 'page'      // ALL CSS on the page, including non-tasty stylesheets
+  | string      // A tasty class ('t123') or a CSS selector ('.my-class')
+  | string[]    // Array of tasty classes (['t0', 't5', 't12'])
+  | Element;    // A DOM element
+```
+
+### `CssOptions`
+
+Common options for CSS retrieval methods:
+
+```typescript
+interface CssOptions {
+  root?: Document | ShadowRoot;  // Target root (default: document)
+  prettify?: boolean;            // Format CSS output (default: true)
+  log?: boolean;                 // Auto-log to console (default: false)
+}
+```
+
+---
+
+## API Reference
+
+### `css(target, opts?): string`
+
+Retrieves CSS text for a given target. This is the primary method for extracting CSS from the runtime.
+
+```typescript
+// All tasty CSS
+tastyDebug.css('all');
+
+// Only CSS for classes currently in the DOM
+tastyDebug.css('active');
+
+// CSS for unused classes (refCount = 0, still in cache)
+tastyDebug.css('unused');
+
+// Only global CSS (injected via injectGlobal)
+tastyDebug.css('global');
+
+// ALL CSS on the page (including non-tasty stylesheets)
+tastyDebug.css('page');
+
+// CSS for a specific tasty class
+tastyDebug.css('t42');
+
+// CSS for multiple tasty classes
+tastyDebug.css(['t0', 't5', 't12']);
+
+// CSS affecting a DOM element (by selector)
+tastyDebug.css('.my-button');
+
+// CSS affecting a DOM element (by reference)
+const el = document.querySelector('.my-button');
+tastyDebug.css(el);
+
+// With options
+tastyDebug.css('active', { prettify: false, log: true });
+
+// Shadow DOM
+const shadowRoot = host.shadowRoot;
+tastyDebug.css('all', { root: shadowRoot });
+```
+
+---
+
+### `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 found on the element (e.g., ['t0', 't5'])
+  chunks: ChunkInfo[];  // Chunk assignment per class
+  css: string;          // Prettified CSS affecting the element
+  size: number;         // CSS size in characters
+  rules: number;        // Number of CSS rule blocks
+}
+
+interface ChunkInfo {
+  className: string;       // e.g., 't0'
+  chunkName: string | null; // e.g., 'appearance', 'font', 'dimension'
+}
+```
+
+```typescript
+// By CSS selector
+const result = tastyDebug.inspect('.my-card');
+console.log(result.classes);  // ['t3', 't7', 't12']
+console.log(result.chunks);   // [{className: 't3', chunkName: 'appearance'}, ...]
+console.log(result.rules);    // 5
+console.log(result.css);      // prettified CSS
+
+// By element reference
+const el = document.querySelector('[data-element="Title"]');
+tastyDebug.inspect(el);
+
+// Shadow DOM
+tastyDebug.inspect('.shadow-component', { root: shadowRoot });
+```
+
+---
+
+### `cache(opts?): CacheStatus`
+
+Returns the current state of the style cache: which classes are active, which are unused, and performance metrics.
+
+```typescript
+interface CacheStatus {
+  classes: {
+    active: string[];  // Classes with refCount > 0 and present in DOM
+    unused: string[];  // Classes with refCount = 0 but still in cache
+    all: string[];     // Union of active and unused
+  };
+  metrics: CacheMetrics | null;
+}
+```
+
+```typescript
+const status = tastyDebug.cache();
+
+console.log(status.classes.active.length);  // 42
+console.log(status.classes.unused.length);  // 8
+console.log(status.metrics?.hits);          // 156
+```
+
+---
+
+### `cleanup(opts?): void`
+
+Forces immediate cleanup of all unused styles (those with `refCount = 0`).
+
+```typescript
+tastyDebug.cleanup();
+
+// Shadow DOM
+tastyDebug.cleanup({ root: shadowRoot });
+```
+
+---
+
+### `metrics(opts?): CacheMetrics | null`
+
+Returns performance metrics for the style cache. Only available when `devMode` is enabled.
+
+```typescript
+interface CacheMetrics {
+  hits: number;             // Successful cache hits
+  misses: number;           // New styles injected (cache misses)
+  bulkCleanups: number;     // Number of bulk cleanup operations
+  totalInsertions: number;  // Lifetime style insertions
+  totalUnused: number;      // Total styles marked as unused
+  stylesCleanedUp: number;  // Total styles removed by cleanup
+  startTime: number;        // Metrics collection start timestamp
+  unusedHits?: number;      // Reactivations of cached unused styles
+  cleanupHistory: {
+    timestamp: number;
+    classesDeleted: number;
+    cssSize: number;
+    rulesDeleted: number;
+  }[];
+}
+```
+
+```typescript
+const m = tastyDebug.metrics();
+
+if (m) {
+  const hitRate = ((m.hits + (m.unusedHits || 0)) / (m.hits + m.misses)) * 100;
+  console.log(`Cache hit rate: ${hitRate.toFixed(1)}%`);
+  console.log(`Total insertions: ${m.totalInsertions}`);
+  console.log(`Bulk cleanups: ${m.bulkCleanups}`);
+}
+```
+
+### `resetMetrics(opts?): void`
+
+Resets all performance metrics counters.
+
+```typescript
+tastyDebug.resetMetrics();
+```
+
+---
+
+### `chunks(opts?): ChunkBreakdown`
+
+Returns a breakdown of styles by chunk type. With style chunking enabled, styles are split into logical chunks (appearance, font, dimension, etc.) for better caching and CSS reuse.
+
+```typescript
+const breakdown = tastyDebug.chunks();
+
+console.log(breakdown.totalChunkTypes);  // 6
+console.log(breakdown.totalClasses);     // 87
+
+for (const [chunkName, data] of Object.entries(breakdown.byChunk)) {
+  console.log(`${chunkName}: ${data.classes.length} classes, ${data.cssSize}B`);
+}
+
+// Log a formatted breakdown to the console
+tastyDebug.chunks({ log: true });
+```
+
+Chunk types: `combined` (non-chunked), `appearance`, `font`, `dimension`, `display`, `layout`, `position`, `misc`, `subcomponents`.
+
+---
+
+### `getGlobalTypeCSS(type, opts?): { css: string; ruleCount: number; size: number }`
+
+Retrieves CSS for a specific global injection type.
+
+```typescript
+// CSS injected via injectGlobal()
+const global = tastyDebug.getGlobalTypeCSS('global');
+
+// CSS injected via injectRawCSS() / useRawCSS()
+const raw = tastyDebug.getGlobalTypeCSS('raw');
+
+// @keyframes CSS
+const keyframes = tastyDebug.getGlobalTypeCSS('keyframes');
+
+// @property CSS
+const properties = tastyDebug.getGlobalTypeCSS('property');
+
+console.log(`Global: ${global.ruleCount} rules, ${global.size}B`);
+console.log(`Raw: ${raw.ruleCount} rules, ${raw.size}B`);
+console.log(`Keyframes: ${keyframes.ruleCount} rules, ${keyframes.size}B`);
+console.log(`Properties: ${properties.ruleCount} rules, ${properties.size}B`);
+```
+
+---
+
+### `defs(opts?): Definitions`
+
+Returns all defined `@property` and `@keyframes` entries.
+
+```typescript
+interface Definitions {
+  properties: string[];  // Defined via @property (e.g., ['--primary-color', '--gap'])
+  keyframes: { name: string; refCount: number }[];
+}
+```
+
+```typescript
+const defs = tastyDebug.defs();
+
+console.log('Properties:', defs.properties);
+// ['--primary-color', '--surface-color', ...]
+
+console.log('Keyframes:', defs.keyframes);
+// [{ name: 'fadeIn', refCount: 2 }, { name: 'pulse', refCount: 1 }]
+```
+
+---
+
+### `summary(opts?): Summary`
+
+One-shot comprehensive overview of the entire Tasty CSS state. Returns detailed statistics and optionally logs a formatted report.
+
+```typescript
+interface SummaryOptions {
+  root?: Document | ShadowRoot;
+  log?: boolean;
+  includePageCSS?:
+    | false    // Do not include page-level CSS stats (default)
+    | true     // Include sizes/counts only
+    | 'all';   // Include stats and return full page CSS string
+}
+```
+
+The returned `Summary` object contains:
+
+- **Classes**: `activeClasses`, `unusedClasses`, `totalStyledClasses`
+- **CSS sizes**: `activeCSSSize`, `unusedCSSSize`, `globalCSSSize`, `rawCSSSize`, `keyframesCSSSize`, `propertyCSSSize`, `totalCSSSize`
+- **CSS payloads**: `activeCSS`, `unusedCSS`, `globalCSS`, `rawCSS`, `keyframesCSS`, `propertyCSS`, `allCSS`
+- **Rule counts**: `globalRuleCount`, `rawRuleCount`, `keyframesRuleCount`, `propertyRuleCount`
+- **Page CSS** (when `includePageCSS` is set): `page.cssSize`, `page.ruleCount`, `page.stylesheetCount`, `page.skippedStylesheets`
+- **Metrics & definitions**: `metrics`, `definedProperties`, `definedKeyframes`, `propertyCount`, `keyframeCount`
+- **Cleanup summary**: `cleanupSummary.totalCleanups`, `cleanupSummary.totalClassesDeleted`, `cleanupSummary.lastCleanup`, etc.
+- **Chunk breakdown**: `chunkBreakdown.byChunk`, `chunkBreakdown.totalChunkTypes`
+
+```typescript
+// Log a formatted report
+tastyDebug.summary({ log: true });
+
+// Get the data programmatically
+const s = tastyDebug.summary();
+console.log(`Active: ${s.activeClasses.length} classes, ${s.activeCSSSize}B`);
+console.log(`Unused: ${s.unusedClasses.length} classes, ${s.unusedCSSSize}B`);
+console.log(`Total CSS: ${s.totalCSSSize}B`);
+
+// Include page-level CSS stats
+const withPage = tastyDebug.summary({ includePageCSS: true });
+console.log(`Page CSS: ${withPage.page?.cssSize}B across ${withPage.page?.stylesheetCount} stylesheets`);
+```
+
+---
+
+### `pageCSS(opts?): string`
+
+Returns all CSS on the page across all stylesheets (not only tasty-generated CSS).
+
+```typescript
+// Get all page CSS
+const css = tastyDebug.pageCSS();
+
+// Log it
+tastyDebug.pageCSS({ log: true });
+
+// Raw (unformatted)
+tastyDebug.pageCSS({ prettify: false });
+
+// Exclude cross-origin stylesheet placeholders
+tastyDebug.pageCSS({ includeCrossOrigin: false });
+```
+
+### `pageStats(opts?): PageStats`
+
+Returns size and rule count statistics for all page CSS without extracting the full text.
+
+```typescript
+const stats = tastyDebug.pageStats();
+console.log(`${stats.cssSize}B across ${stats.stylesheetCount} stylesheets`);
+console.log(`${stats.ruleCount} rules, ${stats.skippedStylesheets} skipped (CORS)`);
+```
+
+---
+
+### `log(target, opts?): void`
+
+Logs CSS for a target to the console with formatted output, collapsible groups, and sub-element detection.
+
+```typescript
+// Log active CSS with stats header
+tastyDebug.log('active');
+
+// Log CSS for a specific class
+tastyDebug.log('t42');
+
+// Log with custom title
+tastyDebug.log('active', { title: 'Button styles' });
+
+// Log CSS for an element
+tastyDebug.log('.my-card');
+```
+
+The output includes:
+- Rule count, line count, and byte size
+- Sub-element breakdown (detects `[data-element="..."]` selectors)
+- Full CSS in a collapsible group
+
+---
+
+### `help(): void`
+
+Prints a quick-start guide to the console with available commands and common targets.
+
+```typescript
+tastyDebug.help();
+```
+
+---
+
+### `install(): void`
+
+Attaches `tastyDebug` to `window.tastyDebug` for console access. Called automatically in development mode.
+
+```typescript
+import { tastyDebug } from '@tenphi/tasty';
+
+// Manual install (e.g., in staging/production for debugging)
+tastyDebug.install();
+
+// Then use from the browser console:
+// > tastyDebug.summary({ log: true })
+```
+
+---
+
+## Common Workflows
+
+### Debugging a component's styles
+
+```typescript
+// 1. Find the element
+tastyDebug.inspect('.my-button');
+// → { classes: ['t3', 't7'], chunks: [...], css: '...', rules: 4 }
+
+// 2. See CSS for a specific class
+tastyDebug.log('t3');
+
+// 3. Check which chunk it belongs to
+tastyDebug.inspect('.my-button').chunks;
+// → [{ className: 't3', chunkName: 'appearance' }, { className: 't7', chunkName: 'font' }]
+```
+
+### Checking cache efficiency
+
+```typescript
+const m = tastyDebug.metrics();
+const hitRate = m ? ((m.hits + (m.unusedHits || 0)) / (m.hits + m.misses)) * 100 : 0;
+console.log(`Hit rate: ${hitRate.toFixed(1)}%`);
+console.log(`Unused style reactivations: ${m?.unusedHits}`);
+```
+
+### Monitoring CSS growth
+
+```typescript
+const s = tastyDebug.summary();
+console.log(`Total tasty CSS: ${(s.totalCSSSize / 1024).toFixed(1)}KB`);
+console.log(`Active: ${(s.activeCSSSize / 1024).toFixed(1)}KB`);
+console.log(`Unused (pending cleanup): ${(s.unusedCSSSize / 1024).toFixed(1)}KB`);
+
+// Compare with total page CSS
+const page = tastyDebug.pageStats();
+const ratio = ((s.totalCSSSize / page.cssSize) * 100).toFixed(1);
+console.log(`Tasty is ${ratio}% of total page CSS`);
+```
+
+### Analyzing chunk distribution
+
+```typescript
+tastyDebug.chunks({ log: true });
+// → Formatted breakdown:
+//   • appearance: 24 classes, 3.2KB, 48 rules
+//   • font: 18 classes, 1.1KB, 18 rules
+//   • dimension: 31 classes, 2.4KB, 45 rules
+//   • ...
+```
+
+---
+
+## Shadow DOM Support
+
+All methods accept a `root` option to target a Shadow DOM instead of the main document:
+
+```typescript
+const shadowRoot = host.shadowRoot;
+
+tastyDebug.css('all', { root: shadowRoot });
+tastyDebug.inspect('.shadow-component', { root: shadowRoot });
+tastyDebug.summary({ root: shadowRoot, log: true });
+tastyDebug.chunks({ root: shadowRoot, log: true });
+```
+
+---
+
+## Integration with Tasty
+
+`tastyDebug` reads directly from the [Style Injector](./injector.md)'s internal registries. It does not inject, modify, or intercept any styles. The `cleanup()` method is the only method with side effects — it triggers the injector's garbage collection for unused styles.
+
+For most development, you'll use the [Tasty style system](./usage.md) to create components and the debug utilities to inspect the resulting CSS at runtime.