@wordpress/interactivity
Version:
Package that provides a standard and simple way to handle the frontend interactivity of Gutenberg blocks.
206 lines • 8.52 kB
TypeScript
/**
* External dependencies
*/
import { type EffectCallback, type Inputs } from 'preact/hooks';
declare global {
interface Window {
scheduler?: {
readonly yield?: () => Promise<void>;
};
}
}
export 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;
contains(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 type DeepReadonly<T> = T extends (...args: any[]) => any ? T : T extends object ? {
readonly [K in keyof T]: DeepReadonly<T[K]>;
} : T;
/**
* Creates a deeply read-only proxy of an object.
*
* This function recursively wraps an object and all its nested objects in
* proxies that prevent any modifications. All mutation operations (`set`,
* `deleteProperty`, and `defineProperty`) will silently fail in production and
* emit warnings in development (when `globalThis.SCRIPT_DEBUG` is true).
*
* The wrapping is lazy: nested objects are only wrapped when accessed, making
* this efficient for large or deeply nested structures.
*
* Proxies are cached using a WeakMap, so calling this function multiple times
* with the same object will return the same proxy instance.
*
* @param obj The object to make read-only.
* @param options Optional configuration.
* @param options.errorMessage Custom error message to display when modification is attempted.
* @return A read-only proxy of the object.
*/
export declare function deepReadOnly<T extends object>(obj: T, options?: {
errorMessage?: string;
}): T;
export declare const navigationSignal: import("@preact/signals-core").Signal<number>;
/**
* Recursively clones the passed object.
*
* @param source Source object.
* @return Cloned object.
*/
export declare function deepClone<T>(source: T): T;
//# sourceMappingURL=utils.d.ts.map