@stratakit/foundations/dist/~hooks.d.ts

Foundational pieces of StrataKit

import * as React from "react";
import type { AnyFunction } from "./~utils.js";
/**
 * SSR-safe wrapper over `React.useLayoutEffect`.
 *
 * @see https://fb.me/react-uselayouteffect-ssr
 *
 * @private
 */
export declare const useLayoutEffect: typeof React.useLayoutEffect;
/**
 * Wrapper over `useState` that always gives preference to the
 * controlled state (which often comes from a prop).
 *
 * This is helpful when a component needs to support both uncontrolled
 * and controlled states. If controlled value/setter is not passed,
 * then it will work just like a regular `useState`.
 *
 * ```tsx
 * const [state, setState] = useControlledState(
 *   props.defaultValue,
 *   props.value,
 *   props.onChange
 * );
 * ```
 *
 * @private
 */
export declare function useControlledState<T>(initialValue: T, controlledState: T | undefined, setControlledState?: React.Dispatch<React.SetStateAction<T>>): readonly [T, React.Dispatch<React.SetStateAction<T>>];
/**
 * Hook that keeps track of the latest value in a ref.
 * This is useful for referencing unmemoized values inside Effects.
 *
 * ```tsx
 * const valueRef = useLatestRef(props.value);
 * ```
 *
 * @private
 */
export declare function useLatestRef<T>(value: T): React.RefObject<T>;
/**
 * Returns a memoized callback ref that merges the provided refs.
 *
 * ```tsx
 * const mergedRef = useMergedRefs(ref1, ref2);
 * ```
 *
 * This is useful when you need to internally use a ref in a component
 * and also need to forward its ref.
 *
 * ```tsx
 * const internalRef = useRef(null);
 * return <div ref={useMergedRefs(internalRef, forwardedRef)} />;
 * ```
 *
 * @private
 */
export declare function useMergedRefs<T>(...refs: ReadonlyArray<React.Ref<T> | React.LegacyRef<T> | undefined | null>): (instance: T | null) => void;
/**
 * Hook that "memoizes" a function by skipping reactivity, similar to `React.useEffectEvent`.
 *
 * The memoization technique used by this hook ensures that only the "latest" callback is ever called,
 * regardless of its dependencies. The "latest" callback is stored in a ref and updated on each render
 * in an Effect. The result is that the callback passed to this hook does not need to be memoized.
 *
 * @private
 */
export declare function useUnreactiveCallback<T extends AnyFunction>(callback: T): T;
/**
 * Hook that accepts a list of event handlers and returns a single memoized (unreactive)
 * handler that ensures `defaultPrevented` is respected for each handler.
 *
 * Example:
 * ```tsx
 * <button onClick={useEventHandlers(props.onClick, ownOnClick)}>
 * ```
 *
 * @private
 */
export declare function useEventHandlers<E extends React.SyntheticEvent>(...handlers: Array<((event: E) => void) | undefined>): (event: E) => void;
/**
 * Wrapper hook around `useContext` to ensure that the Context is provided.
 * The component calling this hook will throw an error if the Context is not found.
 *
 * The Context's `displayName` will be used for a more useful error message.
 *
 * @private
 */
export declare function useSafeContext<C>(context: React.Context<C>): C & ({} | null);
/**
 * Hook that makes it easy to use the [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) consistently.
 *
 * Internally, this hook will sync the `open` state with the `element`'s "popover-open" state.
 *
 * Returns a set of DOM props that should be passed back to the element.
 *
 * @private
 */
export declare function usePopoverApi({ element, open, }: {
    element: HTMLElement | null | undefined;
    open: boolean | undefined;
}): {
    readonly style: {
        readonly zIndex: 9999 | undefined;
    };
    readonly popover: "manual";
};
/**
 * Hook that returns true for the first "full" client render.
 * Useful to guard against using client APIs during SSR.
 *
 * Note: This will return `false` during hydration.
 *
 * @private
 */
export declare function useIsClient(): boolean;