@malva-ui/core 0.1.13 → 0.1.14

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

@@ -0,0 +1,954 @@
+import * as _angular_core from '@angular/core';
+import { TemplateRef, WritableSignal, ElementRef, InjectionToken, Signal, OutputEmitterRef, ViewContainerRef, NgZone } from '@angular/core';
+import { MlvPopup, MlvPopupService } from '@malva-ui/core/popup';
+import { MlvDensity } from '@malva-ui/cdk/density';
+import { Observable } from 'rxjs';
+import { MlvDataSource } from '@malva-ui/cdk/data-source';
+import { FocusableOption } from '@angular/cdk/a11y';
+import { BooleanInput } from '@angular/cdk/coercion';
+
+/** Serializable item data consumed by reactive menus. */
+interface MlvMenuItemData<T = unknown> {
+    /** Stable item identifier used for tracking and selection. */
+    readonly id: string | number;
+    /** Visible label rendered for the menu item. */
+    readonly label: string;
+    /** Optional consumer-owned payload associated with the item. */
+    readonly data?: T;
+    /** Whether the item is present but not interactive. */
+    readonly disabled?: boolean;
+    /** Optional lazy child stream for submenu items. */
+    readonly children?: Observable<MlvMenuItemData<T>[]>;
+}
+/** Menu item collections accepted by the reactive menu APIs. */
+type MlvMenuDataSource<T> = T[] | MlvDataSource<T>;
+/** Divider row data used by menubars that mix items and separators. */
+interface MlvMenubarDividerData {
+    /** Discriminator for separator entries. */
+    readonly kind: 'divider';
+    /** Stable divider identifier used for tracking. */
+    readonly id: string | number;
+}
+/** One menubar row entry: an item or a visual divider. */
+type MlvMenubarEntry<TItem> = TItem | MlvMenubarDividerData;
+/** Context exposed to a custom `[mlvMenuItemDef]` template. */
+interface MlvMenuItemDefContext<T> {
+    /** The rendered item data for the current row. */
+    $implicit: T;
+    /** Zero-based item index within the rendered collection. */
+    index: number;
+    /** Whether the item currently advertises a child menu. */
+    hasChildren: boolean;
+    /** Whether child items are still loading for this row. */
+    loading: boolean;
+}
+
+/** Marks a custom template for rendering reactive menu items. */
+declare class MlvMenuItemDef<T extends MlvMenuItemData<unknown> = MlvMenuItemData<unknown>> {
+    /** The template reference used for each rendered menu row. */
+    readonly templateRef: TemplateRef<any>;
+    /** Type guard so `let-` variables infer from `MlvMenuItemDefContext<T>`. */
+    static ngTemplateContextGuard<T extends MlvMenuItemData<unknown>>(_directive: MlvMenuItemDef<T>, _context: unknown): _context is MlvMenuItemDefContext<T>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvMenuItemDef<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvMenuItemDef<any>, "[mlvMenuItemDef]", never, {}, {}, never, never, true, never>;
+}
+
+/** Internal item shape the menu key manager navigates across. */
+interface MenuKeyItem {
+    readonly disabledBoolean: boolean;
+    readonly _tabIndex: WritableSignal<number>;
+    readonly _elementRef?: ElementRef<HTMLElement>;
+    focus(): void;
+    getLabel(): string;
+}
+
+/**
+ * Interface that a menu exposes to its child `MenuItemComponent` instances.
+ * Used via the `MENU_TOKEN` injection token for decoupled parent–child communication.
+ */
+interface MlvMenuAccessor {
+    /** Closes this menu panel. */
+    close(): void;
+    /** Closes this menu panel and any ancestor menu panels. */
+    closeAll(): void;
+}
+/** Injection token for the parent menu. */
+declare const MENU_TOKEN: InjectionToken<MlvMenuAccessor>;
+/** Internal data-row controller injected into generated `mlvMenuItem` views. */
+interface MlvMenuDataItemContext {
+    /** Whether the generated row currently owns a submenu. */
+    hasChildren(): boolean;
+    /** Whether the submenu's first child payload is still loading. */
+    loading(): boolean;
+    /** Whether the submenu overlay is currently open. */
+    isOpen(): boolean;
+    /** Stable submenu panel id used for `aria-controls`. */
+    panelId(): string | null;
+    /** Whether the generated row should be treated as disabled. */
+    isDisabled(): boolean;
+    /** Opens the generated submenu. */
+    open(): void;
+    /** Closes the generated submenu. */
+    close(): void;
+    /** Toggles the generated submenu. */
+    toggle(): void;
+    /** Opens the submenu and focuses its first enabled child row. */
+    openWithFirstItemFocused(): void;
+    /** Opens the submenu and focuses its last enabled child row. */
+    openWithLastItemFocused(): void;
+    /** Delegates pointer entry to the shared submenu controller. */
+    onMouseEnter(): void;
+    /** Delegates pointer exit to the shared submenu controller. */
+    onMouseLeave(event: MouseEvent): void;
+}
+/** Internal injector token for generated menu-row submenu behaviour. */
+declare const MLV_MENU_DATA_ITEM: InjectionToken<MlvMenuDataItemContext>;
+
+/** Data source accepted by a data-driven menubar. */
+type MlvMenubarDataSource<TItem extends MlvMenuItemData<unknown> = MlvMenuItemData<unknown>> = MlvMenubarEntry<TItem>[] | MlvDataSource<MlvMenubarEntry<TItem>>;
+/**
+ * The subset of the `MlvMenuTrigger` API a `mlv-menubar` needs to
+ * coordinate its top-level items (roving tabindex, arrow navigation, and the
+ * "open-follow" behaviour where moving to a sibling while a menu is open opens
+ * that sibling's menu).
+ *
+ * `MlvMenuTrigger` implements this shape at runtime when it is a direct
+ * child of a `mlv-menubar` (i.e. it can inject {@link MENUBAR_TOKEN}).
+ */
+interface MlvMenubarItem extends FocusableOption {
+    /** Optional host element used to keep registry order aligned with the DOM. */
+    readonly _elementRef?: ElementRef<HTMLElement>;
+    /** Whether this top-level item is disabled — used by the bar's `skipPredicate`. */
+    readonly disabledBoolean: boolean;
+    /**
+     * Roving tabindex signal for this item — `0` for the currently active item,
+     * `-1` for every other item. Written by the parent `mlv-menubar`.
+     */
+    readonly _tabIndex: WritableSignal<number>;
+    /** Whether this item's dropdown menu is currently open. */
+    isMenuOpen(): boolean;
+    /** Opens this item's dropdown without moving focus into the panel. */
+    openMenu(): void;
+    /** Closes this item's dropdown. */
+    closeMenu(): void;
+    /** Opens this item's dropdown and moves focus to the first menu item. */
+    openMenuWithFirstItemFocused(): void;
+    /** Opens this item's dropdown and moves focus to the last menu item. */
+    openMenuWithLastItemFocused(): void;
+    /** Returns the item's visible text label, used for menubar type-ahead. */
+    getLabel(): string;
+}
+/**
+ * Accessor a `mlv-menubar` exposes to its child triggers via {@link MENUBAR_TOKEN}.
+ * Child triggers use it to report open/close state and to request sibling-menu
+ * navigation, without importing the concrete `MlvMenubar`.
+ */
+interface MlvMenubarAccessor {
+    /**
+     * Host element of the menubar. Passed to `MlvPopupService` as a click-outside
+     * exclusion so that clicking a sibling top-level item switches menus instead
+     * of dismissing the open dropdown.
+     */
+    readonly hostElement: HTMLElement;
+    /**
+     * Called by a child when its dropdown opens. The bar records the open item,
+     * closes any previously-open sibling, and syncs the roving tabindex.
+     */
+    notifyItemOpened(item: MlvMenubarItem): void;
+    /** Called by a child when its dropdown closes. */
+    notifyItemClosed(item: MlvMenubarItem): void;
+    /**
+     * Called on `mouseenter` of a child. Opens the hovered item's dropdown **only
+     * while another dropdown in the bar is already open** (hover-follow); does
+     * nothing when the bar is fully closed.
+     */
+    onItemPointerEnter(item: MlvMenubarItem): void;
+    /** Whether any dropdown in the bar is currently open. */
+    hasOpenMenu(): boolean;
+    /**
+     * Moves to the item adjacent to `from` (wrapping over disabled items) and
+     * opens its dropdown with focus on the first item. Called from within an open
+     * dropdown on ArrowRight (`dir = 1`) or ArrowLeft (`dir = -1`) to cross to a
+     * sibling menubar menu.
+     */
+    openAdjacentItemMenu(from: MlvMenubarItem, dir: 1 | -1): void;
+}
+/**
+ * Controller a menubar dropdown uses to cross to a sibling menubar menu when
+ * ArrowRight / ArrowLeft is pressed at the top level of the open dropdown.
+ * Registered on the `MlvMenu` by the opening `MlvMenuTrigger` when
+ * (and only when) that trigger is a menubar child.
+ */
+interface MlvMenubarMenuController {
+    /** Cross to the next menubar item's menu (in-menu ArrowRight). */
+    openNextItemMenu(): void;
+    /** Cross to the previous menubar item's menu (in-menu ArrowLeft). */
+    openPreviousItemMenu(): void;
+}
+/** Injection token for the parent `mlv-menubar`. */
+declare const MENUBAR_TOKEN: InjectionToken<MlvMenubarAccessor>;
+
+/**
+ * Dropdown menu panel (`mlv-menu`).
+ *
+ * Renders a `role="menu"` panel containing `mlv-menu-item`, `mlv-menu-separator`,
+ * and `mlv-menu-group` children. Manages keyboard navigation (ArrowUp, ArrowDown,
+ * Home, End, Escape) via `FocusKeyManager`.
+ *
+ * The menu uses `mlv-popup` for visual chrome (background, border, radius, shadow,
+ * animations). The panel is rendered inside the popup's content template via
+ * `[mlvPopupContent]`, so no DOM manipulation is required.
+ *
+ * @example
+ * ```html
+ * <button [mlvMenuTrigger]="myMenu">Open</button>
+ * <mlv-menu #myMenu>
+ *   <mlv-menu-item (itemClick)="onEdit()">Edit</mlv-menu-item>
+ *   <mlv-menu-separator />
+ *   <mlv-menu-item (itemClick)="onDelete()">Delete</mlv-menu-item>
+ * </mlv-menu>
+ * ```
+ */
+declare class MlvMenu<TItem extends MlvMenuItemData<unknown> = MlvMenuItemData<unknown>> implements MlvMenuAccessor {
+    /**
+     * @private Element reference for the host element.
+     */
+    readonly _elementRef: ElementRef<any>;
+    private readonly _itemRegistry;
+    private readonly _dataSourceAdapter;
+    /**
+     * @private The popup component managing the overlay chrome (background, border, shadow, animations).
+     * Accessed by `MlvMenuTrigger` to open the overlay and manage animation state.
+     * The menu panel (`mlv-list`) is declared inside this popup's `[mlvPopupContent]` template.
+     */
+    readonly _popup: _angular_core.Signal<MlvPopup>;
+    private readonly _projectedItems;
+    /** @protected The projected row definition used by data-driven rendering. */
+    protected readonly _itemDef: _angular_core.Signal<MlvMenuItemDef<any> | undefined>;
+    /** @protected All registered menu items, in render order. */
+    protected readonly _items: _angular_core.Signal<readonly MenuKeyItem[]>;
+    /** @protected Items currently rendered in this menu panel. */
+    protected readonly _navigationItems: _angular_core.Signal<readonly MenuKeyItem[]>;
+    /**
+     * Accessible label for the menu panel (`aria-label`).
+     * Use when there is no visible heading that labels the menu.
+     */
+    readonly label: _angular_core.InputSignal<string>;
+    /**
+     * Density applied to the menu panel's item rows.
+     *
+     * The panel is portaled to the CDK overlay container, outside the trigger's
+     * DOM tree, so ancestor density classes cannot cascade into it. Forwarded to
+     * the underlying `mlv-popup`, which stamps the resolved `mlv--{density}`
+     * class on the detached panel. When omitted, the global `MlvDensityService`
+     * density applies. Submenus are separate `mlv-menu` instances — set the
+     * input on each when overriding the density of a nested menu tree.
+     */
+    readonly mlvDensity: _angular_core.InputSignal<MlvDensity | undefined>;
+    /**
+     * Optional data source for this menu. Arrays render immediately; an
+     * `MlvDataSource` supplies the current collection and loading state.
+     */
+    readonly dataSource: _angular_core.InputSignal<MlvMenuDataSource<TItem> | undefined>;
+    /**
+     * Stable DOM id of the menu panel (`role="menu"` list). Consumed by
+     * `MlvMenuTrigger` to wire `aria-controls` from the trigger to the panel.
+     */
+    readonly panelId: string;
+    /**
+     * Emits when the menu requests to be closed (e.g., Escape key, Tab key,
+     * or after a menu item is activated).
+     */
+    readonly closed: _angular_core.OutputEmitterRef<void>;
+    /**
+     * @private Whether the panel is currently open. Set by `MlvMenuTrigger`.
+     */
+    readonly _isOpen: _angular_core.WritableSignal<boolean>;
+    /** @protected Whether this menu is using data-driven rather than projected content. */
+    protected readonly _dataMode: _angular_core.Signal<boolean>;
+    /** @protected Current data-driven items normalized from the active source. */
+    protected readonly _dataSourceItems: _angular_core.Signal<TItem[]>;
+    /** @protected Current loading state normalized from the active source. */
+    protected readonly _dataSourceLoading: _angular_core.Signal<boolean>;
+    /**
+     * @private Parent menu that opened this menu as a submenu.
+     */
+    private _parentMenu;
+    /**
+     * @private Controller supplied by the opening `MlvMenuTrigger` when this
+     * menu is a top-level menubar dropdown. Enables ArrowRight / ArrowLeft at the
+     * top level of the panel to cross to the adjacent menubar menu. `null` for
+     * standalone menus and submenus.
+     */
+    private _menubarController;
+    /** @private Normalizes horizontal menu navigation for RTL layouts. */
+    private readonly _rtlService;
+    /**
+     * @private `FocusKeyManager` managing the menu items.
+     * Initialized lazily when items are first available.
+     */
+    private _keyManager;
+    /**
+     * @private Subscription to the key manager's `change` stream, used to keep the
+     * roving tabindex in sync when type-ahead moves the active item asynchronously.
+     */
+    private _changeSub;
+    /**
+     * @private Snapshot of the items the current `_keyManager` was built from.
+     * Compared member-by-member so a change-detection pass that re-runs the content
+     * query without changing the projected items does not rebuild the manager —
+     * a rebuild resets `activeItemIndex` and would wipe the roving tabindex.
+     */
+    private _managedItems;
+    /** @private The last menu item that received focus, retained across row removal. */
+    private _focusedItem;
+    constructor();
+    /**
+     * Focuses the first non-disabled item in the menu.
+     * Called by `MlvMenuTrigger` when the menu opens via keyboard ArrowDown or Enter.
+     */
+    focusFirstItem(): void;
+    /**
+     * Focuses the last non-disabled item in the menu.
+     * Called by `MlvMenuTrigger` when the menu opens via keyboard ArrowUp.
+     */
+    focusLastItem(): void;
+    /**
+     * Closes the menu panel by emitting the `closed` output.
+     * Called by `MlvMenuItem` after item activation and by the keyboard handler.
+     */
+    close(): void;
+    /**
+     * Closes this menu panel and any ancestor menu panels.
+     * Called by submenu items so selecting a nested action dismisses the full menu stack.
+     */
+    closeAll(): void;
+    /**
+     * Registers the parent menu that owns this menu when it is opened as a submenu.
+     * Called by `MlvMenuTrigger` while opening submenu overlays.
+     */
+    registerParentMenu(parentMenu: MlvMenuAccessor | null): void;
+    /**
+     * Registers (or clears) the menubar controller when this menu is opened as a
+     * top-level menubar dropdown. Called by `MlvMenuTrigger` while opening.
+     */
+    registerMenubarController(controller: MlvMenubarMenuController | null): void;
+    /**
+     * @protected Routes keydown events to `FocusKeyManager` and handles Escape / Tab.
+     */
+    protected _onKeydown(event: KeyboardEvent): void;
+    /** @protected Remembers item focus before a live data update can remove its row. */
+    protected _onFocusIn(event: FocusEvent): void;
+    /**
+     * @private Reconciles the `FocusKeyManager` with the projected items.
+     *
+     * No-ops when the item set is unchanged — rebuilding a manager throws away its
+     * `activeItemIndex`, which is what previously broke arrow navigation. When the
+     * set really did change the manager is replaced and the active item carried
+     * over, so the roving tabindex survives adding or removing an item.
+     */
+    private _syncKeyManager;
+    /**
+     * @private Creates the `FocusKeyManager` for `items`.
+     * Skips items whose `disabled` property is `true`.
+     *
+     * `withTypeAhead()` enables type-to-focus (press a letter to jump to the
+     * first matching item by its `getLabel()`). Type-ahead matching is debounced
+     * and can move the active item outside of `_onKeydown`, so the manager's
+     * `change` stream is used to keep the roving tabindex in sync.
+     */
+    private _initKeyManager;
+    /**
+     * @private Disposes the current key manager and its `change` subscription.
+     */
+    private _teardownKeyManager;
+    /**
+     * @private Carries the active item of the previous key manager over to a freshly
+     * built one, using `updateActiveItem()` so the roving tabindex is restored
+     * without stealing DOM focus. When the previously active item was removed (or
+     * became disabled) the nearest enabled item to its old position takes over.
+     * Does nothing when no item was active yet.
+     */
+    private _restoreActiveItem;
+    /**
+     * @private Updates `_tabIndex` on every item so that exactly one item has
+     * `tabindex="0"` (roving tabindex pattern) and all others have `-1`.
+     *
+     * That is the active item once keyboard navigation has started. Before then —
+     * a pointer-opened panel puts focus on the `role="menu"` list itself — the first
+     * enabled item is the tab stop, so the open menu is never entirely untabbable.
+     */
+    private _syncTabIndices;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvMenu<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvMenu<any>, "mlv-menu", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "mlvDensity": { "alias": "mlvDensity"; "required": false; "isSignal": true; }; "dataSource": { "alias": "dataSource"; "required": false; "isSignal": true; }; }, { "closed": "closed"; }, ["_projectedItems", "_itemDef"], ["*"], true, never>;
+}
+
+/**
+ * Menu item directive — applied to `mlv-list-item` to give it menu-item semantics
+ * and behavior.
+ *
+ * Overrides the list item's default `role="listitem"` with `role="menuitem"`,
+ * wires into the parent menu's `FocusKeyManager` (via `focus()` / `disabledBoolean`),
+ * and closes the parent menu stack on leaf activation. A co-hosted enabled
+ * submenu trigger owns its own activation so opening a child menu keeps the
+ * ancestor open; a disabled submenu trigger falls back to leaf activation.
+ *
+ * Use `[mlvListItemPrefix]` for leading icons and `[mlvListItemSuffix]` for
+ * trailing content (chevron, shortcut label, etc.).
+ *
+ * @example
+ * ```html
+ * <mlv-list-item mlvMenuItem (itemClick)="onSave()">Save</mlv-list-item>
+ *
+ * <mlv-list-item mlvMenuItem disabled>Unavailable</mlv-list-item>
+ *
+ * <mlv-list-item mlvMenuItem (itemClick)="onEdit()">
+ *   <svg mlvListItemPrefix lucideEdit [size]="14" />
+ *   Edit
+ * </mlv-list-item>
+ * ```
+ */
+declare class MlvMenuItem {
+    /** @private Normalizes horizontal submenu navigation for RTL layouts. */
+    private readonly _rtlService;
+    /** @private Reference to parent menu, if any. Used to close on activation. */
+    private readonly _menu;
+    private readonly _registry;
+    private readonly _renderer;
+    private readonly _dataItemContext;
+    private readonly _menubar;
+    /** @private A co-hosted submenu trigger owns activation instead of this leaf item. */
+    private readonly _submenuTrigger;
+    /** @private Host element used to call `focus()` for `FocusKeyManager`. */
+    readonly _elementRef: ElementRef<any>;
+    constructor();
+    /**
+     * When true, disables the item — removes it from the tab order and
+     * prevents activation. Supports attribute syntax: `<mlv-list-item mlvMenuItem disabled>`.
+     */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * Emits when a leaf item is activated (click or Enter/Space key).
+     * The parent menu stack closes automatically after this event. Submenu-trigger
+     * rows delegate activation to `MlvMenuTrigger` and do not emit this output
+     * while that trigger is enabled.
+     */
+    readonly itemClick: _angular_core.OutputEmitterRef<void>;
+    /**
+     * @private Tabindex managed by the parent menu's `FocusKeyManager`.
+     * `0` for the active (focused) item, `-1` for all others (roving tabindex).
+     * A signal so the host `[attr.tabindex]` binding updates under OnPush.
+     */
+    readonly _tabIndex: _angular_core.WritableSignal<number>;
+    /**
+     * Boolean getter for `FocusKeyManager.skipPredicate`.
+     * The key manager calls `item.disabledBoolean` so this bridges
+     * the signal API to the CDK interface.
+     */
+    get disabledBoolean(): boolean;
+    /**
+     * Focuses the host element.
+     * Required by CDK `FocusableOption` for `FocusKeyManager`.
+     */
+    focus(): void;
+    /**
+     * Returns the item's visible text label, used by the parent menu's
+     * `FocusKeyManager` type-ahead (type a letter to jump to the first matching
+     * item). Reads the host element's trimmed `textContent`.
+     * Required by CDK `FocusKeyManager.withTypeAhead()`.
+     */
+    getLabel(): string;
+    /**
+     * @protected Handles click activation.
+     */
+    protected _onClick(): void;
+    /**
+     * @protected Handles Enter / Space keyboard activation.
+     * Prevents default scroll on Space and triggers the same logic as a click.
+     */
+    protected _onActivate(event: Event): void;
+    /** @protected Delegates hover-open behavior for generated submenu rows. */
+    protected _onMouseEnter(): void;
+    /** @protected Delegates hover-close intent for generated submenu rows. */
+    protected _onMouseLeave(event: MouseEvent): void;
+    /** @protected Handles submenu keyboard opening for generated rows. */
+    protected _onKeydown(event: KeyboardEvent): void;
+    /** @private Whether a co-hosted trigger can handle submenu activation. */
+    private _enabledSubmenuOwnsActivation;
+    /** @private Whether this row is a generated submenu row without an explicit trigger. */
+    protected _hasAutomaticSubmenu(): boolean;
+    /** @private Whether this generated row is a root item of a reactive menubar. */
+    private _isMenubarDataItem;
+    /** @private Resolved disabled state from explicit input or generated row data. */
+    protected _isDisabled(): boolean;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvMenuItem, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvMenuItem, "mlv-list-item[mlvMenuItem]", never, { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, { "itemClick": "itemClick"; }, never, never, true, never>;
+}
+
+/**
+ * A visual separator between groups of menu items in a `mlv-menu`.
+ *
+ * Renders as a horizontal rule (`<hr role="separator">`) styled to match
+ * `mlv-divider` visual design.
+ *
+ * @example
+ * ```html
+ * <mlv-menu-item (itemClick)="onEdit()">Edit</mlv-menu-item>
+ * <mlv-menu-separator />
+ * <mlv-menu-item (itemClick)="onDelete()">Delete</mlv-menu-item>
+ * ```
+ */
+declare class MlvMenuSeparator {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvMenuSeparator, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvMenuSeparator, "mlv-menu-separator", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Marks an element as the label for a `mlv-menu-group`.
+ * The group applies `aria-labelledby` pointing to this element's generated id.
+ *
+ * @example
+ * ```html
+ * <mlv-menu-group>
+ *   <span mlvMenuGroupLabel>File actions</span>
+ *   <mlv-menu-item>Open</mlv-menu-item>
+ * </mlv-menu-group>
+ * ```
+ */
+declare class MlvMenuGroupLabel {
+    /**
+     * Stable DOM id applied to the label element so the parent
+     * `mlv-menu-group` can reference it via `aria-labelledby`.
+     */
+    readonly id: string;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvMenuGroupLabel, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvMenuGroupLabel, "[mlvMenuGroupLabel]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Groups related menu items with an optional label inside a `mlv-menu`.
+ *
+ * Use `[mlvMenuGroupLabel]` on a child element to provide an accessible label
+ * for the group. When present, the group's `role="group"` is named via
+ * `aria-labelledby` pointing at the label element.
+ *
+ * @example
+ * ```html
+ * <mlv-menu-group>
+ *   <span mlvMenuGroupLabel>File</span>
+ *   <mlv-menu-item (itemClick)="onNew()">New</mlv-menu-item>
+ *   <mlv-menu-item (itemClick)="onOpen()">Open</mlv-menu-item>
+ * </mlv-menu-group>
+ * ```
+ */
+declare class MlvMenuGroup {
+    /**
+     * @protected Projected `[mlvMenuGroupLabel]` element, if any. Its generated
+     * id names this group via `aria-labelledby`.
+     */
+    protected readonly _label: _angular_core.Signal<MlvMenuGroupLabel | undefined>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvMenuGroup, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvMenuGroup, "mlv-menu-group", never, {}, {}, ["_label"], ["*"], true, never>;
+}
+
+/**
+ * Structural menu surface required by the overlay controller.
+ *
+ * Keeping the overlay contract structural lets `MlvMenuTrigger` accept menus
+ * with any data item type without making the trigger itself generic.
+ */
+interface MlvMenuOverlayTarget extends MlvMenuAccessor {
+    readonly _popup: Signal<MlvPopup>;
+    readonly _isOpen: WritableSignal<boolean>;
+    readonly closed: OutputEmitterRef<void>;
+    readonly panelId: string;
+    registerParentMenu(parentMenu: MlvMenuAccessor | null): void;
+    registerMenubarController(controller: MlvMenubarMenuController | null): void;
+    focusFirstItem(): void;
+    focusLastItem(): void;
+}
+/** Configuration used by the shared menu overlay controller. */
+interface MlvMenuOverlayControllerConfig {
+    /** Resolves the menu panel opened by this controller. */
+    readonly getMenu: () => MlvMenuOverlayTarget;
+    /** Element from which the popup is positioned and to which focus returns. */
+    readonly origin: ElementRef<HTMLElement>;
+    /** View container used to instantiate the menu popup portal. */
+    readonly vcr: ViewContainerRef;
+    /** Parent menu accessor for submenu registration. */
+    readonly parentMenu: MlvMenuAccessor | null;
+    /** Parent menubar accessor for top-level coordination. */
+    readonly menubar: MlvMenubarAccessor | null;
+    /** Whether the current trigger is configured as a submenu trigger. */
+    readonly isSubmenu: () => boolean;
+    /** Whether the current trigger is a direct child of a menubar. */
+    readonly isMenubarChild: boolean;
+    /** Resolves the current disabled state. */
+    readonly isDisabled: () => boolean;
+    /** Returns the menubar item represented by the trigger. */
+    readonly getMenubarItem: () => MlvMenubarItem;
+    /** Requests closure through the owning trigger façade when available. */
+    readonly requestClose?: () => void;
+    /** Called after the popup has been opened. */
+    readonly onOpened?: () => void;
+    /** Called after the popup has been fully closed. */
+    readonly onClosed?: () => void;
+}
+/**
+ * Owns the common popup, focus restoration, and submenu hover-intent lifecycle
+ * used by explicit and data-generated menu triggers.
+ */
+declare class MlvMenuOverlayController {
+    private readonly _config;
+    /** Whether the controlled menu overlay is currently open. */
+    readonly isOpen: WritableSignal<boolean>;
+    private readonly _popupService;
+    private readonly _ngZone;
+    private readonly _destroyRef;
+    private _overlayRef;
+    private _openSubscriptions;
+    private _triangleState;
+    private _closeTimer;
+    private _mousemoveCleanup;
+    private _destroyed;
+    constructor(_config: MlvMenuOverlayControllerConfig, dependencies?: {
+        readonly popupService?: MlvPopupService;
+        readonly ngZone?: NgZone;
+    });
+    /** Opens the menu overlay unless it is already open or disabled. */
+    open(): void;
+    /** Closes the menu overlay when it is open. */
+    close(): void;
+    /** Toggles the controlled menu overlay. */
+    toggle(): void;
+    /** Opens the menu and focuses its first enabled item. */
+    openWithFirstItemFocused(): void;
+    /** Opens the menu and focuses its last enabled item. */
+    openWithLastItemFocused(): void;
+    /** Handles pointer entry for menubar and submenu triggers. */
+    onMouseEnter(): void;
+    /** Handles pointer exit for submenu triggers using triangle intent. */
+    onMouseLeave(event: MouseEvent): void;
+    /** Cleans up listeners and disposes the controlled overlay. */
+    destroy(): void;
+    private _restoreFocusToTrigger;
+    private _closeOverlay;
+    private _setupSubmenuTracking;
+    private _installSubmenuOverlayListeners;
+    private _installMousemoveListener;
+    private _isPointerOnSiblingItem;
+    private _removeMousemoveListener;
+    private _scheduleClose;
+    private _clearCloseTimer;
+}
+
+/**
+ * Trigger directive for `mlv-menu`.
+ *
+ * Attach to any element to open a `mlv-menu` panel on click. Uses `MlvPopupService`
+ * from `@malva-ui/core/popup` to create the CDK overlay with the popup component's
+ * template for visual chrome (background, border, radius, shadow, animations).
+ * The menu panel and items are declared inside `[mlvPopupContent]` in the menu's
+ * template and are rendered directly into the overlay — no DOM manipulation required.
+ *
+ * When used as a submenu trigger (`[isSubmenuTrigger]="true"`), the panel opens on
+ * mouseenter and the triangle-pointer-tracking algorithm keeps it open while the
+ * cursor moves diagonally toward it.
+ *
+ * Hover intent is resolved by what the pointer is over, with geometry used only
+ * for the ambiguous space between item and panel:
+ * - over the trigger item — stays open, whatever the trajectory;
+ * - over a different row of the same menu — closes;
+ * - in between (including the 8px `SUBMENU_POSITIONS` gap) — the safe cone
+ *   decides, and a short grace timer absorbs jitter and gap crossings.
+ *
+ * Once the cursor enters the submenu panel, triangle tracking stops and the
+ * panel's own `mouseleave` schedules the close.
+ *
+ * @example Simple trigger
+ * ```html
+ * <button [mlvMenuTrigger]="menu">Open menu</button>
+ * <mlv-menu #menu>
+ *   <mlv-menu-item (itemClick)="onEdit()">Edit</mlv-menu-item>
+ *   <mlv-menu-separator />
+ *   <mlv-menu-item (itemClick)="onDelete()">Delete</mlv-menu-item>
+ * </mlv-menu>
+ * ```
+ *
+ * @example Submenu trigger on a menu item
+ * ```html
+ * <mlv-menu-item [mlvMenuTrigger]="sub" [isSubmenuTrigger]="true">
+ *   More options
+ * </mlv-menu-item>
+ * <mlv-menu #sub>
+ *   <mlv-menu-item (itemClick)="onOption()">Option A</mlv-menu-item>
+ * </mlv-menu>
+ * ```
+ */
+declare class MlvMenuTrigger {
+    /** @private Normalizes horizontal submenu opening for RTL layouts. */
+    private readonly _rtlService;
+    /** @private Host element reference. */
+    readonly _elementRef: ElementRef<any>;
+    /** @private DestroyRef for cleanup on directive destruction. */
+    private readonly _destroyRef;
+    /** @private Parent menu for submenu triggers, if this trigger lives inside one. */
+    private readonly _parentMenu;
+    /**
+     * @private Parent menubar, if this trigger is a direct child of a `mlv-menubar`
+     * (i.e. a top-level File / Edit / View item). `null` for standalone triggers
+     * and submenu triggers.
+     */
+    private readonly _menubar;
+    private readonly _menubarItemRegistry;
+    /**
+     * @private Whether this trigger is a top-level menubar item. When `true` the
+     * host exposes `role="menuitem"` + a roving tabindex, and open/close state is
+     * coordinated with the parent `mlv-menubar`.
+     */
+    readonly _isMenubarChild: boolean;
+    /**
+     * The `mlv-menu` panel to open. Required.
+     */
+    readonly mlvMenuTrigger: _angular_core.InputSignal<MlvMenuOverlayTarget>;
+    /**
+     * When true, treats this trigger as a submenu trigger:
+     * - Opens the panel using submenu positions (right-of-parent).
+     * - Activates triangle pointer tracking while the submenu is open.
+     * - Opens on `mouseenter` in addition to `click`.
+     */
+    readonly isSubmenuTrigger: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * When `true`, disables the trigger — no overlay will open.
+     */
+    readonly menuTriggerDisabled: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Emits when the menu panel opens. */
+    readonly menuOpened: _angular_core.OutputEmitterRef<void>;
+    /** Emits when the menu panel closes. */
+    readonly menuClosed: _angular_core.OutputEmitterRef<void>;
+    /**
+     * @private Roving tabindex for menubar top-level items — `0` for the active
+     * item, `-1` otherwise. Written by the parent `mlv-menubar`; only reflected
+     * on the host when `_isMenubarChild` is `true`.
+     */
+    readonly _tabIndex: _angular_core.WritableSignal<number>;
+    /** @private Shared overlay and submenu hover-intent controller. */
+    readonly _overlayController: MlvMenuOverlayController;
+    /** @private Whether the menu overlay is currently open. */
+    readonly _isOpen: _angular_core.WritableSignal<boolean>;
+    constructor();
+    /**
+     * Opens the menu overlay programmatically.
+     * No-op if the overlay is already open or the trigger is disabled.
+     */
+    open(): void;
+    /**
+     * Closes the menu overlay programmatically.
+     * No-op if the overlay is not open.
+     */
+    close(): void;
+    /**
+     * Toggles the menu overlay open/closed.
+     */
+    toggle(): void;
+    /**
+     * Whether this trigger is disabled. Bridges the `menuTriggerDisabled` signal
+     * to the `MlvMenubarItem` / `FocusKeyManager.skipPredicate` contract.
+     */
+    get disabledBoolean(): boolean;
+    /**
+     * Focuses the trigger host element. Required by CDK `FocusableOption` for the
+     * menubar's `FocusKeyManager` roving tabindex.
+     */
+    focus(): void;
+    /**
+     * Returns the trigger's trimmed visible text, used by the menubar's
+     * `FocusKeyManager` type-ahead. Required by `FocusKeyManager.withTypeAhead()`.
+     */
+    getLabel(): string;
+    /** Whether this item's dropdown menu is currently open (`MlvMenubarItem`). */
+    isMenuOpen(): boolean;
+    /** Opens this item's dropdown without moving focus into the panel (`MlvMenubarItem`). */
+    openMenu(): void;
+    /** Closes this item's dropdown (`MlvMenubarItem`). */
+    closeMenu(): void;
+    /**
+     * Opens this item's dropdown and moves focus to its first item (`MlvMenubarItem`).
+     */
+    openMenuWithFirstItemFocused(): void;
+    /**
+     * Opens this item's dropdown and moves focus to its last item (`MlvMenubarItem`).
+     */
+    openMenuWithLastItemFocused(): void;
+    /**
+     * @protected Click handler — toggles the menu.
+     */
+    protected _onTriggerClick(): void;
+    /**
+     * @protected Mouseenter handler.
+     *
+     * - Menubar top-level item: delegates to the bar's hover-follow, which opens
+     *   this item's menu only while another dropdown in the bar is already open.
+     * - Submenu trigger: opens the submenu on hover (triangle tracking).
+     * - Standalone trigger: no-op (opens on click only).
+     */
+    protected _onTriggerMouseEnter(): void;
+    /**
+     * @protected Mouseleave handler — for submenu triggers, starts a delayed close
+     * unless the cursor is heading into the submenu triangle.
+     * Once the cursor has entered the submenu panel, the submenu overlay's own
+     * mouseleave listener handles closing — no triangle tracking needed here.
+     */
+    protected _onTriggerMouseLeave(event: MouseEvent): void;
+    /**
+     * @protected Keyboard handler — Enter/Space opens; Escape closes;
+     * ArrowDown/Up opens with keyboard focus.
+     */
+    protected _onKeydown(event: KeyboardEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvMenuTrigger, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvMenuTrigger, "[mlvMenuTrigger]", never, { "mlvMenuTrigger": { "alias": "mlvMenuTrigger"; "required": true; "isSignal": true; }; "isSubmenuTrigger": { "alias": "isSubmenuTrigger"; "required": false; "isSignal": true; }; "menuTriggerDisabled": { "alias": "menuTriggerDisabled"; "required": false; "isSignal": true; }; }, { "menuOpened": "menuOpened"; "menuClosed": "menuClosed"; }, never, never, true, never>;
+}
+
+/**
+ * Horizontal application menu bar (`mlv-menubar`) — a File / Edit / View style
+ * row of top-level menu triggers, implementing the
+ * [WAI-ARIA Menubar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/).
+ *
+ * Wrap a set of `[mlvMenuTrigger]` elements. Each trigger opens a standard
+ * `mlv-menu` dropdown; the bar coordinates them:
+ *
+ * - `role="menubar"` container with a **roving tabindex** across the top-level
+ *   items (only the active item is in the tab order).
+ * - `ArrowLeft` / `ArrowRight` move between top-level items (wrapping); `Home` /
+ *   `End` jump to the first / last; printable characters type-ahead by label.
+ * - `ArrowDown` / `Enter` / `Space` open the focused item's menu with focus on
+ *   its first item; `ArrowUp` opens with focus on the last item (handled by the
+ *   trigger).
+ * - While any dropdown is open, hovering or arrowing to another top-level item
+ *   closes the current menu and opens the sibling (hover-follow only-while-open).
+ * - `ArrowRight` / `ArrowLeft` at the top level of an open dropdown cross to the
+ *   adjacent menubar menu; a focused submenu trigger's own `ArrowRight` wins.
+ * - `Escape` closes the menu and restores focus to its top-level item.
+ *
+ * Declare the `mlv-menu` panels **as siblings of the menubar** (outside its
+ * content), so the bar's `contentChildren` query only picks up the top-level
+ * triggers — see the example below.
+ *
+ * @example
+ * ```html
+ * <mlv-menubar aria-label="Main">
+ *   <button mlvButton variant="transparent" [mlvMenuTrigger]="fileMenu">File</button>
+ *   <button mlvButton variant="transparent" [mlvMenuTrigger]="editMenu">Edit</button>
+ * </mlv-menubar>
+ *
+ * <mlv-menu #fileMenu label="File">
+ *   <mlv-list-item mlvMenuItem (itemClick)="onNew()">New</mlv-list-item>
+ * </mlv-menu>
+ * <mlv-menu #editMenu label="Edit">
+ *   <mlv-list-item mlvMenuItem (itemClick)="onUndo()">Undo</mlv-list-item>
+ * </mlv-menu>
+ * ```
+ */
+declare class MlvMenubar<TItem extends MlvMenuItemData<unknown> = MlvMenuItemData<unknown>> implements MlvMenubarAccessor {
+    /** @private Host element reference. */
+    private readonly _elementRef;
+    private readonly _itemRegistry;
+    private readonly _rtlService;
+    private readonly _dataSourceAdapter;
+    /**
+     * @private The `aria-label` the consumer placed directly on the `<mlv-menubar>`
+     * element, captured before the host binding runs. Used as the accessible-name
+     * fallback so a natively-provided `aria-label` is preserved when the `label`
+     * input is not used — without it the `[attr.aria-label]` host binding would
+     * clobber the consumer's attribute with `null`.
+     */
+    protected readonly _initialAriaLabel: string | null;
+    private readonly _projectedItems;
+    /** @protected The projected row definition used by data-driven rendering. */
+    protected readonly _itemDef: _angular_core.Signal<MlvMenuItemDef<any> | undefined>;
+    /** @protected The registered top-level menu triggers, in render order. */
+    protected readonly _items: _angular_core.Signal<readonly MlvMenubarItem[]>;
+    /**
+     * Accessible label for the menubar (`aria-label`). Use when there is no
+     * visible heading that labels the bar.
+     */
+    readonly label: _angular_core.InputSignal<string>;
+    /**
+     * Optional reactive source for the root menubar entries. Entries may be
+     * menu-item data or `{ kind: 'divider', id }` separator records.
+     */
+    readonly dataSource: _angular_core.InputSignal<MlvMenubarDataSource<TItem> | undefined>;
+    /**
+     * @private `FocusKeyManager` managing the roving tabindex and horizontal
+     * arrow / Home / End / type-ahead navigation across top-level items.
+     */
+    private _keyManager;
+    /**
+     * @private Subscription to the key manager's `change` stream, keeping the
+     * roving tabindex in sync when type-ahead moves the active item.
+     */
+    private _changeSub;
+    /**
+     * @private The top-level item whose dropdown is currently open, or `null`
+     * when the whole bar is closed.
+     */
+    private _openItem;
+    /** @protected Whether the bar is rendering reactive data instead of projected triggers. */
+    protected readonly _dataMode: _angular_core.Signal<boolean>;
+    /** @protected Current entries normalized from the active reactive source. */
+    protected readonly _dataSourceItems: _angular_core.Signal<MlvMenubarEntry<TItem>[]>;
+    /** @protected Current source loading state. */
+    protected readonly _dataSourceLoading: _angular_core.Signal<boolean>;
+    constructor();
+    /** Host element of the menubar (used as a click-outside exclusion). */
+    get hostElement(): HTMLElement;
+    /**
+     * Records `item` as the open dropdown, closing any previously-open sibling
+     * and syncing the roving tabindex so the bar's active item follows the open
+     * menu. Called by a child trigger from its open path.
+     */
+    notifyItemOpened(item: MlvMenubarItem): void;
+    /** Clears the open-item record when `item`'s dropdown closes. */
+    notifyItemClosed(item: MlvMenubarItem): void;
+    /** Whether any dropdown in the bar is currently open. */
+    hasOpenMenu(): boolean;
+    /**
+     * Hover-follow: while a dropdown is already open, opening the hovered item's
+     * dropdown (which, via `notifyItemOpened`, closes the previous one). Does
+     * nothing when the bar is fully closed or the item is disabled/already open.
+     */
+    onItemPointerEnter(item: MlvMenubarItem): void;
+    /**
+     * Crosses from the open dropdown to an adjacent top-level item's menu,
+     * wrapping over disabled items, and opens it with focus on its first item.
+     */
+    openAdjacentItemMenu(from: MlvMenubarItem, dir: 1 | -1): void;
+    /**
+     * @protected Menubar-level keyboard handler.
+     *
+     * Opening keys (`Enter`, `Space`, `ArrowDown`, `ArrowUp`) are handled by the
+     * focused trigger itself, so they are ignored here. Everything else is routed
+     * to `FocusKeyManager` for horizontal navigation, Home/End, and type-ahead.
+     * If a dropdown is open when the active item changes, the newly-focused item's
+     * menu is opened (open-follow).
+     */
+    protected _onKeydown(event: KeyboardEvent): void;
+    /**
+     * @private Creates or replaces the `FocusKeyManager` with the current items,
+     * using horizontal orientation, wrap, Home/End and type-ahead, skipping
+     * disabled items. Sets the first item active so the bar has a tabbable entry.
+     */
+    private _initKeyManager;
+    /**
+     * @private Updates `_tabIndex` on every item so that only the active item has
+     * `tabindex="0"` (roving tabindex). All others get `-1`.
+     */
+    private _syncTabIndices;
+    /** @private The non-disabled top-level items, in DOM order. */
+    private _navigableItems;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvMenubar<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvMenubar<any>, "mlv-menubar", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "dataSource": { "alias": "dataSource"; "required": false; "isSignal": true; }; }, {}, ["_projectedItems", "_itemDef"], ["*"], true, never>;
+}
+
+export { MENUBAR_TOKEN, MENU_TOKEN, MLV_MENU_DATA_ITEM, MlvMenu, MlvMenuGroup, MlvMenuGroupLabel, MlvMenuItem, MlvMenuItemDef, MlvMenuSeparator, MlvMenuTrigger, MlvMenubar };
+export type { MlvMenuAccessor, MlvMenuDataItemContext, MlvMenuDataSource, MlvMenuItemData, MlvMenuItemDefContext, MlvMenubarAccessor, MlvMenubarDataSource, MlvMenubarDividerData, MlvMenubarEntry, MlvMenubarItem, MlvMenubarMenuController };