@studiometa/js-toolkit/Base/Base.d.ts

A set of useful little bits of JavaScript to boost your project! 🚀

import { ChildrenManager, RefsManager, ServicesManager, EventsManager, OptionsManager } from './managers/index.js';
export type BaseEl = HTMLElement & {
    __base__?: WeakMap<BaseConstructor, Base | 'terminated'>;
};
export type BaseConstructor<T extends Base = Base> = {
    new (...args: any[]): T;
    prototype: Base;
} & Pick<typeof Base, keyof typeof Base>;
export type BaseAsyncConstructor<T extends Base = Base> = (instance: Base) => Promise<BaseConstructor<T> | {
    default: BaseConstructor<T>;
}>;
export type BaseOptions = {
    [name: string]: unknown;
};
export type BaseRefs = {
    [name: string]: HTMLElement | HTMLElement[];
};
export type BaseChildren = {
    [nameOrSelector: string]: Base[] | Promise<Base>[];
};
export type BaseConfigComponents = {
    [nameOrSelector: string]: BaseConstructor | BaseAsyncConstructor;
};
export type BaseConfig = {
    name: string;
    debug?: boolean;
    log?: boolean;
    refs?: string[];
    emits?: string[];
    components?: BaseConfigComponents;
    options?: import('./managers/OptionsManager').OptionsSchema;
};
export type BaseProps = {
    $el?: HTMLElement;
    $options?: BaseOptions;
    $refs?: BaseRefs;
    $children?: BaseChildren;
    $parent?: Base;
};
export type Managers = {
    ChildrenManager: typeof ChildrenManager;
    EventsManager: typeof EventsManager;
    OptionsManager: typeof OptionsManager;
    RefsManager: typeof RefsManager;
    ServicesManager: typeof ServicesManager;
};
/**
 * Base class.
 */
export declare class Base<T extends BaseProps = BaseProps> {
    /**
     * Declare the `this.constructor` type
     * @see https://github.com/microsoft/TypeScript/issues/3841#issuecomment-2381594311
     */
    ['constructor']: BaseConstructor;
    /**
     * This is a Base instance.
     */
    static readonly $isBase: true;
    /**
     * The instance parent.
     */
    $parent: T['$parent'] & Base;
    /**
     * The instance id.
     */
    $id: string;
    /**
     * The root element.
     */
    $el: T['$el'] & BaseEl;
    /**
     * The state of the component.
     */
    $isMounted: boolean;
    /**
     * Is the component currently mounting itself and its children?
     * @private
     */
    __isMounting: boolean;
    /**
     * Store the event handlers.
     * @private
     */
    __eventHandlers: Map<string, Set<EventListenerOrEventListenerObject>>;
    /**
     * Get the root instance of the app.
     */
    get $root(): Base;
    /**
     * Merge configuration with the parents' configurations.
     * @private
     */
    get __config(): BaseConfig;
    get $config(): BaseConfig;
    static config: BaseConfig;
    __services: ServicesManager;
    get $services(): ServicesManager;
    __refs: RefsManager<T['$refs'] & BaseRefs>;
    get $refs(): T['$refs'] & BaseRefs;
    __options: OptionsManager<T['$options'] & BaseOptions>;
    get $options(): T['$options'] & BaseOptions;
    __children: ChildrenManager<T['$children'] & BaseChildren>;
    get $children(): T['$children'] & BaseChildren;
    __events: EventsManager;
    /**
     * Small helper to log stuff.
     */
    get $log(): (...args: unknown[]) => void;
    /**
     * Small helper to make warning easier.
     */
    get $warn(): (...args: unknown[]) => void;
    /**
     * Small helper to debug information.
     */
    get __debug(): (...args: unknown[]) => void;
    /**
     * Get manager constructors.
     */
    get __managers(): Managers;
    /**
     * Call an instance method and emit corresponding events.
     */
    __callMethod(method: string, ...args: unknown[]): unknown;
    /**
     * Test if the given event has been bound to the instance.
     *
     * @param   {string} event The event's name.
     * @returns {boolean}      Wether the given event has been bound or not.
     */
    __hasEvent(event: string): boolean;
    /**
     * Class constructor where all the magic takes place.
     *
     * @param {HTMLElement} element The component's root element dd.
     */
    constructor(element: HTMLElement);
    /**
     * Trigger the `mounted` callback.
     */
    $mount(): Promise<this>;
    /**
     * Update the instance children.
     */
    $update(): Promise<this>;
    /**
     * Trigger the `destroyed` callback.
     */
    $destroy(): Promise<this>;
    /**
     * Terminate a child instance when it is not needed anymore.
     */
    $terminate(): Promise<void>;
    /**
     * Add an emitted event.
     *
     * @param   {string} event The event name.
     * @returns {void}
     */
    __addEmits(event: string): void;
    /**
     * Remove an emitted event.
     *
     * @param   {string} event The event name.
     * @returns {void}
     */
    __removeEmits(event: string): void;
    /**
     * Bind a listener function to an event.
     *
     * @param  {string} event
     *   Name of the event.
     * @param  {EventListenerOrEventListenerObject} listener
     *   Function to be called.
     * @param {boolean|AddEventListenerOptions} [options]
     *   Options for the `removeEventListener` method.
     * @returns {() => void}
     *   A function to unbind the listener.
     */
    $on(event: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): () => void;
    /**
     * Unbind a listener function from an event.
     *
     * @param {string} event
     *   Name of the event.
     * @param {EventListenerOrEventListenerObject} listener
     *   Function to be removed.
     * @param {boolean|EventListenerOptions} [options]
     *   Options for the `removeEventListener` method.
     * @returns {void}
     */
    $off(event: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
    /**
     * Emits an event.
     *
     * @param  {string} event Name of the event.
     * @param  {any[]}  args  The arguments to apply to the functions bound to this event.
     * @returns {void}
     */
    $emit(event: string | Event, ...args: unknown[]): void;
    /**
     * Register and mount all instances of the component.
     */
    static $register(nameOrSelector?: string): Array<Promise<Base>>;
}