ngx-com 0.0.1 → 0.0.4

package/types/ngx-com-components-menu.d.ts

@@ -0,0 +1,479 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, Signal, InputSignal, TemplateRef, InputSignalWithTransform, ModelSignal, OutputEmitterRef, WritableSignal } from '@angular/core';
+import { VariantProps, cva } from 'class-variance-authority';
+import { FocusableOption } from '@angular/cdk/a11y';
+
+/**
+ * Interface for the root menu trigger, allowing items to close the entire menu tree.
+ */
+interface RootMenuTrigger {
+    /** Close the menu and all submenus. */
+    close(): void;
+    /** Whether to close the menu when an item is selected. */
+    menuCloseOnSelect(): boolean;
+    /** Called by MenuComponent to register itself when attached. */
+    registerMenu?(menu: MenuRef): void;
+}
+/**
+ * Interface for a parent menu, allowing items and submenus to coordinate.
+ */
+interface MenuRef {
+    /** Unique ID of the menu for ARIA. */
+    readonly menuId: string;
+    /** Size variant inherited by items. */
+    readonly menuSize: () => 'sm' | 'md' | 'lg';
+    /** Close this menu level. */
+    close(): void;
+    /** Focus the first item. */
+    focusFirstItem(): void;
+    /** Focus the last item. */
+    focusLastItem(): void;
+}
+/**
+ * Token to access the root menu trigger from anywhere in the menu tree.
+ * Used by items to close the entire menu on selection.
+ */
+declare const ROOT_MENU_TRIGGER: InjectionToken<RootMenuTrigger>;
+/**
+ * Token to access the nearest parent menu component.
+ * Used by items and submenu triggers to coordinate with their parent.
+ */
+declare const MENU_REF: InjectionToken<MenuRef>;
+
+type MenuSize = 'sm' | 'md' | 'lg';
+type MenuVariant = 'default' | 'compact';
+type MenuPosition = 'above' | 'below' | 'left' | 'right';
+type MenuAlignment = 'start' | 'center' | 'end';
+/**
+ * Menu panel styling variants.
+ *
+ * @tokens `--color-popover`, `--color-popover-foreground`, `--color-border`, `--shadow-lg`, `--radius-popover`
+ */
+declare const menuPanelVariants: ReturnType<typeof cva<{
+    size: Record<MenuSize, string>;
+    variant: Record<MenuVariant, string>;
+}>>;
+type MenuPanelVariants = VariantProps<typeof menuPanelVariants>;
+type BooleanVariant = Record<'true' | 'false', string>;
+/**
+ * Menu item styling variants (base for all item types).
+ *
+ * @tokens `--color-popover-foreground`, `--color-foreground`, `--color-muted`, `--color-warn`, `--color-warn-subtle`
+ */
+declare const menuItemVariants: ReturnType<typeof cva<{
+    size: Record<MenuSize, string>;
+    focused: BooleanVariant;
+    disabled: BooleanVariant;
+    destructive: BooleanVariant;
+}>>;
+type MenuItemVariants = VariantProps<typeof menuItemVariants>;
+/**
+ * Menu label (section header) styling variants.
+ *
+ * @tokens `--color-muted-foreground`
+ */
+declare const menuLabelVariants: ReturnType<typeof cva<{
+    size: Record<MenuSize, string>;
+}>>;
+type MenuLabelVariants = VariantProps<typeof menuLabelVariants>;
+/**
+ * Check/radio indicator sizing variants.
+ */
+declare const menuCheckIndicatorVariants: ReturnType<typeof cva<{
+    size: Record<MenuSize, string>;
+}>>;
+type MenuCheckIndicatorVariants = VariantProps<typeof menuCheckIndicatorVariants>;
+/**
+ * Keyboard shortcut hint styling variants.
+ *
+ * @tokens `--color-muted-foreground`
+ */
+declare const menuShortcutVariants: ReturnType<typeof cva<{
+    size: Record<MenuSize, string>;
+}>>;
+type MenuShortcutVariants = VariantProps<typeof menuShortcutVariants>;
+
+/** Side for submenu positioning. */
+type MenuSide = 'left' | 'right';
+/**
+ * Unified menu trigger directive — opens a menu in a CDK overlay.
+ *
+ * **Root context** (outside a menu): Opens on click, has backdrop.
+ * **Submenu context** (inside a menu): Opens on hover/ArrowRight, no backdrop.
+ *
+ * @tokens `--color-popover`, `--color-popover-foreground`, `--color-border`, `--shadow-lg`
+ *
+ * @example Root trigger
+ * ```html
+ * <button comButton [comMenuTrigger]="menu">Options</button>
+ * <ng-template #menu>
+ *   <com-menu>
+ *     <button comMenuItem>Edit</button>
+ *     <button comMenuItem>Delete</button>
+ *   </com-menu>
+ * </ng-template>
+ * ```
+ *
+ * @example Submenu trigger (inside a menu, combined with comMenuItem)
+ * ```html
+ * <button comMenuItem [comMenuTrigger]="shareMenu" side="right" align="start">
+ *   Share
+ *   <com-menu-sub-indicator />
+ * </button>
+ * ```
+ */
+declare class MenuTriggerDirective implements RootMenuTrigger {
+    private readonly overlay;
+    private readonly elementRef;
+    private readonly viewContainerRef;
+    private readonly injector;
+    private readonly destroyRef;
+    private readonly renderer;
+    private readonly parentMenu;
+    private readonly parentRootTrigger;
+    private overlayRef;
+    private attachedMenu;
+    private readonly menuId;
+    private openDelayTimer;
+    private closeDelayTimer;
+    private mouseInSubmenu;
+    private submenuMouseEnterCleanup;
+    private submenuMouseLeaveCleanup;
+    /** Whether this trigger is inside a menu (submenu context). */
+    readonly isSubmenu: Signal<boolean>;
+    /** Template containing `<com-menu>` with items. */
+    readonly comMenuTrigger: InputSignal<TemplateRef<unknown>>;
+    /** Preferred position direction (root trigger only). */
+    readonly menuPosition: InputSignal<MenuPosition>;
+    /** Alignment along cross-axis (root trigger only). */
+    readonly menuAlignment: InputSignal<MenuAlignment>;
+    /** Gap in px between trigger and menu. */
+    readonly menuOffset: InputSignal<number>;
+    /** Prevents opening when true. */
+    readonly menuDisabled: InputSignalWithTransform<boolean, unknown>;
+    /** Two-way bindable open state. */
+    readonly menuOpen: ModelSignal<boolean>;
+    /** Custom CSS class(es) on the overlay panel. */
+    readonly menuPanelClass: InputSignal<string | string[]>;
+    /** Close menu when an item is selected. */
+    readonly menuCloseOnSelect: InputSignalWithTransform<boolean, unknown>;
+    /** Side for submenu positioning (submenu context only). */
+    readonly side: InputSignal<MenuSide>;
+    /** Alignment for submenu positioning (submenu context only). */
+    readonly align: InputSignal<MenuAlignment>;
+    /** Hover delay before submenu opens in ms (submenu context only). */
+    readonly subMenuOpenDelay: InputSignal<number>;
+    /** Hover delay before submenu closes in ms (submenu context only). */
+    readonly subMenuCloseDelay: InputSignal<number>;
+    /** Emitted after menu opens. */
+    readonly menuOpened: OutputEmitterRef<void>;
+    /** Emitted after menu closes. */
+    readonly menuClosed: OutputEmitterRef<void>;
+    protected readonly ariaControls: Signal<string | null>;
+    private readonly panelClassArray;
+    constructor();
+    /** Programmatically open the menu. */
+    open(): void;
+    /** Programmatically close the menu. */
+    close(): void;
+    /** Toggle the menu open/close state. */
+    toggle(): void;
+    /** Called by MenuComponent to register itself when attached. */
+    registerMenu(menu: MenuRef): void;
+    protected onClick(event: Event): void;
+    protected onArrowDown(event: Event): void;
+    protected onArrowUp(event: Event): void;
+    protected onArrowRight(event: Event): void;
+    protected onArrowLeft(event: Event): void;
+    protected onEnter(event: Event): void;
+    protected onSpace(event: Event): void;
+    protected onMouseEnter(): void;
+    protected onMouseLeave(): void;
+    private focusFirstItemDeferred;
+    private focusLastItemDeferred;
+    private openMenu;
+    private closeMenu;
+    private openSubmenuInternal;
+    private closeSubmenu;
+    private createOverlay;
+    private attachContent;
+    private subscribeToCloseEvents;
+    private subscribeToSubmenuCloseEvents;
+    private onSubmenuMouseEnter;
+    private onSubmenuMouseLeave;
+    private cancelOpenTimer;
+    private cancelCloseTimer;
+    private disposeOverlay;
+    private cleanupSubmenuListeners;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MenuTriggerDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MenuTriggerDirective, "[comMenuTrigger]", ["comMenuTrigger"], { "comMenuTrigger": { "alias": "comMenuTrigger"; "required": true; "isSignal": true; }; "menuPosition": { "alias": "menuPosition"; "required": false; "isSignal": true; }; "menuAlignment": { "alias": "menuAlignment"; "required": false; "isSignal": true; }; "menuOffset": { "alias": "menuOffset"; "required": false; "isSignal": true; }; "menuDisabled": { "alias": "menuDisabled"; "required": false; "isSignal": true; }; "menuOpen": { "alias": "menuOpen"; "required": false; "isSignal": true; }; "menuPanelClass": { "alias": "menuPanelClass"; "required": false; "isSignal": true; }; "menuCloseOnSelect": { "alias": "menuCloseOnSelect"; "required": false; "isSignal": true; }; "side": { "alias": "side"; "required": false; "isSignal": true; }; "align": { "alias": "align"; "required": false; "isSignal": true; }; "subMenuOpenDelay": { "alias": "subMenuOpenDelay"; "required": false; "isSignal": true; }; "subMenuCloseDelay": { "alias": "subMenuCloseDelay"; "required": false; "isSignal": true; }; }, { "menuOpen": "menuOpenChange"; "menuOpened": "menuOpened"; "menuClosed": "menuClosed"; }, never, never, true, never>;
+}
+
+/**
+ * Base class for focusable menu items.
+ * All item directives must implement this interface for FocusKeyManager.
+ */
+declare abstract class MenuItemBase implements FocusableOption {
+    abstract focus(): void;
+    abstract getLabel(): string;
+    /** Whether the item is disabled. */
+    abstract get disabled(): boolean;
+}
+/**
+ * Menu panel component that renders inside an overlay.
+ * Manages keyboard navigation across its items using CDK FocusKeyManager.
+ *
+ * @tokens `--color-popover`, `--color-popover-foreground`, `--color-border`, `--shadow-lg`
+ *
+ * @example
+ * ```html
+ * <com-menu>
+ *   <button comMenuItem>Edit</button>
+ *   <button comMenuItem>Delete</button>
+ * </com-menu>
+ * ```
+ */
+declare class MenuComponent implements MenuRef {
+    private readonly rootTrigger;
+    private keyManager;
+    /** Size variant for the menu panel. */
+    readonly menuSize: InputSignal<MenuSize>;
+    /** Spacing density variant. */
+    readonly menuVariant: InputSignal<MenuVariant>;
+    /** Accessible label for the menu. */
+    readonly ariaLabel: InputSignal<string | null>;
+    /** ID of element labeling this menu. */
+    readonly ariaLabelledBy: InputSignal<string | null>;
+    readonly menuId: string;
+    readonly animationState: WritableSignal<'open' | 'closed'>;
+    /** Query all focusable items in the menu. */
+    private readonly items;
+    protected readonly panelClasses: Signal<string>;
+    constructor();
+    /** Focus the first non-disabled item. */
+    focusFirstItem(): void;
+    /** Focus the last non-disabled item. */
+    focusLastItem(): void;
+    /** Close this menu level. */
+    close(): void;
+    protected onKeydown(event: KeyboardEvent): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MenuComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MenuComponent, "com-menu", never, { "menuSize": { "alias": "menuSize"; "required": false; "isSignal": true; }; "menuVariant": { "alias": "menuVariant"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "ariaLabelledBy": { "alias": "ariaLabelledBy"; "required": false; "isSignal": true; }; }, {}, ["items"], ["*"], true, never>;
+}
+
+/**
+ * Menu item directive for actionable menu items.
+ * Applied to buttons, anchors, or any element that should be selectable.
+ *
+ * @tokens `--color-popover-foreground`, `--color-foreground`, `--color-muted`, `--color-warn`, `--color-warn-subtle`
+ *
+ * @example
+ * ```html
+ * <button comMenuItem (menuItemSelect)="onEdit()">Edit</button>
+ * <button comMenuItem [menuItemDisabled]="true">Disabled</button>
+ * <button comMenuItem destructive>Delete</button>
+ * ```
+ */
+declare class MenuItemDirective extends MenuItemBase {
+    private readonly elementRef;
+    private readonly menu;
+    private readonly rootTrigger;
+    /** Disables the item. */
+    readonly menuItemDisabled: InputSignalWithTransform<boolean, unknown>;
+    /** Marks item as destructive (delete, remove actions). */
+    readonly destructive: InputSignalWithTransform<boolean, unknown>;
+    /** Emitted when item is activated. */
+    readonly menuItemSelect: OutputEmitterRef<void>;
+    private readonly isFocused;
+    private readonly size;
+    protected readonly itemClasses: Signal<string>;
+    get disabled(): boolean;
+    focus(): void;
+    getLabel(): string;
+    protected onAction(event: Event): void;
+    protected onMouseEnter(): void;
+    protected onMouseLeave(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MenuItemDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MenuItemDirective, "[comMenuItem]", ["comMenuItem"], { "menuItemDisabled": { "alias": "menuItemDisabled"; "required": false; "isSignal": true; }; "destructive": { "alias": "destructive"; "required": false; "isSignal": true; }; }, { "menuItemSelect": "menuItemSelect"; }, never, never, true, never>;
+}
+
+/**
+ * Checkbox menu item component with toggleable checked state.
+ *
+ * @tokens `--color-popover-foreground`, `--color-foreground`, `--color-muted`
+ *
+ * @example
+ * ```html
+ * <button comMenuItemCheckbox [(checked)]="showSidebar">Sidebar</button>
+ * ```
+ */
+declare class MenuItemCheckboxComponent extends MenuItemBase {
+    private readonly elementRef;
+    private readonly menu;
+    /** Disables the item. */
+    readonly menuItemDisabled: InputSignalWithTransform<boolean, unknown>;
+    /** Two-way bindable checked state. */
+    readonly checked: ModelSignal<boolean>;
+    private readonly isFocused;
+    private readonly size;
+    protected readonly itemClasses: Signal<string>;
+    protected readonly indicatorClasses: Signal<string>;
+    get disabled(): boolean;
+    focus(): void;
+    getLabel(): string;
+    protected toggle(event: Event): void;
+    protected onMouseEnter(): void;
+    protected onMouseLeave(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MenuItemCheckboxComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MenuItemCheckboxComponent, "[comMenuItemCheckbox]", ["comMenuItemCheckbox"], { "menuItemDisabled": { "alias": "menuItemDisabled"; "required": false; "isSignal": true; }; "checked": { "alias": "checked"; "required": false; "isSignal": true; }; }, { "checked": "checkedChange"; }, never, ["*"], true, never>;
+}
+
+/**
+ * Radio menu item component for single-selection within a group.
+ *
+ * @tokens `--color-popover-foreground`, `--color-foreground`, `--color-muted`
+ *
+ * @example
+ * ```html
+ * <div comMenuGroup [(groupValue)]="sortField">
+ *   <button comMenuItemRadio value="name">Name</button>
+ *   <button comMenuItemRadio value="date">Date</button>
+ * </div>
+ * ```
+ */
+declare class MenuItemRadioComponent extends MenuItemBase {
+    private readonly elementRef;
+    private readonly menu;
+    private readonly rootTrigger;
+    private readonly group;
+    /** Disables the item. */
+    readonly menuItemDisabled: InputSignalWithTransform<boolean, unknown>;
+    /** The value this radio item represents. */
+    readonly value: InputSignal<unknown>;
+    private readonly isFocused;
+    private readonly size;
+    /** Whether this radio item is currently selected. */
+    readonly isChecked: Signal<boolean>;
+    protected readonly itemClasses: Signal<string>;
+    protected readonly indicatorClasses: Signal<string>;
+    get disabled(): boolean;
+    focus(): void;
+    getLabel(): string;
+    protected select(event: Event): void;
+    protected onMouseEnter(): void;
+    protected onMouseLeave(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MenuItemRadioComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MenuItemRadioComponent, "[comMenuItemRadio]", ["comMenuItemRadio"], { "menuItemDisabled": { "alias": "menuItemDisabled"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": true; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+}
+
+/**
+ * Token for menu group to allow radio items to coordinate.
+ */
+declare abstract class MenuGroupRef {
+    abstract readonly groupValue: () => unknown;
+    abstract setGroupValue(value: unknown): void;
+}
+/**
+ * Menu group directive for organizing related items.
+ * For radio items, ensures mutual exclusivity within the group.
+ *
+ * @example
+ * ```html
+ * <div comMenuGroup [(groupValue)]="sortField">
+ *   <button comMenuItemRadio value="name">Name</button>
+ *   <button comMenuItemRadio value="date">Date</button>
+ * </div>
+ * ```
+ *
+ * @tokens None - uses only ARIA attributes
+ */
+declare class MenuGroupDirective extends MenuGroupRef {
+    /** Optional accessible label for the group. */
+    readonly ariaLabel: InputSignal<string | null>;
+    /** Two-way bindable value for radio groups. */
+    readonly groupValue: ModelSignal<unknown>;
+    setGroupValue(value: unknown): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MenuGroupDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MenuGroupDirective, "[comMenuGroup]", ["comMenuGroup"], { "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "groupValue": { "alias": "groupValue"; "required": false; "isSignal": true; }; }, { "groupValue": "groupValueChange"; }, never, never, true, never>;
+}
+
+/**
+ * Non-interactive section label/header inside a menu.
+ *
+ * @tokens `--color-muted-foreground`
+ *
+ * @example
+ * ```html
+ * <span comMenuLabel>Team</span>
+ * <button comMenuItem>View Members</button>
+ * ```
+ */
+declare class MenuLabelDirective {
+    private readonly menu;
+    /** Unique ID that can be referenced by aria-labelledby. */
+    readonly labelId: string;
+    private readonly size;
+    protected readonly labelClasses: Signal<string>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MenuLabelDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MenuLabelDirective, "[comMenuLabel]", ["comMenuLabel"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Visual separator between menu sections.
+ *
+ * @tokens `--color-border`
+ *
+ * @example
+ * ```html
+ * <button comMenuItem>Edit</button>
+ * <hr comMenuDivider />
+ * <button comMenuItem>Delete</button>
+ * ```
+ */
+declare class MenuDividerDirective {
+    static ɵfac: i0.ɵɵFactoryDeclaration<MenuDividerDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MenuDividerDirective, "[comMenuDivider]", ["comMenuDivider"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Submenu indicator component — displays a chevron icon indicating a submenu.
+ * Place inside a menu item that has `[comMenuTrigger]` to indicate it opens a submenu.
+ *
+ * @tokens `--color-muted-foreground`
+ *
+ * @example
+ * ```html
+ * <button comMenuItem [comMenuTrigger]="shareMenu">
+ *   Share
+ *   <com-menu-sub-indicator />
+ * </button>
+ * ```
+ */
+declare class MenuSubIndicatorComponent {
+    static ɵfac: i0.ɵɵFactoryDeclaration<MenuSubIndicatorComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MenuSubIndicatorComponent, "com-menu-sub-indicator", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Keyboard shortcut hint displayed in a menu item.
+ *
+ * @tokens `--color-muted-foreground`
+ *
+ * @example
+ * ```html
+ * <button comMenuItem>
+ *   Save
+ *   <span comMenuShortcut>⌘S</span>
+ * </button>
+ * ```
+ */
+declare class MenuShortcutDirective {
+    private readonly menu;
+    private readonly size;
+    protected readonly shortcutClasses: Signal<string>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MenuShortcutDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MenuShortcutDirective, "[comMenuShortcut]", ["comMenuShortcut"], {}, {}, never, never, true, never>;
+}
+
+export { MENU_REF, MenuComponent, MenuDividerDirective, MenuGroupDirective, MenuGroupRef, MenuItemBase, MenuItemCheckboxComponent, MenuItemDirective, MenuItemRadioComponent, MenuLabelDirective, MenuShortcutDirective, MenuSubIndicatorComponent, MenuTriggerDirective, ROOT_MENU_TRIGGER, menuCheckIndicatorVariants, menuItemVariants, menuLabelVariants, menuPanelVariants, menuShortcutVariants };
+export type { MenuAlignment, MenuCheckIndicatorVariants, MenuItemVariants, MenuLabelVariants, MenuPanelVariants, MenuPosition, MenuRef, MenuShortcutVariants, MenuSide, MenuSize, MenuVariant, RootMenuTrigger };