@adpt/core/dist/src/hooks/use_method.d.ts

AdaptJS core library

import { MethodNames, ReturnTypeOrNever } from "@adpt/utils";
import { Handle, HandleInstanceType } from "../handle";
import { AdaptElement, ElementPredicate } from "../jsx";
/**
 * Call an instance method on the Element that `hand` refers to.
 *
 * @remarks
 * This hook is the primary way for a function component to call an
 * instance method on another component element. A hook is used in order to delay
 * execution of the method until the DOM is completely built. The reason this
 * delayed execution is needed is because during the DOM build process, the
 * element that `hand` refers to may not have been built yet, or `hand` may
 * change to point to a different element later in the build process.
 * By waiting until this avoids element build order issues and ensures
 * that handle references are no longer changing.
 *
 * Because execution of the methods is delayed, `useMethod` will always return
 * the `initial` value on the initial build of a component. After every
 * DOM build is complete, the method will be invoked during the state update
 * phase and the return value stored in the component's state. This state
 * update (or any state update) will cause the DOM to build again. Upon
 * rebuild, the value stored from the last method invocation in the
 * component's state will be returned and a new invocation will be queued.
 *
 * If the value returned by the called method continues to change, this will
 * cause the DOM to continue to be rebuilt again.
 *
 * As this is a hook, it **must not** be called conditionally by a component.
 * In cases where a handle is not always present or the method should not be
 * called, call `useMethod` with `null` for `hand`.
 *
 * @param hand - The handle for the element upon which to call the method
 * `method`. `hand` may also be `null`, in which case, `initial` is always
 * the return value and the other arguments are ignored.
 *
 * @param initial - The initial value that `useMethod` will return before
 * execution of the method has occurred. This value will **always** be returned
 * on the first build of the component, when no component state is present.
 *
 * @param method - Name of the instance method to call.
 *
 * @param args - Variable arguments to be passed to the method call.
 *
 * @privateremarks
 * This overload is used when no explicit type parameters are defined and
 * only two arguments are passed.
 * @beta
 */
export declare function useMethod<H extends Handle, Instance = HandleInstanceType<H>, MethodName extends MethodNames<Instance> = MethodNames<Instance>, Ret = ReturnTypeOrNever<Instance[MethodName]>>(hand: H | null, method: MethodName): Ret | undefined;
/**
 * {@inheritdoc useMethod}
 * @privateremarks
 * This overload is used when no explicit type parameters are defined and
 * three or more arguments are passed.
 * @beta
 */
export declare function useMethod<Initial, H extends Handle, Instance = HandleInstanceType<H>, MethodName extends MethodNames<Instance> = MethodNames<Instance>, Ret = ReturnTypeOrNever<Instance[MethodName]>>(hand: H | null, initial: Initial, method: MethodName, ...args: any[]): Ret | Initial;
/**
 * {@inheritdoc useMethod}
 * @privateremarks
 * This overload is used when an explicit type parameter is passed, along
 * with two function arguments.
 * @beta
 */
export declare function useMethod<OverrideReturn, H extends Handle = Handle, Instance = HandleInstanceType<H>, MethodName extends MethodNames<Instance> = MethodNames<Instance>>(hand: Handle | null, method: MethodName): OverrideReturn | undefined;
/**
 * {@inheritdoc useMethod}
 * @privateremarks
 * This overload is used when an explicit type parameter is passed, along
 * with three or more function arguments.
 * @beta
 */
export declare function useMethod<OverrideReturn>(hand: Handle | null, initial: OverrideReturn, method: string, ...args: any[]): OverrideReturn;
export declare function hasInstanceMethod(name: string, skip?: AdaptElement | null): ElementPredicate;
export declare function notReplacedByStyle(): ElementPredicate;
/**
 * Search for the first built Element in the handle chain of `hand` and
 * immediately execute the instance method `methodName` on that Element's
 * instance.
 *
 * @remarks
 * If an Element is found that satisfies the search, but method `methodName`
 * does not exist on the Element's instance, an error is thrown.
 *
 * The exact check that is currently used when searching the handle chain is
 * for mounted Elements that satisfy the predicate {@link notReplacedByStyle}.
 * In practice, this only selects Elements that are both mounted and built.
 *
 * @returns The return value of the called instance method if `hand` is
 * associated and there is an Element in the handle chain that has not been
 * replaced by a style sheet rule. Otherwise, returns the default value `def`.
 * @beta
 */
export declare function callInstanceMethod<T = any>(hand: Handle, def: T, methodName: string, ...args: any[]): T;
/**
 * Search for the first built Element instance in the Handle chain of `hand` that
 * implements method `methodName` and immediately execute it.
 *
 * @remarks
 * The exact check that is currently used when searching the handle chain is
 * mounted Elements that have an instance method `methodName`. Because only
 * built Elements have an Element instance, this only selects Elements that
 * are mounted and built and will not select Elements that have been replaced
 * by a style sheet rule.
 *
 * @returns The return value of the called instance method if `hand` is
 * associated and there is an Element in the handle chain that has method
 * `methodName`. Otherwise, returns the default value `def`.
 * @beta
 */
export declare function callFirstInstanceWithMethod<T = any>(hand: Handle, def: T, methodName: string, ...args: any[]): T;
/**
 * Starting with the successor of `hand`, search for a built Element instance in
 * the handle chain that implements method `methodName` and immediately
 * execute it.
 *
 * @remarks
 * If `hand` is not associated with an Element, an error is thrown.
 *
 * The exact check that is currently used when searching the handle chain is
 * mounted Elements that have an instance method `methodName`. Because only
 * built Elements have an Element instance, this only selects Elements that
 * are mounted and built and will not select Elements that have been replaced
 * by a style sheet rule.
 *
 *
 * @returns The return value of the called instance method if `hand` is
 * associated and there is an Element in the handle chain (other than `hand`)
 * that has method `methodName`. Otherwise, returns the default value `def`.
 * @beta
 */
export declare function callNextInstanceWithMethod<T = any>(hand: Handle, def: T, methodName: string, ...args: any[]): T;
/**
 * Starting with the successor of `hand`, search for a built Element instance in
 * the handle chain that implements method `methodName` and immediately
 * execute it.
 *
 * @remarks
 * If `hand` is not associated with an Element, an error is thrown.
 *
 * The exact check that is currently used when searching the handle chain is
 * mounted Elements that have an instance method `methodName`. Because only
 * built Elements have an Element instance, this only selects Elements that
 * are mounted and built and will not select Elements that have been replaced
 * by a style sheet rule.
 *
 * @returns The return value of the called instance method if `hand` is
 * associated and there is an Element in the handle chain (other than `hand`)
 * that has method `methodName`. Otherwise, returns the default value `def`.
 * @deprecated
 * Renamed to {@link callNextInstanceWithMethod}.
 */
export declare const callNextInstanceMethod: typeof callNextInstanceWithMethod;
export declare const defaultGetInstanceValueOptions: GetInstanceValueOptions;
export interface GetInstanceValueOptions {
    pred?: ElementPredicate;
    throwOnNoElem?: boolean;
}
/**
 * Get the value of a field on an element instance
 *
 * @beta
 */
export declare function getInstanceValue<T = any>(hand: Handle, def: T, field: string, optionsIn?: GetInstanceValueOptions): T;
/**
 * Get the value of field from the instance referenced by handled instance.
 *
 * @remarks
 * On first invocation, or if the handle is not associated with an element, or the field is not found,
 * the value of `initial` will be returned.  After the element referenced by handle has been instantiated,
 * this hook will fetch the actual value of `field`, cause a rebuild, and then return that value
 * on the next call of the hook.
 *
 * @beta
 */
export declare function useInstanceValue<T>(hand: Handle, initial: T, field: string): T;
//# sourceMappingURL=use_method.d.ts.map