@versini/ui-menu 5.3.3 → 6.0.0

package/README.md

@@ -3,9 +3,9 @@
 [![npm version](https://img.shields.io/npm/v/@versini/ui-menu?style=flat-square)](https://www.npmjs.com/package/@versini/ui-menu)
 ![npm package minimized gzipped size](<https://img.shields.io/bundlejs/size/%40versini%2Fui-menu?style=flat-square&label=size%20(gzip)>)
 
-> Accessible and flexible React menu components built with TypeScript and TailwindCSS.
+> Accessible and lightweight React menu components built with TypeScript and TailwindCSS — no external UI library required.
 
-The Menu package provides dropdown menus and navigation components with full keyboard navigation, focus management, theming for triggers, and composable items / separators.
+The Menu package provides dropdown menus with full keyboard navigation, focus management, theming for triggers, and composable items / separators. It offers the same capabilities as `@versini/ui-dropdown` but with a smaller footprint by replacing Radix UI with a custom implementation using the native Popover API.
 
 ## Table of Contents
 
@@ -17,13 +17,14 @@ The Menu package provides dropdown menus and navigation components with full key
 
 ## Features
 
-- **📋 Composable**: `Menu`, `MenuItem`, `MenuSeparator`, `MenuGroupLabel`
-- **🔄 Nested Sub-menus**: Support for multi-level menu hierarchies with automatic positioning
-- **♿ Accessible**: Built with Floating UI & ARIA roles for robust a11y
-- **⌨️ Keyboard Support**: Arrow navigation, typeahead matching, ESC / click outside close
-- **🎨 Theme & Focus Modes**: Trigger inherits color + separate focus styling
-- **🧭 Smart Positioning**: Auto flip / shift to remain within viewport, responsive spacing
-- **🧪 Type Safe**: Strongly typed props & label-based typeahead
+- **Composable**: `Menu`, `MenuItem`, `MenuSeparator`, `MenuGroupLabel`, `MenuSub`
+- **Nested Sub-menus**: Support for multi-level menu hierarchies with automatic positioning
+- **Accessible**: Built with ARIA roles & WAI-ARIA menu patterns for robust a11y
+- **Keyboard Support**: Arrow navigation, ESC / click outside to close
+- **Theme & Focus Modes**: Trigger inherits color + separate focus styling
+- **Smart Positioning**: Auto flip / shift to remain within viewport
+- **Type Safe**: Strongly typed props with TypeScript
+- **Lightweight**: No Radix UI dependency — uses the native Popover API
 
 ## Installation
 
@@ -51,9 +52,18 @@ function App() {
         </ButtonIcon>
       }
     >
-      <MenuItem label="Profile" onClick={() => console.log("Profile")} />
-      <MenuItem label="Settings" onClick={() => console.log("Settings")} />
-      <MenuItem label="Logout" onClick={() => console.log("Logout")} />
+      <MenuItem
+        label="Profile"
+        onSelect={() => console.info("Profile")}
+      />
+      <MenuItem
+        label="Settings"
+        onSelect={() => console.info("Settings")}
+      />
+      <MenuItem
+        label="Logout"
+        onSelect={() => console.info("Logout")}
+      />
     </Menu>
   );
 }
@@ -64,7 +74,11 @@ function App() {
 ### Menu with Icons & Selection
 
 ```tsx
-import { Menu, MenuItem } from "@versini/ui-menu";
+import {
+  Menu,
+  MenuItem,
+  MenuSeparator
+} from "@versini/ui-menu";
 import { ButtonIcon } from "@versini/ui-button";
 import {
   IconMenu,
@@ -83,23 +97,23 @@ function AccountMenu() {
           <IconMenu />
         </ButtonIcon>
       }
-      onOpenChange={(o) => console.log("open?", o)}
+      onOpenChange={(o) => console.info("open?", o)}
     >
       <MenuItem
         label="Profile"
         icon={<IconUser />}
-        onClick={() => setLast("profile")}
+        onSelect={() => setLast("profile")}
       />
       <MenuItem
         label="Settings"
         icon={<IconSettings />}
-        onClick={() => setLast("settings")}
+        onSelect={() => setLast("settings")}
       />
       <MenuSeparator />
       <MenuItem
         label="Logout"
         icon={<IconLogout />}
-        onClick={() => setLast("logout")}
+        onSelect={() => setLast("logout")}
       />
     </Menu>
   );
@@ -127,10 +141,15 @@ function AccountMenu() {
 
 ### Nested Sub-menus
 
-Create hierarchical menus by nesting `Menu` components. Simply use a `Menu` with a `label` prop but no `trigger` to create a sub-menu:
+Create hierarchical menus using `MenuSub`:
 
 ```tsx
-import { Menu, MenuItem, MenuGroupLabel } from "@versini/ui-menu";
+import {
+  Menu,
+  MenuItem,
+  MenuSub,
+  MenuGroupLabel
+} from "@versini/ui-menu";
 import { ButtonIcon } from "@versini/ui-button";
 import { IconSettings, IconOpenAI, IconAnthropic } from "@versini/ui-icons";
 
@@ -148,22 +167,24 @@ function SettingsMenu() {
       <MenuItem label="Profile" />
       <MenuItem label="Preferences" />
 
-      {/* Nested sub-menu */}
-      <Menu label="AI Settings">
-        <MenuGroupLabel>Engines</MenuGroupLabel>
+      {/* Nested sub-menu with icon */}
+      <MenuSub label="AI Settings" icon={<IconSettings />}>
+        <MenuGroupLabel icon={<IconSettings />}>
+          Engines
+        </MenuGroupLabel>
         <MenuItem
           label="OpenAI"
           icon={<IconOpenAI />}
           selected={engine === "openai"}
-          onClick={() => setEngine("openai")}
+          onSelect={() => setEngine("openai")}
         />
         <MenuItem
           label="Anthropic"
           icon={<IconAnthropic />}
           selected={engine === "anthropic"}
-          onClick={() => setEngine("anthropic")}
+          onSelect={() => setEngine("anthropic")}
         />
-      </Menu>
+      </MenuSub>
 
       <MenuItem label="About" />
     </Menu>
@@ -174,7 +195,7 @@ function SettingsMenu() {
 **Features of nested sub-menus:**
 
 - Automatically positioned to the right (or left if no space)
-- Visual chevron indicator (`→`) shows expandable items
+- Visual chevron indicator shows expandable items
 - Hover or click to open sub-menus
 - Smart positioning adjusts for viewport constraints
 - Keyboard navigation works across all levels
@@ -184,38 +205,50 @@ function SettingsMenu() {
 
 ### Menu Props
 
-| Prop               | Type                                            | Default          | Description                                                                                    |
-| ------------------ | ----------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------- |
-| `trigger`          | `React.ReactNode`                               | -                | Element used to open the menu (Button / ButtonIcon / custom). Optional for nested sub-menus.   |
-| `children`         | `React.ReactNode`                               | -                | One or more `MenuItem` / `MenuSeparator` / `Menu` (for sub-menus) / custom nodes.              |
-| `label`            | `string`                                        | `"Open menu"`    | Accessible label for the trigger. When used without `trigger`, creates a nested sub-menu item. |
-| `defaultPlacement` | `Placement` (Floating UI)                       | `"bottom-start"` | Initial preferred placement (only applies to root menu).                                       |
-| `mode`             | `"dark" \| "light" \| "system" \| "alt-system"` | `"system"`       | Color mode of trigger (when using UI buttons).                                                 |
-| `focusMode`        | `"dark" \| "light" \| "system" \| "alt-system"` | `"system"`       | Focus ring thematic mode (when using UI buttons).                                              |
-| `onOpenChange`     | `(open: boolean) => void`                       | -                | Called when menu opens or closes.                                                              |
-
-**Creating nested sub-menus:**
-
-- Use `Menu` with `label` but without `trigger` to create a sub-menu item
-- Sub-menus automatically show a chevron (`→`) indicator
-- Positioning is automatically handled (right-start, flips to left if needed)
-- Hover or click to open nested menus
+| Prop               | Type                                                                                                                                           | Default          | Description                                    |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ---------------------------------------------- |
+| `trigger`          | `React.ReactElement`                                                                                                                           | -                | Element used to open the menu (Button, etc.).  |
+| `children`         | `React.ReactNode`                                                                                                                              | -                | MenuItem, MenuSeparator, etc.                  |
+| `label`            | `string`                                                                                                                                       | `"Open menu"`    | Accessible label for the trigger.              |
+| `defaultPlacement` | `"bottom"` \| `"bottom-start"` \| `"bottom-end"` \| `"top"` \| `"top-start"` \| `"top-end"` \| `"left"` \| `"left-start"` \| `"right"` \| etc. | `"bottom-start"` | Initial preferred placement.                   |
+| `mode`             | `"dark"` \| `"light"` \| `"system"` \| `"alt-system"`                                                                                          | `"system"`       | Color mode of trigger (when using UI buttons). |
+| `focusMode`        | `"dark"` \| `"light"` \| `"system"` \| `"alt-system"`                                                                                          | `"system"`       | Focus ring thematic mode.                      |
+| `onOpenChange`     | `(open: boolean) => void`                                                                                                                      | -                | Called when menu opens or closes.              |
+| `sideOffset`       | `number`                                                                                                                                       | `10`             | Offset distance from the trigger element.      |
 
 ### MenuItem Props
 
-| Prop          | Type              | Default | Description                                          |
-| ------------- | ----------------- | ------- | ---------------------------------------------------- |
-| `label`       | `string`          | -       | Text label of the item (used for typeahead).         |
-| `disabled`    | `boolean`         | `false` | Disable item interaction.                            |
-| `icon`        | `React.ReactNode` | -       | Icon element displayed before label.                 |
-| `raw`         | `boolean`         | `false` | Render custom content (bypasses built-in button).    |
-| `ignoreClick` | `boolean`         | `false` | Prevent auto menu close on click.                    |
-| `selected`    | `boolean`         | `false` | Visually indicate selected state (shows check icon). |
-
-### MenuSeparator
-
-Simple visual separator between items.
-
-### MenuGroupLabel
-
-Optional label element to group logical sets; pass standard `div` attributes.
+| Prop           | Type                     | Default     | Description                                   |
+| -------------- | ------------------------ | ----------- | --------------------------------------------- |
+| `label`        | `string`                 | -           | The label to display for the menu item.       |
+| `disabled`     | `boolean`                | `false`     | Whether the menu item is disabled.            |
+| `icon`         | `React.ReactNode`        | -           | Icon to display on the left of the label.     |
+| `raw`          | `boolean`                | `false`     | Disable internal styling for custom content.  |
+| `ignoreClick`  | `boolean`                | `false`     | Prevent menu from closing when item selected. |
+| `selected`     | `boolean`                | `undefined` | Show selected/unselected indicator.           |
+| `onSelect`     | `(event: Event) => void` | -           | Callback fired when the item is selected.     |
+| `onClick`      | `(event) => void`        | -           | Optional click handler.                       |
+| `onFocus`      | `(event) => void`        | -           | Optional focus handler.                       |
+| `onMouseEnter` | `(event) => void`        | -           | Optional mouse enter handler.                 |
+
+### MenuSub Props
+
+| Prop         | Type              | Default | Description                               |
+| ------------ | ----------------- | ------- | ----------------------------------------- |
+| `label`      | `string`          | -       | The label for the sub-menu trigger.       |
+| `icon`       | `React.ReactNode` | -       | Icon to display on the left of the label. |
+| `children`   | `React.ReactNode` | -       | Items to render inside sub-menu.          |
+| `disabled`   | `boolean`         | `false` | Whether the sub-menu is disabled.         |
+| `sideOffset` | `number`          | `14`    | Offset from sub-menu trigger.             |
+
+### MenuSeparator Props
+
+Standard `React.HTMLAttributes<HTMLDivElement>` - use `className` for custom styling.
+
+### MenuGroupLabel Props
+
+| Prop        | Type              | Default | Description                               |
+| ----------- | ----------------- | ------- | ----------------------------------------- |
+| `icon`      | `React.ReactNode` | -       | Icon to display on the left of the label. |
+| `children`  | `React.ReactNode` | -       | The label content.                        |
+| `className` | `string`          | -       | Custom CSS class for styling.             |

package/dist/index.d.ts

@@ -1,13 +1,26 @@
 import { JSX } from 'react/jsx-runtime';
-import type { Placement } from '@floating-ui/react';
-import { default as React_2 } from 'react';
-import * as React_3 from 'react';
 
-export declare const Menu: React_2.ForwardRefExoticComponent<Omit<MenuProps & React_2.HTMLProps<HTMLButtonElement>, "ref"> & React_2.RefAttributes<HTMLButtonElement>>;
+export declare const Menu: {
+    ({ trigger, children, label, defaultPlacement, onOpenChange, mode, focusMode, sideOffset, }: MenuProps): JSX.Element;
+    displayName: string;
+};
+
+export declare const MenuGroupLabel: {
+    ({ className, icon, children, ...props }: MenuGroupLabelProps): JSX.Element;
+    displayName: string;
+};
 
-export declare const MenuGroupLabel: ({ className, ...props }: React_3.HTMLAttributes<HTMLDivElement>) => JSX.Element;
+declare type MenuGroupLabelProps = {
+    /**
+     * A React component of type Icon to be placed on the left of the label.
+     */
+    icon?: React.ReactNode;
+} & React.HTMLAttributes<HTMLDivElement>;
 
-export declare const MenuItem: React_3.ForwardRefExoticComponent<MenuItemProps & React_3.ButtonHTMLAttributes<HTMLButtonElement> & React_3.RefAttributes<HTMLButtonElement>>;
+export declare const MenuItem: {
+    ({ label, disabled, icon, raw, children, ignoreClick, selected, onSelect, onClick, onFocus, onMouseEnter, ...props }: MenuItemProps): JSX.Element;
+    displayName: string;
+};
 
 declare type MenuItemProps = {
     /**
@@ -22,12 +35,16 @@ declare type MenuItemProps = {
     /**
      * A React component of type Icon to be placed on the left of the label.
      */
-    icon?: React_2.ReactNode;
+    icon?: React.ReactNode;
     /**
      * Disable internal menu item behavior (click, focus, etc.).
      * @default false
      */
     raw?: boolean;
+    /**
+     * Children to render when using raw mode.
+     */
+    children?: React.ReactNode;
     /**
      * Whether or not the menu should close when the menu item is selected.
      * @default false
@@ -35,26 +52,41 @@ declare type MenuItemProps = {
     ignoreClick?: boolean;
     /**
      * Whether or not the menu item is selected.
-     * @default false
+     * @default undefined
      */
     selected?: boolean;
+    /**
+     * Callback fired when the menu item is selected.
+     */
+    onSelect?: (event: Event) => void;
+    /**
+     * Optional click handler.
+     */
+    onClick?: (event: React.MouseEvent<HTMLDivElement>) => void;
+    /**
+     * Optional focus handler.
+     */
+    onFocus?: (event: React.FocusEvent<HTMLDivElement>) => void;
+    /**
+     * Optional mouse enter handler.
+     */
+    onMouseEnter?: (event: React.MouseEvent<HTMLDivElement>) => void;
 };
 
 declare type MenuProps = {
     /**
      * The component to use to open the menu, e.g. a ButtonIcon, a Button, etc.
-     * Required for root menus, omit for nested sub-menus (use label instead).
      */
-    trigger?: React_2.ReactNode;
+    trigger?: React.ReactElement;
     /**
-     * The children to render.
+     * The children to render (MenuItem, MenuSeparator, etc.).
      */
-    children?: React_2.ReactNode;
+    children?: React.ReactNode;
     /**
      * The default location of the popup.
      * @default "bottom-start"
      */
-    defaultPlacement?: Placement;
+    defaultPlacement?: "bottom" | "bottom-start" | "bottom-end" | "top" | "top-start" | "top-end" | "left" | "left-start" | "left-end" | "right" | "right-start" | "right-end";
     /**
      * The type of focus for the Button. This will change the color
      * of the focus ring around the Button.
@@ -65,8 +97,7 @@ declare type MenuProps = {
      */
     mode?: "dark" | "light" | "system" | "alt-system";
     /**
-     * The label to use for the menu button (root menu) or the sub-menu trigger text (nested menu).
-     * When used without a trigger, this creates a nested sub-menu.
+     * The label to use for the menu button.
      */
     label?: string;
     /**
@@ -74,10 +105,48 @@ declare type MenuProps = {
      * @param open whether or not the menu is open
      */
     onOpenChange?: (open: boolean) => void;
+    /**
+     * The offset distance from the trigger element.
+     * @default 10
+     */
+    sideOffset?: number;
+};
+
+export declare const MenuSeparator: {
+    ({ className, ...props }: MenuSeparatorProps): JSX.Element;
+    displayName: string;
 };
 
-export declare const MenuSeparator: ({ className, ...props }: MenuSeparatorProps) => JSX.Element;
+declare type MenuSeparatorProps = React.HTMLAttributes<HTMLDivElement>;
+
+export declare const MenuSub: {
+    ({ label, icon, children, disabled, sideOffset, }: MenuSubProps): JSX.Element;
+    displayName: string;
+};
 
-declare type MenuSeparatorProps = React_2.HTMLAttributes<HTMLDivElement>;
+declare type MenuSubProps = {
+    /**
+     * The label for the sub-menu trigger.
+     */
+    label: string;
+    /**
+     * A React component of type Icon to be placed on the left of the label.
+     */
+    icon?: React.ReactNode;
+    /**
+     * The children to render inside the sub-menu.
+     */
+    children?: React.ReactNode;
+    /**
+     * Whether the sub-menu trigger is disabled.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * The offset distance from the sub-menu trigger.
+     * @default 14
+     */
+    sideOffset?: number;
+};
 
 export { }