@tenphi/tasty 0.0.0-snapshot.05c1c22

package/dist/config.d.ts

@@ -0,0 +1,366 @@
+import { CounterStyleDescriptors, FontFaceInput, KeyframesSteps, PropertyDefinition } from "./injector/types.js";
+import { StyleDetails, UnitHandler } from "./parser/types.js";
+import { StyleHandlerDefinition } from "./utils/styles.js";
+import { ConfigTokens, RecipeStyles } from "./styles/types.js";
+import { StyleInjector } from "./injector/injector.js";
+import { ColorSpace } from "./utils/color-space.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;
+  /** Threshold for bulk cleanup of unused styles (default: 500) */
+  unusedStylesThreshold?: number;
+  /** Delay before bulk cleanup in ms, ignored if idleCleanup is true (default: 5000) */
+  bulkCleanupDelay?: number;
+  /** Use requestIdleCallback for cleanup when available (default: true) */
+  idleCleanup?: boolean;
+  /** 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;
+  /**
+   * Ratio of unused styles to delete per bulk cleanup run (0..1).
+   * Defaults to 0.5 (oldest half) to reduce risk of removing styles
+   * that may be restored shortly after being marked unused.
+   */
+  bulkCleanupBatchRatio?: number;
+  /**
+   * Minimum age (in ms) a style must remain unused before eligible for deletion.
+   * Helps avoid races during rapid mount/unmount cycles. Default: 10000ms.
+   */
+  unusedStylesMinAgeMs?: number;
+  /**
+   * 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;
+  /**
+   * 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).
+   * Properties are only injected when the component using them is rendered.
+   *
+   * 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
+   *   },
+   * });
+   *
+   * // 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>;
+}
+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.
+ */
+declare function getGlobalFontFace(): Record<string, FontFaceInput> | null;
+/**
+ * Get global counter-style configuration.
+ * Returns null if no counter styles configured.
+ */
+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