@luzmo/lucero 0.0.4 → 0.0.6

package/components/overlay/overlay.d.ts

@@ -0,0 +1,464 @@
+import { PropertyValues, TemplateResult } from 'lit';
+import { ElementResolutionController } from '../../utils/reactive-controllers/element-resolution';
+import { AbstractOverlay } from './abstract-overlay';
+import { ClickController } from './click-controller';
+import { HoverController } from './hover-controller';
+import { LongpressController } from './longpress-controller';
+import { OpenableElement, OverlayState, OverlayTypes, Placement, TriggerInteraction } from './overlay-types';
+import { PlacementController } from './placement-controller';
+import { VirtualTrigger } from './virtual-trigger';
+declare let ComputedOverlayBase: typeof AbstractOverlay & import("./overlay-types").Constructor<import("../../utils/base").LuzmoElement>;
+/**
+ * @element luzmo-overlay
+ *
+ * @fires luzmo-opened - announces that an overlay has completed any entry animations
+ * @fires luzmo-closed - announce that an overlay has compelted any exit animations
+ * @fires slottable-request - requests to add or remove slottable content
+ */
+export declare class Overlay extends ComputedOverlayBase {
+    static styles: import("lit").CSSResult[];
+    /**
+     * An Overlay that is `delayed` will wait until a warm-up period of 1000ms
+     * has completed before opening. Once the warm-up period has completed, all
+     * subsequent Overlays will open immediately. When no Overlays are opened,
+     * a cool-down period of 1000ms will begin. Once the cool-down has completed,
+     * the next Overlay to be opened will be subject to the warm-up period if
+     * provided that option.
+     *
+     * This behavior helps to manage the performance and user experience by
+     * preventing multiple overlays from opening simultaneously and ensuring
+     * a smooth transition between opening and closing overlays.
+     *
+     * @type {boolean}
+     * @default false
+     */
+    get delayed(): boolean;
+    set delayed(delayed: boolean);
+    private _delayed;
+    /**
+     * A reference to the dialog element within the overlay.
+     * This element is expected to have `showPopover` and `hidePopover` methods.
+     */
+    dialogEl: HTMLDialogElement & {
+        showPopover(): void;
+        hidePopover(): void;
+    };
+    /**
+     * Indicates whether the overlay is currently functional or not.
+     *
+     * When set to `true`, the overlay is disabled, and any active strategy is aborted.
+     * The overlay will also close if it is currently open. When set to `false`, the
+     * overlay will re-bind events and re-open if it was previously open.
+     *
+     * @type {boolean}
+     * @default false
+     */
+    get disabled(): boolean;
+    set disabled(disabled: boolean);
+    private _disabled;
+    /**
+     * A query to gather all elements slotted into the default slot, excluding elements
+     * with the slot name "longpress-describedby-descriptor".
+     */
+    elements: OpenableElement[];
+    /**
+     * A reference to the parent overlay that should be force-closed, if any.
+     */
+    parentOverlayToForceClose?: Overlay;
+    /**
+     * Determines if the overlay has a non-virtual trigger element.
+     *
+     * @returns `true` if the trigger element is not a virtual trigger, otherwise `false`.
+     */
+    private get hasNonVirtualTrigger();
+    /**
+     * The `offset` property accepts either a single number to define the offset of the
+     * Overlay along the main axis from the trigger, or a 2-tuple to define the offset
+     * along both the main axis and the cross axis. This option has no effect when there
+     * is no trigger element.
+     *
+     * @type {number | [number, number]}
+     * @default 0
+     */
+    offset: number | [number, number];
+    /**
+     * Provides an instance of the `PlacementController` for managing the positioning
+     * of the overlay relative to its trigger element.
+     *
+     * If the `PlacementController` instance does not already exist, it is created and
+     * assigned to the `_placementController` property.
+     *
+     * @protected
+     * @returns The `PlacementController` instance.
+     */
+    protected get placementController(): PlacementController;
+    /**
+     * Indicates whether the Overlay is projected onto the "top layer" or not.
+     *
+     * When set to `true`, the overlay is open and visible. When set to `false`, the overlay is closed and hidden.
+     *
+     * @type {boolean}
+     * @default false
+     */
+    get open(): boolean;
+    set open(open: boolean);
+    private _open;
+    /**
+     * Tracks the number of overlays that have been opened.
+     *
+     * This static property is used to manage the stacking context of multiple overlays.
+     *
+     * @type {number}
+     * @default 1
+     */
+    static openCount: number;
+    /**
+     * Instruct the Overlay where to place itself in relationship to the trigger element.
+     *
+     * @type {"top" | "top-start" | "top-end" | "right" | "right-start" | "right-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end"}
+     */
+    placement?: Placement;
+    /**
+     * The state in which the last `request-slottable` event was dispatched.
+     *
+     * This property ensures that overlays do not dispatch the same state twice in a row.
+     *
+     * @type {boolean}
+     * @default false
+     */
+    private lastRequestSlottableState;
+    /**
+     * Whether to pass focus to the overlay once opened, or
+     * to the appropriate value based on the "type" of the overlay
+     * when set to `"auto"`.
+     *
+     * @type {'true' | 'false' | 'auto'}
+     * @default 'auto'
+     */
+    receivesFocus: 'true' | 'false' | 'auto';
+    /**
+     * A reference to the slot element within the overlay.
+     *
+     * This element is used to manage the content slotted into the overlay.
+     *
+     * @type {HTMLSlotElement}
+     */
+    slotEl: HTMLSlotElement;
+    /**
+     * The current state of the overlay.
+     *
+     * This property reflects the current state of the overlay, such as 'opened' or 'closed'.
+     * When the state changes, it triggers the appropriate actions and updates the component.
+     *
+     * @type {OverlayState}
+     * @default 'closed'
+     */
+    get state(): OverlayState;
+    set state(state: OverlayState);
+    _state: OverlayState;
+    /**
+     * The interaction strategy for opening the overlay.
+     * This can be a ClickController, HoverController, or LongpressController.
+     */
+    strategy?: ClickController | HoverController | LongpressController;
+    /**
+     * The padding around the tip of the overlay.
+     * This property defines the padding around the tip of the overlay, which can be used to adjust its positioning.
+     *
+     * @type {number}
+     */
+    tipPadding?: number;
+    /**
+     * An optional ID reference for the trigger element combined with the optional
+     * interaction (click | hover | longpress) by which the overlay should open.
+     * The format is `trigger@interaction`, e.g., `trigger@click` opens the overlay
+     * when an element with the ID "trigger" is clicked.
+     *
+     * @type {string}
+     */
+    trigger?: string;
+    /**
+     * An element reference for the trigger element that the overlay should relate to.
+     * This property is not reflected as an attribute.
+     *
+     * @type {HTMLElement | VirtualTrigger | null}
+     */
+    triggerElement: HTMLElement | VirtualTrigger | null;
+    /**
+     * The specific interaction to listen for on the `triggerElement` to open the overlay.
+     * This property is not reflected as an attribute.
+     *
+     * @type {TriggerInteraction}
+     */
+    triggerInteraction?: TriggerInteraction;
+    /**
+     * Configures the open/close heuristics of the Overlay.
+     *
+     * @type {"auto" | "hint" | "manual" | "modal" | "page"}
+     * @default "auto"
+     */
+    type: OverlayTypes;
+    /**
+     * Tracks whether the overlay was previously open.
+     * This is used to restore the open state when re-enabling the overlay.
+     *
+     * @type {boolean}
+     * @default false
+     */
+    protected wasOpen: boolean;
+    /**
+     * Provides an instance of the `ElementResolutionController` for managing the element
+     * that the overlay should be associated with. If the instance does not already exist,
+     * it is created and assigned to the `_elementResolver` property.
+     *
+     * @protected
+     * @returns The `ElementResolutionController` instance.
+     */
+    protected get elementResolver(): ElementResolutionController;
+    /**
+     * Determines if the overlay uses a dialog.
+     * Returns `true` if the overlay type is "modal" or "page".
+     *
+     * @private
+     * @returns `true` if the overlay uses a dialog, otherwise `false`.
+     */
+    private get usesDialog();
+    /**
+     * Determines the value for the popover attribute based on the overlay type.
+     *
+     * @private
+     * @returns The popover value or undefined if not applicable.
+     */
+    private get popoverValue();
+    /**
+     * Determines if the overlay requires positioning based on its type and state.
+     *
+     * @protected
+     * @returns True if the overlay requires positioning, otherwise false.
+     */
+    protected get requiresPositioning(): boolean;
+    /**
+     * Manages the positioning of the overlay relative to its trigger element.
+     *
+     * This method calculates the necessary parameters for positioning the overlay,
+     * such as offset, placement, and tip padding, and then delegates the actual
+     * positioning to the `PlacementController`.
+     *
+     * @protected
+     * @override
+     */
+    protected managePosition(): void;
+    /**
+     * Manages the process of opening the popover.
+     *
+     * This method handles the necessary steps to open the popover, including managing delays,
+     * ensuring the popover is in the DOM, making transitions, and applying focus.
+     *
+     * @protected
+     * @override
+     * @returns A promise that resolves when the popover has been fully opened.
+     */
+    protected managePopoverOpen(): Promise<void>;
+    /**
+     * Applies focus to the appropriate element after the popover has been opened.
+     *
+     * This method handles the focus management for the overlay, ensuring that the correct
+     * element receives focus based on the overlay's type and state.
+     *
+     * @protected
+     * @override
+     * @param targetOpenState - The target open state of the overlay.
+     * @param focusEl - The element to focus after opening the popover.
+     * @returns A promise that resolves when the focus has been applied.
+     */
+    protected applyFocus(targetOpenState: boolean, focusEl: HTMLElement | null): Promise<void>;
+    /**
+     * Returns focus to the trigger element if the overlay is closed.
+     *
+     * This method ensures that focus is returned to the trigger element when the overlay is closed,
+     * unless the overlay is of type "hint" or the focus is already outside the overlay.
+     *
+     * @protected
+     * @override
+     */
+    protected returnFocus(): void;
+    /**
+     * Handles the focus out event to close the overlay if the focus moves outside of it.
+     *
+     * This method ensures that the overlay is closed when the focus moves to an element
+     * outside of the overlay, unless the focus is moved to a related element.
+     *
+     * @private
+     * @param event - The focus out event.
+     */
+    private closeOnFocusOut;
+    /**
+     * Manages the process of opening or closing the overlay.
+     *
+     * This method handles the necessary steps to open or close the overlay, including updating the state,
+     * managing the overlay stack, and handling focus events.
+     *
+     * @protected
+     * @param oldOpen - The previous open state of the overlay.
+     * @returns A promise that resolves when the overlay has been fully managed.
+     */
+    protected manageOpen(oldOpen: boolean): Promise<void>;
+    /**
+     * Binds event handling strategies to the overlay based on the specified trigger interaction.
+     *
+     * This method sets up the appropriate event handling strategy for the overlay, ensuring that
+     * it responds correctly to user interactions such as clicks, hovers, or long presses.
+     *
+     * @protected
+     */
+    protected bindEvents(): void;
+    /**
+     * Handles the `beforetoggle` event to manage the overlay's state.
+     *
+     * This method checks the new state of the event and calls `handleBrowserClose`
+     * if the new state is not 'open'.
+     *
+     * @protected
+     * @param event - The `beforetoggle` event with the new state.
+     */
+    protected handleBeforetoggle(event: Event & {
+        newState: string;
+    }): void;
+    /**
+     * Handles the browser's close event to manage the overlay's state.
+     *
+     * This method stops the propagation of the event and closes the overlay if it is not
+     * actively opening. If the overlay is actively opening, it calls `manuallyKeepOpen`.
+     *
+     * @protected
+     * @param event - The browser's close event.
+     */
+    protected handleBrowserClose(event: Event): void;
+    /**
+     * Manually keeps the overlay open.
+     *
+     * This method sets the overlay to open, allows placement updates, and manages the open state.
+     *
+     * @public
+     * @override
+     */
+    manuallyKeepOpen(): void;
+    /**
+     * Handles the `slotchange` event to manage the overlay's state.
+     *
+     * This method checks if there are any elements in the slot. If there are no elements,
+     * it releases the description from the strategy. If there are elements and the trigger
+     * is non-virtual, it prepares the description for the trigger element.
+     *
+     * @protected
+     */
+    protected handleSlotchange(): void;
+    /**
+     * Determines whether the overlay should prevent closing.
+     *
+     * This method checks the `willPreventClose` flag and resets it to `false`.
+     * It returns the value of the `willPreventClose` flag.
+     *
+     * @public
+     * @returns `true` if the overlay should prevent closing, otherwise `false`.
+     */
+    shouldPreventClose(): boolean;
+    /**
+     * Requests slottable content for the overlay.
+     *
+     * This method dispatches a `SlottableRequestEvent` to request or remove slottable content
+     * based on the current open state of the overlay. It ensures that the same state is not
+     * dispatched twice in a row.
+     *
+     * @protected
+     * @override
+     */
+    protected requestSlottable(): void;
+    /**
+     * Lifecycle method called before the component updates.
+     *
+     * This method handles various tasks before the component updates, such as setting an ID,
+     * managing the open state, resolving the trigger element, and binding events.
+     *
+     * @override
+     * @param changes - The properties that have changed.
+     */
+    willUpdate(changes: PropertyValues): void;
+    /**
+     * Lifecycle method called after the component updates.
+     *
+     * This method handles various tasks after the component updates, such as updating the placement
+     * attribute, resetting the overlay position, and clearing the overlay position based on the state.
+     *
+     * @override
+     * @param changes - The properties that have changed.
+     */
+    protected updated(changes: PropertyValues): void;
+    /**
+     * Renders the content of the overlay.
+     *
+     * This method returns a template result containing a slot element. The slot element
+     * listens for the `slotchange` event to manage the overlay's state.
+     *
+     * @protected
+     * @returns The template result containing the slot element.
+     */
+    protected renderContent(): TemplateResult;
+    /**
+     * Generates a style map for the dialog element.
+     *
+     * This method returns an object containing CSS custom properties for the dialog element.
+     * The `--luzmo-overlay-open-count` custom property is set to the current open count of overlays.
+     *
+     * @private
+     * @returns The style map for the dialog element.
+     */
+    private get dialogStyleMap();
+    /**
+     * Renders the dialog element for the overlay.
+     *
+     * This method returns a template result containing a dialog element. The dialog element
+     * includes various attributes and event listeners to manage the overlay's state and behavior.
+     *
+     * @protected
+     * @returns The template result containing the dialog element.
+     */
+    protected renderDialog(): TemplateResult;
+    /**
+     * Renders the popover element for the overlay.
+     *
+     * This method returns a template result containing a div element styled as a popover.
+     * The popover element includes various attributes and event listeners to manage the overlay's state and behavior.
+     *
+     * @protected
+     * @returns The template result containing the popover element.
+     */
+    protected renderPopover(): TemplateResult;
+    /**
+     * Renders the overlay component.
+     *
+     * This method returns a template result containing either a dialog or popover element
+     * based on the overlay type. It also includes a slot for longpress descriptors.
+     *
+     * @override
+     * @returns The template result containing the overlay content.
+     */
+    render(): TemplateResult;
+    /**
+     * Lifecycle method called when the component is added to the DOM.
+     *
+     * This method sets up event listeners and binds events if the component has already updated.
+     *
+     * @override
+     */
+    connectedCallback(): void;
+    /**
+     * Lifecycle method called when the component is removed from the DOM.
+     *
+     * This method releases the description from the strategy and updates the 'open' property.
+     *
+     * @override
+     */
+    disconnectedCallback(): void;
+}
+export {};

package/components/overlay/placement-controller.d.ts

@@ -0,0 +1,157 @@
+import { Placement } from '@floating-ui/dom';
+import type { ReactiveController, ReactiveElement } from 'lit';
+import type { OpenableElement } from './overlay-types';
+import type { VirtualTrigger } from './virtual-trigger';
+type OverlayOptionsV1 = {
+    abortPromise?: Promise<boolean>;
+    delayed?: boolean;
+    offset?: number | [number, number];
+    placement: Placement;
+    notImmediatelyClosable?: boolean;
+    receivesFocus?: 'auto';
+    root?: HTMLElement;
+    tipPadding?: number;
+    trigger: HTMLElement | VirtualTrigger;
+    type?: 'modal' | 'page' | 'hint' | 'auto' | 'manual';
+};
+/**
+ * Symbol used to indicate that the placement has been updated.
+ */
+export declare const placementUpdatedSymbol: unique symbol;
+/**
+ * Controller for managing the placement of an overlay.
+ *
+ * This class implements the ReactiveController interface and provides methods
+ * for managing the positioning and constraints of an overlay element.
+ */
+export declare class PlacementController implements ReactiveController {
+    /**
+     * Function to clean up resources when the controller is no longer needed.
+     *
+     * @private
+     */
+    private cleanup?;
+    /**
+     * Initial height of the overlay.
+     *
+     * @type {number}
+     */
+    initialHeight?: number;
+    /**
+     * Indicates whether the overlay is constrained by available space.
+     *
+     * @type {boolean}
+     */
+    isConstrained?: boolean;
+    /**
+     * The host element that uses this controller.
+     *
+     * @private
+     * @type {ReactiveElement & { elements: OpenableElement[] }}
+     */
+    private host;
+    /**
+     * Options for configuring the overlay placement.
+     *
+     * @private
+     * @type {OverlayOptionsV1}
+     */
+    private options;
+    /**
+     * A WeakMap to store the original placements of overlay elements.
+     *
+     * @private
+     * @type {WeakMap<HTMLElement, Placement>}
+     */
+    private originalPlacements;
+    /**
+     * The target element for the overlay.
+     *
+     * @private
+     * @type {HTMLElement}
+     */
+    private target;
+    /**
+     * Creates an instance of the PlacementController.
+     *
+     * @param host - The host element that uses this controller.
+     */
+    constructor(host: ReactiveElement & {
+        elements: OpenableElement[];
+    });
+    /**
+     * Places the overlay relative to the target element.
+     *
+     * This method sets up the necessary configurations and event listeners to manage the
+     * positioning and constraints of the overlay element.
+     *
+     * @param [target=this.target] - The target element for the overlay.
+     * @param [options=this.options] - The options for configuring the overlay placement.
+     * @returns A promise that resolves when the overlay has been placed.
+     */
+    placeOverlay(target?: HTMLElement, options?: OverlayOptionsV1): void;
+    /**
+     * Flag to allow or disallow placement updates.
+     *
+     * @type {boolean}
+     */
+    allowPlacementUpdate: boolean;
+    /**
+     * Closes the overlay if an ancestor element is updated.
+     *
+     * This method checks if placement updates are allowed and if the overlay type is not 'modal'.
+     * If these conditions are met and a cleanup function is defined, it dispatches a 'close' event
+     * on the target element to close the overlay.
+     */
+    closeForAncestorUpdate: () => void;
+    /**
+     * Updates the placement of the overlay.
+     *
+     * This method calls the computePlacement method to recalculate the overlay's position.
+     *
+     * @private
+     */
+    private updatePlacement;
+    /**
+     * Computes the placement of the overlay relative to the target element.
+     *
+     * This method calculates the necessary positioning and constraints for the overlay element
+     * using various middleware functions. It updates the overlay's style and attributes based
+     * on the computed position.
+     *
+     * @returns A promise that resolves when the placement has been computed.
+     */
+    computePlacement(): Promise<void>;
+    /**
+     * Clears the overlay's position styles.
+     *
+     * This method removes the max-height and max-width styles from the target element,
+     * and resets the initial height and constrained state of the overlay.
+     */
+    clearOverlayPosition(): void;
+    /**
+     * Resets the overlay's position.
+     *
+     * This method clears the overlay's position, forces a reflow, and recomputes the placement.
+     */
+    resetOverlayPosition: () => void;
+    /**
+     * Lifecycle method called when the host element is connected to the DOM.
+     *
+     * This method sets up an event listener to reset the overlay's position when the 'luzmo-update-overlays' event is dispatched.
+     */
+    hostConnected(): void;
+    /**
+     * Lifecycle method called when the host element is updated.
+     *
+     * This method cleans up resources if the overlay is not open.
+     */
+    hostUpdated(): void;
+    /**
+     * Lifecycle method called when the host element is disconnected from the DOM.
+     *
+     * This method removes the event listener and cleans up resources.
+     */
+    hostDisconnected(): void;
+}
+export {};

package/components/overlay/slottable-request-directive.d.ts

@@ -0,0 +1,17 @@
+import { ElementPart, TemplateResult } from 'lit';
+import { AsyncDirective } from 'lit/async-directive.js';
+import { SlottableRequestEvent } from './slottable-request-event';
+export declare class SlottableRequestDirective extends AsyncDirective {
+    protected template: () => TemplateResult;
+    protected target: HTMLElement;
+    private renderBefore;
+    protected listenerHost: HTMLElement;
+    protected listeners: AbortController;
+    render(_template: () => TemplateResult): unknown;
+    update(part: ElementPart, [template]: Parameters<this['render']>): void;
+    handleSlottableRequest(event: SlottableRequestEvent): void;
+    init(): void;
+    disconnected(): void;
+    reconnected(): void;
+}
+export declare const slottableRequest: (_template: () => TemplateResult) => import("lit-html/directive.js").DirectiveResult<typeof SlottableRequestDirective>;

package/components/overlay/slottable-request-event.d.ts

@@ -0,0 +1,12 @@
+export declare class SlottableRequestEvent extends Event {
+    readonly data: unknown;
+    readonly name: string;
+    readonly slotName: string;
+    constructor(name: string, data: unknown, key?: string);
+}
+export declare const removeSlottableRequest: unique symbol;
+declare global {
+    interface GlobalEventHandlersEventMap {
+        'slottable-request': SlottableRequestEvent;
+    }
+}

package/components/overlay/strategies.d.ts

@@ -0,0 +1,8 @@
+import { ClickController } from './click-controller';
+import { HoverController } from './hover-controller';
+import { LongpressController } from './longpress-controller';
+export declare const strategies: {
+    click: typeof ClickController;
+    longpress: typeof LongpressController;
+    hover: typeof HoverController;
+};

package/components/overlay/virtual-trigger.d.ts

@@ -0,0 +1,7 @@
+export declare class VirtualTrigger {
+    private x;
+    private y;
+    constructor(x: number, y: number);
+    updateBoundingClientRect(x: number, y: number): void;
+    getBoundingClientRect(): DOMRect;
+}