@cube-dev/ui-kit 0.99.3 → 0.101.0

package/es/tasty/chunks/definitions.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.99.3
+ * @cube-dev/ui-kit v0.101.0
  * Released under the MIT license.
  */
 
@@ -13,6 +13,37 @@
  * 2. Logical grouping - related styles grouped for better cache reuse
  *
  * See STYLE_CHUNKING_SPEC.md for detailed rationale.
+ *
+ * ============================================================================
+ * ⚠️  CRITICAL ARCHITECTURAL CONSTRAINT: NO CROSS-CHUNK HANDLER DEPENDENCIES
+ * ============================================================================
+ *
+ * Style handlers declare their dependencies via `__lookupStyles` array.
+ * This creates a dependency graph where handlers read multiple style props.
+ *
+ * **ALL styles in a handler's `__lookupStyles` MUST be in the SAME chunk.**
+ *
+ * Why this matters:
+ * 1. Each chunk computes a cache key from ONLY its own style values
+ * 2. If a handler reads a style from another chunk, that value isn't in the cache key
+ * 3. Changing the cross-chunk style won't invalidate this chunk's cache
+ * 4. Result: stale CSS output or incorrect cache hits
+ *
+ * Example of a violation:
+ * ```
+ * // flowStyle.__lookupStyles = ['display', 'flow']
+ * // If 'display' is in DISPLAY chunk and 'flow' is in LAYOUT chunk:
+ * // - User sets { display: 'grid', flow: 'column' }
+ * // - LAYOUT chunk caches CSS with flow=column, display=grid
+ * // - User changes to { display: 'flex', flow: 'column' }
+ * // - LAYOUT chunk cache key unchanged (only has 'flow')
+ * // - Returns stale CSS computed with display=grid!
+ * ```
+ *
+ * Before adding/moving styles, verify:
+ * 1. Find all handlers that use this style (grep for the style name in __lookupStyles)
+ * 2. Ensure ALL styles from each handler's __lookupStyles are in the same chunk
+ * ============================================================================
  */
 import { isSelector } from '../pipeline/index.js';
 // ============================================================================
@@ -27,15 +58,17 @@ export const APPEARANCE_CHUNK_STYLES = [
     'opacity', // independent
     'border', // borderStyle (independent)
     'radius', // radiusStyle (independent)
-    'outline', // outlineStyle (independent)
-    'outlineOffset', // independent (used with outline)
+    'outline', // outlineStyle: outline ↔ outlineOffset
+    'outlineOffset', // outlineStyle: outline ↔ outlineOffset
     'shadow', // shadowStyle (independent)
     'fade', // fadeStyle (independent)
 ];
 /**
  * Font chunk - typography styles
- * ⚠️ presetStyle handler requires: preset, fontSize, lineHeight, letterSpacing,
- *    textTransform, fontWeight, fontStyle, font - all MUST stay together
+ *
+ * Handler dependencies (all styles in each handler MUST stay in this chunk):
+ * ⚠️ presetStyle: preset, fontSize, lineHeight, letterSpacing, textTransform,
+ *    fontWeight, fontStyle, font
  */
 export const FONT_CHUNK_STYLES = [
     // All from presetStyle handler - MUST stay together
@@ -50,17 +83,19 @@ export const FONT_CHUNK_STYLES = [
     // Independent text styles grouped for cohesion
     'fontFamily', // independent alias (logical grouping with font styles)
     'textAlign',
-    'whiteSpace',
     'textDecoration',
-    'textOverflow',
     'wordBreak',
     'wordWrap',
     'boldFontWeight',
 ];
 /**
  * Dimension chunk - sizing and spacing
- * ⚠️ paddingStyle handler requires all padding variants together
- * ⚠️ marginStyle handler requires all margin variants together
+ *
+ * Handler dependencies (all styles in each handler MUST stay in this chunk):
+ * ⚠️ paddingStyle: padding, paddingTop/Right/Bottom/Left, paddingBlock/Inline
+ * ⚠️ marginStyle: margin, marginTop/Right/Bottom/Left, marginBlock/Inline
+ * ⚠️ widthStyle: width, minWidth, maxWidth
+ * ⚠️ heightStyle: height, minHeight, maxHeight
  */
 export const DIMENSION_CHUNK_STYLES = [
     // All from paddingStyle handler - MUST stay together
@@ -79,11 +114,12 @@ export const DIMENSION_CHUNK_STYLES = [
     'marginLeft',
     'marginBlock',
     'marginInline',
-    // Independent sizing styles
-    'width', // widthStyle (independent)
-    'height', // heightStyle (independent)
+    // widthStyle handler - MUST stay together
+    'width',
     'minWidth',
     'maxWidth',
+    // heightStyle handler - MUST stay together
+    'height',
     'minHeight',
     'maxHeight',
     'flexBasis',
@@ -92,19 +128,37 @@ export const DIMENSION_CHUNK_STYLES = [
     'flex',
 ];
 /**
- * Container chunk - display, flow, and grid layout
- * ⚠️ FORCED TOGETHER by transitive handler dependencies:
- *    displayStyle(display,hide) + flowStyle(display,flow) +
- *    gapStyle(display,flow,gap) + groupRadiusAttr(groupRadius,flow)
+ * Display chunk - display mode, layout flow, text overflow, and scrollbar
+ *
+ * Handler dependencies (all styles in each handler MUST stay in this chunk):
+ * ⚠️ displayStyle: display, hide, textOverflow, overflow, whiteSpace
+ * ⚠️ flowStyle: display, flow
+ * ⚠️ gapStyle: display, flow, gap
+ * ⚠️ scrollbarStyle: scrollbar, overflow
  */
-export const CONTAINER_CHUNK_STYLES = [
-    // Forced together by handler dependencies
-    'display', // displayStyle: display ↔ hide
-    'hide', // displayStyle: display ↔ hide
-    'flow', // flowStyle: display ↔ flow
-    'gap', // gapStyle: display ↔ flow ↔ gap
-    'groupRadius', // groupRadiusAttr: groupRadius ↔ flow
-    // Related container styles (independent but logically grouped)
+export const DISPLAY_CHUNK_STYLES = [
+    // displayStyle handler
+    'display',
+    'hide',
+    'textOverflow',
+    'overflow', // also used by scrollbarStyle
+    'whiteSpace',
+    // flowStyle handler (requires display)
+    'flow',
+    // gapStyle handler (requires display, flow)
+    'gap',
+    // scrollbarStyle handler (requires overflow)
+    'scrollbar',
+    'styledScrollbar', // styledScrollbarStyle (deprecated)
+];
+/**
+ * Layout chunk - flex/grid alignment and grid templates
+ *
+ * Note: flow and gap are in DISPLAY chunk due to handler dependencies
+ * (flowStyle and gapStyle both require 'display' prop).
+ */
+export const LAYOUT_CHUNK_STYLES = [
+    // Alignment styles (all independent handlers)
     'placeItems',
     'placeContent',
     'alignItems',
@@ -116,6 +170,7 @@ export const CONTAINER_CHUNK_STYLES = [
     'place', // placeStyle (independent)
     'columnGap',
     'rowGap',
+    // Grid template styles
     'gridColumns',
     'gridRows',
     'gridTemplate',
@@ -125,20 +180,17 @@ export const CONTAINER_CHUNK_STYLES = [
     'gridAutoRows',
 ];
 /**
- * Scrollbar chunk - scrollbar and overflow
- * ⚠️ scrollbarStyle handler requires scrollbar ↔ overflow together
- */
-export const SCROLLBAR_CHUNK_STYLES = [
-    'scrollbar', // scrollbarStyle: scrollbar ↔ overflow
-    'overflow', // scrollbarStyle: scrollbar ↔ overflow
-    'styledScrollbar', // styledScrollbarStyle (independent, deprecated)
-];
-/**
- * Position chunk - element positioning (all independent handlers)
+ * Position chunk - element positioning
+ *
+ * Handler dependencies (all styles in each handler MUST stay in this chunk):
+ * ⚠️ insetStyle: inset, insetBlock, insetInline, top, right, bottom, left
  */
 export const POSITION_CHUNK_STYLES = [
     'position',
-    'inset', // insetStyle (independent)
+    // All from insetStyle handler - MUST stay together
+    'inset',
+    'insetBlock',
+    'insetInline',
     'top',
     'right',
     'bottom',
@@ -165,8 +217,8 @@ export const CHUNK_NAMES = {
     APPEARANCE: 'appearance',
     FONT: 'font',
     DIMENSION: 'dimension',
-    CONTAINER: 'container',
-    SCROLLBAR: 'scrollbar',
+    DISPLAY: 'display',
+    LAYOUT: 'layout',
     POSITION: 'position',
     MISC: 'misc',
 };
@@ -189,11 +241,11 @@ function populateStyleToChunkMap() {
     for (const style of DIMENSION_CHUNK_STYLES) {
         STYLE_TO_CHUNK.set(style, CHUNK_NAMES.DIMENSION);
     }
-    for (const style of CONTAINER_CHUNK_STYLES) {
-        STYLE_TO_CHUNK.set(style, CHUNK_NAMES.CONTAINER);
+    for (const style of DISPLAY_CHUNK_STYLES) {
+        STYLE_TO_CHUNK.set(style, CHUNK_NAMES.DISPLAY);
     }
-    for (const style of SCROLLBAR_CHUNK_STYLES) {
-        STYLE_TO_CHUNK.set(style, CHUNK_NAMES.SCROLLBAR);
+    for (const style of LAYOUT_CHUNK_STYLES) {
+        STYLE_TO_CHUNK.set(style, CHUNK_NAMES.LAYOUT);
     }
     for (const style of POSITION_CHUNK_STYLES) {
         STYLE_TO_CHUNK.set(style, CHUNK_NAMES.POSITION);
@@ -212,8 +264,8 @@ const CHUNK_ORDER = [
     CHUNK_NAMES.APPEARANCE,
     CHUNK_NAMES.FONT,
     CHUNK_NAMES.DIMENSION,
-    CHUNK_NAMES.CONTAINER,
-    CHUNK_NAMES.SCROLLBAR,
+    CHUNK_NAMES.DISPLAY,
+    CHUNK_NAMES.LAYOUT,
     CHUNK_NAMES.POSITION,
     CHUNK_NAMES.MISC,
     CHUNK_NAMES.SUBCOMPONENTS,
@@ -240,8 +292,8 @@ export function categorizeStyleKeys(styles) {
     const keys = Object.keys(styles);
     for (const key of keys) {
         // Skip the $ helper key (used for selector combinators)
-        // Skip @keyframes (processed separately in useStyles)
-        if (key === '$' || key === '@keyframes') {
+        // Skip @keyframes and @properties (processed separately in useStyles)
+        if (key === '$' || key === '@keyframes' || key === '@properties') {
             continue;
         }
         if (isSelector(key)) {

package/es/tasty/chunks/index.js

@@ -1,11 +1,11 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.99.3
+ * @cube-dev/ui-kit v0.101.0
  * Released under the MIT license.
  */
 
-export { APPEARANCE_CHUNK_STYLES, FONT_CHUNK_STYLES, DIMENSION_CHUNK_STYLES, CONTAINER_CHUNK_STYLES, SCROLLBAR_CHUNK_STYLES, POSITION_CHUNK_STYLES, CHUNK_NAMES, STYLE_TO_CHUNK, categorizeStyleKeys, } from './definitions.js';
+export { APPEARANCE_CHUNK_STYLES, FONT_CHUNK_STYLES, DIMENSION_CHUNK_STYLES, DISPLAY_CHUNK_STYLES, LAYOUT_CHUNK_STYLES, POSITION_CHUNK_STYLES, CHUNK_NAMES, STYLE_TO_CHUNK, categorizeStyleKeys, } from './definitions.js';
 export { generateChunkCacheKey } from './cacheKey.js';
 export { renderStylesForChunk } from './renderChunk.js';
 

package/es/tasty/chunks/renderChunk.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.99.3
+ * @cube-dev/ui-kit v0.101.0
  * Released under the MIT license.
  */
 

package/es/tasty/config.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.99.3
+ * @cube-dev/ui-kit v0.101.0
  * Released under the MIT license.
  */
 
@@ -18,9 +18,11 @@
  * reconfigure will emit a warning and be ignored.
  */
 import { StyleInjector } from './injector/injector.js';
+import { clearPipelineCache } from './pipeline/index.js';
 import { setGlobalPredefinedStates } from './states/index.js';
+import { normalizeHandlerDefinition, registerHandler, resetHandlers, } from './styles/predefined.js';
 import { isDevEnv } from './utils/isDevEnv.js';
-import { CUSTOM_UNITS, getGlobalFuncs, getGlobalParser } from './utils/styles.js';
+import { CUSTOM_UNITS, getGlobalFuncs, getGlobalParser, resetGlobalPredefinedTokens, setGlobalPredefinedTokens, } from './utils/styles.js';
 // Warnings tracking to avoid duplicates
 const emittedWarnings = new Set();
 const devMode = isDevEnv();
@@ -42,6 +44,8 @@ let stylesGenerated = false;
 let currentConfig = null;
 // Global keyframes storage (null = no keyframes configured, empty object checked via hasGlobalKeyframes)
 let globalKeyframes = null;
+// Global properties storage (null = no properties configured)
+let globalProperties = null;
 // Global injector instance key
 const GLOBAL_INJECTOR_KEY = '__TASTY_GLOBAL_INJECTOR__';
 /**
@@ -94,9 +98,20 @@ function createDefaultConfig(isTest) {
 /**
  * Mark that styles have been generated (called by injector on first inject)
  * This locks the configuration - no further changes allowed.
+ * Also injects any global properties that were configured.
  */
 export function markStylesGenerated() {
+    if (stylesGenerated)
+        return; // Already marked, skip
     stylesGenerated = true;
+    // Inject global properties if any were configured
+    // Properties are permanent and only need to be injected once
+    if (globalProperties && Object.keys(globalProperties).length > 0) {
+        const injector = getGlobalInjector();
+        for (const [token, definition] of Object.entries(globalProperties)) {
+            injector.property(token, definition);
+        }
+    }
 }
 /**
  * Check if styles have been generated (configuration is locked)
@@ -140,6 +155,35 @@ function setGlobalKeyframes(keyframes) {
     }
     globalKeyframes = keyframes;
 }
+// ============================================================================
+// Global Properties Management
+// ============================================================================
+/**
+ * Check if any global properties are configured.
+ * Fast path: returns false if no properties were ever set.
+ */
+export function hasGlobalProperties() {
+    return globalProperties !== null && Object.keys(globalProperties).length > 0;
+}
+/**
+ * Get global properties configuration.
+ * Returns null if no properties configured (fast path for zero-overhead).
+ */
+export function getGlobalProperties() {
+    return globalProperties;
+}
+/**
+ * Set global properties (called from configure).
+ * Internal use only.
+ */
+function setGlobalProperties(properties) {
+    if (stylesGenerated) {
+        warnOnce('properties-after-styles', `[Tasty] Cannot update properties after styles have been generated.\n` +
+            `The new properties will be ignored.`);
+        return;
+    }
+    globalProperties = properties;
+}
 /**
  * Check if configuration is locked (styles have been generated)
  */
@@ -180,6 +224,8 @@ export function configure(config = {}) {
     let mergedStates = {};
     let mergedUnits = {};
     let mergedFuncs = {};
+    let mergedHandlers = {};
+    let mergedTokens = {};
     // Process plugins in order
     if (config.plugins) {
         for (const plugin of config.plugins) {
@@ -192,6 +238,12 @@ export function configure(config = {}) {
             if (plugin.funcs) {
                 mergedFuncs = { ...mergedFuncs, ...plugin.funcs };
             }
+            if (plugin.handlers) {
+                mergedHandlers = { ...mergedHandlers, ...plugin.handlers };
+            }
+            if (plugin.tokens) {
+                mergedTokens = { ...mergedTokens, ...plugin.tokens };
+            }
         }
     }
     // Direct config overrides plugins
@@ -204,6 +256,12 @@ export function configure(config = {}) {
     if (config.funcs) {
         mergedFuncs = { ...mergedFuncs, ...config.funcs };
     }
+    if (config.handlers) {
+        mergedHandlers = { ...mergedHandlers, ...config.handlers };
+    }
+    if (config.tokens) {
+        mergedTokens = { ...mergedTokens, ...config.tokens };
+    }
     // Handle predefined states
     if (Object.keys(mergedStates).length > 0) {
         setGlobalPredefinedStates(mergedStates);
@@ -230,8 +288,30 @@ export function configure(config = {}) {
     if (config.keyframes) {
         setGlobalKeyframes(config.keyframes);
     }
-    // Create config without states, parser options, plugins, and keyframes (handled separately)
-    const { states: _states, parserCacheSize: _parserCacheSize, units: _units, funcs: _funcs, plugins: _plugins, keyframes: _keyframes, ...injectorConfig } = config;
+    // Handle properties
+    if (config.properties) {
+        setGlobalProperties(config.properties);
+    }
+    // Handle custom handlers
+    if (Object.keys(mergedHandlers).length > 0) {
+        for (const [name, definition] of Object.entries(mergedHandlers)) {
+            const handler = normalizeHandlerDefinition(name, definition);
+            registerHandler(handler);
+        }
+    }
+    // Handle predefined tokens
+    // Note: Tokens are processed by the classifier, not here.
+    // We just store the raw values; the classifier will process them when encountered.
+    if (Object.keys(mergedTokens).length > 0) {
+        // Store tokens (keys are normalized to lowercase by setGlobalPredefinedTokens)
+        const processedTokens = {};
+        for (const [key, value] of Object.entries(mergedTokens)) {
+            processedTokens[key] = String(value);
+        }
+        setGlobalPredefinedTokens(processedTokens);
+    }
+    // Create config without states, parser options, plugins, keyframes, properties, handlers, and tokens (handled separately)
+    const { states: _states, parserCacheSize: _parserCacheSize, units: _units, funcs: _funcs, plugins: _plugins, keyframes: _keyframes, properties: _properties, handlers: _handlers, tokens: _tokens, ...injectorConfig } = config;
     const fullConfig = {
         ...createDefaultConfig(),
         ...currentConfig,
@@ -272,6 +352,10 @@ export function resetConfig() {
     stylesGenerated = false;
     currentConfig = null;
     globalKeyframes = null;
+    globalProperties = null;
+    resetGlobalPredefinedTokens();
+    resetHandlers();
+    clearPipelineCache();
     emittedWarnings.clear();
     const storage = typeof window !== 'undefined' ? window : globalThis;
     delete storage[GLOBAL_INJECTOR_KEY];

package/es/tasty/debug.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.99.3
+ * @cube-dev/ui-kit v0.101.0
  * Released under the MIT license.
  */
 
@@ -490,8 +490,8 @@ export const tastyDebug = {
                 CHUNK_NAMES.APPEARANCE,
                 CHUNK_NAMES.FONT,
                 CHUNK_NAMES.DIMENSION,
-                CHUNK_NAMES.CONTAINER,
-                CHUNK_NAMES.SCROLLBAR,
+                CHUNK_NAMES.DISPLAY,
+                CHUNK_NAMES.LAYOUT,
                 CHUNK_NAMES.POSITION,
                 CHUNK_NAMES.MISC,
                 CHUNK_NAMES.SUBCOMPONENTS,
@@ -816,8 +816,8 @@ export const tastyDebug = {
                     CHUNK_NAMES.APPEARANCE,
                     CHUNK_NAMES.FONT,
                     CHUNK_NAMES.DIMENSION,
-                    CHUNK_NAMES.CONTAINER,
-                    CHUNK_NAMES.SCROLLBAR,
+                    CHUNK_NAMES.DISPLAY,
+                    CHUNK_NAMES.LAYOUT,
                     CHUNK_NAMES.POSITION,
                     CHUNK_NAMES.MISC,
                     CHUNK_NAMES.SUBCOMPONENTS,

package/es/tasty/hooks/index.js

@@ -1,12 +1,14 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.99.3
+ * @cube-dev/ui-kit v0.101.0
  * Released under the MIT license.
  */
 
 export { useStyles } from './useStyles.js';
 export { useGlobalStyles } from './useGlobalStyles.js';
 export { useRawCSS } from './useRawCSS.js';
+export { useKeyframes } from './useKeyframes.js';
+export { useProperty } from './useProperty.js';
 
         

package/es/tasty/hooks/useGlobalStyles.js

@@ -1,7 +1,7 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.99.3
+ * @cube-dev/ui-kit v0.101.0
  * 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.101.0
+ * 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.101.0
+ * 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.99.3
+ * @cube-dev/ui-kit v0.101.0
  * Released under the MIT license.
  */