@ufoui/core 0.0.5 → 0.0.12

package/components/switch/switch.d.ts

@@ -1,5 +1,5 @@
 import { default as React, ReactNode } from 'react';
-import { BorderColor, ElementAlign, ElementDensity, ElementElevation, ElementFocusEffect, ElementFont, ElementHoverEffect, ElementOutline, ElementPressedEffect, ElementSelectedEffect, ElementShape, ElementSize, ElementTextPlacement, ElementTouchEffect, SemanticColor, SurfaceColor } from '../../utils';
+import { BorderColor, ElementAlign, ElementDensity, ElementElevation, ElementFocusEffect, ElementFont, ElementHoverEffect, ElementOutline, ElementPressedEffect, ElementSelectedEffect, ElementShape, ElementSize, ElementTextPlacement, ElementTouchEffect, SemanticColor } from '../../utils';
 /**
  * Props for the Switch component.
  *
@@ -26,10 +26,6 @@ export interface SwitchProps extends Omit<React.InputHTMLAttributes<HTMLInputEle
     density?: ElementDensity;
     /** Supporting text displayed below the label. */
     description?: string;
-    /** Text color override for the description. */
-    descriptionColor?: SurfaceColor;
-    /** Font token applied to the description text. */
-    descriptionFont?: ElementFont;
     /** Elevation level of the control surface. */
     elevation?: ElementElevation;
     /** Error message text. Overrides description when present. */
@@ -50,8 +46,6 @@ export interface SwitchProps extends Omit<React.InputHTMLAttributes<HTMLInputEle
     id?: string;
     /** Text label associated with the control. */
     label?: string;
-    /** Text color override for the label. */
-    labelColor?: SurfaceColor;
     /** Name attribute forwarded to the input element. */
     name?: string;
     /** Change event handler. */
@@ -66,8 +60,6 @@ export interface SwitchProps extends Omit<React.InputHTMLAttributes<HTMLInputEle
     shape?: ElementShape;
     /** Size of the control. */
     size?: ElementSize;
-    /** Text color override for label and content. */
-    textColor?: SurfaceColor;
     /** Layout of text relative to the control. */
     textPlacement?: ElementTextPlacement;
     /** Tooltip alignment relative to the control. */

package/components/toast/toast.d.ts

@@ -1,13 +1,15 @@
 import { default as React, ReactNode } from 'react';
-import { ElementElevation, ElementShape, SurfaceColor } from '../../utils';
+import { ElementElevation, ElementShape, SurfaceColor, ToastStatus } from '../../utils';
 import { BoxBaseProps } from '../base';
-import { ToastStatus } from '../../utils/toasts/toast';
+import { MotionAnimation, MotionStyle } from '../../types';
 /**
  * Props for Toast component.
  *
  * @category Toast
  */
 export interface ToastProps extends Omit<BoxBaseProps, 'children'> {
+    /** Toast identifier used for lifecycle control. */
+    id: string;
     /** Primary heading text. */
     title?: string;
     /** Secondary supporting text. */
@@ -20,18 +22,30 @@ export interface ToastProps extends Omit<BoxBaseProps, 'children'> {
     action?: ReactNode;
     /** Full content override replacing internal layout. */
     content?: ReactNode;
+    /** Time in milliseconds before the toast is automatically dismissed. */
+    timeout?: number;
     /** Elevation token. Default: 3 */
     elevation?: ElementElevation;
     /** Status variant applied as CSS modifier class. */
     status?: ToastStatus;
     /** Shape token. Default: smooth */
     shape?: ElementShape;
+    /** Animation preset used by internal motion elements. */
+    animation?: MotionAnimation;
+    /** Animation duration in milliseconds. */
+    duration?: number;
+    /** Motion style applied to animated elements. */
+    motionStyle?: MotionStyle;
+    leaving?: boolean;
+    onExitComplete?: (id: string) => void;
 }
 /**
- * Toast overlay container.
+ * Toast notification container.
+ *
+ * Handles auto-dismiss lifecycle using the timeout property.
  *
  * @function
- * @param props Component props.
+ * @param props Component properties.
  *
  * @category Toast
  */

package/components/toast/toastViewport.d.ts

@@ -1,6 +1,7 @@
-export type ToastPosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+export type ToastPosition = 'topLeft' | 'topCenter' | 'topRight' | 'bottomLeft' | 'bottomCenter' | 'bottomRight';
 export interface ToastViewportProps {
     position?: ToastPosition;
-    gap?: number;
+    timeout?: number;
+    limit?: number;
 }
-export declare const ToastViewport: ({ position, gap, }: ToastViewportProps) => import("react/jsx-runtime").JSX.Element;
+export declare const ToastViewport: ({ position, timeout, limit }: ToastViewportProps) => import("react/jsx-runtime").JSX.Element;

package/components/toolbar/toolbar.d.ts

@@ -19,7 +19,7 @@ export interface ToolbarProps extends Omit<BoxBaseProps, 'component' | 'elementC
     /** Density token. */
     density?: ElementDensity;
     /** Makes toolbar full width. */
-    fullWidth?: boolean;
+    wFull?: boolean;
     /** Positions floating toolbar. */
     placement?: 'top' | 'bottom' | 'left' | 'right' | 'center';
     /** Makes floating toolbar fixed. */

package/context/selectionContext.d.ts

@@ -1,31 +1,32 @@
+import { useRovingFocus } from '../hooks/useRovingFocus';
 /**
  * Context value shared by components that rely on selection behavior.
  *
- * Provides state and control logic for managing single or multiple
- * selected values.
+ * @typeParam T - Optional configuration object provided by the parent component.
  *
  * @category Contexts
  */
-export interface SelectionContextValue {
-    /** Currently selected values. */
-    values: string[];
-    /** Selection mode: single or multiple. */
-    mode: 'single' | 'multiple';
-    /** Toggles selection state for a given value. */
-    toggle: (value: string) => void;
-    /** Sets a value directly (primarily for single mode). */
-    set: (value: string) => void;
+export interface SelectionContextValue<T = unknown> {
     /** Clears all selected values. */
     clear: () => void;
+    /** Optional configuration object passed from the parent component. */
+    config?: T;
+    /** Selection type: single or multiple. */
+    type: 'single' | 'multiple';
+    /** Optional roving focus controller for keyboard navigation between items. */
+    roving?: ReturnType<typeof useRovingFocus>;
+    /** Sets a value directly. */
+    set: (value: string) => void;
+    /** Toggles selection state for a given value. */
+    toggle: (value: string) => void;
+    /** Currently selected values. */
+    values: string[];
 }
 /**
- * SelectionContext provides access to shared selection state.
- *
- * Used by components such as Accordion, Tabs, RadioGroup,
- * and similar patterns that require controlled selection logic.
+ * React context that exposes shared selection state and optional configuration.
  *
- * Returns `null` if used outside a provider.
+ * Returns `null` when accessed outside of a provider.
  *
  * @category Contexts
  */
-export declare const SelectionContext: import('react').Context<SelectionContextValue | null>;
+export declare const SelectionContext: import('react').Context<SelectionContextValue<unknown> | null>;

package/hooks/index.d.ts

@@ -1,8 +1,10 @@
 export * from './useAnimate';
 export * from './useClickOutside';
 export * from './useEscapeHandler';
-export * from './useFocusState';
 export * from './useFocusVisible';
 export * from './useResizeObserver';
 export * from './useSelection';
 export * from './useTheme';
+export * from './useSliderKeys';
+export * from './useSelectionState';
+export * from './useFocusTrap';

package/hooks/useAnimate.d.ts

@@ -19,36 +19,56 @@ export interface UseAnimateOptions {
  * @category Hooks
  */
 export interface UseAnimateResult {
-    /** True while in the opening phase. */
+    /** True during the opening phase. */
     opening: boolean;
-    /** True while in the closing phase. */
+    /** True during the closing phase. */
     closing: boolean;
-    /** True while an animation is actively running. */
+    /** True when animation is running and not temporarily suppressed. */
     animating: boolean;
-    /** True when no animation is active. */
+    /** True while animation is in progress (opening or closing). */
+    active: boolean;
+    /** True only before any animation has started. */
     idle: boolean;
     /** CSS variables controlling animation timing and direction. */
     animationVars: Record<string, string>;
-    /** Triggers the next animation step or forces open or closed direction. */
+    /** Triggers animation towards open or closed state. */
     animate(next?: 'open' | 'closed'): void;
 }
 /**
- * Animation state hook supporting automatic, one-shot, and manual step modes.
+ * Handles open/close animation with interrupt support.
  *
- * Mode behavior:
- * - Automatic mode: when t1 is provided, animate runs a timed open or close sequence.
- * - One-shot mode: when enabled, only the opening transition is performed.
- * - Manual mode: when t1 is not provided, each animate call advances the phase by one step.
+ * Flow:
+ * - animate('open') → sets phase to "opening" and starts a timer
+ * - after t1 → phase becomes "open" and timer is cleared
+ * - animate('closed') → sets phase to "closing" and starts a timer
+ * - after t2 → phase becomes "closed" and timer is cleared
  *
- * The hook handles animation interruption by clearing active timers and
- * temporarily suppressing visual animation to avoid glitches.
+ * Interrupt:
+ * - calling animate() during an active transition clears the current timer
+ * - a new transition starts immediately
+ * - for one render animating = false (reset frame)
  *
- * animationVars return CSS custom properties describing the active phase:
- * - --uui-duration defines the duration of the current phase in milliseconds.
- * - --uui-reverse indicates whether the animation direction should be reversed.
+ * State usage:
+ * - opening / closing → current transition phase
+ * - active → true while transition is in progress (used for mount/visibility)
+ * - animating → same as active, but disabled during reset frame (used for CSS classes)
+ * - idle → true only before the first animation
+ *
+ * Important:
+ * - use `active` to control visibility (mount/unmount)
+ * - use `animating` to apply or remove animation classes
+ *
+ * Timer:
+ * - created when transition starts
+ * - cleared on completion or interrupt
+ *
+ * Modes:
+ * - t1 defined → automatic timed transitions
+ * - t1 undefined → manual stepper (each call advances phase)
+ * - oneShot → only opening transition is executed
  *
  * @function
- * @param options Hook configuration options.
+ * @param options Hook configuration options
  *
  * @category Hooks
  */

package/hooks/useFocusTrap.d.ts

@@ -0,0 +1,32 @@
+import { RefObject } from 'react';
+/**
+ * Options for the useFocusTrap hook.
+ *
+ * @category Hooks
+ */
+export interface UseFocusTrapOptions {
+    /** Root element used as focus boundary. */
+    ref: RefObject<HTMLElement | null>;
+    /** Enables or disables the focus trap. */
+    enabled?: boolean;
+    /** Moves focus inside on mount when not already inside. */
+    autoFocus?: boolean;
+}
+/**
+ * Focus trap for modal containers.
+ *
+ * Keeps keyboard focus inside the given element.
+ * Handles Tab loop and restores focus on unmount.
+ * Also redirects focus back when returning from outside the document.
+ *
+ * Behavior:
+ * - traps Tab navigation within the root element
+ * - moves focus to element with data-autofocus or first focusable on mount
+ * - restores previous focus on cleanup
+ *
+ * @function
+ * @param options
+ *
+ * @category Hooks
+ */
+export declare const useFocusTrap: ({ ref, enabled, autoFocus }: UseFocusTrapOptions) => void;

package/hooks/useFocusVisible.d.ts

@@ -1,20 +1,22 @@
+import { FocusEventHandler } from 'react';
 /**
- * Determines whether focus indicators (focus rings) should be visible.
+ * Tracks focus state and determines whether focus indicators
+ * should be visibly rendered.
  *
- * Returns `true` when the user is navigating with the keyboard and `false`
- * for pointer-based interactions (mouse, touch, pen).
+ * Automatically merges external focus handlers.
  *
- * Internally tracks global interaction modality and mirrors the behavior
- * of the `:focus-visible` specification.
- *
- * @returns `true` if focus should be visibly rendered
- *
- * @example
- * const focusVisible = useFocusVisible();
- *
- * @example
- * <button className={focusVisible ? 'uui-focus-visible' : undefined} />
+ * @function useFocusVisible
+ * @param onFocus External onFocus handler
+ * @param onBlur External onBlur handler
+ * @returns Object containing focus flags and merged handlers
  *
  * @category Hooks
  */
-export declare function useFocusVisible(): boolean;
+export declare function useFocusVisible(onFocus?: FocusEventHandler<HTMLElement>, onBlur?: FocusEventHandler<HTMLElement>): {
+    focusVisible: boolean;
+    isFocused: boolean;
+    focusHandlers: {
+        onFocus: FocusEventHandler<HTMLElement>;
+        onBlur: FocusEventHandler<HTMLElement>;
+    };
+};

package/hooks/useResizeObserver.d.ts

@@ -1,6 +1,6 @@
 import { RefObject } from 'react';
 /**
- * Size information reported by ResizeObserver.
+ * Size information reported by ResizeObserver (CSS pixels).
  *
  * @category Hooks
  */
@@ -12,7 +12,10 @@ export interface ObservedElementSize {
 }
 /**
  * Observes a single DOM element using ResizeObserver
- * and invokes a callback when its content box size changes.
+ * and invokes a callback when its size changes.
+ *
+ * Uses the content box by default, or the border box when `borderBox` is true
+ * (includes padding and border; excludes margin).
  *
  * Does not trigger component re-render.
  *
@@ -20,7 +23,8 @@ export interface ObservedElementSize {
  * @param ref Reference to the observed HTMLElement.
  * @param onResize Called when size changes.
  * @param enabled Enables or disables observation. Default: true.
+ * @param borderBox When true, report border box size; when false, content box. Default: false.
  *
  * @category Hooks
  */
-export declare function useResizeObserver<T extends HTMLElement>(ref: RefObject<T>, onResize: (size: ObservedElementSize) => void, enabled?: boolean): void;
+export declare function useResizeObserver<T extends HTMLElement>(ref: RefObject<T>, onResize: (size: ObservedElementSize) => void, enabled?: boolean, borderBox?: boolean): void;

package/hooks/useRovingFocus.d.ts

@@ -0,0 +1,30 @@
+import { default as React } from 'react';
+/**
+ * Defines the directional axis used for roving focus navigation.
+ *
+ * @category Hooks
+ */
+export type RovingOrientation = 'vertical' | 'horizontal';
+/**
+ * Provides roving focus keyboard navigation for a group of elements.
+ *
+ * Enables Arrow, Home, and End key navigation across registered items
+ * using vertical or horizontal orientation.
+ *
+ * @param orientation Navigation direction. Default: 'vertical'.
+ * @param loop Whether focus should wrap around. Default: true.
+ *
+ * @returns Object containing register, unregister, and onKeyDown handlers.
+ *
+ * @example
+ * const roving = useRovingFocus('vertical');
+ *
+ * <button ref={roving.register} onKeyDown={roving.onKeyDown} />
+ *
+ * @category Hooks
+ */
+export declare function useRovingFocus(orientation?: RovingOrientation, loop?: boolean): {
+    register: (el: HTMLElement | null) => void;
+    unregister: (el: HTMLElement | null) => void;
+    onKeyDown: (e: React.KeyboardEvent<HTMLElement>) => void;
+};

package/hooks/useSelection.d.ts

@@ -1,13 +1,16 @@
-import { SelectionContextValue } from '../context/selectionContext';
+import { SelectionContextValue } from '../context';
 /**
- * Hook to access the current selection context.
+ * Provides typed access to SelectionContext including selection state,
+ * optional configuration, and roving focus controller.
  *
- * Must be used within a component that provides SelectionContext.
- * If used outside, it will throw an error.
+ * @typeParam T Optional configuration object type provided by the parent.
  *
- * @throws Error if the context is unavailable.
- * @returns The current SelectionContextValue.
+ * @returns The current selection context value.
+ *
+ * @example
+ * const { values, toggle, config, roving } =
+ *   useSelection<MyConfig>();
  *
  * @category Hooks
  */
-export declare function useSelection(): SelectionContextValue;
+export declare function useSelection<T = unknown>(): SelectionContextValue<T>;

package/hooks/useSelectionState.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Hook that provides shared selection state logic for components
+ * such as Accordion, Tabs or List.
+ *
+ * Manages selected values, exposes selection helpers and optionally
+ * enables roving focus for keyboard navigation.
+ *
+ * @function
+ *
+ * @param type Selection type controlling whether one or multiple values can be active.
+ * @param orientation Orientation used by roving focus navigation.
+ *
+ * @returns Object containing selection state, helper functions and roving focus controller.
+ *
+ * @category Hooks
+ */
+export declare function useSelectionState(type: 'single' | 'multiple', orientation?: 'vertical' | 'horizontal'): {
+    values: string[];
+    toggle: (value: string) => void;
+    set: (value: string) => void;
+    clear: () => void;
+    roving: {
+        register: (el: HTMLElement | null) => void;
+        unregister: (el: HTMLElement | null) => void;
+        onKeyDown: (e: React.KeyboardEvent<HTMLElement>) => void;
+    };
+    type: "single" | "multiple";
+    orientation: "vertical" | "horizontal";
+};

package/hooks/useSliderKeys.d.ts

@@ -0,0 +1,41 @@
+import { default as React } from 'react';
+/**
+ * Configuration for slider keyboard navigation.
+ *
+ * @category Hooks
+ */
+export interface UseSliderKeysOptions {
+    /** Current value. */
+    value: number;
+    /** Minimum value. */
+    min: number;
+    /** Maximum value. */
+    max: number;
+    /** Step applied by arrow keys. */
+    step: number;
+    /** Disables interaction. */
+    disabled?: boolean;
+    /** Prevents value changes. */
+    readOnly?: boolean;
+    /** Called when value changes. */
+    onChange: (value: number) => void;
+}
+/**
+ * Provides keyboard navigation for slider-like controls.
+ *
+ * Supports Arrow, Home and End keys to change the value.
+ *
+ * @param options Slider keyboard configuration.
+ *
+ * @returns Object containing onKeyDown handler.
+ *
+ * @example
+ * const keys = useSliderKeys({ value, min: 0, max: 5, step: 0.5, onChange });
+ *
+ * <div role="slider" onKeyDown={keys.onKeyDown} />
+ *
+ * @category Hooks
+ */
+export declare function useSliderKeys({ value, min, max, step, disabled, readOnly, onChange }: UseSliderKeysOptions): {
+    onKeyDown: (e: React.KeyboardEvent<HTMLElement>) => void;
+};