@cube-dev/ui-kit 0.99.3 → 0.100.0

package/types/tasty/styles/predefined.d.ts

@@ -1,6 +1,33 @@
-import { RawStyleHandler, StyleHandler } from '../utils/styles';
+import { RawStyleHandler, StyleHandler, StyleHandlerDefinition } from '../utils/styles';
+import { alignStyle } from './align';
+import { borderStyle } from './border';
+import { colorStyle } from './color';
+import { displayStyle } from './display';
+import { fadeStyle } from './fade';
+import { fillStyle, svgFillStyle } from './fill';
+import { flowStyle } from './flow';
+import { gapStyle } from './gap';
+import { heightStyle } from './height';
+import { insetStyle } from './inset';
+import { justifyStyle } from './justify';
+import { marginStyle } from './margin';
+import { outlineStyle } from './outline';
+import { paddingStyle } from './padding';
+import { presetStyle } from './preset';
+import { radiusStyle } from './radius';
+import { resetStyle } from './reset';
+import { scrollbarStyle } from './scrollbar';
+import { shadowStyle } from './shadow';
+import { styledScrollbarStyle } from './styledScrollbar';
+import { transitionStyle } from './transition';
+import { widthStyle } from './width';
 type StyleHandlerMap = Record<string, StyleHandler[]>;
 export declare const STYLE_HANDLER_MAP: StyleHandlerMap;
+/**
+ * Reset STYLE_HANDLER_MAP to the initial built-in state.
+ * Called by resetConfig() to restore handlers after tests.
+ */
+export declare function resetHandlers(): void;
 export declare function defineCustomStyle(names: string[] | StyleHandler, handler?: RawStyleHandler): void;
 type ConverterHandler = (s: string | boolean | number | undefined) => string | undefined;
 export declare function defineStyleAlias(styleName: string, cssStyleName?: string, converter?: ConverterHandler): void;
@@ -9,4 +36,74 @@ export declare function predefine(): {
     defineCustomStyle: typeof defineCustomStyle;
     defineStyleAlias: typeof defineStyleAlias;
 };
+/**
+ * Normalize a handler definition to a StyleHandler with __lookupStyles.
+ * - Function only: lookup styles inferred from key name
+ * - [string, fn]: single lookup style
+ * - [string[], fn]: multiple lookup styles
+ */
+export declare function normalizeHandlerDefinition(keyName: string, definition: StyleHandlerDefinition): StyleHandler;
+/**
+ * Validate a handler result in development mode.
+ * Call this after invoking a handler to check the return value.
+ */
+export declare function validateHandlerResult(name: string, result: unknown): void;
+/**
+ * Register a custom handler, replacing any existing handlers for the same lookup styles.
+ * This is called by configure() to process user-defined handlers.
+ *
+ * When registering a handler for style X, any existing handler that processes X
+ * is removed from ALL its lookup styles to prevent double-processing.
+ * For example, if gapStyle handles ['display', 'flow', 'gap'] and a new handler
+ * is registered for just ['gap'], gapStyle is removed from display and flow too.
+ */
+export declare function registerHandler(handler: StyleHandler): void;
+/**
+ * Exported object containing wrapped predefined style handlers.
+ * Users can import and call these to extend or delegate to built-in behavior.
+ *
+ * Internal handlers use *Style suffix for searchability.
+ * External API uses short names for convenience.
+ *
+ * @example
+ * ```ts
+ * import { styleHandlers, configure } from '@cube-dev/ui-kit';
+ *
+ * configure({
+ *   handlers: {
+ *     fill: ({ fill }) => {
+ *       if (fill?.startsWith('gradient:')) {
+ *         return { background: fill.slice(9) };
+ *       }
+ *       return styleHandlers.fill({ fill });
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare const styleHandlers: {
+    readonly align: typeof alignStyle;
+    readonly border: typeof borderStyle;
+    readonly color: typeof colorStyle;
+    readonly display: typeof displayStyle;
+    readonly fade: typeof fadeStyle;
+    readonly fill: typeof fillStyle;
+    readonly svgFill: typeof svgFillStyle;
+    readonly flow: typeof flowStyle;
+    readonly gap: typeof gapStyle;
+    readonly height: typeof heightStyle;
+    readonly inset: typeof insetStyle;
+    readonly justify: typeof justifyStyle;
+    readonly margin: typeof marginStyle;
+    readonly outline: typeof outlineStyle;
+    readonly padding: typeof paddingStyle;
+    readonly preset: typeof presetStyle;
+    readonly radius: typeof radiusStyle;
+    readonly reset: typeof resetStyle;
+    readonly scrollbar: typeof scrollbarStyle;
+    readonly shadow: typeof shadowStyle;
+    readonly styledScrollbar: typeof styledScrollbarStyle;
+    readonly transition: typeof transitionStyle;
+    readonly width: typeof widthStyle;
+};
 export {};

package/types/tasty/styles/preset.d.ts

@@ -1,14 +1,33 @@
 import { Styles } from './types';
-export declare function presetStyle({ preset, fontSize, lineHeight, textTransform, letterSpacing, fontWeight, fontStyle, font, }: {
+interface PresetStyleProps {
     preset?: string | boolean;
     fontSize?: string | number;
     lineHeight?: string | number;
     textTransform?: string;
     letterSpacing?: string | number;
     fontWeight?: string | number;
-    fontStyle?: string;
-    font?: string;
-}): "" | Styles;
+    fontStyle?: string | boolean;
+    fontFamily?: string;
+    /** Alias for fontFamily with special handling for 'monospace' and boolean */
+    font?: string | boolean;
+}
+/**
+ * Handles typography preset and individual font properties.
+ *
+ * When `preset` is defined, it sets up CSS custom properties for typography.
+ * Individual font props can be used with or without `preset`:
+ * - With `preset`: overrides the preset value for that property
+ * - Without `preset`: outputs the CSS directly
+ *
+ * Number values are converted to pixels for fontSize, lineHeight, letterSpacing.
+ * fontWeight accepts numbers directly (e.g., 400, 700).
+ *
+ * font vs fontFamily:
+ * - `font` is the recommended prop with special handling (monospace, boolean, fallback)
+ * - `fontFamily` is a direct value without special handling
+ */
+export declare function presetStyle({ preset, fontSize, lineHeight, textTransform, letterSpacing, fontWeight, fontStyle, fontFamily, font, }: PresetStyleProps): Styles | undefined;
 export declare namespace presetStyle {
     var __lookupStyles: string[];
 }
+export {};

package/types/tasty/styles/radius.d.ts

@@ -1,8 +1,8 @@
 export declare function radiusStyle({ radius }: {
     radius: any;
-}): "" | {
+}): {
     'border-radius': string;
-};
+} | undefined;
 export declare namespace radiusStyle {
     var __lookupStyles: string[];
 }

package/types/tasty/styles/shadow.d.ts

@@ -1,8 +1,8 @@
 export declare function shadowStyle({ shadow }: {
     shadow: any;
-}): "" | {
+}): {
     'box-shadow': any;
-};
+} | undefined;
 export declare namespace shadowStyle {
     var __lookupStyles: string[];
 }

package/types/tasty/styles/types.d.ts

@@ -1,5 +1,5 @@
 import { CSSProperties } from 'react';
-import { KeyframesSteps } from '../injector/types';
+import { KeyframesSteps, PropertyDefinition } from '../injector/types';
 import { StyleValue, StyleValueStateMap } from '../utils/styles';
 type NamedColor = 'purple' | 'purple-text' | 'purple-icon' | 'purple-bg' | 'purple-01' | 'purple-02' | 'purple-03' | 'purple-04' | 'dark' | 'dark-01' | 'dark-02' | 'dark-03' | 'dark-04' | 'dark-05' | 'dark-bg' | 'text' | 'primary' | 'disabled' | 'disabled-bg' | 'disabled-text' | 'danger' | 'danger-bg' | 'danger-text' | 'danger-icon' | 'success' | 'success-bg' | 'success-text' | 'success-icon' | 'note' | 'note-bg' | 'note-text' | 'note-icon' | 'white' | 'light' | 'light-grey' | 'black' | 'pink' | 'pink-01' | 'pink-02' | 'border' | 'clear' | 'shadow' | 'draft' | 'minor';
 type Digit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
@@ -28,6 +28,27 @@ export interface StylesInterface extends Omit<CSSProperties, 'color' | 'fill' |
      * - `fill={true}` // default fill color
      */
     fill?: `#${NamedColor}${OpaquePercentage}` | `rgb(${string})` | `rgba(${string})` | boolean | (string & {});
+    /**
+     * @deprecated Use `fill` instead.
+     */
+    backgroundColor?: CSSProperties['backgroundColor'];
+    /**
+     * Set the background image of the element. Shortcut for `background-image` with enhanced support for Tasty tokens.
+     *
+     * Examples:
+     * - `image="url(/path/to/image.png)"` // image from URL
+     * - `image="linear-gradient(to right, #purple, #danger)"` // gradient
+     */
+    image?: CSSProperties['backgroundImage'];
+    /**
+     * @deprecated Use `image` instead.
+     */
+    backgroundImage?: CSSProperties['backgroundImage'];
+    /**
+     * @deprecated Use separate background styles (`fill`, `image`, `backgroundSize`, etc.) instead.
+     * When set, overrides all other background-related styles.
+     */
+    background?: CSSProperties['background'];
     /**
      * Set the fill color of SVG elements. Outputs the native CSS `fill` property with enhanced support for Tasty color tokens and syntaxes.
      *
@@ -51,13 +72,23 @@ export interface StylesInterface extends Omit<CSSProperties, 'color' | 'fill' |
     /**
      * The fade style applies gradient-based fading masks to the edges of an element. Replaces complex CSS mask gradients with a simple, declarative API.
      *
-     * Syntax: `[width] [directions]`
+     * Syntax: `[width] [directions] [#transparent-color] [#opaque-color]`
+     *
+     * Multiple groups can be separated by commas to specify different colors per direction.
+     *
+     * Color tokens (optional):
+     * - First color: transparent mask color (start of gradient, default: `rgb(0 0 0 / 0)`)
+     * - Second color: opaque mask color (end of gradient, default: `rgb(0 0 0 / 1)`)
      *
      * Examples:
      * - `fade="top"` // fade only top edge with default width
      * - `fade="2x left right"` // fade left and right edges with 2x width
      * - `fade="1x top"` // fade only top edge with 1x width
      * - `fade="3x 1x top bottom"` // top: 3x width, bottom: 1x width
+     * - `fade="2x #transparent #dark"` // custom colors for gradient mask
+     * - `fade="1x top #clear #solid"` // top edge with custom mask colors
+     * - `fade="top #red #blue, bottom #green #yellow"` // different colors per direction
+     * - `fade="2x top #a #b, 1x bottom #c #d"` // different widths and colors per direction
      */
     fade?: 'top' | 'right' | 'bottom' | 'left' | string;
     /**
@@ -157,11 +188,15 @@ export interface StylesInterface extends Omit<CSSProperties, 'color' | 'fill' |
      *
      * Syntax: `[width] [style] [color] [directions]` | `[directions]` | `true`
      *
+     * Multiple groups can be separated by commas. Later groups override earlier groups for conflicting directions.
+     *
      * Examples:
      * - `border={true}` // default border on all sides (1bw solid)
      * - `border="2bw dashed #purple"` // 2bw dashed purple border
      * - `border="2bw top"` // only top border: 2bw solid
      * - `border="dotted #danger left right"` // left/right: 1bw dotted danger
+     * - `border="1bw #red, 2bw #blue top"` // all sides red 1bw, top overridden to blue 2bw
+     * - `border="1bw, dashed top bottom, #purple left right"` // base 1bw, dashed on top/bottom, purple on left/right
      */
     border?: CSSProperties['border'] | string | boolean;
     /**
@@ -210,18 +245,6 @@ export interface StylesInterface extends Omit<CSSProperties, 'color' | 'fill' |
      * - `radius="1r top"` // round only top corners
      */
     radius?: 'round' | 'ellipse' | 'leaf' | 'backleaf' | string | true;
-    /**
-     * The group radius style rounds the corners of a container's outer border edge by applying radius styles to its children.
-     *
-     * Syntax: `[value] [shape]` | `true`
-     *
-     * Examples:
-     * - `groupRadius="2r"` // apply 2r radius to children
-     * - `groupRadius="round"` // fully rounded children
-     * - `groupRadius="ellipse"` // elliptical children corners
-     * - `groupRadius={true}` // default group radius
-     */
-    groupRadius?: 'round' | 'ellipse' | string | boolean;
     /**
      * The flow style is a unified shorthand for controlling layout direction and wrapping in both flex and grid containers. Replaces `flexDirection` and `gridAutoFlow`.
      *
@@ -279,17 +302,24 @@ export interface StylesInterface extends Omit<CSSProperties, 'color' | 'fill' |
      */
     font?: CSSProperties['fontFamily'] | boolean;
     /**
-     * The outline style sets the outline for the element using `box-shadow` CSS property. The outline is drawn inside if `inset` modifier is set.
+     * The outline style sets the outline for the element.
      *
-     * Syntax: `[width] [style] [color] [offset]` | `[width] [color] inset` | `true`
+     * Syntax: `[width] [style] [color] / [offset]` | `true`
      *
      * Examples:
      * - `outline="2ow dashed #purple"` // 2ow dashed purple outline
-     * - `outline="2ow #danger 1x"` // 2ow solid danger outline, 1x offset
-     * - `outline="inset"` // inset outline with defaults
+     * - `outline="2ow #danger / 1x"` // 2ow solid danger outline, 1x offset
      * - `outline={true}` // default outline (1ow solid)
      */
     outline?: string | boolean;
+    /**
+     * The outline offset style sets the offset of the outline.
+     *
+     * Examples:
+     * - `outlineOffset="4px"` // 4px offset
+     * - `outlineOffset="1x"` // 1x (8px) offset
+     */
+    outlineOffset?: string | number;
     /**
      * The preset style sets base text settings according to named presets. Affects `font-size`, `line-height`, `letter-spacing`, `font-weight`, and `text-transform`.
      *
@@ -370,19 +400,41 @@ export interface StylesInterface extends Omit<CSSProperties, 'color' | 'fill' |
      * - `'@keyframes': { pulse: { '0%, 100%': 'transform: scale(1)', '50%': 'transform: scale(1.05)' } }`
      */
     '@keyframes'?: Record<string, KeyframesSteps>;
+    /**
+     * CSS @property definitions for custom properties using tasty token syntax.
+     * Properties are registered once and are permanent (never removed).
+     *
+     * Token formats:
+     * - `$name` for regular properties → `--name` (requires syntax to be specified)
+     * - `#name` for color properties → `--name-color` (auto-sets syntax: '<color>', defaults initialValue: 'transparent')
+     *
+     * Examples:
+     * - `'@properties': { '$rotation': { syntax: '<angle>', inherits: false, initialValue: '45deg' } }`
+     * - `'@properties': { '#theme': { initialValue: 'purple' } }` // syntax: '<color>' is auto-set
+     */
+    '@properties'?: Record<string, PropertyDefinition>;
 }
 export type SuffixForSelector = '&' | '.' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
 export type Selector = `${SuffixForSelector}${string}`;
 export type NotSelector = Exclude<string, Selector | keyof StylesInterface>;
+/** Special style keys that should not be wrapped in StyleValue/StyleValueStateMap */
+type SpecialStyleKeys = '@keyframes' | '@properties';
 export type StylesWithoutSelectors = {
-    [key in keyof StylesInterface]?: StyleValue<StylesInterface[key]> | StyleValueStateMap<StylesInterface[key]>;
+    [key in keyof StylesInterface as key extends SpecialStyleKeys ? never : key]?: StyleValue<StylesInterface[key]> | StyleValueStateMap<StylesInterface[key]>;
 };
-export type Styles = StylesWithoutSelectors & {
-    [key: string]: StyleValue<string | number | boolean | undefined> | StyleValueStateMap<string | number | boolean | undefined> | Styles;
+/** Special properties that are not regular style values */
+export interface SpecialStyleProperties {
+    '@keyframes'?: StylesInterface['@keyframes'];
+    '@properties'?: StylesInterface['@properties'];
+}
+/** Index signature for arbitrary style keys (sub-elements, CSS variables, etc.) */
+export interface StylesIndexSignature {
+    [key: string]: StyleValue<string | number | boolean | undefined> | StyleValueStateMap<string | number | boolean | undefined> | Styles | StylesInterface['@keyframes'] | StylesInterface['@properties'];
     /**
      * Selector combinator: `undefined` (descendant, default), `'>'` (child), `'+'` (adjacent), `'~'` (sibling).
      * Can chain with capitalized names: `'> Body > Row >'`. Spaces required around combinators.
      */
     $?: string;
-};
+}
+export type Styles = StylesWithoutSelectors & SpecialStyleProperties & StylesIndexSignature;
 export {};

package/types/tasty/styles/width.d.ts

@@ -1,6 +1,10 @@
-export declare function widthStyle({ width }: {
-    width: any;
-}): "" | Record<string, string | string[]>;
+interface WidthStyleProps {
+    width?: string | number | boolean;
+    minWidth?: string | number | boolean;
+    maxWidth?: string | number | boolean;
+}
+export declare function widthStyle({ width, minWidth, maxWidth }: WidthStyleProps): Record<string, string | string[]> | undefined;
 export declare namespace widthStyle {
     var __lookupStyles: string[];
 }
+export {};