@ufoui/core 0.0.4 → 0.0.12

package/context/themeContext.d.ts

@@ -1,5 +1,5 @@
-import { Theme } from '../types/index.ts';
-import { ThemeColor } from '../index.ts';
+import { Theme } from '../types';
+import { ThemeColor } from '../utils';
 /**
  * Provides shape for the theme context shared across the application.
  * Allows reading and updating theme configuration and resolving token values.

package/hooks/index.d.ts

@@ -0,0 +1,10 @@
+export * from './useAnimate';
+export * from './useClickOutside';
+export * from './useEscapeHandler';
+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

@@ -10,8 +10,8 @@ export interface UseAnimateOptions {
     t2?: number;
     /** Enables one-shot animation behavior. */
     oneShot?: boolean;
-    /** One-time start command executed on mount. */
-    action?: 'idle' | 'open' | 'close';
+    /** Initial phase on mount. */
+    initial?: 'idle' | 'open' | 'closed';
 }
 /**
  * Result returned by the useAnimate hook.
@@ -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

@@ -0,0 +1,30 @@
+import { RefObject } from 'react';
+/**
+ * Size information reported by ResizeObserver (CSS pixels).
+ *
+ * @category Hooks
+ */
+export interface ObservedElementSize {
+    /** Element width in pixels. */
+    width: number;
+    /** Element height in pixels. */
+    height: number;
+}
+/**
+ * Observes a single DOM element using ResizeObserver
+ * 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.
+ *
+ * @function
+ * @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, 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

@@ -0,0 +1,16 @@
+import { SelectionContextValue } from '../context';
+/**
+ * Provides typed access to SelectionContext including selection state,
+ * optional configuration, and roving focus controller.
+ *
+ * @typeParam T Optional configuration object type provided by the parent.
+ *
+ * @returns The current selection context value.
+ *
+ * @example
+ * const { values, toggle, config, roving } =
+ *   useSelection<MyConfig>();
+ *
+ * @category Hooks
+ */
+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;
+};