@tenphi/tasty 0.1.0

package/dist/chunks/renderChunk.mjs

@@ -0,0 +1,61 @@
+import { extractLocalPredefinedStates } from "../states/index.mjs";
+import { renderStyles } from "../pipeline/index.mjs";
+import { CHUNK_NAMES } from "./definitions.mjs";
+
+//#region src/chunks/renderChunk.ts
+/**
+* Render styles for a specific chunk.
+*
+* Creates a filtered styles object containing only the keys for this chunk,
+* then delegates to the existing renderStyles function.
+*
+* IMPORTANT: Local predefined states (e.g., '@mobile': '@media(w < 600px)')
+* are always included in the filtered styles, regardless of which chunk is
+* being rendered. This ensures that state references like '@mobile' in any
+* chunk can be properly resolved by the pipeline.
+*
+* @param styles - The full styles object
+* @param chunkName - Name of the chunk being rendered
+* @param styleKeys - Keys of styles belonging to this chunk
+* @returns RenderResult with rules for this chunk
+*/
+function renderStylesForChunk(styles, chunkName, styleKeys) {
+	if (styleKeys.length === 0) return {
+		rules: [],
+		className: ""
+	};
+	if (chunkName === CHUNK_NAMES.SUBCOMPONENTS) return renderSubcomponentsChunk(styles, styleKeys);
+	const localPredefinedStates = extractLocalPredefinedStates(styles);
+	const filteredStyles = {};
+	for (const [key, value] of Object.entries(localPredefinedStates)) filteredStyles[key] = value;
+	for (const key of styleKeys) {
+		const value = styles[key];
+		if (value !== void 0) filteredStyles[key] = value;
+	}
+	return renderStyles(filteredStyles);
+}
+/**
+* Render the subcomponents chunk.
+*
+* Subcomponents (selectors like Label, &::before, etc.) contain nested
+* style objects that need to be preserved in their entirety.
+*
+* @param styles - The full styles object
+* @param selectorKeys - Keys of selectors in this chunk
+* @returns RenderResult with rules for all subcomponents
+*/
+function renderSubcomponentsChunk(styles, selectorKeys) {
+	const localPredefinedStates = extractLocalPredefinedStates(styles);
+	const filteredStyles = {};
+	for (const [key, value] of Object.entries(localPredefinedStates)) filteredStyles[key] = value;
+	for (const key of selectorKeys) {
+		const value = styles[key];
+		if (value !== void 0) filteredStyles[key] = value;
+	}
+	if (styles.$ !== void 0) filteredStyles.$ = styles.$;
+	return renderStyles(filteredStyles);
+}
+
+//#endregion
+export { renderStylesForChunk };
+//# sourceMappingURL=renderChunk.mjs.map

package/dist/chunks/renderChunk.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderChunk.mjs","names":[],"sources":["../../src/chunks/renderChunk.ts"],"sourcesContent":["/**\n * Chunk-specific style rendering.\n *\n * Renders styles for a specific chunk by filtering the styles object\n * to only include relevant keys before passing to renderStyles.\n */\n\nimport type { RenderResult} from '../pipeline';\nimport { renderStyles } from '../pipeline';\nimport { extractLocalPredefinedStates } from '../states';\nimport type { Styles } from '../styles/types';\n\nimport { CHUNK_NAMES } from './definitions';\n\n/**\n * Render styles for a specific chunk.\n *\n * Creates a filtered styles object containing only the keys for this chunk,\n * then delegates to the existing renderStyles function.\n *\n * IMPORTANT: Local predefined states (e.g., '@mobile': '@media(w < 600px)')\n * are always included in the filtered styles, regardless of which chunk is\n * being rendered. This ensures that state references like '@mobile' in any\n * chunk can be properly resolved by the pipeline.\n *\n * @param styles - The full styles object\n * @param chunkName - Name of the chunk being rendered\n * @param styleKeys - Keys of styles belonging to this chunk\n * @returns RenderResult with rules for this chunk\n */\nexport function renderStylesForChunk(\n  styles: Styles,\n  chunkName: string,\n  styleKeys: string[],\n): RenderResult {\n  // Empty chunk - return empty result\n  if (styleKeys.length === 0) {\n    return { rules: [], className: '' };\n  }\n\n  // For subcomponents, we need to preserve the nested structure\n  if (chunkName === CHUNK_NAMES.SUBCOMPONENTS) {\n    return renderSubcomponentsChunk(styles, styleKeys);\n  }\n\n  // Extract local predefined states from the full styles object\n  // These must be included for state resolution to work across chunks\n  const localPredefinedStates = extractLocalPredefinedStates(styles);\n\n  // For regular chunks, create a filtered styles object\n  // This is memory-efficient: we only create a shallow copy with filtered keys\n  const filteredStyles: Styles = {};\n\n  // First, add local predefined states so they're available for resolution\n  for (const [key, value] of Object.entries(localPredefinedStates)) {\n    filteredStyles[key] = value;\n  }\n\n  // Then add the chunk's style keys\n  for (const key of styleKeys) {\n    const value = styles[key];\n    if (value !== undefined) {\n      filteredStyles[key] = value;\n    }\n  }\n\n  // Delegate to existing renderStyles\n  return renderStyles(filteredStyles);\n}\n\n/**\n * Render the subcomponents chunk.\n *\n * Subcomponents (selectors like Label, &::before, etc.) contain nested\n * style objects that need to be preserved in their entirety.\n *\n * @param styles - The full styles object\n * @param selectorKeys - Keys of selectors in this chunk\n * @returns RenderResult with rules for all subcomponents\n */\nfunction renderSubcomponentsChunk(\n  styles: Styles,\n  selectorKeys: string[],\n): RenderResult {\n  // Extract local predefined states from the full styles object\n  // These must be included for state resolution to work in nested styles\n  const localPredefinedStates = extractLocalPredefinedStates(styles);\n\n  // Create a styles object containing only the selector keys\n  const filteredStyles: Styles = {};\n\n  // First, add local predefined states so they're available for resolution\n  for (const [key, value] of Object.entries(localPredefinedStates)) {\n    filteredStyles[key] = value;\n  }\n\n  // Then add the selector keys\n  for (const key of selectorKeys) {\n    const value = styles[key];\n    if (value !== undefined) {\n      filteredStyles[key] = value;\n    }\n  }\n\n  // Also copy the $ helper if present (used for selector combinators)\n  if (styles.$ !== undefined) {\n    filteredStyles.$ = styles.$;\n  }\n\n  // Delegate to existing renderStyles\n  return renderStyles(filteredStyles);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AA8BA,SAAgB,qBACd,QACA,WACA,WACc;AAEd,KAAI,UAAU,WAAW,EACvB,QAAO;EAAE,OAAO,EAAE;EAAE,WAAW;EAAI;AAIrC,KAAI,cAAc,YAAY,cAC5B,QAAO,yBAAyB,QAAQ,UAAU;CAKpD,MAAM,wBAAwB,6BAA6B,OAAO;CAIlE,MAAM,iBAAyB,EAAE;AAGjC,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,sBAAsB,CAC9D,gBAAe,OAAO;AAIxB,MAAK,MAAM,OAAO,WAAW;EAC3B,MAAM,QAAQ,OAAO;AACrB,MAAI,UAAU,OACZ,gBAAe,OAAO;;AAK1B,QAAO,aAAa,eAAe;;;;;;;;;;;;AAarC,SAAS,yBACP,QACA,cACc;CAGd,MAAM,wBAAwB,6BAA6B,OAAO;CAGlE,MAAM,iBAAyB,EAAE;AAGjC,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,sBAAsB,CAC9D,gBAAe,OAAO;AAIxB,MAAK,MAAM,OAAO,cAAc;EAC9B,MAAM,QAAQ,OAAO;AACrB,MAAI,UAAU,OACZ,gBAAe,OAAO;;AAK1B,KAAI,OAAO,MAAM,OACf,gBAAe,IAAI,OAAO;AAI5B,QAAO,aAAa,eAAe"}

package/dist/config.d.ts

@@ -0,0 +1,279 @@
+import { KeyframesSteps, PropertyDefinition } from "./injector/types.js";
+import { StyleDetails, UnitHandler } from "./parser/types.js";
+import { StyleHandlerDefinition } from "./utils/styles.js";
+import { RecipeStyles } from "./styles/types.js";
+import { StyleInjector } from "./injector/injector.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>;
+  /**
+   * 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>;
+  /**
+   * 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>;
+  /**
+   * Predefined tokens that are replaced during style parsing.
+   * Token values are processed through the parser (like component tokens).
+   * Use `$name` for custom properties and `#name` for color tokens.
+   *
+   * For color tokens (#name), boolean `true` is converted to `transparent`.
+   *
+   * @example
+   * ```ts
+   * configure({
+   *   tokens: {
+   *     $spacing: '2x',
+   *     '$card-padding': '4x',
+   *     '#accent': '#purple',
+   *     '#surface': '#white',
+   *     '#overlay': true, // → transparent
+   *   },
+   * });
+   *
+   * // Now use in styles - tokens are replaced at parse time:
+   * const Card = tasty({
+   *   styles: {
+   *     padding: '$card-padding',  // → calc(4 * var(--gap))
+   *     fill: '#surface',          // → var(--white-color)
+   *   },
+   * });
+   * ```
+   */
+  tokens?: 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'`.
+   * 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.
+ * Fast path: returns false if no keyframes were ever set.
+ */
+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;
+/**
+ * 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, getGlobalKeyframes, getGlobalRecipes, hasGlobalKeyframes, hasGlobalRecipes, hasStylesGenerated, isConfigLocked, isTestEnvironment, resetConfig };
+//# sourceMappingURL=config.d.ts.map