@lumx/core 4.16.1-alpha.2 → 4.17.0-next.0

package/components-and-utils.css

@@ -8302,6 +8302,16 @@ table {
   background-color: var(--lumx-color-dark-L5);
 }
 
+/* ==========================================================================
+   Menu
+   ========================================================================== */
+.lumx-menu-popover {
+  max-height: 50vh;
+}
+.lumx-menu-popover__scroll {
+  overflow-y: auto;
+}
+
 /* ==========================================================================
    Message
    ========================================================================== */

package/js/components/Menu/MenuButton.d.ts

@@ -0,0 +1,15 @@
+import type { JSXElement, LumxClassName } from '../../types';
+export interface MenuButtonProps {
+    label?: JSXElement;
+    children?: JSXElement;
+    triggerProps?: Record<string, any>;
+    popoverProps?: Record<string, any>;
+    onOpen?: (isOpen: boolean) => void;
+}
+export interface MenuButtonComponents {
+    Menu: any;
+}
+export declare const COMPONENT_NAME = "MenuButton";
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/** Menu button core template (composition of menu provider, trigger, popover and list) */
+export declare const MenuButton: (props: MenuButtonProps, { Menu }: MenuButtonComponents) => import("react").JSX.Element;

package/js/components/Menu/MenuButtonStories.d.ts

@@ -0,0 +1,41 @@
+import type { SetupStoriesOptions } from '@lumx/core/stories/types';
+export declare function setup({ components: { MenuButton, MenuItem, MenuDivider }, }: SetupStoriesOptions<{
+    components: {
+        MenuButton: any;
+        MenuItem: any;
+        MenuDivider: any;
+    };
+}>): {
+    meta: {
+        component: any;
+        argTypes: {
+            onOpen: {
+                action: boolean;
+            };
+        };
+        args: {
+            label: string;
+        };
+        play(): Promise<void>;
+    };
+    Default: {
+        argTypes: {
+            onProfile: {
+                action: boolean;
+            };
+            onSettings: {
+                action: boolean;
+            };
+            onHelp: {
+                action: boolean;
+            };
+            onLogout: {
+                action: boolean;
+            };
+        };
+        args: {
+            emphasis: string;
+        };
+        render: ({ onProfile, onSettings, onHelp, onLogout, ...args }: any) => import("react").JSX.Element;
+    };
+};

package/js/components/Menu/MenuButtonTestStories.d.ts

@@ -0,0 +1,31 @@
+export declare function setup({ components: { MenuButton, MenuItem } }: {
+    components: {
+        MenuButton: any;
+        MenuItem: any;
+    };
+}): {
+    meta: {
+        tags: string[];
+        args: {
+            onOne: import("storybook/test").Mock<(...args: any[]) => any>;
+            onTwo: import("storybook/test").Mock<(...args: any[]) => any>;
+            onThree: import("storybook/test").Mock<(...args: any[]) => any>;
+        };
+        render: (args: any) => import("react").JSX.Element;
+    };
+    TabFromLastItemClosesAndMovesFocus: {
+        play: ({ canvasElement }: any) => Promise<void>;
+    };
+    ShiftTabFromFirstItemClosesAndReturnsToTrigger: {
+        play: ({ canvasElement }: any) => Promise<void>;
+    };
+    EscapeRestoresFocusToTrigger: {
+        play: ({ canvasElement }: any) => Promise<void>;
+    };
+    ItemActivationRestoresFocusToTrigger: {
+        play: ({ canvasElement, args }: any) => Promise<void>;
+    };
+    ClickAwayClosesMenu: {
+        play: ({ canvasElement }: any) => Promise<void>;
+    };
+};

package/js/components/Menu/MenuButtonTests.d.ts

@@ -0,0 +1,22 @@
+type RenderResult = {
+    unmount: () => void;
+    container: HTMLElement;
+};
+/**
+ * Options to set up the MenuButton test suite.
+ * Injected by the framework-specific test file (React or Vue).
+ */
+export interface MenuButtonTestSetup {
+    components: {
+        MenuButton: any;
+        MenuItem: any;
+    };
+    /**
+     * Render a MenuButton template.
+     *
+     * @param template JSX render function returning the element to render.
+     */
+    render: (template: () => any) => RenderResult;
+}
+export default function menuButtonTests({ components, render }: MenuButtonTestSetup): void;
+export {};

package/js/components/Menu/MenuItem.d.ts

@@ -0,0 +1,26 @@
+import type { CommonRef, HasClassName, JSXElement, LumxClassName } from '../../types';
+/** MenuItem props. */
+export interface MenuItemProps extends HasClassName {
+    /** Item label content. */
+    children?: JSXElement;
+    /** Content rendered before the label (e.g. an icon). */
+    before?: JSXElement;
+    /** Content rendered after the label (e.g. a shortcut hint). */
+    after?: JSXElement;
+    /** Whether the item is disabled. Skipped by Tab and arrow nav. */
+    isDisabled?: boolean;
+    /** Click handler for the action element. */
+    handleClick?(event: any): void;
+    /** Extra props forwarded to the inner action element (e.g. link props when `as="a"`). */
+    actionProps?: Record<string, any>;
+    /** ref to the inner action element (the focusable `<button>` / `<a>`). */
+    actionRef?: CommonRef;
+    /** ref to the root `<li>` element. */
+    ref?: CommonRef;
+}
+/** Props overridden by framework wrappers. */
+export type MenuItemPropsToOverride = 'before' | 'after' | 'children' | 'handleClick' | 'actionProps' | 'actionRef';
+export declare const COMPONENT_NAME = "MenuItem";
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/** MenuItem core template. Renders a `ListItem` with a `ListItemAction`. */
+export declare const MenuItem: (props: MenuItemProps) => import("react").JSX.Element;

package/js/components/Menu/MenuItemTests.d.ts

@@ -0,0 +1,11 @@
+import { SetupOptions } from '../../../testing';
+/**
+ * Mounts the component and returns common DOM elements / data needed in multiple tests further down.
+ */
+export declare const setup: (propsOverride: any | undefined, { render, screen, ...options }: SetupOptions<any>) => {
+    props: any;
+    menuItem: HTMLElement;
+    action: HTMLElement;
+    screen: import("@testing-library/dom").Screen;
+};
+export declare function menuItemTests(renderOptions: SetupOptions<any>): void;

package/js/components/Menu/MenuList.d.ts

@@ -0,0 +1,16 @@
+import type { CommonRef, HasClassName, JSXElement, LumxClassName } from '../../types';
+/** Menu list props. */
+export type MenuListProps = HasClassName & {
+    /** Menu content (MenuItem, ListDivider, ListSection…). */
+    children?: JSXElement;
+    /** The id of the menu container element (matches `aria-controls` on the trigger). */
+    id?: string;
+    /** The id of the element that labels the menu (auto-set to the trigger id by wrappers). */
+    'aria-labelledby'?: string;
+    /** ref to the root `<ul>` element. */
+    ref?: CommonRef;
+};
+export declare const COMPONENT_NAME = "Menu";
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/** MenuList core template. Wraps `List` with menu-specific class and ARIA labelling. */
+export declare const MenuList: (props: MenuListProps) => import("react").JSX.Element;

package/js/components/Menu/MenuPopover.d.ts

@@ -0,0 +1,34 @@
+import type { CommonRef, HasClassName, JSXElement, LumxClassName } from '../../types';
+import type { Placement } from '../Popover/constants';
+/** MenuPopover props. */
+export interface MenuPopoverProps extends HasClassName {
+    /** Popover content (a `Menu`). */
+    children?: JSXElement;
+    /** Whether the popover is open. */
+    isOpen?: boolean;
+    /** Placement relative to the anchor. Defaults to `'bottom-start'`. */
+    placement?: Placement;
+    /** Reference to the anchor element. */
+    anchorRef?: CommonRef;
+    /** Callback invoked when the popover requests to close (click away, escape). */
+    handleClose?(): void;
+    /** Whether the popover should close when clicking outside. Default: true. */
+    closeOnClickAway?: boolean;
+    /** Whether the popover should close on Escape. Default: true. */
+    closeOnEscape?: boolean;
+    /** Whether to render in a portal. Default: false (avoid stacking-context surprises). */
+    usePortal?: boolean;
+    /** Whether to focus the anchor on close. Default: true. */
+    focusAnchorOnClose?: boolean;
+}
+/** Framework components injected by wrappers. */
+export interface MenuPopoverComponents {
+    /** Popover component (framework-specific). */
+    Popover: any;
+    /** FlexBox component (framework-specific). */
+    FlexBox: any;
+}
+export declare const COMPONENT_NAME = "MenuPopover";
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/** MenuPopover core template. Renders a `Popover` with menu-friendly defaults. */
+export declare const MenuPopover: (props: MenuPopoverProps, { Popover, FlexBox }: MenuPopoverComponents) => import("react").JSX.Element;

package/js/components/Menu/MenuTrigger.d.ts

@@ -0,0 +1,21 @@
+import type { CommonRef, HasClassName, JSXElement, LumxClassName } from '../../types';
+/** MenuTrigger props. */
+export interface MenuTriggerProps extends HasClassName {
+    /** Content of the trigger (label / icon / etc.). */
+    children?: JSXElement;
+    /** The id of the menu container (for `aria-controls`). */
+    menuId?: string;
+    /** Whether the menu is currently open. */
+    isOpen?: boolean;
+    /** ref to the trigger element. */
+    ref?: CommonRef;
+}
+/** Framework components injected by wrappers. */
+export interface MenuTriggerComponents {
+    /** Component to render as the trigger (e.g. Button, IconButton, Chip, link). */
+    Trigger: any;
+}
+export declare const COMPONENT_NAME = "MenuTrigger";
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/** MenuTrigger core template. Renders `Trigger` with disclosure ARIA attributes. */
+export declare const MenuTrigger: (props: MenuTriggerProps, { Trigger }: MenuTriggerComponents) => import("react").JSX.Element;

package/js/components/Menu/setupMenu.d.ts

@@ -0,0 +1,18 @@
+import type { MenuHandle, SetupMenuOptions } from './types';
+/**
+ * Set up a disclosure-pattern menu handle.
+ *
+ * The trigger is registered separately via {@link MenuHandle.registerTrigger}
+ * once the trigger mounts. The menu container is registered separately via
+ * {@link MenuHandle.registerMenu} once on mount — the popover uses
+ * `closeMode="hide"` so the `<ul>` stays in the DOM at all times.
+ *
+ * IMPORTANT: this is the **disclosure widget** pattern, NOT WAI-ARIA's
+ * `role="menu"`. Items are native `<button>` / `<a>` elements with `tabindex="0"`,
+ * so screen readers announce them naturally and Tab navigates between them in
+ * DOM order. There is no focus trap.
+ *
+ * @param options Options (menuId for `aria-controls`).
+ * @returns A {@link MenuHandle} for interacting with the menu.
+ */
+export declare function setupMenu(options?: SetupMenuOptions): MenuHandle;

package/js/components/Menu/types.d.ts

@@ -0,0 +1,40 @@
+/** Map of menu event names to their payload types. */
+export interface MenuEventMap {
+    /** Fired when the menu open state changes. Payload: whether the menu is open. */
+    open: boolean;
+}
+/**
+ * Handle returned by `setupMenu`. Used by framework wrappers to plug DOM elements
+ * into the menu state machine.
+ */
+export interface MenuHandle {
+    /** The trigger element, registered via `registerTrigger`. Null before registration. */
+    readonly trigger: HTMLElement | null;
+    /** Set the open state, update ARIA, fire `open` event. */
+    setOpen(open: boolean): void;
+    /**
+     * Register the trigger element. Wires click toggle, keyboard handlers (ArrowUp/Down
+     * to open with focus, trigger typeahead) and ARIA attributes. Returns a cleanup fn.
+     */
+    registerTrigger(el: HTMLElement): () => void;
+    /**
+     * Register the menu container (`<ul>`). Wires keyboard handlers (arrow nav, typeahead,
+     * Tab-edge close, Escape). Always mounted (`closeMode="hide"`), so runs once.
+     * Returns a cleanup fn.
+     */
+    registerMenu(el: HTMLElement): () => void;
+    /**
+     * Apply a focus request deferred while the menu was closed (trigger ArrowDown/Up,
+     * typeahead, or click-open). The wrapper must call this once items commit to the DOM.
+     */
+    flushPendingNavigation(): void;
+    /** Subscribe to a menu event. Returns an unsubscribe function. */
+    subscribe<E extends keyof MenuEventMap>(event: E, listener: (value: MenuEventMap[E]) => void): () => void;
+    /** Tear down — removes all event listeners and clears state. */
+    destroy(): void;
+}
+/** Options for `setupMenu`. The wrapper sets the matching `id` on the `<ul>` itself. */
+export interface SetupMenuOptions {
+    /** The id to advertise via `aria-controls` on the trigger. */
+    menuId?: string;
+}

package/js/components/Menu/utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * CSS selector for menu items (inner focusable element). Includes disabled items: per
+ * WAI-ARIA APG they stay focusable so AT announces them; click is no-op'd via `aria-disabled`.
+ */
+export declare const MENU_ITEM_SELECTOR = "[data-menu-item]";
+/** Get an item's text label (trimmed `textContent`) for typeahead matching. */
+export declare function getItemText(item: HTMLElement): string;
+/** Get all item elements within a menu container, in DOM order (includes disabled). */
+export declare function getItems(menu: HTMLElement): HTMLElement[];

package/js/utils/browser/isPrintableKey.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Is the key a single printable character (not Space, no modifier keys)?
+ *
+ * Used by typeahead-style keyboard handlers (menu, combobox) to detect when a
+ * keypress should start/continue a type-to-search rather than trigger navigation.
+ */
+export declare function isPrintableKey({ key, altKey, ctrlKey, metaKey }: KeyboardEvent): boolean;

package/lumx.css

@@ -8983,6 +8983,16 @@ table {
   background-color: var(--lumx-color-dark-L5);
 }
 
+/* ==========================================================================
+   Menu
+   ========================================================================== */
+.lumx-menu-popover {
+  max-height: 50vh;
+}
+.lumx-menu-popover__scroll {
+  overflow-y: auto;
+}
+
 /* ==========================================================================
    Message
    ========================================================================== */

package/package.json

@@ -7,7 +7,7 @@
     },
     "dependencies": {
         "@floating-ui/dom": "^1.7.5",
-        "@lumx/icons": "^4.16.1-alpha.2",
+        "@lumx/icons": "^4.17.0-next.0",
         "classnames": "^2.3.2",
         "focus-visible": "^5.0.2",
         "lodash": "4.18.1",
@@ -66,7 +66,7 @@
         "update-version-changelog": "yarn version-changelog ../../CHANGELOG.md"
     },
     "sideEffects": false,
-    "version": "4.16.1-alpha.2",
+    "version": "4.17.0-next.0",
     "devDependencies": {
         "@rollup/plugin-typescript": "^12.3.0",
         "@testing-library/dom": "^10.4.1",

package/scss/_components_classes.scss

@@ -26,6 +26,7 @@
 @import "./components/link/index";
 @import "./components/link-preview/index";
 @import "./components/list/index";
+@import "./components/menu/index";
 @import "./components/message/index";
 @import "./components/mosaic/index";
 @import "./components/navigation/index";

package/scss/components/menu/_index.scss

@@ -0,0 +1,11 @@
+/* ==========================================================================
+   Menu
+   ========================================================================== */
+
+.#{$lumx-base-prefix}-menu-popover {
+    max-height: 50vh;
+
+    &__scroll {
+        overflow-y: auto;
+    }
+}