@malva-ui/core 0.1.13 → 0.1.14

package/types/malva-ui-core-popup.d.ts

@@ -0,0 +1,834 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, Provider, ElementRef, TemplateRef, ViewContainerRef, OnDestroy } from '@angular/core';
+import { Subject } from 'rxjs';
+import { BooleanInput } from '@angular/cdk/coercion';
+import { ConnectedPosition, OverlayRef, ConnectedOverlayPositionChange } from '@angular/cdk/overlay';
+import { MlvStructural, MlvBreakpoint } from '@malva-ui/cdk/utils';
+import { MlvDensity } from '@malva-ui/cdk/density';
+
+declare class MlvPopupContent extends MlvStructural {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvPopupContent, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvPopupContent, "[mlvPopupContent]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Marks an `<ng-template>` as extra chrome rendered inside the popup's
+ * full-screen mobile header, directly beneath the title/close row.
+ *
+ * Generic and reusable: the popup renders it only while
+ * {@link MlvPopup.isFullscreen} is `true`, and no-ops when the slot is
+ * absent or the popup is trigger-anchored. Consumers use it to move controls
+ * that must stay reachable inside the full-screen sheet — e.g. `mlv-combobox`
+ * projects an in-sheet search input here so type-to-filter keeps working when
+ * the solid backdrop and focus trap would otherwise occlude/block the outer
+ * trigger input.
+ */
+declare class MlvPopupHeaderContent extends MlvStructural {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvPopupHeaderContent, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvPopupHeaderContent, "[mlvPopupHeaderContent]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Marks an `<ng-template>` as extra chrome pinned above the popup's scroll
+ * region in every mode — never scrolls with the content.
+ *
+ * Generic and reusable: the popup stamps it directly above
+ * `.mlv-popup__scrollbar` whether the panel is trigger-anchored or a
+ * full-screen sheet (where it sits below the header), and no-ops when the slot
+ * is absent. Consumers use it for chrome that must stay visible no matter how
+ * far the content scrolls — e.g. `mlv-select` projects its in-dropdown search
+ * field here so a long option list cannot push it out of view.
+ */
+declare class MlvPopupPinnedContent extends MlvStructural {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvPopupPinnedContent, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvPopupPinnedContent, "[mlvPopupPinnedContent]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * The set of named popup positions supported out of the box.
+ *
+ * Positions follow the `{side}-{alignment}` convention:
+ * - **side** — the side of the trigger the popup appears on (`top`, `bottom`, `left`, `right`)
+ * - **alignment** — where the popup edge aligns to the trigger:
+ *   `start` = top (for left/right) or left (for top/bottom),
+ *   `end`   = bottom (for left/right) or right (for top/bottom),
+ *   _(omitted)_ = centered
+ *
+ * All positions include an 8px gap between the trigger and the popup.
+ */
+type MlvPopupPositionName = 'top-start' | 'top' | 'top-end' | 'bottom-start' | 'bottom' | 'bottom-end' | 'left-start' | 'left' | 'left-end' | 'right-start' | 'right' | 'right-end';
+/**
+ * The default named-position map used when no custom `POPUP_POSITIONS` provider
+ * is registered. Contains all twelve standard popup placements.
+ *
+ * Override globally with `providePopupPositions()`, or per-component via
+ * the `POPUP_POSITIONS` injection token.
+ */
+declare const POPUP_POSITION_MAP: ReadonlyMap<MlvPopupPositionName, ConnectedPosition>;
+/**
+ * Injection token that holds the active named-position map.
+ *
+ * Defaults to {@link POPUP_POSITION_MAP}. Override at the application or
+ * component level with {@link providePopupPositions} to add, remove, or
+ * replace named positions.
+ *
+ * @example Override globally in app providers
+ * ```ts
+ * providePopupPositions(new Map([
+ *   ['bottom', { originX: 'center', originY: 'bottom', overlayX: 'center', overlayY: 'top', offsetY: 4 }],
+ * ]))
+ * ```
+ */
+declare const POPUP_POSITIONS: InjectionToken<ReadonlyMap<MlvPopupPositionName, ConnectedPosition>>;
+/**
+ * Registers a custom named-position map as the active `POPUP_POSITIONS`.
+ *
+ * Call in the root `providers` array (or a component's `providers`) to
+ * replace all default positions with a custom set.
+ *
+ * @param positions — A `Map` of {@link MlvPopupPositionName} → CDK `ConnectedPosition`.
+ *
+ * @example
+ * ```ts
+ * // app.config.ts
+ * providers: [
+ *   providePopupPositions(new Map([
+ *     ...POPUP_POSITION_MAP,
+ *     ['bottom', { originX: 'center', originY: 'bottom', overlayX: 'center', overlayY: 'top', offsetY: 4 }],
+ *   ]))
+ * ]
+ * ```
+ */
+declare function providePopupPositions(positions: ReadonlyMap<MlvPopupPositionName, ConnectedPosition>): Provider;
+/**
+ * Static utility class for resolving named popup positions.
+ *
+ * Centralises all lookup logic so that {@link MlvPopup} and
+ * {@link MlvPopupService} share one consistent resolution path.
+ */
+declare class MlvPopupPositionResolver {
+    /**
+     * Resolves one or more {@link MlvPopupPositionName} strings to CDK
+     * `ConnectedPosition` objects using the provided map.
+     *
+     * - Positions are returned in the same order as `names`.
+     * - If a name is not found in the map, it is skipped and a warning is
+     *   emitted in dev mode via `console.warn`.
+     * - Returns an empty array if no names resolve successfully.
+     *
+     * @param names      — A single name or ordered array of names (CDK uses
+     *                     the first one that fits in the viewport).
+     * @param positionMap — The active position map (from `POPUP_POSITIONS` token).
+     */
+    static resolve(names: MlvPopupPositionName | MlvPopupPositionName[], positionMap: ReadonlyMap<MlvPopupPositionName, ConnectedPosition>): ConnectedPosition[];
+    /**
+     * Returns all positions in the map as an ordered array.
+     * Used as the CDK fallback sequence when no explicit `position` is set.
+     *
+     * @param positionMap — The active position map (from `POPUP_POSITIONS` token).
+     */
+    static allPositions(positionMap: ReadonlyMap<MlvPopupPositionName, ConnectedPosition>): ConnectedPosition[];
+}
+/**
+ * Ordered CDK positions for a dropdown menu panel that opens below its trigger:
+ * `bottom-start` preferred, flipping vertically (`top-start`) then aligning to
+ * the trigger's end edge (`bottom-end`, `top-end`) when space is constrained.
+ *
+ * Derived from {@link POPUP_POSITION_MAP} so menu overlays stay consistent with
+ * the rest of the Malva UI overlay system. Consumed by `MlvMenuTrigger`.
+ */
+declare const MENU_POSITIONS: ConnectedPosition[];
+/**
+ * Ordered CDK positions for a submenu panel that opens to the right of its
+ * parent item (`right-start`), flipping to the left (`left-start`) when there
+ * is no room on the right.
+ *
+ * Derived from {@link POPUP_POSITION_MAP}. Consumed by `MlvMenuTrigger`.
+ */
+declare const SUBMENU_POSITIONS: ConnectedPosition[];
+
+/**
+ * Controls what happens to the popup when the user scrolls.
+ *
+ * - `'reposition'` (default) — the overlay repositions with the trigger as the page scrolls.
+ * - `'close'` — the overlay closes as soon as the user scrolls.
+ * - `'block'` — scroll is blocked while the overlay is open.
+ * - `'noop'` — the overlay stays fixed at its original position; no repositioning or closing.
+ */
+type MlvPopupScrollStrategy = 'reposition' | 'close' | 'block' | 'noop';
+/** Size constraints passed to the CDK overlay on creation. */
+interface MlvPopupSizeConfig {
+    /** Explicit panel width (CSS value or pixel number). */
+    width?: number | string;
+    /** Explicit panel height (CSS value or pixel number). */
+    height?: number | string;
+    /** Minimum panel width. */
+    minWidth?: number | string;
+    /** Minimum panel height. */
+    minHeight?: number | string;
+    /** Maximum panel width. */
+    maxWidth?: number | string;
+    /** Maximum panel height. */
+    maxHeight?: number | string;
+}
+/** Configuration object passed to {@link MlvPopupService.open}. */
+interface MlvPopupOpenConfig {
+    /** The element the overlay attaches to. */
+    origin: ElementRef;
+    /** The `<ng-template>` to render inside the overlay. */
+    template: TemplateRef<unknown>;
+    /** The `ViewContainerRef` used to instantiate the portal. */
+    vcr: ViewContainerRef;
+    /**
+     * Ordered list of CDK `ConnectedPosition` objects the overlay will try in
+     * sequence until one fits within the viewport.
+     *
+     * Use {@link MlvPopupService.resolvePositions} to build this list from named
+     * positions when working programmatically.
+     */
+    positions: ConnectedPosition[];
+    /** Optional size constraints applied to the overlay panel. */
+    size?: MlvPopupSizeConfig;
+    /**
+     * When `true`, the overlay is rendered as a full-screen mobile sheet:
+     * a global (viewport-filling) position strategy replaces the connected
+     * strategy, a solid backdrop is always shown, page scroll is locked
+     * (block scroll strategy), and the connected {@link positions}/{@link size}
+     * are ignored. Defaults to `false` (trigger-anchored behaviour).
+     */
+    fullscreen?: boolean;
+    /**
+     * When `true` (default), a transparent CDK backdrop is created; clicking it
+     * triggers `onRequestClose`.
+     *
+     * When `false`, no visual backdrop is rendered, but click-outside detection
+     * is preserved via a document-level click listener (attached after a
+     * `setTimeout(0)` to avoid catching the opening click). Escape key closure
+     * is always active regardless of this flag.
+     */
+    hasBackdrop?: boolean;
+    /** Optional CDK backdrop class. Defaults to `cdk-overlay-transparent-backdrop`. */
+    backdropClass?: string;
+    /**
+     * Controls overlay behaviour when the page is scrolled.
+     * Defaults to `'reposition'`.
+     */
+    scrollStrategy?: MlvPopupScrollStrategy;
+    /** Allow the overlay to grow in the axis constrained by the viewport. */
+    flexibleDimensions?: boolean;
+    /**
+     * Extra elements treated as "inside" the popup for click-outside detection
+     * (backdrop-less mode only). A click within any of these — in addition to the
+     * overlay panel itself — does not trigger `onRequestClose`. Typically the
+     * trigger/anchor element, which lives outside the floating overlay panel.
+     */
+    dismissExcludeElements?: readonly HTMLElement[];
+    /** Called after the overlay is fully disposed. */
+    onClose: () => void;
+    /**
+     * Called when the user requests closure (backdrop click, Escape key).
+     * Defaults to `onClose` when not provided.
+     */
+    onRequestClose?: () => void;
+    /** Called each time CDK selects a different `ConnectedPosition`. */
+    onPositionChange?: (change: ConnectedOverlayPositionChange) => void;
+}
+/** Return value of {@link MlvPopupService.open}. */
+interface MlvPopupHandle {
+    /** The underlying CDK overlay reference. */
+    overlayRef: OverlayRef;
+    /** Disposes the overlay and triggers `onClose`. */
+    close: () => void;
+}
+/**
+ * Low-level CDK overlay service for Malva UI popup components.
+ *
+ * Handles overlay creation, portal attachment, position strategy,
+ * backdrop clicks, and Escape-key closure.
+ *
+ * For template-driven usage prefer `[mlvPopupTrigger]` or
+ * `<mlv-popup-container>`. Use this service directly only when you need
+ * full programmatic control.
+ *
+ * @example Programmatic usage
+ * ```ts
+ * const handle = this.popupService.open({
+ *   origin: this.triggerRef,
+ *   template: this.tpl,
+ *   vcr: this.vcr,
+ *   positions: this.popupService.resolvePositions(['bottom', 'top']),
+ *   onClose: () => this.isOpen.set(false),
+ * });
+ * // Later:
+ * handle.close();
+ * ```
+ */
+declare class MlvPopupService {
+    /** @private CDK overlay service. */
+    private readonly _overlay;
+    /**
+     * @private Resolves the direction scoped to each popup's origin so portaled
+     * panes mirror with their trigger rather than with the document.
+     */
+    private readonly _rtl;
+    /** @private Active named-position map (overridable via `POPUP_POSITIONS` token). */
+    private readonly _positionMap;
+    /** @private Angular zone for running document-level event handlers inside change detection. */
+    private readonly _ngZone;
+    /**
+     * Resolves one or more {@link MlvPopupPositionName} strings to CDK
+     * `ConnectedPosition` objects.
+     *
+     * Positions are resolved from the active `POPUP_POSITIONS` map. If a name
+     * is not found, it is skipped and a `console.warn` is emitted in dev mode.
+     * CDK uses the first position in the returned array that fits in the viewport.
+     *
+     * @param names — A single name or ordered array of fallback names.
+     *
+     * @example
+     * ```ts
+     * positions: this.popupService.resolvePositions('bottom-end')
+     * positions: this.popupService.resolvePositions(['bottom-end', 'top-end'])
+     * ```
+     */
+    resolvePositions(names: MlvPopupPositionName | MlvPopupPositionName[]): ConnectedPosition[];
+    /**
+     * Creates a CDK overlay, attaches the given template portal, and wires up
+     * backdrop and Escape-key closure.
+     *
+     * @param config — Full overlay configuration.
+     * @returns A {@link MlvPopupHandle} with the `overlayRef` and a `close()` method.
+     */
+    open(config: MlvPopupOpenConfig): MlvPopupHandle;
+    /**
+     * @private Maps a {@link MlvPopupScrollStrategy} name to a CDK scroll-strategy instance.
+     */
+    private _resolveScrollStrategy;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvPopupService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<MlvPopupService>;
+}
+
+type MlvPopupArrowEdge = 'top' | 'bottom' | 'left' | 'right';
+type MlvPopupArrowAlign = 'start' | 'center' | 'end';
+/**
+ * Fallback delay (ms) after which a pending leave is force-completed when the
+ * panel's `animationend` never fires — `prefers-reduced-motion` removes the
+ * leave animation entirely, and hidden/background tabs throttle CSS animations.
+ * Comfortably above the default leave duration (`--mlv-duration-fast`, 100ms);
+ * matches the dialog's `LEAVE_FALLBACK_MS` (250 ms).
+ */
+declare const POPUP_LEAVE_FALLBACK_MS = 250;
+/**
+ * Delay (ms) after which an overlay owner force-detaches a popup whose leave
+ * animation never completed. Sits just past {@link POPUP_LEAVE_FALLBACK_MS} so
+ * the normal `animationend` / fallback path always wins when it works.
+ */
+declare const POPUP_DETACH_WATCHDOG_MS: number;
+/**
+ * Controls whether the popup renders as a full-screen mobile sheet.
+ *
+ * - `'off'` (default) — always anchored to the trigger (byte-identical to the
+ *   original popup behaviour). Consumers must opt in to enable the mechanism.
+ * - `'auto'` — full-screen when the viewport is below {@link MlvPopup.mobileBreakpoint},
+ *   anchored otherwise.
+ * - `'fullscreen'` — always full-screen regardless of viewport (useful for demos/forcing).
+ */
+type MlvPopupMobileMode = 'auto' | 'fullscreen' | 'off';
+declare class MlvPopup {
+    /** @private Active named-position map (overridable via `POPUP_POSITIONS` token). */
+    private readonly _positionMap;
+    /**
+     * Named position(s) controlling where the popup appears relative to its trigger.
+     *
+     * Accepts a single {@link MlvPopupPositionName} or an ordered array of names.
+     * CDK tries positions in array order and uses the first one that fits in the
+     * viewport — useful for automatic flip behaviour.
+     *
+     * When set, takes precedence over the raw {@link positions} input.
+     * When both are omitted, all twelve default positions are passed to CDK.
+     *
+     * An unrecognised name is skipped and a `console.warn` is emitted in dev mode.
+     *
+     * @example Single preferred position
+     * ```html
+     * <mlv-popup position="bottom-end" />
+     * ```
+     *
+     * @example Preferred + fallback
+     * ```html
+     * <mlv-popup [position]="['bottom-end', 'top-end']" />
+     * ```
+     */
+    readonly position: _angular_core.InputSignal<MlvPopupPositionName | MlvPopupPositionName[] | undefined>;
+    /**
+     * Raw CDK `ConnectedPosition` array for advanced use cases where named
+     * positions are insufficient.
+     *
+     * When set and `position` is not set, these positions are passed directly
+     * to the CDK overlay. Prefer `position` for standard placements.
+     */
+    readonly positions: _angular_core.InputSignal<ConnectedPosition[] | undefined>;
+    /** Explicit CSS width of the popup panel. */
+    readonly width: _angular_core.InputSignal<string | number | undefined>;
+    /** Explicit CSS height of the popup panel. */
+    readonly height: _angular_core.InputSignal<string | number | undefined>;
+    /** Minimum CSS width of the popup panel. */
+    readonly minWidth: _angular_core.InputSignal<string | number | undefined>;
+    /** Minimum CSS height of the popup panel. */
+    readonly minHeight: _angular_core.InputSignal<string | number | undefined>;
+    /** Maximum CSS width of the popup panel. */
+    readonly maxWidth: _angular_core.InputSignal<string | number | undefined>;
+    /** Maximum CSS height of the popup panel. */
+    readonly maxHeight: _angular_core.InputSignal<string | number | undefined>;
+    /** When `true`, a directional arrow is rendered pointing toward the trigger. */
+    readonly hasArrow: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** When `true` (default), a drop-shadow is applied to the popup panel. */
+    readonly hasShadow: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Additional CSS classes forwarded to the popup panel host. */
+    readonly class: _angular_core.InputSignal<string | undefined>;
+    /**
+     * Density applied to the popup's content.
+     *
+     * The popup panel is portaled to the CDK overlay container on `<body>`, so it
+     * sits outside any `mlvDensityRoot` / ancestor density cascade in the page.
+     * This input restores the cascade on the detached panel: the resolved density
+     * is stamped as a `mlv--{density}` class on the panel element, and every
+     * density-aware descendant (e.g. `mlv-list-item` rows in a dropdown panel)
+     * responds through the standard CSS cascade.
+     *
+     * When omitted, the nearest ancestor `MLV_DENSITY_CONTEXT` (e.g. a
+     * `form[mlvForm]`) is used, then the global `MlvDensityService`, so popovers
+     * follow the surrounding / app-wide density without extra wiring. Components
+     * that embed a popup (select, combobox, pagination, menu, …) forward their
+     * own `mlvDensity` input here.
+     */
+    readonly mlvDensity: _angular_core.InputSignal<MlvDensity | undefined>;
+    /**
+     * @private Global density service — fallback when no explicit
+     * {@link mlvDensity} is supplied.
+     */
+    private readonly _densityService;
+    /**
+     * @private Density projected by an ancestor container (e.g. `form[mlvForm]`).
+     * Consulted after the explicit {@link mlvDensity} input, before the service.
+     */
+    private readonly _densityContext;
+    /**
+     * @protected Class list for the detached panel element: consumer classes from
+     * {@link class} plus the resolved `mlv--{density}` cascade class.
+     */
+    protected readonly _panelClasses: _angular_core.Signal<string>;
+    /** Allow the overlay panel to grow to fill available viewport space. */
+    readonly flexibleDimensions: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * Controls overlay behaviour when the page is scrolled.
+     *
+     * - `'reposition'` (default) — overlay follows the trigger.
+     * - `'close'` — overlay closes on scroll.
+     * - `'block'` — page scroll is blocked while the overlay is open.
+     * - `'noop'` — overlay stays fixed.
+     */
+    readonly scrollStrategy: _angular_core.InputSignal<MlvPopupScrollStrategy>;
+    /**
+     * Whether to render a transparent backdrop behind the popup.
+     *
+     * When `undefined` (default), the trigger decides — click/keyboard triggers
+     * use a backdrop; hover triggers do not.
+     *
+     * Set to `false` to suppress the backdrop while keeping click-outside and
+     * Escape detection active.
+     */
+    readonly hasBackdrop: _angular_core.InputSignalWithTransform<boolean | undefined, BooleanInput>;
+    /**
+     * When `true` (default), only the explicitly provided position(s) are passed to CDK.
+     * CDK will push the popup into the viewport if none of them fit, but won't try other
+     * named positions automatically.
+     *
+     * When `false`, the provided position(s) are used first and all remaining positions
+     * from the active `POPUP_POSITIONS` map are appended as ordered fallbacks. CDK will
+     * try them in sequence and use the first one that fits — useful for popups near edges
+     * that should freely reposition rather than be pushed.
+     *
+     * @example Prefer bottom-start, fall back to any position that fits
+     * ```html
+     * <mlv-popup position="bottom-start" [restrictPosition]="false" />
+     * ```
+     */
+    readonly restrictPosition: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * ARIA role applied to the popup panel element.
+     *
+     * Defaults to `null` — the panel is a neutral positioning/chrome container and
+     * the semantic role is expected to come from the projected content
+     * (e.g. a `role="menu"` list, a `role="listbox"`, or a `role="tooltip"`).
+     *
+     * Set to `'dialog'` (together with {@link modal}`= true`) for genuine modal
+     * dialog surfaces such as a date-picker calendar. When `panelRole === 'dialog'`
+     * and {@link modal} is `true`, an accessible name via {@link ariaLabel} (or a
+     * projected labelling element) is required.
+     */
+    readonly panelRole: _angular_core.InputSignal<string | null>;
+    /**
+     * Whether the popup panel behaves as a modal surface.
+     *
+     * When `true`, the panel renders `aria-modal="true"` and enables the CDK focus
+     * trap (Tab / Shift+Tab cycle within the panel). When `false` (default), no
+     * `aria-modal` is emitted and focus is free to leave the panel — the correct
+     * behaviour for menus, listboxes, and tooltips whose focus is managed by their
+     * own trigger / roving-tabindex logic.
+     */
+    readonly modal: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * Optional accessible name for the popup panel.
+     * Applied as `aria-label` on the popup element.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
+    /**
+     * Extra elements that count as "inside" the popup for click-outside dismissal.
+     *
+     * When the popup is opened without a backdrop (`[hasBackdrop]="false"`),
+     * dismissal is detected by a document-level click listener that closes the
+     * popup on any click outside the overlay panel. The trigger/anchor lives in
+     * the normal document flow — outside the floating panel — so a click on it
+     * (or on any control it owns) would otherwise be treated as "outside" and
+     * dismiss the popup. List these elements (typically the trigger) so clicks
+     * within them do not close the popup; e.g. `mlv-combobox` passes its input
+     * row so caret repositioning while the list is open keeps the list open.
+     *
+     * Has no effect when a backdrop is used.
+     */
+    readonly dismissExcludeElements: _angular_core.InputSignal<readonly HTMLElement[]>;
+    /** @private Signal-based viewport breakpoint service (SSR-safe via CDK). */
+    private readonly _breakpoint;
+    /**
+     * @private Optional popup i18n slice — provides the fullscreen close-button
+     * label. Injected optionally so the popup keeps working when no i18n provider
+     * is configured (falls back to the English default).
+     */
+    private readonly _i18n;
+    /**
+     * Controls whether the popup renders as a full-screen mobile sheet with a
+     * header bar and close button instead of a trigger-anchored panel.
+     *
+     * Defaults to `'off'` so existing consumers are unaffected — the pickers
+     * (day/date-range/time) opt into `'auto'`.
+     */
+    readonly mobileMode: _angular_core.InputSignal<MlvPopupMobileMode>;
+    /**
+     * Breakpoint below which `mobileMode="auto"` switches the popup to full-screen.
+     * Defaults to `'md'` (viewport narrower than 768px, per `MLV_BREAKPOINT_CONFIG`).
+     */
+    readonly mobileBreakpoint: _angular_core.InputSignal<MlvBreakpoint>;
+    /**
+     * Optional visible title rendered in the full-screen header bar. When omitted,
+     * the header shows only the close button.
+     */
+    readonly mobileTitle: _angular_core.InputSignal<string | undefined>;
+    /**
+     * Optional override for the full-screen close-button accessible name.
+     * Falls back to the `MLV_POPUP_I18N` `close` string, then to `'Close'`.
+     */
+    readonly mobileCloseLabel: _angular_core.InputSignal<string | undefined>;
+    /**
+     * Whether the popup is currently rendering as a full-screen mobile sheet.
+     *
+     * `'off'` → always `false`; `'fullscreen'` → always `true`; `'auto'` → `true`
+     * when the viewport is below {@link mobileBreakpoint}. Public so consumers with
+     * their own inner focus trap (e.g. `mlv-date-range-picker`) can disable it to
+     * avoid nesting two traps inside the full-screen panel.
+     */
+    readonly isFullscreen: _angular_core.Signal<boolean>;
+    /** @protected Resolved accessible name for the full-screen close button. */
+    protected readonly _closeLabel: _angular_core.Signal<string>;
+    /** Two-way binding for the open/closed state. */
+    readonly opened: _angular_core.ModelSignal<boolean>;
+    /** Emitted after the popup enters the view and the enter animation completes. */
+    readonly afterOpened: _angular_core.OutputEmitterRef<void>;
+    /** Emitted after the popup leaves the view and the leave animation completes. */
+    readonly afterClosed: _angular_core.OutputEmitterRef<void>;
+    readonly animationState: _angular_core.WritableSignal<"enter" | "leave" | "idle">;
+    readonly arrowEdge: _angular_core.WritableSignal<MlvPopupArrowEdge>;
+    readonly arrowAlign: _angular_core.WritableSignal<MlvPopupArrowAlign>;
+    /**
+     * CSS transform value for the popup's hidden/offscreen position.
+     * Used as `--mlv-popup-hidden-transform` so the enter/leave keyframes
+     * slide in from the correct edge depending on where the popup is placed.
+     */
+    readonly popupHiddenTransform: _angular_core.Signal<"translateY(-4px)" | "translateY(4px)" | "translateX(-4px)" | "translateX(4px)">;
+    /** @protected Projected popup content template, rendered into the overlay panel. */
+    protected readonly contentRef: _angular_core.Signal<MlvPopupContent | undefined>;
+    /**
+     * @protected Optional header-extension template projected via
+     * `[mlvPopupHeaderContent]`. Rendered inside the full-screen header, directly
+     * beneath the title/close row. Ignored while the popup is trigger-anchored
+     * (only stamped when {@link isFullscreen} is `true`), so anchored popups are
+     * byte-identical whether or not the slot is supplied.
+     */
+    protected readonly headerContentRef: _angular_core.Signal<MlvPopupHeaderContent | undefined>;
+    /**
+     * @protected Optional pinned-chrome template projected via
+     * `[mlvPopupPinnedContent]`. Rendered in **every** mode, directly above
+     * `.mlv-popup__scrollbar`, so it never scrolls with the content (in
+     * full-screen it sits below the header). An absent slot stamps nothing —
+     * byte-identical markup to a popup that never declared one.
+     */
+    protected readonly pinnedContentRef: _angular_core.Signal<MlvPopupPinnedContent | undefined>;
+    /** @internal Emits when the leave animation finishes so the container can dispose the overlay. */
+    readonly leaveAnimationDone$: Subject<void>;
+    /**
+     * @private Fallback timer guaranteeing `leaveAnimationDone$` fires even when
+     * the panel's `animationend` never arrives — `prefers-reduced-motion` strips
+     * the leave animation entirely, and hidden/background tabs throttle CSS
+     * animations indefinitely. Without it the overlay would never dispose.
+     * Mirrors `MlvOverlayRef`'s `_leaveFallbackMs` used by the drawer, and the
+     * dialog's `LEAVE_FALLBACK_MS`.
+     */
+    private _leaveFallbackTimer;
+    constructor();
+    readonly popupTemplate: _angular_core.Signal<TemplateRef<unknown>>;
+    /**
+     * Resolves the active CDK `ConnectedPosition[]` to pass to the overlay.
+     *
+     * **Position source** (first match wins):
+     * 1. `position` input — named position(s) looked up in `POPUP_POSITIONS` map.
+     * 2. `positions` input — raw CDK positions for advanced use.
+     * 3. All defaults — every position in the active `POPUP_POSITIONS` map.
+     *
+     * **`restrictPosition` modifier:**
+     * - `true` (default) — return the resolved positions as-is; CDK pushes the popup
+     *   if none fit.
+     * - `false` — append all remaining map positions (deduped by reference) after the
+     *   resolved ones so CDK can freely choose a fitting position.
+     */
+    resolvedPositions(): ConnectedPosition[];
+    buildSizeConfig(): MlvPopupSizeConfig;
+    onAnimationEnd(): void;
+    /**
+     * @internal Promotes a freshly attached panel from `'idle'` to `'enter'`.
+     *
+     * Overlay owners (`MlvPopupContainer`, `MlvPopupTrigger`, `MlvMenuTrigger`)
+     * call this from a microtask so the panel is in the DOM before the enter
+     * keyframes start. A close requested in the same tick as the attach already
+     * moved the state to `'leave'` by then, and overwriting it would strand the
+     * overlay: the leave keyframes never play, so no `animationend` arrives, and
+     * the write itself cancels the leave fallback timer — leaving no path back to
+     * a detach. Promote only from the exact state the attach left behind.
+     */
+    beginEnterAnimation(): void;
+    /**
+     * @protected Handles the full-screen header close button. Requests closure via
+     * the two-way `opened` model so the consumer's `afterClosed` (focus restore)
+     * and the container/trigger leave-animation machinery run — identical to the
+     * Escape / backdrop close path.
+     */
+    protected _onCloseClick(): void;
+    /**
+     * Derives `arrowEdge` and `arrowAlign` from a resolved CDK `ConnectedPosition`.
+     *
+     * Detection logic:
+     * - `overlayX='end'` + `originX='start'`  → popup is to the **left** of the trigger  → arrow on right edge
+     * - `overlayX='start'` + `originX='end'`  → popup is to the **right** of the trigger → arrow on left edge
+     * - `overlayY='top'` (all other cases)   → popup is **below** the trigger           → arrow on top edge
+     * - `overlayY='bottom'` (all other cases) → popup is **above** the trigger           → arrow on bottom edge
+     *
+     * For left/right arrows the vertical alignment is read from `overlayY`
+     * (`'top'` → `'start'`, `'center'` → `'center'`, `'bottom'` → `'end'`).
+     * For top/bottom arrows the horizontal alignment comes directly from `overlayX`.
+     */
+    updateArrowFromPosition(pair: ConnectedPosition): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvPopup, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvPopup, "mlv-popup", never, { "position": { "alias": "position"; "required": false; "isSignal": true; }; "positions": { "alias": "positions"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; "height": { "alias": "height"; "required": false; "isSignal": true; }; "minWidth": { "alias": "minWidth"; "required": false; "isSignal": true; }; "minHeight": { "alias": "minHeight"; "required": false; "isSignal": true; }; "maxWidth": { "alias": "maxWidth"; "required": false; "isSignal": true; }; "maxHeight": { "alias": "maxHeight"; "required": false; "isSignal": true; }; "hasArrow": { "alias": "hasArrow"; "required": false; "isSignal": true; }; "hasShadow": { "alias": "hasShadow"; "required": false; "isSignal": true; }; "class": { "alias": "class"; "required": false; "isSignal": true; }; "mlvDensity": { "alias": "mlvDensity"; "required": false; "isSignal": true; }; "flexibleDimensions": { "alias": "flexibleDimensions"; "required": false; "isSignal": true; }; "scrollStrategy": { "alias": "scrollStrategy"; "required": false; "isSignal": true; }; "hasBackdrop": { "alias": "hasBackdrop"; "required": false; "isSignal": true; }; "restrictPosition": { "alias": "restrictPosition"; "required": false; "isSignal": true; }; "panelRole": { "alias": "panelRole"; "required": false; "isSignal": true; }; "modal": { "alias": "modal"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "dismissExcludeElements": { "alias": "dismissExcludeElements"; "required": false; "isSignal": true; }; "mobileMode": { "alias": "mobileMode"; "required": false; "isSignal": true; }; "mobileBreakpoint": { "alias": "mobileBreakpoint"; "required": false; "isSignal": true; }; "mobileTitle": { "alias": "mobileTitle"; "required": false; "isSignal": true; }; "mobileCloseLabel": { "alias": "mobileCloseLabel"; "required": false; "isSignal": true; }; "opened": { "alias": "opened"; "required": false; "isSignal": true; }; }, { "opened": "openedChange"; "afterOpened": "afterOpened"; "afterClosed": "afterClosed"; }, ["contentRef", "headerContentRef", "pinnedContentRef"], never, true, never>;
+}
+
+type MlvPopupTriggerType = 'click' | 'hover' | 'focus';
+declare class MlvPopupTrigger implements OnDestroy {
+    /** @private Low-level overlay API used in standalone mode. */
+    private readonly _popupService;
+    /** @private Host element ref used as the overlay anchor. */
+    private readonly _elementRef;
+    /** @private View container used to instantiate the popup template portal. */
+    private readonly _vcr;
+    /** @private Zone used to re-enter Angular after out-of-zone hover timers. */
+    private readonly _ngZone;
+    /**
+     * Optional injection of a parent {@link MlvPopupContainer}.
+     *
+     * When present the trigger operates in **container mode**: it delegates
+     * open/close/toggle to the container instead of creating its own overlay,
+     * and registers its host element as the visual anchor.
+     *
+     * When absent the trigger operates in **standalone mode** and manages the
+     * overlay lifecycle itself (legacy behaviour).
+     */
+    private readonly _container;
+    /** @private The active overlay handle in standalone mode, or `null` when closed. */
+    private _handle;
+    /** @private Guards against re-triggering the leave animation while already closing. */
+    private _closing;
+    /** @private Subscription to the popup's leave-animation-done stream. */
+    private _leaveSubscription;
+    /** @private Pending hover-close timer handle, or `null` when none is scheduled. */
+    private _hoverCloseTimer;
+    /**
+     * @private Last-resort timer that force-detaches an overlay whose leave never
+     * completed — without it a lost `animationState` write latches `_closing`
+     * with no path back to a detach.
+     */
+    private _detachWatchdog;
+    /** @private Teardown callbacks for the overlay hover mouse listeners. */
+    private _overlayMouseListeners;
+    /**
+     * The `MlvPopup` to control.
+     *
+     * **Standalone mode** (no parent `mlv-popup-container`): must be bound to the
+     * target `<mlv-popup>` element: `[mlvPopupTrigger]="myPopup"`.
+     *
+     * **Container mode** (inside `mlv-popup-container`): can be used as a bare
+     * attribute (`mlvPopupTrigger`) without a value — the container already holds
+     * the popup reference and orchestrates the overlay. The empty-string value from
+     * the bare attribute is coerced to `undefined` by the transform.
+     */
+    readonly mlvPopupTrigger: _angular_core.InputSignalWithTransform<MlvPopup | undefined, string | MlvPopup | undefined>;
+    /** One or more event types that open the popup. Defaults to `'click'`. */
+    readonly triggerOn: _angular_core.InputSignal<MlvPopupTriggerType | MlvPopupTriggerType[]>;
+    /**
+     * Value applied to the trigger's `aria-haspopup` attribute. Should match the
+     * semantic role of the popup panel's content — e.g. `'menu'` for a menu
+     * flyout, `'listbox'` for a select, `'dialog'` for a modal surface. Defaults
+     * to `'dialog'` for backwards compatibility. Set to `null` to omit the
+     * attribute entirely (e.g. for a tooltip-only popup).
+     */
+    readonly ariaHasPopup: _angular_core.InputSignal<string | null>;
+    /** @protected Whether the associated popup is currently open. */
+    protected readonly _isOpen: _angular_core.Signal<boolean>;
+    constructor();
+    open(): void;
+    close(): void;
+    toggle(): void;
+    ngOnDestroy(): void;
+    onClick(): void;
+    onMouseEnter(): void;
+    onMouseLeave(): void;
+    onFocus(): void;
+    onBlur(): void;
+    hasTrigger(type: MlvPopupTriggerType): boolean;
+    /** @private Schedules a delayed close after the pointer leaves the trigger. */
+    private _scheduleHoverClose;
+    /** @private Cancels any pending hover-close timer. */
+    private _clearHoverTimer;
+    /** @private Creates the CDK overlay and plays the enter animation (standalone mode). */
+    private _attachOverlay;
+    /** @private Wires hover enter/leave listeners on the overlay panel to keep it open on hover. */
+    private _addOverlayMouseListeners;
+    /** @private Removes the overlay hover listeners. */
+    private _removeOverlayMouseListeners;
+    /** @private Triggers the popup leave animation before detaching the overlay. */
+    private _startLeaveAnimation;
+    /** @private Tears down the overlay, its subscriptions, and pending timers. */
+    private _detachOverlay;
+    /**
+     * @private Arms the force-detach timer for the pending leave. Detaching is
+     * what resets `_closing` and `_handle`, so a leave that never completes must
+     * still end in a detach or the trigger latches permanently.
+     */
+    private _armDetachWatchdog;
+    /** @private Cancels a pending force-detach timer. */
+    private _clearDetachWatchdog;
+    /** @private Unsubscribes from the leave-animation-done stream. */
+    private _cleanupSubscription;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvPopupTrigger, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvPopupTrigger, "[mlvPopupTrigger]", ["mlvPopupTrigger"], { "mlvPopupTrigger": { "alias": "mlvPopupTrigger"; "required": false; "isSignal": true; }; "triggerOn": { "alias": "triggerOn"; "required": false; "isSignal": true; }; "ariaHasPopup": { "alias": "ariaHasPopup"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Interface implemented by {@link MlvPopupContainer}.
+ *
+ * Injected by {@link MlvPopupTrigger} when it detects a parent container,
+ * enabling the trigger to delegate lifecycle management without needing an explicit
+ * `[mlvPopupTrigger]` binding.
+ */
+interface MlvPopupContainerRef {
+    /** Open the popup. */
+    open(): void;
+    /** Close the popup. */
+    close(): void;
+    /** Toggle the popup open/closed. */
+    toggle(): void;
+    /** Returns whether the popup is currently open. */
+    isOpen?(): boolean;
+    /**
+     * Called by a child `MlvPopupTrigger` to register its host element as the
+     * visual anchor for the overlay and to indicate whether a backdrop should be used.
+     *
+     * @param origin     — The trigger element used as the CDK overlay origin.
+     * @param hasBackdrop — `false` for hover triggers (no transparent backdrop needed).
+     */
+    registerTrigger(origin: ElementRef, hasBackdrop: boolean): void;
+}
+/**
+ * Injection token for the nearest `MlvPopupContainer`.
+ *
+ * Used by `MlvPopupTrigger` to detect container mode and delegate
+ * open/close/toggle calls without creating a conflicting overlay.
+ */
+declare const POPUP_CONTAINER: InjectionToken<MlvPopupContainerRef>;
+
+declare class MlvPopupContainer implements OnDestroy, MlvPopupContainerRef {
+    /** @private Low-level popup overlay service used to open/close the CDK overlay. */
+    private readonly _popupService;
+    /** @private View container used as the anchor for the popup's template portal. */
+    private readonly _vcr;
+    /** @private Host element reference, used as the overlay origin when no trigger is registered. */
+    private readonly _elementRef;
+    /** @private Handle to the currently-open overlay, or `null` when closed. */
+    private _handle;
+    /** @private True while the leave animation is playing, before the overlay detaches. */
+    private _closing;
+    /** @private Subscription to the popup's leave-animation-done stream. */
+    private _leaveSubscription;
+    /**
+     * @private Last-resort timer that force-detaches an overlay whose leave never
+     * completed. The popup's own animation fallback normally gets there first;
+     * this one also covers a lost `animationState` write, which would otherwise
+     * latch `_closing` with no path back to a detach.
+     */
+    private _detachWatchdog;
+    /** @private Origin registered by a child `MlvPopupTrigger`, if any. */
+    private _triggerOrigin;
+    /** @private Backdrop preference registered by a child `MlvPopupTrigger`. */
+    private _hasBackdrop;
+    readonly popup: _angular_core.Signal<MlvPopup>;
+    /**
+     * Called by a child {@link MlvPopupTrigger} to register its host element
+     * as the visual anchor for the CDK overlay.
+     */
+    registerTrigger(origin: ElementRef, hasBackdrop: boolean): void;
+    constructor();
+    open(): void;
+    close(): void;
+    toggle(): void;
+    /** Returns whether the popup is currently open. */
+    isOpen(): boolean;
+    ngOnDestroy(): void;
+    /** @private Opens the CDK overlay for the popup and subscribes to its leave-animation completion. */
+    private _attachOverlay;
+    /** @private Marks the container as closing and triggers the popup's leave animation. */
+    private _startLeaveAnimation;
+    /** @private Cleans up subscriptions, timers, and closes the overlay handle. */
+    private _detachOverlay;
+    /**
+     * @private Arms the force-detach timer for the pending leave. Detaching is
+     * what resets `_closing` and `_handle`, so a leave that never completes must
+     * still end in a detach or the container latches permanently.
+     */
+    private _armDetachWatchdog;
+    /** @private Cancels a pending force-detach timer. */
+    private _clearDetachWatchdog;
+    /** @private Unsubscribes from and clears the leave-animation subscription. */
+    private _cleanupSubscription;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvPopupContainer, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvPopupContainer, "mlv-popup-container", never, {}, {}, ["popup"], ["*"], true, never>;
+}
+
+export { MENU_POSITIONS, MlvPopup, MlvPopupContainer, MlvPopupContent, MlvPopupHeaderContent, MlvPopupPinnedContent, MlvPopupPositionResolver, MlvPopupService, MlvPopupTrigger, POPUP_CONTAINER, POPUP_DETACH_WATCHDOG_MS, POPUP_LEAVE_FALLBACK_MS, POPUP_POSITIONS, POPUP_POSITION_MAP, SUBMENU_POSITIONS, providePopupPositions };
+export type { MlvPopupArrowAlign, MlvPopupArrowEdge, MlvPopupContainerRef, MlvPopupHandle, MlvPopupMobileMode, MlvPopupOpenConfig, MlvPopupPositionName, MlvPopupScrollStrategy, MlvPopupSizeConfig, MlvPopupTriggerType };