@wordpress/interactivity/build-types/utils.d.ts

Package that provides a standard and simple way to handle the frontend interactivity of Gutenberg blocks.

/**
 * External dependencies
 */
import { type EffectCallback, type Inputs } from 'preact/hooks';
declare global {
    interface Window {
        scheduler?: {
            readonly yield?: () => Promise<void>;
        };
    }
}
interface SyncAwareFunction extends Function {
    sync?: boolean;
}
/**
 * Returns a promise that resolves after yielding to main.
 *
 * @return Promise<void>
 */
export declare const splitTask: () => Promise<unknown>;
/**
 * Custom hook that executes a callback function whenever a signal is triggered.
 * Version of `useSignalEffect` with a `useEffect`-like execution. This hook
 * implementation comes from this PR, but we added short-cirtuiting to avoid
 * infinite loops: https://github.com/preactjs/signals/pull/290
 *
 * @param callback The callback function to be executed.
 */
export declare function useSignalEffect(callback: () => unknown): void;
/**
 * Returns the passed function wrapped with the current scope so it is
 * accessible whenever the function runs. This is primarily to make the scope
 * available inside hook callbacks.
 *
 * Asynchronous functions should use generators that yield promises instead of awaiting them.
 * See the documentation for details: https://developer.wordpress.org/block-editor/reference-guides/packages/packages-interactivity/packages-interactivity-api-reference/#the-store
 *
 * @param func The passed function.
 * @return The wrapped function.
 */
export declare function withScope<Func extends (...args: any[]) => Generator<any, any>>(func: Func): (...args: Parameters<Func>) => ReturnType<Func> extends Generator<any, infer Return> ? Promise<Return> : never;
export declare function withScope<Func extends Function>(func: Func): Func;
export declare function withScope<Func extends SyncAwareFunction>(func: Func): Func;
/**
 * Accepts a function that contains imperative code which runs whenever any of
 * the accessed _reactive_ properties (e.g., values from the global state or the
 * context) is modified.
 *
 * This hook makes the element's scope available so functions like
 * `getElement()` and `getContext()` can be used inside the passed callback.
 *
 * @param callback The hook callback.
 */
export declare function useWatch(callback: () => unknown): void;
/**
 * Accepts a function that contains imperative code which runs only after the
 * element's first render, mainly useful for initialization logic.
 *
 * This hook makes the element's scope available so functions like
 * `getElement()` and `getContext()` can be used inside the passed callback.
 *
 * @param callback The hook callback.
 */
export declare function useInit(callback: EffectCallback): void;
/**
 * Accepts a function that contains imperative, possibly effectful code. The
 * effects run after browser paint, without blocking it.
 *
 * This hook is equivalent to Preact's `useEffect` and makes the element's scope
 * available so functions like `getElement()` and `getContext()` can be used
 * inside the passed callback.
 *
 * @param callback Imperative function that can return a cleanup
 *                 function.
 * @param inputs   If present, effect will only activate if the
 *                 values in the list change (using `===`).
 */
export declare function useEffect(callback: EffectCallback, inputs: Inputs): void;
/**
 * Accepts a function that contains imperative, possibly effectful code. Use
 * this to read layout from the DOM and synchronously re-render.
 *
 * This hook is equivalent to Preact's `useLayoutEffect` and makes the element's
 * scope available so functions like `getElement()` and `getContext()` can be
 * used inside the passed callback.
 *
 * @param callback Imperative function that can return a cleanup
 *                 function.
 * @param inputs   If present, effect will only activate if the
 *                 values in the list change (using `===`).
 */
export declare function useLayoutEffect(callback: EffectCallback, inputs: Inputs): void;
/**
 * Returns a memoized version of the callback that only changes if one of the
 * inputs has changed (using `===`).
 *
 * This hook is equivalent to Preact's `useCallback` and makes the element's
 * scope available so functions like `getElement()` and `getContext()` can be
 * used inside the passed callback.
 *
 * @param callback Callback function.
 * @param inputs   If present, the callback will only be updated if the
 *                 values in the list change (using `===`).
 *
 * @return The callback function.
 */
export declare function useCallback<T extends Function>(callback: T, inputs: Inputs): T;
/**
 * Returns the memoized output of the passed factory function, allowing access
 * to the current element's scope.
 *
 * This hook is equivalent to Preact's `useMemo` and makes the element's scope
 * available so functions like `getElement()` and `getContext()` can be used
 * inside the passed factory function. Note that `useMemo` will only recompute
 * the memoized value when one of the inputs has changed.
 *
 * @param factory Factory function that returns that value for memoization.
 * @param inputs  If present, the factory will only be run to recompute if the
 *                values in the list change (using `===`).
 *
 * @return The memoized value.
 */
export declare function useMemo<T>(factory: () => T, inputs: Inputs): T;
/**
 * Creates a root fragment by replacing a node or an array of nodes in a parent element.
 * For wrapperless hydration.
 * See https://gist.github.com/developit/f4c67a2ede71dc2fab7f357f39cff28c
 *
 * @param parent      The parent element where the nodes will be replaced.
 * @param replaceNode The node or array of nodes to replace in the parent element.
 * @return The created root fragment.
 */
export declare const createRootFragment: (parent: Element, replaceNode: Node | Node[]) => {
    nodeType: number;
    parentNode: Element;
    firstChild: Node;
    childNodes: Node[];
    insertBefore: (child: any, root: any) => void;
    appendChild: (child: any, root: any) => void;
    removeChild(c: Node): void;
};
/**
 * Transforms a kebab-case string to camelCase.
 *
 * @param str The kebab-case string to transform to camelCase.
 * @return The transformed camelCase string.
 */
export declare function kebabToCamelCase(str: string): string;
/**
 * Shows a warning with `message` if environment is not `production`.
 *
 * Based on the `@wordpress/warning` package.
 *
 * @param message Message to show in the warning.
 */
export declare const warn: (message: string) => void;
/**
 * Checks if the passed `candidate` is a plain object with just the `Object`
 * prototype.
 *
 * @param candidate The item to check.
 * @return Whether `candidate` is a plain object.
 */
export declare const isPlainObject: (candidate: unknown) => candidate is Record<string, unknown>;
/**
 * Indicates that the passed `callback` requires synchronous access to the event object.
 *
 * @param callback The event callback.
 * @return Altered event callback.
 */
export declare function withSyncEvent(callback: Function): SyncAwareFunction;
export {};
//# sourceMappingURL=utils.d.ts.map