@cube-dev/ui-kit 0.0.0-canary-00718fb → 0.0.0-canary-837dfc4

package/es/tasty/hooks/useGlobalStyles.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 

package/es/tasty/hooks/useKeyframes.js

@@ -0,0 +1,82 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
+ * Released under the MIT license.
+ */
+
+import { useInsertionEffect, useMemo, useRef } from 'react';
+import { keyframes } from '../injector/index.js';
+// Implementation
+export function useKeyframes(stepsOrFactory, depsOrOptions, options) {
+    // Detect which overload is being used
+    const isFactory = typeof stepsOrFactory === 'function';
+    // Parse arguments based on overload
+    const deps = isFactory && Array.isArray(depsOrOptions) ? depsOrOptions : undefined;
+    const opts = isFactory
+        ? options
+        : depsOrOptions;
+    // Memoize the keyframes steps to get a stable reference
+    const stepsData = useMemo(() => {
+        const steps = isFactory
+            ? stepsOrFactory()
+            : stepsOrFactory;
+        if (!steps || Object.keys(steps).length === 0) {
+            return null;
+        }
+        return steps;
+    }, isFactory ? deps ?? [] : [stepsOrFactory]);
+    // Store keyframes results for cleanup - we need to track both the render-time
+    // injection (for the name) and the effect-time injection (for Strict Mode safety)
+    const renderResultRef = useRef(null);
+    const effectResultRef = useRef(null);
+    // Inject keyframes during render to ensure the animation name is available
+    // immediately. The keyframes() function uses reference counting internally,
+    // so multiple calls with the same content are deduplicated.
+    const name = useMemo(() => {
+        // Dispose previous render-time result if deps changed
+        renderResultRef.current?.dispose();
+        renderResultRef.current = null;
+        if (!stepsData) {
+            return '';
+        }
+        // Inject keyframes synchronously
+        const result = keyframes(stepsData, {
+            name: opts?.name,
+            root: opts?.root,
+        });
+        renderResultRef.current = result;
+        return result.toString();
+    }, [stepsData, opts?.name, opts?.root]);
+    // Handle injection and cleanup in useInsertionEffect to properly support
+    // React 18+ Strict Mode double-invocation (mount → unmount → mount).
+    // The effect setup re-injects the keyframes if cleanup was called, ensuring
+    // the CSS exists after Strict Mode remounts.
+    useInsertionEffect(() => {
+        // Dispose previous effect-time result
+        effectResultRef.current?.dispose();
+        effectResultRef.current = null;
+        // Re-inject keyframes. This ensures the CSS exists after Strict Mode cleanup.
+        // The keyframes() function uses reference counting, so this is idempotent
+        // if the CSS wasn't disposed.
+        if (stepsData) {
+            const result = keyframes(stepsData, {
+                name: opts?.name,
+                root: opts?.root,
+            });
+            effectResultRef.current = result;
+        }
+        // Cleanup on unmount or when dependencies change.
+        // Dispose both the effect-time and render-time results to properly
+        // decrement the reference count.
+        return () => {
+            effectResultRef.current?.dispose();
+            effectResultRef.current = null;
+            renderResultRef.current?.dispose();
+            renderResultRef.current = null;
+        };
+    }, [stepsData, opts?.name, opts?.root]);
+    return name;
+}
+
+        

package/es/tasty/hooks/useProperty.js

@@ -0,0 +1,100 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
+ * Released under the MIT license.
+ */
+
+import { useInsertionEffect, useMemo } from 'react';
+import { getGlobalInjector } from '../config.js';
+/**
+ * Hook to register a CSS @property custom property.
+ * This enables advanced features like animating custom properties.
+ *
+ * Note: @property rules are global and persistent once defined.
+ * The hook ensures the property is only registered once per root.
+ *
+ * Accepts tasty token syntax for the property name:
+ * - `$name` → defines `--name`
+ * - `#name` → defines `--name-color` (auto-sets syntax: '<color>', defaults initialValue: 'transparent')
+ * - `--name` → defines `--name` (legacy format)
+ *
+ * @param name - The property token ($name, #name) or CSS property name (--name)
+ * @param options - Property configuration
+ *
+ * @example Basic property with token syntax
+ * ```tsx
+ * function Spinner() {
+ *   useProperty('$rotation', {
+ *     syntax: '<angle>',
+ *     inherits: false,
+ *     initialValue: '0deg',
+ *   });
+ *
+ *   return <div className="spinner" />;
+ * }
+ * ```
+ *
+ * @example Color property with token syntax (auto-sets syntax)
+ * ```tsx
+ * function MyComponent() {
+ *   useProperty('#theme', {
+ *     initialValue: 'red', // syntax: '<color>' is auto-set
+ *   });
+ *
+ *   // Now --theme-color can be animated with CSS transitions
+ *   return <div style={{ '--theme-color': 'blue' } as React.CSSProperties}>Colored</div>;
+ * }
+ * ```
+ *
+ * @example Legacy format (still supported)
+ * ```tsx
+ * function ResizableBox() {
+ *   useProperty('--box-size', {
+ *     syntax: '<length>',
+ *     initialValue: '100px',
+ *   });
+ *
+ *   return <div style={{ width: 'var(--box-size)' }} />;
+ * }
+ * ```
+ */
+export function useProperty(name, options) {
+    // Memoize the options to create a stable dependency
+    const optionsKey = useMemo(() => {
+        if (!options)
+            return '';
+        return JSON.stringify({
+            syntax: options.syntax,
+            inherits: options.inherits,
+            initialValue: options.initialValue,
+        });
+    }, [options?.syntax, options?.inherits, options?.initialValue]);
+    useInsertionEffect(() => {
+        if (!name) {
+            if (process.env.NODE_ENV !== 'production') {
+                console.warn(`[Tasty] useProperty: property name is required`);
+            }
+            return;
+        }
+        const injector = getGlobalInjector();
+        // Check if already defined (properties are persistent)
+        // The injector handles token parsing internally
+        if (injector.isPropertyDefined(name, { root: options?.root })) {
+            return;
+        }
+        // Register the property
+        // The injector handles $name, #name, --name parsing and auto-sets
+        // syntax for color tokens
+        injector.property(name, {
+            syntax: options?.syntax,
+            inherits: options?.inherits,
+            initialValue: options?.initialValue,
+            root: options?.root,
+        });
+        // No cleanup - @property rules are global and persistent
+        // Re-registering is a no-op anyway due to the isPropertyDefined check
+    }, [name, optionsKey, options?.root]);
+}
+
+        

package/es/tasty/hooks/useRawCSS.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 

package/es/tasty/hooks/useStyles.js

@@ -1,16 +1,17 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 
 import { useInsertionEffect, useMemo, useRef } from 'react';
 import { categorizeStyleKeys, CHUNK_NAMES, generateChunkCacheKey, renderStylesForChunk, } from '../chunks/index.js';
 import { getGlobalKeyframes, hasGlobalKeyframes } from '../config.js';
-import { allocateClassName, inject, keyframes } from '../injector/index.js';
+import { allocateClassName, inject, keyframes, property } from '../injector/index.js';
 import { extractAnimationNamesFromStyles, extractLocalKeyframes, filterUsedKeyframes, hasLocalKeyframes, mergeKeyframes, replaceAnimationNames, } from '../keyframes/index.js';
 import { renderStyles } from '../pipeline/index.js';
+import { extractLocalProperties, hasLocalProperties } from '../properties/index.js';
 import { stringifyStyles } from '../utils/styles.js';
 /**
  * Check if styles contain @starting-style rules.
@@ -173,6 +174,18 @@ export function useStyles(styles) {
                 nameMap = null;
             }
         }
+        // Register @properties if defined (no dispose needed - properties are permanent)
+        // Token formats: $name → --name, #name → --name-color (with auto syntax: '<color>')
+        // The injector.property() handles token parsing and auto-settings internally
+        if (currentStyles && hasLocalProperties(currentStyles)) {
+            const properties = extractLocalProperties(currentStyles);
+            if (properties) {
+                for (const [token, definition] of Object.entries(properties)) {
+                    // Pass the token directly - injector handles parsing
+                    property(token, definition);
+                }
+            }
+        }
         // Inject each chunk
         for (const chunk of processedChunks) {
             if (chunk.renderResult.rules.length > 0) {

package/es/tasty/index.js

@@ -1,14 +1,14 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 
 import { configure } from './config.js';
 import { okhslPlugin } from './plugins/index.js';
 export { tasty, Element } from './tasty.js';
-export { useStyles, useGlobalStyles, useRawCSS } from './hooks/index.js';
+export { useStyles, useGlobalStyles, useRawCSS, useProperty, useKeyframes, } from './hooks/index.js';
 // Configuration API
 export { configure, getConfig, isConfigLocked, hasStylesGenerated, resetConfig, isTestEnvironment, hasGlobalKeyframes, getGlobalKeyframes, } from './config.js';
 // Plugins

package/es/tasty/injector/index.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 
@@ -59,6 +59,44 @@ export function getRawCSSText(options) {
 export function keyframes(steps, nameOrOptions) {
     return getGlobalInjector().keyframes(steps, nameOrOptions);
 }
+/**
+ * Define a CSS @property custom property.
+ * This enables advanced features like animating custom properties.
+ *
+ * Note: @property rules are global and persistent once defined.
+ * Re-registering the same property name is a no-op.
+ *
+ * @param name - The custom property name (must start with --)
+ * @param options - Property configuration
+ *
+ * @example
+ * ```ts
+ * // Define a color property that can be animated
+ * property('--my-color', {
+ *   syntax: '<color>',
+ *   initialValue: 'red',
+ * });
+ *
+ * // Define an angle property
+ * property('--rotation', {
+ *   syntax: '<angle>',
+ *   inherits: false,
+ *   initialValue: '0deg',
+ * });
+ * ```
+ */
+export function property(name, options) {
+    return getGlobalInjector().property(name, options);
+}
+/**
+ * Check if a CSS @property has already been defined
+ *
+ * @param name - The custom property name to check
+ * @param options - Options including root
+ */
+export function isPropertyDefined(name, options) {
+    return getGlobalInjector().isPropertyDefined(name, options);
+}
 /**
  * Get CSS text from all sheets (for SSR)
  */

package/es/tasty/injector/injector.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 
@@ -9,6 +9,8 @@
  * Style injector that works with structured style objects
  * Eliminates CSS string parsing for better performance
  */
+import { getEffectiveDefinition, normalizePropertyDefinition, } from '../properties/index.js';
+import { isDevEnv } from '../utils/isDevEnv.js';
 import { parseStyle } from '../utils/styles.js';
 import { SheetManager } from './sheet-manager.js';
 /**
@@ -315,56 +317,105 @@ export class StyleInjector {
         this.sheetManager.resetMetrics(registry);
     }
     /**
-     * Define a CSS @property custom property
+     * Define a CSS @property custom property.
+     *
+     * Accepts tasty token syntax for the property name:
+     * - `$name` → defines `--name`
+     * - `#name` → defines `--name-color` (auto-sets syntax: '<color>', defaults initialValue: 'transparent')
+     * - `--name` → defines `--name` (legacy format)
+     *
      * Example:
      * @property --rotation { syntax: "<angle>"; inherits: false; initial-value: 45deg; }
+     *
      * Note: No caching or dispose — this defines a global property.
+     *
+     * If the same property is registered with different options, a warning is emitted
+     * but the original definition is preserved (CSS @property cannot be redefined).
      */
     property(name, options) {
         const root = options?.root || document;
         const registry = this.sheetManager.getRegistry(root);
-        // Check if already defined to avoid duplicates
-        if (registry.injectedProperties.has(name)) {
+        // Parse the token and get effective definition
+        // This handles $name, #name, --name formats and auto-sets syntax for colors
+        const userDefinition = {
+            syntax: options?.syntax,
+            inherits: options?.inherits,
+            initialValue: options?.initialValue,
+        };
+        const effectiveResult = getEffectiveDefinition(name, userDefinition);
+        if (!effectiveResult.isValid) {
+            if (isDevEnv()) {
+                console.warn(`[Tasty] property(): ${effectiveResult.error}. Got: "${name}"`);
+            }
+            return;
+        }
+        const cssName = effectiveResult.cssName;
+        const definition = effectiveResult.definition;
+        // Normalize the definition for comparison
+        const normalizedDef = normalizePropertyDefinition(definition);
+        // Check if already defined
+        const existingDef = registry.injectedProperties.get(cssName);
+        if (existingDef !== undefined) {
+            // Property already exists - check if definitions match
+            if (existingDef !== normalizedDef) {
+                // Different definition - warn but don't replace (CSS @property can't be redefined)
+                if (isDevEnv()) {
+                    console.warn(`[Tasty] @property ${cssName} was already defined with a different declaration. ` +
+                        `The new declaration will be ignored. ` +
+                        `Original: ${existingDef}, New: ${normalizedDef}`);
+                }
+            }
+            // Either exact match or warned - skip injection
             return;
         }
         const parts = [];
-        if (options?.syntax != null) {
-            let syntax = String(options.syntax).trim();
+        if (definition.syntax != null) {
+            let syntax = String(definition.syntax).trim();
             if (!/^['"]/u.test(syntax))
                 syntax = `"${syntax}"`;
             parts.push(`syntax: ${syntax};`);
         }
         // inherits is required by the CSS @property spec - default to true
-        const inherits = options?.inherits ?? true;
+        const inherits = definition.inherits ?? true;
         parts.push(`inherits: ${inherits ? 'true' : 'false'};`);
-        if (options?.initialValue != null) {
+        if (definition.initialValue != null) {
             let initialValueStr;
-            if (typeof options.initialValue === 'number') {
-                initialValueStr = String(options.initialValue);
+            if (typeof definition.initialValue === 'number') {
+                initialValueStr = String(definition.initialValue);
             }
             else {
                 // Process via tasty parser to resolve custom units/functions
-                initialValueStr = parseStyle(options.initialValue).output;
+                initialValueStr = parseStyle(definition.initialValue).output;
             }
             parts.push(`initial-value: ${initialValueStr};`);
         }
         const declarations = parts.join(' ').trim();
         const rule = {
-            selector: `@property ${name}`,
+            selector: `@property ${cssName}`,
             declarations,
         };
         // Insert as a global rule; ignore returned info (no tracking/dispose)
         this.sheetManager.insertGlobalRule(registry, [rule], `property:${name}`, root);
-        // Track that this property was injected
-        registry.injectedProperties.add(name);
+        // Track that this property was injected with its normalized definition
+        registry.injectedProperties.set(cssName, normalizedDef);
     }
     /**
-     * Check whether a given @property name was already injected by this injector
+     * Check whether a given @property name was already injected by this injector.
+     *
+     * Accepts tasty token syntax:
+     * - `$name` → checks `--name`
+     * - `#name` → checks `--name-color`
+     * - `--name` → checks `--name` (legacy format)
      */
     isPropertyDefined(name, options) {
         const root = options?.root || document;
         const registry = this.sheetManager.getRegistry(root);
-        return registry.injectedProperties.has(name);
+        // Parse the token to get the CSS property name
+        const effectiveResult = getEffectiveDefinition(name, {});
+        if (!effectiveResult.isValid) {
+            return false;
+        }
+        return registry.injectedProperties.has(effectiveResult.cssName);
     }
     /**
      * Inject keyframes and return object with toString() and dispose()

package/es/tasty/injector/sheet-manager.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 
@@ -49,7 +49,7 @@ export class SheetManager {
                 keyframesCache: new Map(),
                 keyframesNameToContent: new Map(),
                 keyframesCounter: 0,
-                injectedProperties: new Set(),
+                injectedProperties: new Map(),
                 globalRules: new Map(),
             };
             this.rootRegistries.set(root, registry);

package/es/tasty/injector/types.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 

package/es/tasty/keyframes/index.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 

package/es/tasty/parser/classify.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 
@@ -72,6 +72,20 @@ export function classify(raw, opts, recurse) {
         (token.startsWith("'") && token.endsWith("'"))) {
         return { bucket: Bucket.Value, processed: token };
     }
+    // 0. Double prefix for literal CSS property names ($$name -> --name, ##name -> --name-color)
+    // Used in transitions and animations to reference the property name itself, not its value
+    if (token.startsWith('$$')) {
+        const name = token.slice(2);
+        if (/^[a-z_][a-z0-9-_]*$/i.test(name)) {
+            return { bucket: Bucket.Value, processed: `--${name}` };
+        }
+    }
+    if (token.startsWith('##')) {
+        const name = token.slice(2);
+        if (/^[a-z_][a-z0-9-_]*$/i.test(name)) {
+            return { bucket: Bucket.Value, processed: `--${name}-color` };
+        }
+    }
     // 0a. Check for predefined tokens (configured via configure({ tokens: {...} }))
     // Must happen before default $ and # handling to allow overriding
     if (token[0] === '$' || token[0] === '#') {

package/es/tasty/parser/const.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 

package/es/tasty/parser/lru.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 

package/es/tasty/parser/parser.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 

package/es/tasty/parser/tokenizer.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 

package/es/tasty/parser/types.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 

package/es/tasty/pipeline/conditions.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 

package/es/tasty/pipeline/exclusive.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 

package/es/tasty/pipeline/index.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 

package/es/tasty/pipeline/materialize.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 

package/es/tasty/pipeline/parseStateKey.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 

package/es/tasty/pipeline/simplify.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 

package/es/tasty/plugins/index.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 

package/es/tasty/plugins/okhsl-plugin.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */
 

package/es/tasty/plugins/types.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.0.0-canary-00718fb
+ * @cube-dev/ui-kit v0.0.0-canary-837dfc4
  * Released under the MIT license.
  */