@sandlada/vue-mdc
Version:
65 lines • 2.93 kB
TypeScript
/**
* @license
* Copyright 2025 Sandlada & Kai Orion
* SPDX-License-Identifier: MIT
*/
import { type ComputedRef, type Ref, type WritableComputedRef } from 'vue';
/**
* An object that can be attached to an associated controlling element.
* Represents the public API of the attachable logic.
*/
export interface IAttachable {
/**
* Reflects the value of the `for` attribute on the host element.
* Setting this property updates the attribute. Setting it also
* implies that the source of the `control` is the `for` attribute,
* overriding any previous imperative `attach` call.
*/
readonly htmlFor: WritableComputedRef<string | null>;
/**
* Gets the element that controls the attachable element. It is one of:
*
* - The control referenced by the `for` attribute (if present and not empty).
* - The control provided to `element.attach(control)` (if `attach` was called).
* - The element's parent (if no `for` and no imperative attachment).
* - `null` if detached (via `detach()` or `for=""`) or not connected.
*
* This is a reactive property.
*/
readonly control: ComputedRef<HTMLElement | null>;
readonly host: ComputedRef<IAttachableHost | null>;
readonly hostRef: Ref<IAttachableHost | null>;
/**
* Attaches the element to an interactive control imperatively.
* This overrides the `for` attribute.
*
* @param control The element that controls the attachable element.
*/
attach(control: HTMLElement): void;
/**
* Detaches the element from its current control.
* Sets the `for` attribute to `""` to prevent parent fallback.
*/
detach(): void;
}
export declare const SAttachableController: unique symbol;
export interface IAttachableHost extends HTMLElement {
[SAttachableController]: IAttachable;
}
/**
* A composable function that provides attachable element logic for a Vue component.
*
* It manages the association between the host element (the element the composable
* is used on) and a 'control' element based on the host's 'for' attribute,
* imperative `attach`/`detach` calls, or the parent element.
*
* @param hostRef A Vue Ref pointing to the host HTMLElement. This ref
* should be assigned to the component's root element or the element that needs
* the attachable behavior. The element must be connected to the DOM for
* 'for' attribute lookup and parent element fallback to work correctly.
* @param onControlChange A callback function that is called whenever the
* `control` element changes. Receives the previous and next control elements.
* @returns An object implementing the `IAttachable` interface.
*/
export declare function useAttachable(hostRef: Ref<HTMLElement | null>, onControlChange: (prev: HTMLElement | null | undefined, next: HTMLElement | null | undefined) => void): IAttachable;
//# sourceMappingURL=use-attachable.d.ts.map