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

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

/**
 * External dependencies
 */
import { h } from 'preact';
import type { VNode, Context, RefObject } from 'preact';
interface DirectiveEntry {
    value: string | Object;
    namespace: string;
    suffix: string;
}
type DirectiveEntries = Record<string, DirectiveEntry[]>;
interface DirectiveArgs {
    /**
     * Object map with the defined directives of the element being evaluated.
     */
    directives: DirectiveEntries;
    /**
     * Props present in the current element.
     */
    props: Object;
    /**
     * Virtual node representing the element.
     */
    element: VNode;
    /**
     * The inherited context.
     */
    context: Context<any>;
    /**
     * Function that resolves a given path to a value either in the store or the
     * context.
     */
    evaluate: Evaluate;
}
interface DirectiveCallback {
    (args: DirectiveArgs): VNode | void;
}
interface DirectiveOptions {
    /**
     * Value that specifies the priority to evaluate directives of this type.
     * Lower numbers correspond with earlier execution.
     *
     * @default 10
     */
    priority?: number;
}
interface Scope {
    evaluate: Evaluate;
    context: Context<any>;
    ref: RefObject<HTMLElement>;
    attributes: h.JSX.HTMLAttributes;
}
interface Evaluate {
    (entry: DirectiveEntry, ...args: any[]): any;
}
interface GetEvaluate {
    (args: {
        scope: Scope;
    }): Evaluate;
}
/**
 * Retrieves the context inherited by the element evaluating a function from the
 * store. The returned value depends on the element and the namespace where the
 * function calling `getContext()` exists.
 *
 * @param namespace Store namespace. By default, the namespace where the calling
 *                  function exists is used.
 * @return The context content.
 */
export declare const getContext: <T extends object>(namespace?: string) => T;
/**
 * Retrieves a representation of the element where a function from the store
 * is being evalutated. Such representation is read-only, and contains a
 * reference to the DOM element, its props and a local reactive state.
 *
 * @return Element representation.
 */
export declare const getElement: () => Readonly<{
    ref: HTMLElement;
    attributes: h.JSX.HTMLAttributes<EventTarget>;
}>;
export declare const getScope: () => Scope;
export declare const setScope: (scope: Scope) => void;
export declare const resetScope: () => void;
export declare const getNamespace: () => string;
export declare const setNamespace: (namespace: string) => void;
export declare const resetNamespace: () => void;
/**
 * Register a new directive type in the Interactivity API runtime.
 *
 * @example
 * ```js
 * directive(
 *   'alert', // Name without the `data-wp-` prefix.
 *   ( { directives: { alert }, element, evaluate } ) => {
 *     const defaultEntry = alert.find( entry => entry.suffix === 'default' );
 *     element.props.onclick = () => { alert( evaluate( defaultEntry ) ); }
 *   }
 * )
 * ```
 *
 * The previous code registers a custom directive type for displaying an alert
 * message whenever an element using it is clicked. The message text is obtained
 * from the store under the inherited namespace, using `evaluate`.
 *
 * When the HTML is processed by the Interactivity API, any element containing
 * the `data-wp-alert` directive will have the `onclick` event handler, e.g.,
 *
 * ```html
 * <div data-wp-interactive='{ "namespace": "messages" }'>
 *   <button data-wp-alert="state.alert">Click me!</button>
 * </div>
 * ```
 * Note that, in the previous example, the directive callback gets the path
 * value (`state.alert`) from the directive entry with suffix `default`. A
 * custom suffix can also be specified by appending `--` to the directive
 * attribute, followed by the suffix, like in the following HTML snippet:
 *
 * ```html
 * <div data-wp-interactive='{ "namespace": "myblock" }'>
 *   <button
 *     data-wp-color--text="state.text"
 *     data-wp-color--background="state.background"
 *   >Click me!</button>
 * </div>
 * ```
 *
 * This could be an hypothetical implementation of the custom directive used in
 * the snippet above.
 *
 * @example
 * ```js
 * directive(
 *   'color', // Name without prefix and suffix.
 *   ( { directives: { color }, ref, evaluate } ) =>
 *     colors.forEach( ( color ) => {
 *       if ( color.suffix = 'text' ) {
 *         ref.style.setProperty(
 *           'color',
 *           evaluate( color.text )
 *         );
 *       }
 *       if ( color.suffix = 'background' ) {
 *         ref.style.setProperty(
 *           'background-color',
 *           evaluate( color.background )
 *         );
 *       }
 *     } );
 *   }
 * )
 * ```
 *
 * @param name             Directive name, without the `data-wp-` prefix.
 * @param callback         Function that runs the directive logic.
 * @param options          Options object.
 * @param options.priority Option to control the directive execution order. The
 *                         lesser, the highest priority. Default is `10`.
 */
export declare const directive: (name: string, callback: DirectiveCallback, { priority }?: DirectiveOptions) => void;
export declare const getEvaluate: GetEvaluate;
export {};
//# sourceMappingURL=hooks.d.ts.map