@aiquants/menu-bar 1.18.3 → 1.19.0

package/README.md

@@ -4,10 +4,13 @@ A React menu bar component with authentication support and theming for modern we
 
 ## Key Features
 
-- **Menu Navigation**: Collapsible menu with smooth animations and hierarchical structure
+- **Menu Navigation**: A drawer that slides in from the right, with top-level links and collapsible groups
+- **Current Page Highlighting**: The entry the current route belongs to carries `aria-current="page"` and its group opens, with exact or prefix matching per entry
 - **Dark/Light Theme**: Comprehensive theming support with scoped CSS
 - **Session Management**: Built-in session information display with user profiles
-- **Responsive Design**: Mobile-friendly with overlay support
+- **Pinning**: Keep the drawer open while navigating, with the pinned width exposed as a CSS variable and an event
+- **Accessible**: Named switch with `aria-expanded`, an inert closed drawer, focus that returns to the switch, visible focus rings, reduced-motion and forced-colors support
+- **Configurable Switch**: Position, size, layering and caption of the open/close switch set through CSS custom properties
 - **TypeScript Support**: Full TypeScript definitions included
 - **React Router Integration**: Built for React Router with generic link component support
 - **CSS Scoped**: All styles are scoped to prevent conflicts with host applications
@@ -20,18 +23,26 @@ npm install @aiquants/menu-bar
 
 ## Exports
 
-This package exports the following components and types:
+This package exports the following components, functions and types:
 
 ```tsx
 // Components
 export { MenuBar } from '@aiquants/menu-bar';
 export { SessionInfo, DefaultLink } from '@aiquants/menu-bar';
 
+// Pin state (event and hook)
+export { useMenuPinState, subscribeMenuPinChange, dispatchMenuPinChange, getInitialPinState, MENU_PIN_CHANGE_EVENT } from '@aiquants/menu-bar';
+
 // Types
-export type { IMenu, ISubmenu, MenuNavigationPayload } from '@aiquants/menu-bar';
+export type { IMenuBarProps } from '@aiquants/menu-bar';
+export type { IMenu, ISubmenu, MenuBarPathMatch, MenuNavigationPayload } from '@aiquants/menu-bar';
 export type { Theme } from '@aiquants/menu-bar';
 export type { SessionInfoProps, LinkProps } from '@aiquants/menu-bar';
 export type { UserProfile } from '@aiquants/menu-bar';
+export type { MenuPinChangeDetail, MenuPinCustomEvent, SubscribeMenuPinOptions, UseMenuPinStateOptions } from '@aiquants/menu-bar';
+
+// Collision-free aliases of the types above
+export type { IMenuBarMenu, IMenuBarSubmenu, MenuBarTheme, MenuBarUserProfile, MenuBarLinkProps, MenuBarSessionInfoProps } from '@aiquants/menu-bar';
 
 // CSS — non-Tailwind hosts load the self-contained standalone build once (Tailwind hosts: see "Styling (CSS)")
 import '@aiquants/menu-bar/styles/menu-bar.standalone.css';
@@ -87,6 +98,8 @@ function App() {
 }
 ```
 
+`MenuBar` renders React Router links, so place it inside a router provider.
+
 ## Props
 
 ### MenuBar Props
@@ -98,9 +111,12 @@ function App() {
 | `toggleTheme` | `() => void` | Yes | Function to toggle between light and dark themes |
 | `onClickSignout` | `() => void` | Yes | Callback function for sign out action |
 | `menuHeader` | `React.ReactNode` | No | Optional header content for the menu |
-| `isMenuhide` | `boolean` | No | Whether to hide the menu bar entirely |
+| `isMenuHide` | `boolean` | No | Whether to hide the menu bar entirely (renders nothing) |
+| `isMenuhide` | `boolean` | No | Legacy spelling of `isMenuHide`; read only when `isMenuHide` is not given |
 | `onMenuNavigate` | `(payload: MenuNavigationPayload) => void` | No | Callback function triggered when a menu or submenu item is selected |
-| `onPinChange` | `(pinned: boolean) => void` | No | Callback function triggered when the menu bar's pin state changes |
+| `isPinned` | `boolean` | No | Controlled pin state. When omitted, the menu bar keeps the pin state itself and stores it in `localStorage` |
+| `pinnedWidth` | `number` | No | Width in pixels reported while pinned (default `240`) |
+| `onPinChange` | `(pinned: boolean, widthPx: number) => void` | No | Called when the pin button toggles the pin state, and with `(false, 0)` whenever the switch, the backdrop or Escape closes the drawer (not when selecting an item closes it) |
 | `pinnedSubmenuIds` | `number[]` | No | Pinned submenu IDs (controlled) |
 | `initialPinnedSubmenuIds` | `number[]` | No | Initial pinned submenu IDs |
 | `onSubmenuPinChange` | `(pinnedIds: number[]) => void` | No | Callback function triggered when submenu pin states change |
@@ -114,6 +130,7 @@ interface IMenu {
   title: string;
   href?: string;
   submenu: ISubmenu[];
+  match?: MenuBarPathMatch; // ignored on a group without href
 }
 ```
 
@@ -126,9 +143,18 @@ interface ISubmenu {
   href: string;
   mark?: string;
   new?: boolean;
+  match?: MenuBarPathMatch;
 }
 ```
 
+### MenuBarPathMatch Type
+
+```tsx
+type MenuBarPathMatch = 'exact' | 'prefix';
+```
+
+How an entry's `href` is matched against the current path. See "Current Page Highlighting" below.
+
 ### MenuNavigationPayload Type
 
 ```tsx
@@ -167,17 +193,17 @@ interface LinkProps {
 
 The package ships **two CSS artifacts** — pick the one that matches your host.
 
-- **Tailwind v4 host** — import the components-only build into the `components` layer, and let your own Tailwind build generate the JSX utility classes by scanning the package source:
+- **Tailwind v4 host** — import the components-only build into the `components` layer, and let your own Tailwind build generate the JSX utility classes by scanning the package's built JavaScript (the published package ships `dist`, not `src`; the class names stay intact in the bundle):
 
   ```css
   /* app tailwind.css */
   @import "@aiquants/menu-bar/styles/menu-bar.css" layer(components);
-  @source "../node_modules/@aiquants/menu-bar/src/**/*.{ts,tsx}";
-  /* monorepo: @source "../../../../packages/menu-bar/src/**/*.{ts,tsx}"; */
+  @source "../node_modules/@aiquants/menu-bar/dist/**/*.js";
+  /* the package as a workspace sibling: @source "../../../../packages/menu-bar/src/**/*.{ts,tsx}"; */
   ```
 
-  `menu-bar.css` (Artifact A) carries only the hand-written `.aiquants-*` component classes — no `:root` theme variables, no Tailwind utilities, no preflight — so it drops into `layer(components)` safely.
-  The one `:root` rule it emits is menu-bar's own runtime variable `--aiquants-menu-pinned-width`, which the component sets inline at runtime (a runtime input, not a theme override).
+  `menu-bar.css` (Artifact A) carries only the hand-written `.aiquants-*` component classes and the package's own `:root` variables — no Tailwind theme variables, no Tailwind utilities, no preflight — so it drops into `layer(components)` safely.
+  Its `:root` rule declares menu-bar's runtime variable `--aiquants-menu-pinned-width` (which the component sets inline at runtime) and the defaults of the menu switch custom properties (`--aqmb-switch-*`, see below).
   Do **not** also `@import` the standalone build in a Tailwind host: it re-emits the same utilities your build produces, and two concatenated builds cannot reproduce the single-build canonical order (base → variants), so base/variant cascade winners flip.
 
 - **Non-Tailwind host** — load the single self-contained standalone build (via `<link>` or a plain `@import`); it bundles the component classes plus every JSX utility:
@@ -188,9 +214,47 @@ The package ships **two CSS artifacts** — pick the one that matches your host.
 
   Dark mode keys off the `.dark` class — add `.dark` to `<html>` to enable the dark styles.
 
+In both setups the component classes sit in the `components` layer and the utilities in the later `utilities` layer, so a utility wins over a component rule for the same property.
+
+## Menu Switch Custom Properties
+
+The open/close switch is a square box with four bars that turn into a cross while the drawer is open, over a "menu" / "close" caption. Its whole drawing lives in the package stylesheet, and it carries no utility classes, so every custom property below takes effect. The defaults are declared on `:root`; override them on `:root` (or any ancestor of the menu bar).
+
+| Property | Default | Effect |
+| --- | --- | --- |
+| `--aqmb-switch-position` | `fixed` | `position` of the switch |
+| `--aqmb-switch-top` | `6px` | `top` of the switch |
+| `--aqmb-switch-right` | `8px` | `right` of the switch |
+| `--aqmb-switch-left` | `auto` | `left` of the switch |
+| `--aqmb-switch-bottom` | `auto` | `bottom` of the switch |
+| `--aqmb-switch-z-index` | `2147483647` | `z-index` of the switch |
+| `--aqmb-switch-size` | `27px` | Side S of the switch's square box; every length of the drawing derives from it |
+| `--aqmb-switch-caption-display` | `block` | `display` of the caption; `none` hides it |
+
+How the drawing follows S:
+
+- The bars are S/9 thick, at 0, 2S/9, 4S/9 and 6S/9 of a stack 7S/9 high. While open, the outer bars become 32S/27 wide and 4S/27 thick and cross at ±45°; the inner bars fade out.
+- The caption's top edge is S/2 + 0.5rem below the top of the stack.
+- With the caption shown (the default) and S below 48px (at a 16px root font size), the column of bars and caption is taller than the box: it starts at the box's top and the caption hangs below the box.
+- With `--aqmb-switch-caption-display: none`, the bars are centred in the box and nothing is drawn above or below it. The cross can still extend slightly past the box's right edge, as it does in the default drawing.
+- The default `27px` gives 3px bars spaced 6px apart, a 32px × 4px cross, and a caption 21.5px below the top of the box.
+- The switch draws in black, and in white on the dark theme and while the drawer is open. Its keyboard focus ring is a 2px outline in the same colour at a 2px offset, so it occupies 4px around the box.
+
+Example — fit the switch into a 32px header bar (4px + 24px line box + 4px):
+
+```css
+:root {
+  --aqmb-switch-size: 24px;
+  --aqmb-switch-caption-display: none;
+  --aqmb-switch-top: 4px;
+}
+```
+
+The box sits on the bar's 24px line box, and the focus ring (0 to 32px from the top) stays inside the bar. Adjust `--aqmb-switch-right` to align it horizontally.
+
 ## Theming
 
-The menu bar supports both light and dark themes. All styles are scoped with the `.aiquants-menu-bar` class to prevent conflicts with your application's styles.
+The menu bar supports both light and dark themes. All styles are scoped with the `.aiquants-menu-bar` class to prevent conflicts with your application's styles. The root element carries the theme as a class: `.aiquants-menu-bar.light` or `.aiquants-menu-bar.dark`.
 
 ### Custom Styling
 
@@ -201,11 +265,11 @@ You can override the default styles by targeting the scoped classes:
   /* Custom menu bar styles */
 }
 
-.aiquants-menu-bar.theme-dark {
+.aiquants-menu-bar.dark {
   /* Dark theme overrides */
 }
 
-.aiquants-menu-bar.theme-light {
+.aiquants-menu-bar.light {
   /* Light theme overrides */
 }
 ```
@@ -247,6 +311,60 @@ function App() {
 }
 ```
 
+## Current Page Highlighting
+
+The menu finds the one entry the current route belongs to, marks its link with `aria-current="page"`, and opens its group. Each top-level item with an `href` and each submenu item can choose how its `href` is matched with `match`:
+
+```tsx
+const menuList: IMenu[] = [
+  { id: 1, title: 'Home', href: '/', submenu: [] },
+  {
+    id: 2,
+    title: 'Admin',
+    submenu: [
+      // Also the current entry on /admin/console/search, /admin/console/users/42, ...
+      { subid: 1, title: 'Console', href: '/admin/console', match: 'prefix' },
+      { subid: 2, title: 'Audit log', href: '/admin/audit' },
+    ],
+  },
+];
+```
+
+The rule:
+
+- `'exact'` (the default) matches the path itself. `'prefix'` also matches every path below the `href` at a segment boundary: `/admin` matches `/admin/users`, not `/administration`. Any other value behaves as `'exact'`.
+- The query, the hash and a trailing slash are ignored on both the `href` and the path.
+- An `href` of `/` matches only the root, even with `'prefix'`. External URLs never match.
+- When several entries match, the longest `href` wins, across groups too; an exact match therefore always beats a prefix match. On a tie, the first entry in menu order wins (a top-level item before its own submenu items).
+
+The group of the matched entry opens once per route change, and only one group is open at a time (pinned groups always stay open). A route with no matching entry leaves the open group as it is, and reloading the menu on the same route does not reopen a group the user closed.
+
+## Accessibility
+
+- **Switch**: a native `<button>` named "Open menu" / "Close menu" (`aria-label`) with `aria-expanded`; the visible caption is `aria-hidden`. Keyboard focus shows a 2px ring (`:focus-visible`).
+- **Closed drawer is inert**: while closed, nothing in the drawer takes focus (by Tab or by script) or appears in the accessibility tree, so the switch is the menu bar's only Tab stop. A pinned drawer stays open and interactive. This relies on the HTML `inert` attribute.
+- **Decorative backdrop**: the dimming layer behind the open drawer is an `aria-hidden` `div` that never takes focus. A pointer press on it closes the drawer without moving the focus; keyboard and assistive-technology users close the drawer with Escape (per `closeOnEscape`) or the switch.
+- **Focus return**: when the drawer closes — by the switch, the backdrop, Escape or selecting an item while not pinned — with the focus inside it, the focus moves to the switch. A focus outside the drawer stays where it is.
+- **Current page**: the matched entry's link carries `aria-current="page"`.
+- **Groups**: group summaries toggle with Enter or Space and show a focus outline on keyboard focus. Every button has an accessible name.
+- **Reduced motion**: the drawer's slide, the backdrop's fade and the switch's transitions run only under `prefers-reduced-motion: no-preference`.
+- **Forced colors**: the switch's bars are drawn in `ButtonText`, so they stay visible when forced colors replace backgrounds.
+
+## DOM Hooks
+
+Select the menu bar's elements in scripts and tests by these attributes (or by role and accessible name). Class names — `.aiquants-*` and utilities — are styling and may change.
+
+| Attribute | Element |
+| --- | --- |
+| `data-aqmb-menu-switch` | The open/close switch button |
+| `data-aqmb-menu-content` | The drawer's root element |
+| `data-aqmb-menu-overlay` | The backdrop |
+| `data-aqmb-menu-list` | The scroll container of the menu list |
+| `data-aqmb-pin-button` | The drawer's pin button |
+| `data-aqmb-theme-button` | The theme toggle button |
+| `data-aqmb-signout-button` | The sign-out button |
+| `data-aqmb-submenu-pin-button` | The pin button of each group |
+
 ## Advanced Usage
 
 ### With Menu Header
@@ -280,7 +398,7 @@ import React from 'react';
   theme={theme}
   toggleTheme={toggleTheme}
   onClickSignout={handleSignout}
-  isMenuhide={shouldHideMenu}
+  isMenuHide={shouldHideMenu}
 />
 ```
 
@@ -290,11 +408,11 @@ import React from 'react';
 
 The main menu bar component that includes:
 
-- Menu toggle button with hamburger icon
-- Company logo and navigation menu
-- Theme toggle functionality
-- Responsive overlay for mobile devices
-- Sign out functionality
+- Open/close switch with four bars that turn into a cross
+- Header slot (`menuHeader`) and navigation menu
+- Pin, theme toggle and sign-out buttons
+- Backdrop that closes the drawer when pressed
+- Focus management and current page highlighting
 
 ### SessionInfo
 
@@ -322,18 +440,21 @@ import { SessionInfo } from '@aiquants/menu-bar';
 
 - **Hierarchical Menu Structure**: Support for main menu items with submenus
 - **Dynamic Navigation**: Menu items can have direct links or submenu collections
+- **Current Page**: Exact or prefix matching per entry, with `aria-current="page"`
 - **Visual Indicators**: Support for special marks (lock icon, etc.) and "new" badges
 - **External Links**: Option to open links in new tabs
 
 ## CSS Classes
 
-All CSS classes are scoped with `.aiquants-` prefix:
+All hand-written CSS classes use the `.aiquants-` prefix, for example:
 
-- `.aiquants-menu-bar` - Main container
-- `.aiquants-menu-switch` - Menu toggle button
-- `.aiquants-menu-content` - Menu content area
-- `.aiquants-session-info` - Session information
-- `.aiquants-overlay-shadow` - Mobile overlay
+- `.aiquants-menu-bar` - Main container (with the theme class `light` or `dark`)
+- `.aiquants-menu-switch` - Open/close switch (`.aiquants-menu-switch-bars`, `.aiquants-menu-switch-bar`, `.aiquants-menu-switch-caption`)
+- `.aiquants-menu-content` - Drawer
+- `.aiquants-menu-list-item` - Menu item and group summary
+- `.aiquants-session-card` - Session information card
+
+These classes are a styling contract, not DOM hooks — use the `data-aqmb-*` attributes above to select elements.
 
 ## Browser Support
 
@@ -346,18 +467,26 @@ All CSS classes are scoped with `.aiquants-` prefix:
 
 ```bash
 # Install dependencies
-npm install
+pnpm install
 
 # Build the package
-npm run build
+pnpm run build
 
 # Run type checking
-npm run typecheck
+pnpm run typecheck
+
+# Run the unit tests (Vitest, jsdom)
+pnpm run test
+
+# Run the browser tests (Playwright, Chromium) against a local harness page
+pnpm run test:e2e
 
 # Clean build files
-npm run clean
+pnpm run clean
 ```
 
+The browser tests start a Vite server for the harness on port `25178`; set `MENU_BAR_E2E_PORT` to use another port, and `MENU_BAR_E2E_REUSE_SERVER=1` to reuse a server that is already running. Install Chromium once with `pnpm exec playwright install chromium` if it is missing.
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) file for details.

package/dist/contents/MenuContent.d.ts

@@ -12,6 +12,7 @@ interface IMenuContentProps {
     onTogglePin(): void;
     pinnedSubmenuIds: number[];
     onToggleSubmenuPin(id: number): void;
+    ref: React.Ref<HTMLDivElement>;
 }
 export declare const MenuContent: (props: IMenuContentProps) => React.JSX.Element;
 export {};

package/dist/contents/MenuList.d.ts

@@ -1,15 +1,18 @@
+export type MenuBarPathMatch = "exact" | "prefix";
 export interface ISubmenu {
     subid: number;
     title?: string;
     href: string;
     mark?: string;
     new?: boolean;
+    match?: MenuBarPathMatch;
 }
 export interface IMenu {
     id: number;
     title: string;
     href?: string;
     submenu: ISubmenu[];
+    match?: MenuBarPathMatch;
 }
 export type MenuNavigationPayload = {
     menu: Pick<IMenu, "id" | "title" | "href">;

package/dist/contents/OverlayShadow.d.ts

@@ -1,6 +1,6 @@
 interface IOverlayProps {
     isOverlay: boolean;
-    onOverlayClick?(): void;
+    onOverlayClick(): void;
 }
 export declare const OverlayShadow: (props: IOverlayProps) => React.JSX.Element;
 export {};

package/dist/elements/MenuSwitch.d.ts

@@ -1,13 +1,8 @@
-import { Theme } from "../types";
-export interface IMenuSwitchProps {
-    open?: boolean;
-    isOpen?: boolean;
-    onMenuOpen?: () => void;
-    onMenuClose?: () => void;
-    onToggle?: (nextOpen: boolean) => void;
-    theme?: Theme;
-    pinned?: boolean;
-    isPinned?: boolean;
-    className?: string;
-}
-export declare const MenuSwitch: (props: IMenuSwitchProps) => React.JSX.Element;
+type MenuSwitchProps = {
+    isMenuOpen: boolean;
+    onMenuOpen(): void;
+    onMenuClose(): void;
+    ref: React.Ref<HTMLButtonElement>;
+};
+export declare const MenuSwitch: ({ isMenuOpen, onMenuOpen, onMenuClose, ref }: MenuSwitchProps) => React.JSX.Element;
+export {};

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export type { LinkProps as MenuBarLinkProps, LinkProps, SessionInfoProps as MenuBarSessionInfoProps, SessionInfoProps } from "./components/SessionInfo";
 export { DefaultLink, SessionInfo } from "./components/SessionInfo";
-export type { IMenu as IMenuBarMenu, IMenu, ISubmenu as IMenuBarSubmenu, ISubmenu, MenuNavigationPayload } from "./contents/MenuList";
+export type { IMenu as IMenuBarMenu, IMenu, ISubmenu as IMenuBarSubmenu, ISubmenu, MenuBarPathMatch, MenuNavigationPayload } from "./contents/MenuList";
 export type { SubscribeMenuPinOptions } from "./events/pinEvent";
 export { dispatchMenuPinChange, getInitialPinState, MENU_PIN_CHANGE_EVENT, subscribeMenuPinChange, } from "./events/pinEvent";
 export type { UseMenuPinStateOptions } from "./hooks/useMenuPinState";