@tenphi/tasty 2.0.3 → 2.0.4

package/dist/config.d.ts

@@ -1,407 +0,0 @@
-import { CounterStyleDescriptors, FontFaceInput, GCConfig, KeyframesSteps, PropertyDefinition } from "./injector/types.js";
-import { StyleDetails, UnitHandler } from "./parser/types.js";
-import { StyleHandlerDefinition } from "./utils/styles.js";
-import { ConfigTokens, RecipeStyles, Styles } from "./styles/types.js";
-import { StyleInjector } from "./injector/injector.js";
-import { ColorSpace } from "./utils/color-space.js";
-import { TypographyPreset } from "./utils/typography.js";
-import { TastyPlugin } from "./plugins/types.js";
-
-//#region src/config.d.ts
-/**
- * Configuration options for the Tasty style system
- */
-interface TastyConfig {
-  /** CSP nonce for style elements */
-  nonce?: string;
-  /** Maximum rules per stylesheet (default: 8192) */
-  maxRulesPerSheet?: number;
-  /** Force text injection mode, auto-detected in test environments (default: auto) */
-  forceTextInjection?: boolean;
-  /** Enable development mode features: performance metrics and debug info (default: auto) */
-  devMode?: boolean;
-  /**
-   * Global predefined states for advanced state mapping.
-   * These are state aliases that can be used in any component.
-   * Example: { '@mobile': '@media(w < 920px)', '@dark': '@root(theme=dark)' }
-   */
-  states?: Record<string, string>;
-  /**
-   * Parser LRU cache size (default: 1000).
-   * Larger values improve performance for apps with many unique style values.
-   */
-  parserCacheSize?: number;
-  /**
-   * Custom units for the style parser (merged with built-in units).
-   * Units transform numeric values like `2x` → `calc(2 * var(--gap))`.
-   * @example { em: 'em', vw: 'vw', custom: (n) => `${n * 10}px` }
-   */
-  units?: Record<string, string | UnitHandler>;
-  /**
-   * Custom functions for the style parser (merged with existing).
-   * Functions process parsed style groups and return CSS values.
-   * @example { myFunc: (groups) => groups.map(g => g.output).join(' ') }
-   */
-  funcs?: Record<string, (groups: StyleDetails[]) => string>;
-  /**
-   * Color space used for decomposed color token companion variables.
-   * Controls the CSS function and suffix for alpha composition.
-   *
-   * - `'rgb'`   — suffix `-rgb`, e.g. `rgb(var(--name-color-rgb) / .5)`
-   * - `'hsl'`   — suffix `-hsl`, e.g. `hsl(var(--name-color-hsl) / .5)`
-   * - `'oklch'` — suffix `-oklch`, e.g. `oklch(var(--name-color-oklch) / .5)`
-   *
-   * @default 'oklch'
-   */
-  colorSpace?: ColorSpace;
-  /**
-   * Automatically infer and register CSS @property declarations
-   * from custom property values found in styles, keyframes, and global config.
-   * Covers all types: \<color\>, \<number\>, \<length\>, \<angle\>, \<percentage\>, \<time\>.
-   * When false, only explicitly declared @properties are registered.
-   * @default true
-   */
-  autoPropertyTypes?: boolean;
-  /**
-   * Garbage collection configuration for unused styles.
-   * GC is triggered by touch count: every `touchInterval` touches, the
-   * oldest unused styles are evicted when their count exceeds `capacity`.
-   * @example
-   * ```ts
-   * configure({
-   *   gc: { touchInterval: 1000, capacity: 1000 },
-   * });
-   * ```
-   */
-  gc?: GCConfig;
-  /**
-   * Plugins that extend tasty with custom functions, units, or states.
-   * Plugins are processed in order, with later plugins overriding earlier ones.
-   * @example
-   * ```ts
-   * import { okhslPlugin } from '@tenphi/tasty';
-   *
-   * configure({
-   *   plugins: [okhslPlugin()],
-   * });
-   * ```
-   */
-  plugins?: TastyPlugin[];
-  /**
-   * Global keyframes definitions that can be referenced by animation names in styles.
-   * Keys are animation names, values are keyframes step definitions.
-   * Keyframes are only injected when actually used in styles.
-   * @example
-   * ```ts
-   * configure({
-   *   keyframes: {
-   *     fadeIn: { from: { opacity: 0 }, to: { opacity: 1 } },
-   *     pulse: { '0%, 100%': { transform: 'scale(1)' }, '50%': { transform: 'scale(1.05)' } },
-   *   },
-   * });
-   * ```
-   */
-  keyframes?: Record<string, KeyframesSteps>;
-  /**
-   * Global CSS @property definitions for custom properties.
-   * Keys use tasty token syntax ($name for properties, #name for colors).
-   *
-   * Tasty ships with `DEFAULT_PROPERTIES` (e.g. `$gap`, `$radius`, `#white`,
-   * `#black`, `#clear`, `#border`, etc.) that are always included.
-   * Properties you specify here are merged on top, so you can override any
-   * default by using the same key.
-   *
-   * For color tokens (#name), `syntax: '<color>'` is auto-set and
-   * `initialValue` defaults to `'transparent'` if not specified.
-   *
-   * @example
-   * ```ts
-   * configure({
-   *   properties: {
-   *     '$rotation': { syntax: '<angle>', initialValue: '0deg' },
-   *     '$scale': { syntax: '<number>', inherits: false, initialValue: 1 },
-   *     '#accent': { initialValue: 'purple' }, // syntax: '<color>' auto-set
-   *     // Override a default property:
-   *     '$gap': { syntax: '<length>', inherits: true, initialValue: '8px' },
-   *   },
-   * });
-   *
-   * // Now use in styles - properties are registered when component renders:
-   * const Spinner = tasty({
-   *   styles: {
-   *     transform: 'rotate($rotation)',
-   *     transition: '$$rotation 0.3s', // outputs: --rotation 0.3s
-   *   },
-   * });
-   * ```
-   */
-  properties?: Record<string, PropertyDefinition>;
-  /**
-   * Global @font-face definitions.
-   * Keys are font-family names, values are descriptors or arrays of descriptors
-   * (for multiple weights/styles of the same family).
-   * Injected eagerly when styles are first generated.
-   * @example
-   * ```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' },
-   *   },
-   * });
-   * ```
-   */
-  fontFace?: Record<string, FontFaceInput>;
-  /**
-   * Global @counter-style definitions.
-   * Keys are counter-style names, values are descriptor objects.
-   * Injected eagerly when styles are first generated.
-   * @example
-   * ```ts
-   * configure({
-   *   counterStyle: {
-   *     thumbs: { system: 'cyclic', symbols: '"👍"', suffix: '" "' },
-   *   },
-   * });
-   * ```
-   */
-  counterStyle?: Record<string, CounterStyleDescriptors>;
-  /**
-   * Custom style handlers that transform style properties into CSS declarations.
-   * Handlers replace built-in handlers for the same style name.
-   * @example
-   * ```ts
-   * import { styleHandlers } from '@tenphi/tasty';
-   *
-   * configure({
-   *   handlers: {
-   *     // Override fill with custom behavior
-   *     fill: ({ fill }) => {
-   *       if (fill?.startsWith('gradient:')) {
-   *         return { background: fill.slice(9) };
-   *       }
-   *       return styleHandlers.fill({ fill });
-   *     },
-   *     // Add new custom style
-   *     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),
-   *       };
-   *     },
-   *   },
-   * });
-   * ```
-   */
-  handlers?: Record<string, StyleHandlerDefinition>;
-  /**
-   * Design tokens injected as CSS custom properties on `:root`.
-   * Values are parsed through the Tasty DSL. Supports state maps
-   * for responsive/theme-aware tokens.
-   *
-   * - `$name` keys become `--name` CSS custom properties
-   * - `#name` keys become `--name-color` and `--name-color-{colorSpace}` properties
-   *
-   * Tokens are injected once when the first style is rendered.
-   *
-   * @example
-   * ```ts
-   * configure({
-   *   tokens: {
-   *     '$gap': '4px',
-   *     '#primary': {
-   *       '': '#purple',
-   *       '@dark': '#light-purple',
-   *     },
-   *   },
-   * });
-   * ```
-   */
-  tokens?: ConfigTokens;
-  /**
-   * Predefined tokens that are replaced during style parsing (parse-time substitution).
-   * Use `$name` for custom properties and `#name` for color tokens.
-   * Values are substituted inline before CSS generation, unlike `tokens` which
-   * inject CSS custom properties on `:root`.
-   *
-   * For color tokens (#name), boolean `true` is converted to `transparent`.
-   *
-   * @example
-   * ```ts
-   * configure({
-   *   replaceTokens: {
-   *     $spacing: '2x',
-   *     '#accent': '#purple',
-   *     '#overlay': true, // → transparent
-   *   },
-   * });
-   *
-   * // Now use in styles - tokens are replaced at parse time:
-   * const Card = tasty({
-   *   styles: {
-   *     padding: '$spacing',  // → calc(2 * var(--gap))
-   *     fill: '#accent',      // → var(--purple-color)
-   *   },
-   * });
-   * ```
-   */
-  replaceTokens?: Record<`$${string}`, string | number | boolean> & Record<`#${string}`, string | number | boolean>;
-  /**
-   * Predefined style recipes -- named style bundles that can be applied via `recipe` style property.
-   * Recipe values are flat tasty styles (no sub-element keys). They may contain base styles,
-   * tokens (`$name`/`#name` definitions), local states, `@keyframes`, and `@properties`.
-   *
-   * Components reference recipes via: `recipe: 'name1 name2'` in their styles.
-   * Use `/` to separate base recipes from post recipes: `recipe: 'base1 base2 / post1'`.
-   * Use `none` to skip base recipes: `recipe: 'none / post1'`.
-   * Resolution order: `base_recipes → component styles → post_recipes`.
-   *
-   * Recipes cannot reference other recipes.
-   *
-   * @example
-   * ```ts
-   * configure({
-   *   recipes: {
-   *     card: { padding: '4x', fill: '#surface', radius: '1r', border: true },
-   *     elevated: { shadow: '2x 2x 4x #shadow' },
-   *   },
-   * });
-   *
-   * // Usage in styles:
-   * const Card = tasty({
-   *   styles: {
-   *     recipe: 'card elevated',
-   *     color: '#text', // Overrides recipe values
-   *   },
-   * });
-   * ```
-   */
-  recipes?: Record<string, RecipeStyles>;
-  /**
-   * Typography presets — shorthand for `generateTypographyTokens()`.
-   * Accepts the same input and internally generates typography tokens
-   * that are merged into `tokens`. Explicit `tokens` override preset-generated ones.
-   *
-   * @example
-   * ```ts
-   * configure({
-   *   presets: {
-   *     h1: { fontSize: '32px', lineHeight: '1.2', fontWeight: '700' },
-   *     t2: { fontSize: '16px', lineHeight: '1.5', fontWeight: '400' },
-   *   },
-   *   tokens: {
-   *     // Overrides the preset-generated $t2-font-weight
-   *     '$t2-font-weight': { '': '400', '@dark': '300' },
-   *   },
-   * });
-   * ```
-   */
-  presets?: Record<string, TypographyPreset>;
-  /**
-   * Global Tasty styles keyed by CSS selector.
-   * Each entry applies the full Tasty style syntax (style properties,
-   * tokens, state maps, selector-based sub-styling) to the given selector.
-   * Injected alongside `:root` tokens when the first style is rendered.
-   *
-   * @example
-   * ```ts
-   * configure({
-   *   globalStyles: {
-   *     body: { fill: '#surface', color: '#text', preset: 't2', margin: 0 },
-   *     html: { overflow: 'hidden' },
-   *   },
-   * });
-   * ```
-   */
-  globalStyles?: Record<string, Styles>;
-}
-declare const GLOBAL_INJECTOR_KEY = "__TASTY_GLOBAL_INJECTOR__";
-declare global {
-  interface Window {
-    [GLOBAL_INJECTOR_KEY]?: StyleInjector;
-  }
-  var __TASTY_GLOBAL_INJECTOR__: StyleInjector | undefined;
-}
-/**
- * Detect if we're running in a test environment
- */
-declare function isTestEnvironment(): boolean;
-/**
- * Check if styles have been generated (configuration is locked)
- */
-declare function hasStylesGenerated(): boolean;
-/**
- * Check if any global keyframes are configured.
- * Uses a pre-computed flag to avoid Object.keys() allocation on every call.
- */
-declare function hasGlobalKeyframes(): boolean;
-/**
- * Get global keyframes configuration.
- * Returns null if no keyframes configured (fast path for zero-overhead).
- */
-declare function getGlobalKeyframes(): Record<string, KeyframesSteps> | null;
-/**
- * Get global font-face configuration.
- * Returns null if no font faces configured.
- * Reads from globalThis first for cross-module SSR support.
- */
-declare function getGlobalFontFace(): Record<string, FontFaceInput> | null;
-/**
- * Get global counter-style configuration.
- * Returns null if no counter styles configured.
- * Reads from globalThis first for cross-module SSR support.
- */
-declare function getGlobalCounterStyle(): Record<string, CounterStyleDescriptors> | null;
-/**
- * Check if any global recipes are configured.
- * Fast path: returns false if no recipes were ever set.
- */
-declare function hasGlobalRecipes(): boolean;
-/**
- * Get global recipes configuration.
- * Returns null if no recipes configured (fast path for zero-overhead).
- */
-declare function getGlobalRecipes(): Record<string, RecipeStyles> | null;
-/**
- * Check if configuration is locked (styles have been generated)
- */
-declare function isConfigLocked(): boolean;
-/**
- * Configure the Tasty style system.
- *
- * Must be called BEFORE any styles are generated (before first render that uses tasty).
- * After styles are generated, configuration is locked and calls to configure() will
- * emit a warning and be ignored.
- *
- * @example
- * ```ts
- * import { configure } from '@tenphi/tasty';
- *
- * // Configure before app renders
- * configure({
- *   nonce: 'abc123',
- *   states: {
- *     '@mobile': '@media(w < 768px)',
- *     '@dark': '@root(theme=dark)',
- *   },
- * });
- * ```
- */
-declare function configure(config?: Partial<TastyConfig>): void;
-/**
- * Get the current configuration.
- * If not configured, returns default configuration.
- */
-declare function getConfig(): TastyConfig;
-/**
- * Reset configuration (for testing only).
- * Clears the global injector and allows reconfiguration.
- */
-declare function resetConfig(): void;
-//#endregion
-export { TastyConfig, configure, getConfig, getGlobalCounterStyle, getGlobalFontFace, getGlobalKeyframes, getGlobalRecipes, hasGlobalKeyframes, hasGlobalRecipes, hasStylesGenerated, isConfigLocked, isTestEnvironment, resetConfig };
-//# sourceMappingURL=config.d.ts.map