@malva-ui/core 0.1.12

package/popup/lib/popup/popup.d.ts

@@ -0,0 +1,343 @@
+import type { TemplateRef } from '@angular/core';
+import { Subject } from 'rxjs';
+import type { BooleanInput } from '@angular/cdk/coercion';
+import type { ConnectedPosition } from '@angular/cdk/overlay';
+import type { MlvBreakpoint } from '@malva-ui/cdk/utils';
+import type { MlvDensity } from '@malva-ui/cdk/density';
+import { MlvPopupContent } from '../popup-content';
+import { MlvPopupHeaderContent } from '../popup-header-content';
+import { MlvPopupPinnedContent } from '../popup-pinned-content';
+import type { MlvPopupScrollStrategy, MlvPopupSizeConfig } from '../popup.service';
+import type { MlvPopupPositionName } from '../popup-positions';
+import * as i0 from "@angular/core";
+export type MlvPopupArrowEdge = 'top' | 'bottom' | 'left' | 'right';
+export 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).
+ */
+export 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.
+ */
+export 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).
+ */
+export type MlvPopupMobileMode = 'auto' | 'fullscreen' | 'off';
+export 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: import("@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: import("@angular/core").InputSignal<ConnectedPosition[] | undefined>;
+    /** Explicit CSS width of the popup panel. */
+    readonly width: import("@angular/core").InputSignal<string | number | undefined>;
+    /** Explicit CSS height of the popup panel. */
+    readonly height: import("@angular/core").InputSignal<string | number | undefined>;
+    /** Minimum CSS width of the popup panel. */
+    readonly minWidth: import("@angular/core").InputSignal<string | number | undefined>;
+    /** Minimum CSS height of the popup panel. */
+    readonly minHeight: import("@angular/core").InputSignal<string | number | undefined>;
+    /** Maximum CSS width of the popup panel. */
+    readonly maxWidth: import("@angular/core").InputSignal<string | number | undefined>;
+    /** Maximum CSS height of the popup panel. */
+    readonly maxHeight: import("@angular/core").InputSignal<string | number | undefined>;
+    /** When `true`, a directional arrow is rendered pointing toward the trigger. */
+    readonly hasArrow: import("@angular/core").InputSignalWithTransform<boolean, BooleanInput>;
+    /** When `true` (default), a drop-shadow is applied to the popup panel. */
+    readonly hasShadow: import("@angular/core").InputSignalWithTransform<boolean, BooleanInput>;
+    /** Additional CSS classes forwarded to the popup panel host. */
+    readonly class: import("@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: import("@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: import("@angular/core").Signal<string>;
+    /** Allow the overlay panel to grow to fill available viewport space. */
+    readonly flexibleDimensions: import("@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: import("@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: import("@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: import("@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: import("@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: import("@angular/core").InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * Optional accessible name for the popup panel.
+     * Applied as `aria-label` on the popup element.
+     */
+    readonly ariaLabel: import("@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: import("@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: import("@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: import("@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: import("@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: import("@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: import("@angular/core").Signal<boolean>;
+    /** @protected Resolved accessible name for the full-screen close button. */
+    protected readonly _closeLabel: import("@angular/core").Signal<string>;
+    /** Two-way binding for the open/closed state. */
+    readonly opened: import("@angular/core").ModelSignal<boolean>;
+    /** Emitted after the popup enters the view and the enter animation completes. */
+    readonly afterOpened: import("@angular/core").OutputEmitterRef<void>;
+    /** Emitted after the popup leaves the view and the leave animation completes. */
+    readonly afterClosed: import("@angular/core").OutputEmitterRef<void>;
+    readonly animationState: import("@angular/core").WritableSignal<"enter" | "leave" | "idle">;
+    readonly arrowEdge: import("@angular/core").WritableSignal<MlvPopupArrowEdge>;
+    readonly arrowAlign: import("@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: import("@angular/core").Signal<"translateY(-4px)" | "translateY(4px)" | "translateX(-4px)" | "translateX(4px)">;
+    /** @protected Projected popup content template, rendered into the overlay panel. */
+    protected readonly contentRef: import("@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: import("@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: import("@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: import("@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: i0.ɵɵFactoryDeclaration<MlvPopup, never>;
+    static ɵcmp: i0.ɵɵ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>;
+}

package/popup/lib/popup-container/popup-container.d.ts

@@ -0,0 +1,61 @@
+import type { OnDestroy } from '@angular/core';
+import { ElementRef } from '@angular/core';
+import { MlvPopup } from '../popup/popup';
+import type { MlvPopupContainerRef } from './popup-container.token';
+import * as i0 from "@angular/core";
+export 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: import("@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: i0.ɵɵFactoryDeclaration<MlvPopupContainer, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MlvPopupContainer, "mlv-popup-container", never, {}, {}, ["popup"], ["*"], true, never>;
+}

package/popup/lib/popup-container/popup-container.token.d.ts

@@ -0,0 +1,34 @@
+import type { ElementRef } from '@angular/core';
+import { InjectionToken } from '@angular/core';
+/**
+ * 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.
+ */
+export 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.
+ */
+export declare const POPUP_CONTAINER: InjectionToken<MlvPopupContainerRef>;

package/popup/lib/popup-content.d.ts

@@ -0,0 +1,6 @@
+import { MlvStructural } from '@malva-ui/cdk/utils';
+import * as i0 from "@angular/core";
+export declare class MlvPopupContent extends MlvStructural {
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvPopupContent, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MlvPopupContent, "[mlvPopupContent]", never, {}, {}, never, never, true, never>;
+}

package/popup/lib/popup-header-content.d.ts

@@ -0,0 +1,18 @@
+import { MlvStructural } from '@malva-ui/cdk/utils';
+import * as i0 from "@angular/core";
+/**
+ * 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.
+ */
+export declare class MlvPopupHeaderContent extends MlvStructural {
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvPopupHeaderContent, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MlvPopupHeaderContent, "[mlvPopupHeaderContent]", never, {}, {}, never, never, true, never>;
+}

package/popup/lib/popup-pinned-content.d.ts

@@ -0,0 +1,17 @@
+import { MlvStructural } from '@malva-ui/cdk/utils';
+import * as i0 from "@angular/core";
+/**
+ * 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.
+ */
+export declare class MlvPopupPinnedContent extends MlvStructural {
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvPopupPinnedContent, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MlvPopupPinnedContent, "[mlvPopupPinnedContent]", never, {}, {}, never, never, true, never>;
+}

package/popup/lib/popup-positions.d.ts

@@ -0,0 +1,105 @@
+import type { Provider } from '@angular/core';
+import { InjectionToken } from '@angular/core';
+import type { ConnectedPosition } from '@angular/cdk/overlay';
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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 }],
+ * ]))
+ * ```
+ */
+export 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 }],
+ *   ]))
+ * ]
+ * ```
+ */
+export 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.
+ */
+export 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`.
+ */
+export 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`.
+ */
+export declare const SUBMENU_POSITIONS: ConnectedPosition[];