@react-hive/honey-layout 15.0.0 → 16.0.0

package/dist/hooks/use-honey-resize.d.ts

@@ -1,45 +0,0 @@
-export type UseHoneyResizeHandler = () => void;
-interface UseHoneyResizeOptions {
-    /**
-     * Whether to invoke the resize handler immediately on mount.
-     *
-     * Useful when initial layout measurements should be performed
-     * before any resize events occur.
-     *
-     * @default false
-     */
-    invokeOnMount?: boolean;
-    /**
-     * Throttle delay (in milliseconds) applied to the resize handler.
-     *
-     * When greater than `0`, the handler will be throttled using
-     * `lodash.throttle` to reduce invocation frequency.
-     *
-     * @default 0
-     */
-    throttleTime?: number;
-    /**
-     * Enables or disables the resize listener.
-     *
-     * @default true
-     */
-    enabled?: boolean;
-}
-/**
- * A hook that subscribes to the window `resize` event and invokes a handler function in response.
- *
- * The handler can be optionally throttled to limit execution frequency, which is useful
- * for expensive layout calculations or DOM measurements.
- *
- * @example
- * ```ts
- * useHoneyResize(() => {
- *   console.log('Window resized');
- * }, { throttleTime: 200 });
- * ```
- *
- * @param handler - Callback invoked when the window is resized.
- * @param options - Configuration options controlling invocation timing and performance.
- */
-export declare const useHoneyResize: (handler: UseHoneyResizeHandler, { invokeOnMount, throttleTime, enabled }?: UseHoneyResizeOptions) => void;
-export {};

package/dist/hooks/use-honey-synthetic-scroll-x.d.ts

@@ -1,19 +0,0 @@
-import type { UseHoneySyntheticScrollOptions } from './use-honey-synthetic-scroll';
-/**
- * Enables synthetic horizontal (X-axis) scrolling for a container element
- * using pointer-based drag interactions.
- *
- * This is a convenience wrapper around {@link useHoneySyntheticScroll} with
- * the axis fixed to `'x'`.
- *
- * All behavior, boundaries, and lifecycle guarantees are identical to the
- * base hook, but limited to horizontal movement only.
- *
- * @template Element - The HTML element type of the scrollable container.
- *
- * @param options - Configuration options forwarded to
- * {@link useHoneySyntheticScroll}, excluding the `axis` option.
- *
- * @returns A ref that must be attached to the scrollable container element.
- */
-export declare const useHoneySyntheticScrollX: <Element extends HTMLElement>(options?: Omit<UseHoneySyntheticScrollOptions<Element>, "axis">) => import("react").RefObject<import("..").Nullable<Element>>;

package/dist/hooks/use-honey-synthetic-scroll-y.d.ts

@@ -1,19 +0,0 @@
-import type { UseHoneySyntheticScrollOptions } from './use-honey-synthetic-scroll';
-/**
- * Enables synthetic vertical (Y-axis) scrolling for a container element
- * using pointer-based drag interactions.
- *
- * This is a convenience wrapper around {@link useHoneySyntheticScroll} with
- * the axis fixed to `'y'`.
- *
- * All behavior, boundaries, and lifecycle guarantees are identical to the
- * base hook, but limited to vertical movement only.
- *
- * @template Element - The HTML element type of the scrollable container.
- *
- * @param options - Configuration options forwarded to
- * {@link useHoneySyntheticScroll}, excluding the `axis` option.
- *
- * @returns A ref that must be attached to the scrollable container element.
- */
-export declare const useHoneySyntheticScrollY: <Element extends HTMLElement>(options?: Omit<UseHoneySyntheticScrollOptions<Element>, "axis">) => import("react").RefObject<import("..").Nullable<Element>>;

package/dist/hooks/use-honey-synthetic-scroll.d.ts

@@ -1,143 +0,0 @@
-import type { RefObject } from 'react';
-import type { Axis } from '@react-hive/honey-utils';
-import type { Nullable } from '../types';
-import type { UseHoneyDragHandlers } from './use-honey-drag';
-interface ResolveAxisTranslateOptions {
-    /**
-     * Drag delta for the axis (deltaX or deltaY).
-     */
-    delta: number;
-    /**
-     * Current translate value for the axis.
-     */
-    translate: number;
-    /**
-     * Visible container size for the axis (width or height).
-     */
-    containerSize: number;
-    /**
-     * Overflow size for the axis.
-     */
-    overflowSize: number;
-    /**
-     * Overscroll window percentage.
-     */
-    overscrollPct: number;
-}
-export declare const resolveAxisTranslate: ({ delta, translate, containerSize, overflowSize, overscrollPct, }: ResolveAxisTranslateOptions) => Nullable<number>;
-export interface UseHoneySyntheticScrollOptions<Element extends HTMLElement> extends Pick<UseHoneyDragHandlers<Element>, 'onStartDrag' | 'onEndDrag'> {
-    /**
-     * Axis along which synthetic scrolling is enabled.
-     *
-     * - `'x'` — horizontal only
-     * - `'y'` — vertical only
-     * - `'both'` — horizontal and vertical
-     *
-     * @default 'both'
-     */
-    axis?: Axis;
-    /**
-     * Percentage of the container size used as an overscroll buffer
-     * on each enabled axis.
-     *
-     * This allows limited dragging beyond the natural content bounds
-     * before movement is clamped.
-     *
-     * A value of `0` disables overscroll entirely.
-     *
-     * @default 0
-     */
-    overscrollPct?: number;
-    /**
-     * Controls how the hook applies scroll-related interaction styles
-     * (`touch-action` and `overscroll-behavior`) to the container.
-     *
-     * Synthetic scrolling often requires restricting native browser scrolling
-     * behavior to ensure consistent drag and wheel handling.
-     *
-     * However, in some embedded layouts (such as carousels placed inside a
-     * vertically scrollable page), applying these styles can unintentionally
-     * block natural page scrolling.
-     *
-     * ### Modes
-     * - `'default'` — Applies restrictive interaction styles:
-     *   - `overscroll-behavior: contain`
-     *   - Axis-aware `touch-action` (`pan-y`, `pan-x`, or `none`)
-     *
-     *   Recommended for standalone synthetic scroll containers.
-     *
-     * - `'embedded'` — Does not apply any interaction-blocking styles.
-     *
-     *   Recommended when the container is integrated into another scrollable
-     *   context (e.g. horizontal carousel inside a page), where native scroll
-     *   chaining must remain intact.
-     *
-     * @default 'default'
-     */
-    scrollMode?: 'default' | 'embedded';
-    /**
-     * Whether to clear any applied translation transforms when the window resizes.
-     *
-     * Useful to keep the layout state consistent after dimension changes.
-     *
-     * @default true
-     */
-    resetOnResize?: boolean;
-    /**
-     * Enables synthetic scrolling driven by pointer-based scroll input,
-     * such as mouse wheels and trackpads.
-     *
-     * When enabled, scroll input is intercepted and converted into bounded
-     * translation using the same logic as drag gestures.
-     *
-     * When disabled, native scrolling behavior is preserved and no scroll
-     * input is handled by this hook.
-     *
-     * @default true
-     */
-    enablePointerScroll?: boolean;
-    /**
-     * Master toggle for the synthetic scroll behavior.
-     *
-     * When `true`, the hook:
-     * - Enables drag-based translation via {@link useHoneyDrag}.
-     * - Optionally resets transforms on resize via {@link useHoneyResize}.
-     * - Applies overscroll and touch-action styles.
-     * - Intercepts wheel / trackpad scroll input if {@link enablePointerScroll} is enabled.
-     *
-     * When `false`, the hook becomes completely inert:
-     * - No drag or wheel listeners are attached.
-     * - No transforms are applied.
-     * - Native scrolling behavior is preserved.
-     *
-     * Useful for conditionally disabling synthetic scrolling
-     * (e.g. mobile layouts, reduced motion, or feature flags).
-     *
-     * @default true
-     */
-    enabled?: boolean;
-}
-/**
- * Enables synthetic scrolling for a container using pointer-based drag gestures.
- *
- * Instead of relying on native scrollbars, this hook translates the container
- * using CSS transforms in response to drag input.
- *
- * ### Key characteristics
- * - Dragging is only applied when content overflows the container on a given axis.
- * - Movement is clamped within calculated bounds, with optional overscroll allowance.
- * - Scroll position is stored purely in `transform: translate(...)`.
- * - Active transforms can be automatically cleared on window resize.
- *
- * ### Internals
- * - Uses {@link useHoneyDrag} to track mouse / touch movement.
- * - Uses {@link useHoneyResize} to optionally reset scroll state on resize.
- *
- * @template Element - The HTML element type of the scrollable container.
- *
- * @param options - Configuration controlling axes, boundaries, and lifecycle behavior.
- *
- * @returns A ref that must be attached to the scrollable container element.
- */
-export declare const useHoneySyntheticScroll: <Element extends HTMLElement>({ axis, overscrollPct, onStartDrag, onEndDrag, scrollMode, resetOnResize, enablePointerScroll, enabled, }?: UseHoneySyntheticScrollOptions<Element>) => RefObject<Nullable<Element>>;
-export {};

package/dist/hooks/use-honey-timer.d.ts

@@ -1,107 +0,0 @@
-/**
- * Timer operating mode.
- *
- * - `countdown` — decreases time until it reaches `targetTimeMs`
- * - `countup` — increases time until it reaches `targetTimeMs` (if provided)
- */
-type UseHoneyTimerMode = 'countdown' | 'countup';
-type UseHoneyTimerOnEndHandler = () => void;
-export interface UseHoneyTimerOptions {
-    /**
-     * Initial timer value in milliseconds.
-     *
-     * - Countdown: starting time
-     * - Count-up: initial offset
-     */
-    initialTimeMs: number;
-    /**
-     * Target time in milliseconds.
-     *
-     * - Countdown: usually `0`
-     * - Count-up: optional upper limit
-     *
-     * When reached, the timer stops and `onEnd` is invoked.
-     *
-     * @default 0
-     */
-    targetTimeMs?: number;
-    /**
-     * Direction in which the timer progresses.
-     *
-     * @default 'countdown'
-     */
-    mode?: UseHoneyTimerMode;
-    /**
-     * Whether the timer should automatically start on mount.
-     *
-     * @default false
-     */
-    autoStart?: boolean;
-    /**
-     * Optional callback invoked exactly once when the timer reaches the target time.
-     */
-    onEnd?: UseHoneyTimerOnEndHandler;
-}
-/**
- * Public control API returned by {@link useHoneyTimer}.
- */
-export interface UseHoneyTimerApi {
-    /**
-     * Current timer value in milliseconds.
-     *
-     * This value updates over time while the timer is running.
-     */
-    timeMs: number;
-    /**
-     * Indicates whether the timer is currently progressing.
-     */
-    isRunning: boolean;
-    /**
-     * Starts the timer from `initialTimeMs`, resetting any previous state.
-     */
-    start: () => void;
-    /**
-     * Pauses the timer while preserving the current time value.
-     */
-    pause: () => void;
-    /**
-     * Resumes the timer from its current time value.
-     *
-     * Has no effect if the timer is already running.
-     */
-    resume: () => void;
-    /**
-     * Resets the timer to a specific time value.
-     *
-     * @param timeMs - Optional new timer value. Defaults to `initialTimeMs`.
-     */
-    reset: (timeMs?: number) => void;
-}
-/**
- * A high-precision timer hook built on top of {@link useHoneyRafLoop}.
- *
- * Features:
- * - Frame-accurate time progression using `requestAnimationFrame`
- * - Supports countdown and count-up modes
- * - Explicit lifecycle control (start / pause / resume / reset)
- * - Drift-free timing using delta-based updates
- * - Safe completion handling via `onEnd`
- *
- * Architectural notes:
- * - Time progression is handled imperatively via refs to avoid stale closures and unnecessary re-renders.
- * - React state is updated only with the derived timer value.
- * - RAF lifecycle is fully delegated to `useHoneyRafLoop`.
- *
- * @example
- * ```ts
- * const timer = useHoneyTimer({
- *   initialTimeMs: 10_000,
- *   targetTimeMs: 0,
- *   onEnd: () => console.log('Done'),
- * });
- *
- * timer.startTimer();
- * ```
- */
-export declare const useHoneyTimer: ({ initialTimeMs, targetTimeMs, mode, autoStart, onEnd, }: UseHoneyTimerOptions) => UseHoneyTimerApi;
-export {};