/**
 * @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