@sandlada/mdc/build/utils/controller/attachable-controller.d.ts

@sandlada/mdc is an open source component library that follows the Material Design 3 design specifications.

/**
 * @license
 * Copyright 2023 Google LLC
 * SPDX-License-Identifier: Apache-2.0
 *
 * @link
 * https://github.com/material-components/material-web/blob/main/internal/controller/attachable-controller.ts
 */
import { type ReactiveController, type ReactiveControllerHost } from 'lit';
/**
 * An element that can be attached to an associated controlling element.
 */
export interface IAttachable {
    /**
     * Reflects the value of the `for` attribute, which is the ID of the element's
     * associated control.
     *
     * Use this when the elements's associated control is not its parent.
     *
     * To manually control an element, set its `for` attribute to `""`.
     *
     * @example
     * ```html
     * <div class="container">
     *   <md-attachable for="interactive"></md-attachable>
     *   <button id="interactive">Action</button>
     * </div>
     * ```
     *
     * @example
     * ```html
     * <button class="manually-controlled">
     *   <md-attachable for=""></md-attachable>
     * </button>
     * ```
     */
    htmlFor: string | null;
    /**
     * Gets or sets the element that controls the visibility of the attachable
     * element. It is one of:
     *
     * - The control referenced by the `for` attribute.
     * - The control provided to `element.attach(control)`
     * - The element's parent.
     * - `null` if the element is not controlled.
     */
    control: HTMLElement | null;
    /**
     * Attaches the element to an interactive control.
     *
     * @param control The element that controls the attachable element.
     */
    attach(control: HTMLElement): void;
    /**
     * Detaches the element from its current control.
     */
    detach(): void;
}
/**
 * A key to retrieve an `IAttachable` element's `AttachableController` from a
 * global `MutationObserver`.
 */
declare const ATTACHABLE_CONTROLLER: unique symbol;
/**
 * The host of an `AttachableController`. The controller will add itself to
 * the host so it can be retrieved in a global `MutationObserver`.
 */
export interface IAttachableControllerHost extends ReactiveControllerHost, HTMLElement {
    [ATTACHABLE_CONTROLLER]?: AttachableController;
}
/**
 * A controller that provides an implementation for `IAttachable` elements.
 *
 * @example
 * ```ts
 * class MyElement extends LitElement implements IAttachable {
 *   get control() { return this.attachableController.control; }
 *
 *   private readonly attachableController = new AttachableController(
 *     this,
 *     (previousControl, newControl) => {
 *       previousControl?.removeEventListener('click', this.handleClick);
 *       newControl?.addEventListener('click', this.handleClick);
 *     }
 *   );
 *
 *   // Implement remaining `IAttachable` properties/methods that call the
 *   // controller's properties/methods.
 * }
 * ```
 */
export declare class AttachableController implements ReactiveController, IAttachable {
    private readonly host;
    private readonly onControlChange;
    get htmlFor(): string | null;
    set htmlFor(htmlFor: string | null);
    get control(): HTMLElement | null;
    set control(control: HTMLElement | null);
    private currentControl;
    /**
     * Creates a new controller for an `IAttachable` element.
     *
     * @param host The `IAttachable` element.
     * @param onControlChange A callback with two parameters for the previous and
     *     next control. An `IAttachable` element may perform setup or teardown
     *     logic whenever the control changes.
     */
    constructor(host: IAttachableControllerHost, onControlChange: (prev: HTMLElement | null, next: HTMLElement | null) => void);
    attach(control: HTMLElement): void;
    detach(): void;
    hostConnected(): void;
    hostDisconnected(): void;
    private setCurrentControl;
}
export {};
//# sourceMappingURL=attachable-controller.d.ts.map