@alwatr/synapse/dist/directiveClass.d.ts

Connect your TypeScript classes to the DOM, declaratively.

/**
 * @package @alwatr/synapse
 *
 * This file defines the `DirectiveBase` class, which is the foundation for creating custom directives
 * in the Alwatr Synapse library. Directives are used to attach behavior and logic to DOM elements
 * declaratively.
 */
/**
 * The abstract base class for all directives.
 *
 * Extend this class to create a new directive that can be registered with the `@directive` decorator.
 * It provides the core functionality for linking a TypeScript class to a DOM element and managing its lifecycle.
 *
 * @example
 * ```ts
 * import {DirectiveBase, directive} from '@alwatr/synapse';
 *
 * @directive('[my-directive]')
 * export class MyDirective extends DirectiveBase {
 *   protected override init_(): void {
 *     super.init_(); // فراخوانی متد والد برای حفظ سازگاری با نسخه‌های قبل ضروری است
 *     this.element_.textContent = 'Hello from MyDirective!';
 *     this.element_.addEventListener('click', () => this.log('Element clicked!'));
 *   }
 * }
 * ```
 */
export declare abstract class DirectiveBase {
    /**
     * The CSS selector that this directive is associated with.
     * This is the selector string provided to the `@directive` decorator.
     */
    protected readonly selector_: string;
    /**
     * A dedicated logger instance for this directive, pre-configured with a context like `directive:[selector]`.
     * Use this for logging to provide clear, contextual messages.
     */
    protected readonly logger_: import("@alwatr/logger").AlwatrLogger;
    /**
     * The DOM element to which this directive instance is attached.
     * All directive logic operates on this element.
     */
    protected readonly element_: HTMLElement;
    /**
     * A list of callback functions to be executed when the directive is destroyed.
     */
    private readonly cleanupTaskList__;
    /**
     * Initializes the directive. This constructor is called by the Synapse bootstrap process and should not be
     * overridden in subclasses.
     *
     * It sets up the logger, element, and selector, and then schedules the `init_` and `update_` lifecycle methods
     * to run in the next microtask.
     *
     * @param element The DOM element to which this directive is attached.
     * @param selector The CSS selector that matched this directive.
     */
    constructor(element: HTMLElement, selector: string);
    /**
     * Called once automatically after the directive is initialized.
     *
     * This method serves as the main entry point for your directive's logic,
     * such as modifying the element or setting up event listeners.
     *
     * **Note:** Do not call this method directly. It is designed to be called only once by the framework.
     */
    protected init_(): Awaitable<void>;
    /**
     * Dispatches a custom event from the target element.
     *
     * This is a convenience method for firing events that can be listened to by other parts of the application.
     * The event bubbles up through the DOM.
     *
     * @param eventName The name of the custom event.
     * @param detail Optional data to include in the event's `detail` property.
     *
     * @example
     * ```ts
     * this.dispatch_('user-action', {action: 'save', id: 123});
     * ```
     */
    protected dispatch_(eventName: string, detail?: unknown): void;
    /**
     * Registers a task to be executed when the directive is destroyed.
     * Follows the `on[Event]` pattern, similar to `onClick`.
     * Useful for cleaning up resources, such as unsubscribing from signals or removing global event listeners.
     *
     * @param task The cleanup task to register.
     *
     * @example
     * ```ts
     * this.onDestroy(
     *   signal.subscribe(() => this.log('signal changed')).unsubscribe
     * );
     * ```
     */
    protected onDestroy_(task: NoopFunction): void;
    /**
     * Cleans up the directive's resources.
     *
     * This method removes the element from the DOM and nullifies the internal reference to it,
     * helping with garbage collection. It can be extended by subclasses to perform additional cleanup,
     * such as removing event listeners.
     */
    protected destroy_(): Awaitable<void>;
}
//# sourceMappingURL=directiveClass.d.ts.map