@cube-dev/ui-kit 0.99.3 → 0.101.0

package/types/components/navigation/Tabs/Tabs.d.ts

@@ -0,0 +1,236 @@
+import { Key } from '@react-types/shared';
+import { ReactElement, ReactNode } from 'react';
+import { BaseProps, OuterStyleProps, Styles } from '../../../tasty';
+import { CubeItemProps } from '../../content/Item';
+/** Visual appearance type for tabs */
+export type TabType = 'default' | 'file' | 'panel' | 'radio';
+/** Tab size options */
+export type TabSize = 'medium' | 'large';
+/** Common props for panel rendering behavior */
+interface PanelBehaviorProps {
+    /** If true, panel is rendered but hidden when not active. */
+    prerender?: boolean;
+    /** If true, once visited the panel stays in DOM. */
+    keepMounted?: boolean;
+}
+/** Common props for QA attributes */
+interface QAProps {
+    /** QA selector attribute. */
+    qa?: string;
+    /** Additional QA value attribute. */
+    qaVal?: string;
+}
+/** Props from CubeItemProps that don't apply to Tab */
+type OmittedItemProps = 'id' | 'type' | 'size' | 'theme' | 'shape' | 'icon' | 'rightIcon' | 'prefix' | 'suffix' | 'description' | 'descriptionPlacement' | 'descriptionProps' | 'tooltip' | 'defaultTooltipPlacement' | 'hotkeys' | 'keyboardShortcutProps' | 'loadingSlot' | 'isLoading' | 'labelProps' | 'labelRef' | 'level' | 'highlight' | 'highlightCaseSensitive' | 'highlightStyles' | 'variant' | 'htmlType' | 'isSelected' | 'preserveActionsSpace' | 'disableActionsFocus' | 'actions' | 'showActionsOnHover';
+/** Common styling props for tabs - inherits style props from CubeItemProps */
+interface TabStyleProps extends Omit<CubeItemProps, OmittedItemProps> {
+    /** Tab size. Large uses `t2m` preset, medium uses `t3m`. */
+    size?: TabSize;
+    /** Visual appearance type. */
+    type?: TabType;
+    /** Whether to show actions only on hover. */
+    showActionsOnHover?: boolean;
+}
+export interface CubeTabsProps extends BaseProps, OuterStyleProps, PanelBehaviorProps {
+    /** Controlled active tab key. When provided, component is controlled. */
+    activeKey?: Key;
+    /** Initial active tab key for uncontrolled mode. */
+    defaultActiveKey?: Key;
+    /**
+     * Visual appearance type for tabs.
+     * - `default` - Standard tabs with selection indicator below (default)
+     * - `file` - File-style tabs with fill highlight on selection, delimiter between tabs
+     * - `panel` - Panel-style tabs with border bottom highlight on selection, delimiter between tabs
+     * - `radio` - Radio button style for tab selection
+     * @default 'default'
+     */
+    type?: TabType;
+    /** Tab size. Large uses `t2m` preset, medium uses `t3m`. */
+    size?: TabSize;
+    /** Accessible label for the tab list. */
+    label?: string;
+    /** Content rendered before the tab list. */
+    prefix?: ReactNode;
+    /** Content rendered after the tab list. */
+    suffix?: ReactNode;
+    /** Callback when active tab changes. */
+    onChange?: (key: Key) => void;
+    /** Callback when tab delete button is clicked. Presence enables delete buttons. */
+    onDelete?: (key: Key) => void;
+    /** Callback when a tab title is changed. Enables title editing on tabs with isEditable. */
+    onTitleChange?: (key: Key, newTitle: string) => void;
+    /** Whether to show tab actions only on hover. Can be overridden per-tab. */
+    showActionsOnHover?: boolean;
+    /** Custom tasty styles for the tab bar container. */
+    styles?: Styles;
+    /** QA selector attribute. */
+    qa?: string;
+    /** Tab components or Tabs.List with Tabs.Panel. */
+    children?: ReactNode;
+    /**
+     * Functional content renderer for optimized lazy evaluation.
+     * When provided, panel content is only evaluated for the active tab,
+     * while inactive tabs use cached content. This prevents expensive
+     * re-renders of tab content on every parent render.
+     *
+     * Use with tabs that have no children for maximum optimization.
+     *
+     * @param key - The key of the tab to render content for
+     * @returns Panel content for the given tab
+     *
+     * @example
+     * ```tsx
+     * <Tabs
+     *   renderPanel={(key) => {
+     *     switch (key) {
+     *       case 'tab1': return <ExpensiveComponent />;
+     *       case 'tab2': return <AnotherExpensive />;
+     *       default: return null;
+     *     }
+     *   }}
+     * >
+     *   <Tab key="tab1" title="Tab 1" />
+     *   <Tab key="tab2" title="Tab 2" />
+     * </Tabs>
+     * ```
+     */
+    renderPanel?: (key: Key) => ReactNode;
+    /**
+     * Cache keys for individual panels. Enables caching for specified panels.
+     *
+     * By default (without cache keys), panels re-render on every Tabs render.
+     * When a panel has a non-undefined cache key defined, its content is cached
+     * and reused until the cache key changes.
+     *
+     * **Important:**
+     * - Cache keys must be primitive values (string, number, boolean, null).
+     * - Objects/arrays will cause cache misses on every render (reference comparison).
+     * - Symbol tab keys are not supported for caching (use string keys instead).
+     * - Setting a key to `undefined` is the same as not having it (no caching).
+     *
+     * @example
+     * ```tsx
+     * // Enable caching for specific panels with their dependencies as cache keys
+     * <Tabs
+     *   renderPanel={(key) => <Panel data={data[key]} />}
+     *   panelCacheKeys={{
+     *     tab1: data.tab1.version,  // Cached, invalidates when version changes
+     *     tab2: data.tab2.version,  // Cached, invalidates when version changes
+     *     // tab3 has no cache key - re-renders on every Tabs render
+     *   }}
+     * />
+     * ```
+     */
+    panelCacheKeys?: Record<string | number, string | number | boolean | null | undefined>;
+}
+export interface CubeTabProps extends TabStyleProps, PanelBehaviorProps {
+    /**
+     * Unique identifier for the tab. Used for activeKey matching.
+     * Auto-injected from the React `key` prop (converted to string).
+     * Note: All keys are internally converted to strings for React Aria compatibility.
+     */
+    id?: string;
+    /** Content displayed in the tab button. */
+    title: ReactNode;
+    /** Panel content rendered when tab is active. */
+    children?: ReactNode;
+    /** Disables the tab (cannot be selected). */
+    isDisabled?: boolean;
+    /** Actions to render in the tab (e.g., icons, buttons). Rendered before delete action if tab is deletable. */
+    actions?: ReactNode;
+    /** Whether the tab title can be edited. Requires onTitleChange on Tabs or Tab. */
+    isEditable?: boolean;
+    /** Callback when this tab's title is changed. Overrides parent's onTitleChange. */
+    onTitleChange?: (newTitle: string) => void;
+}
+export interface CubeTabPanelProps extends PanelBehaviorProps, QAProps {
+    /**
+     * Panel identifier. Must match a Tab's id.
+     * Auto-injected from the React `key` prop (converted to string).
+     */
+    id?: string;
+    /** Panel content. */
+    children?: ReactNode;
+    /** Custom tasty styles for the panel container. */
+    styles?: Styles;
+}
+export interface CubeTabListProps {
+    /** Tab components. */
+    children?: ReactNode;
+}
+/** Ref API for programmatic control of Tabs component */
+export interface CubeTabsRef {
+    /** The root DOM element of the Tabs component */
+    element: HTMLDivElement | null;
+    /** Start editing a tab's title by its key */
+    startEditing: (key: Key) => void;
+    /** Cancel the current editing session */
+    cancelEditing: () => void;
+}
+declare function Tab(_props: CubeTabProps): ReactElement | null;
+declare namespace Tab {
+    var displayName: string;
+}
+declare function TabPanel(_props: CubeTabPanelProps): ReactElement | null;
+declare namespace TabPanel {
+    var displayName: string;
+}
+declare function TabList(_props: CubeTabListProps): ReactElement | null;
+declare namespace TabList {
+    var displayName: string;
+}
+/**
+ * Tabs component for organizing content into multiple panels.
+ * Built with React Aria for full accessibility support.
+ *
+ * **Note:** Tab keys are internally converted to strings for React Aria compatibility.
+ * When using `activeKey`, `onChange`, etc., be aware that numeric keys will be
+ * converted to their string equivalents.
+ *
+ * @example
+ * // Simple usage
+ * <Tabs defaultActiveKey="tab1">
+ *   <Tab key="tab1" title="Tab 1">Content 1</Tab>
+ *   <Tab key="tab2" title="Tab 2">Content 2</Tab>
+ * </Tabs>
+ *
+ * @example
+ * // Tabs-only (no panels)
+ * <Tabs activeKey={activeTab} onChange={setActiveTab}>
+ *   <Tab key="overview" title="Overview" />
+ *   <Tab key="settings" title="Settings" />
+ * </Tabs>
+ *
+ * @example
+ * // Explicit panels
+ * <Tabs defaultActiveKey="tab1">
+ *   <Tabs.List>
+ *     <Tab key="tab1" title="Tab 1" />
+ *     <Tab key="tab2" title="Tab 2" />
+ *   </Tabs.List>
+ *   <Tabs.Panel key="tab1">Content 1</Tabs.Panel>
+ *   <Tabs.Panel key="tab2">Content 2</Tabs.Panel>
+ * </Tabs>
+ *
+ * @example
+ * // Optimized lazy rendering with renderPanel
+ * <Tabs
+ *   defaultActiveKey="tab1"
+ *   renderPanel={(key) => {
+ *     switch (key) {
+ *       case 'tab1': return <ExpensiveComponent />;
+ *       case 'tab2': return <AnotherExpensive />;
+ *       default: return null;
+ *     }
+ *   }}
+ * >
+ *   <Tab key="tab1" title="Tab 1" />
+ *   <Tab key="tab2" title="Tab 2" />
+ * </Tabs>
+ */
+export declare const Tabs: import("react").ForwardRefExoticComponent<CubeTabsProps & import("react").RefAttributes<CubeTabsRef>> & {
+    Tab: typeof Tab;
+    List: typeof TabList;
+    Panel: typeof TabPanel;
+};
+export { Tab, TabList, TabPanel };

package/types/components/navigation/Tabs/index.d.ts

@@ -0,0 +1,2 @@
+export { Tabs, Tab } from './Tabs';
+export type { CubeTabsProps, CubeTabsRef, CubeTabProps, CubeTabPanelProps, CubeTabListProps, } from './Tabs';

package/types/components/navigation/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Tabs';
+export type { CubeTabsProps, CubeTabProps, CubeTabPanelProps, CubeTabListProps, } from './Tabs';

package/types/index.d.ts

@@ -98,6 +98,7 @@ export type { CubeTooltipTriggerProps } from './components/overlays/Tooltip/Tool
 export { TooltipProvider } from './components/overlays/Tooltip/TooltipProvider';
 export type { CubeTooltipProviderProps } from './components/overlays/Tooltip/TooltipProvider';
 export * from './components/content/Alert';
+export * from './components/navigation';
 export { FileTabs } from './components/organisms/FileTabs/FileTabs';
 export type { CubeFileTabProps } from './components/organisms/FileTabs/FileTabs';
 export { StatsCard } from './components/organisms/StatsCard/StatsCard';

package/types/tasty/chunks/definitions.d.ts

@@ -6,6 +6,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
+ * ============================================================================
  */
 /**
  * Appearance chunk - visual styling with independent handlers
@@ -13,32 +44,46 @@
 export declare const APPEARANCE_CHUNK_STYLES: readonly ["fill", "color", "opacity", "border", "radius", "outline", "outlineOffset", "shadow", "fade"];
 /**
  * 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 declare const FONT_CHUNK_STYLES: readonly ["preset", "font", "fontWeight", "fontStyle", "fontSize", "lineHeight", "letterSpacing", "textTransform", "fontFamily", "textAlign", "whiteSpace", "textDecoration", "textOverflow", "wordBreak", "wordWrap", "boldFontWeight"];
+export declare const FONT_CHUNK_STYLES: readonly ["preset", "font", "fontWeight", "fontStyle", "fontSize", "lineHeight", "letterSpacing", "textTransform", "fontFamily", "textAlign", "textDecoration", "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 declare const DIMENSION_CHUNK_STYLES: readonly ["padding", "paddingTop", "paddingRight", "paddingBottom", "paddingLeft", "paddingBlock", "paddingInline", "margin", "marginTop", "marginRight", "marginBottom", "marginLeft", "marginBlock", "marginInline", "width", "height", "minWidth", "maxWidth", "minHeight", "maxHeight", "flexBasis", "flexGrow", "flexShrink", "flex"];
+export declare const DIMENSION_CHUNK_STYLES: readonly ["padding", "paddingTop", "paddingRight", "paddingBottom", "paddingLeft", "paddingBlock", "paddingInline", "margin", "marginTop", "marginRight", "marginBottom", "marginLeft", "marginBlock", "marginInline", "width", "minWidth", "maxWidth", "height", "minHeight", "maxHeight", "flexBasis", "flexGrow", "flexShrink", "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 declare const CONTAINER_CHUNK_STYLES: readonly ["display", "hide", "flow", "gap", "groupRadius", "placeItems", "placeContent", "alignItems", "alignContent", "justifyItems", "justifyContent", "align", "justify", "place", "columnGap", "rowGap", "gridColumns", "gridRows", "gridTemplate", "gridAreas", "gridAutoFlow", "gridAutoColumns", "gridAutoRows"];
+export declare const DISPLAY_CHUNK_STYLES: readonly ["display", "hide", "textOverflow", "overflow", "whiteSpace", "flow", "gap", "scrollbar", "styledScrollbar"];
 /**
- * Scrollbar chunk - scrollbar and overflow
- * ⚠️ scrollbarStyle handler requires scrollbar ↔ overflow together
+ * 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 declare const SCROLLBAR_CHUNK_STYLES: readonly ["scrollbar", "overflow", "styledScrollbar"];
+export declare const LAYOUT_CHUNK_STYLES: readonly ["placeItems", "placeContent", "alignItems", "alignContent", "justifyItems", "justifyContent", "align", "justify", "place", "columnGap", "rowGap", "gridColumns", "gridRows", "gridTemplate", "gridAreas", "gridAutoFlow", "gridAutoColumns", "gridAutoRows"];
 /**
- * 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 declare const POSITION_CHUNK_STYLES: readonly ["position", "inset", "top", "right", "bottom", "left", "zIndex", "gridArea", "gridColumn", "gridRow", "order", "placeSelf", "alignSelf", "justifySelf", "transform", "transition", "animation"];
+export declare const POSITION_CHUNK_STYLES: readonly ["position", "inset", "insetBlock", "insetInline", "top", "right", "bottom", "left", "zIndex", "gridArea", "gridColumn", "gridRow", "order", "placeSelf", "alignSelf", "justifySelf", "transform", "transition", "animation"];
 export declare const CHUNK_NAMES: {
     /** Special chunk for styles that cannot be split (e.g., @starting-style) */
     readonly COMBINED: "combined";
@@ -46,8 +91,8 @@ export declare const CHUNK_NAMES: {
     readonly APPEARANCE: "appearance";
     readonly FONT: "font";
     readonly DIMENSION: "dimension";
-    readonly CONTAINER: "container";
-    readonly SCROLLBAR: "scrollbar";
+    readonly DISPLAY: "display";
+    readonly LAYOUT: "layout";
     readonly POSITION: "position";
     readonly MISC: "misc";
 };

package/types/tasty/chunks/index.d.ts

@@ -1,4 +1,4 @@
-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';
+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';
 export type { ChunkName, ChunkInfo } from './definitions';
 export { generateChunkCacheKey } from './cacheKey';
 export { renderStylesForChunk } from './renderChunk';

package/types/tasty/config.d.ts

@@ -10,9 +10,10 @@
  * After the first `inject()` call, configuration is locked and attempts to
  * reconfigure will emit a warning and be ignored.
  */
-import type { KeyframesSteps } from './injector/types';
+import type { KeyframesSteps, PropertyDefinition } from './injector/types';
 import type { StyleDetails, UnitHandler } from './parser/types';
 import type { TastyPlugin } from './plugins/types';
+import type { StyleHandlerDefinition } from './utils/styles';
 /**
  * Configuration options for the Tasty style system
  */
@@ -93,6 +94,90 @@ export interface TastyConfig {
      * ```
      */
     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 '@cube-dev/ui-kit';
+     *
+     * 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.
+     * @example
+     * ```ts
+     * configure({
+     *   tokens: {
+     *     $spacing: '2x',
+     *     '$card-padding': '4x',
+     *     '#accent': '#purple',
+     *     '#surface': '#white',
+     *   },
+     * });
+     *
+     * // 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?: {
+        [key: `$${string}` | `#${string}`]: string | number;
+    };
 }
 declare const GLOBAL_INJECTOR_KEY = "__TASTY_GLOBAL_INJECTOR__";
 declare global {
@@ -107,6 +192,7 @@ export declare function isTestEnvironment(): boolean;
 /**
  * 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 declare function markStylesGenerated(): void;
 /**
@@ -127,6 +213,16 @@ export declare function hasGlobalKeyframes(): boolean;
  * Returns null if no keyframes configured (fast path for zero-overhead).
  */
 export declare function getGlobalKeyframes(): Record<string, KeyframesSteps> | null;
+/**
+ * Check if any global properties are configured.
+ * Fast path: returns false if no properties were ever set.
+ */
+export declare function hasGlobalProperties(): boolean;
+/**
+ * Get global properties configuration.
+ * Returns null if no properties configured (fast path for zero-overhead).
+ */
+export declare function getGlobalProperties(): Record<string, PropertyDefinition> | null;
 /**
  * Check if configuration is locked (styles have been generated)
  */

package/types/tasty/hooks/index.d.ts

@@ -2,3 +2,6 @@ export { useStyles } from './useStyles';
 export type { UseStylesOptions, UseStylesResult } from './useStyles';
 export { useGlobalStyles } from './useGlobalStyles';
 export { useRawCSS } from './useRawCSS';
+export { useKeyframes } from './useKeyframes';
+export { useProperty } from './useProperty';
+export type { UsePropertyOptions } from './useProperty';

package/types/tasty/hooks/useKeyframes.d.ts

@@ -0,0 +1,52 @@
+import { KeyframesSteps } from '../injector/types';
+type UseKeyframesOptions = {
+    name?: string;
+    root?: Document | ShadowRoot;
+};
+/**
+ * Hook to inject CSS @keyframes and return the generated animation name.
+ * Handles keyframes injection with proper cleanup on unmount or dependency changes.
+ *
+ * @example Basic usage - steps object is the dependency
+ * ```tsx
+ * function MyComponent() {
+ *   const bounce = useKeyframes({
+ *     '0%': { transform: 'scale(1)' },
+ *     '50%': { transform: 'scale(1.1)' },
+ *     '100%': { transform: 'scale(1)' },
+ *   });
+ *
+ *   return <div style={{ animation: `${bounce} 1s infinite` }}>Bouncing</div>;
+ * }
+ * ```
+ *
+ * @example With custom name
+ * ```tsx
+ * function MyComponent() {
+ *   const fadeIn = useKeyframes(
+ *     { from: { opacity: 0 }, to: { opacity: 1 } },
+ *     { name: 'fadeIn' }
+ *   );
+ *
+ *   return <div style={{ animation: `${fadeIn} 0.3s ease-out` }}>Fading in</div>;
+ * }
+ * ```
+ *
+ * @example Factory function with dependencies
+ * ```tsx
+ * function MyComponent({ scale }: { scale: number }) {
+ *   const pulse = useKeyframes(
+ *     () => ({
+ *       '0%': { transform: 'scale(1)' },
+ *       '100%': { transform: `scale(${scale})` },
+ *     }),
+ *     [scale]
+ *   );
+ *
+ *   return <div style={{ animation: `${pulse} 1s infinite` }}>Pulsing</div>;
+ * }
+ * ```
+ */
+export declare function useKeyframes(steps: KeyframesSteps, options?: UseKeyframesOptions): string;
+export declare function useKeyframes(factory: () => KeyframesSteps, deps: readonly unknown[], options?: UseKeyframesOptions): string;
+export {};

package/types/tasty/hooks/useProperty.d.ts

@@ -0,0 +1,75 @@
+export interface UsePropertyOptions {
+    /**
+     * CSS syntax string for the property (e.g., '<color>', '<length>', '<angle>').
+     * For color tokens (#name), this is auto-set to '<color>' and cannot be overridden.
+     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/@property/syntax
+     */
+    syntax?: string;
+    /**
+     * Whether the property inherits from parent elements
+     * @default true
+     */
+    inherits?: boolean;
+    /**
+     * Initial value for the property.
+     * For color tokens (#name), this defaults to 'transparent' if not specified.
+     */
+    initialValue?: string | number;
+    /**
+     * Shadow root or document to inject into
+     */
+    root?: Document | ShadowRoot;
+}
+/**
+ * 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 declare function useProperty(name: string, options?: UsePropertyOptions): void;

package/types/tasty/index.d.ts

@@ -1,6 +1,6 @@
 export { tasty, Element } from './tasty';
-export { useStyles, useGlobalStyles, useRawCSS } from './hooks';
-export type { UseStylesOptions, UseStylesResult } from './hooks';
+export { useStyles, useGlobalStyles, useRawCSS, useProperty, useKeyframes, } from './hooks';
+export type { UseStylesOptions, UseStylesResult, UsePropertyOptions, } from './hooks';
 export { configure, getConfig, isConfigLocked, hasStylesGenerated, resetConfig, isTestEnvironment, hasGlobalKeyframes, getGlobalKeyframes, } from './config';
 export type { TastyConfig } from './config';
 export { okhslPlugin, okhslFunc } from './plugins';
@@ -13,6 +13,7 @@ export * from './utils/filterBaseProps';
 export * from './utils/colors';
 export * from './utils/styles';
 export * from './utils/modAttrs';
+export { styleHandlers } from './styles';
 export { renderStyles, isSelector } from './pipeline';
 export type { StyleResult, RenderResult } from './pipeline';
 export * from './utils/dotize';