@aiquants/menu-bar 1.18.3 → 1.19.1

package/README.md

@@ -4,13 +4,16 @@ 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
+- **Scoped Component CSS**: The hand-written rules are scoped to `.aiquants-*` classes and package-prefixed variables; the standalone build also carries Tailwind utilities and theme variables, which are global (see "Styling (CSS)")
 
 ## Installation
 
@@ -18,20 +21,30 @@ A React menu bar component with authentication support and theming for modern we
 npm install @aiquants/menu-bar
 ```
 
+Peer dependencies: `react` and `react-dom` `^19.2.7`, and `react-router-dom` `^7.7.1`. The package's `engines` field asks for Node.js 18 or later.
+
 ## 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';
@@ -41,11 +54,11 @@ import '@aiquants/menu-bar/styles/menu-bar.standalone.css';
 
 ```tsx
 import React, { useState } from 'react';
-import { MenuBar } from '@aiquants/menu-bar';
+import { MenuBar, type Theme } from '@aiquants/menu-bar';
 import '@aiquants/menu-bar/styles/menu-bar.standalone.css';
 
 function App() {
-  const [theme, setTheme] = useState('light');
+  const [theme, setTheme] = useState<Theme>('light');
 
   const menuList = [
     {
@@ -87,6 +100,8 @@ function App() {
 }
 ```
 
+`MenuBar` renders React Router links, so place it inside a router provider.
+
 ## Props
 
 ### MenuBar Props
@@ -98,9 +113,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 while `true`, but the pin state is still reported: while pinned, `--aiquants-menu-pinned-width` and the pin event keep the pinned width (see "Pin State") |
+| `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 +132,7 @@ interface IMenu {
   title: string;
   href?: string;
   submenu: ISubmenu[];
+  match?: MenuBarPathMatch; // ignored on a group without href
 }
 ```
 
@@ -126,9 +145,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 +195,20 @@ 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";
+  /* consuming the package's sources from a workspace: point @source at its src/**/*.{ts,tsx} instead */
+  @custom-variant dark (&:where(.dark, .dark *));
   ```
 
-  `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).
+  The `@custom-variant` line makes the menu bar's `dark:` utilities follow the `theme` prop: the menu bar's root carries `.dark` while `theme` is `'dark'`. With Tailwind's default `dark` variant (`prefers-color-scheme`), they follow the OS setting instead. The variant applies to your whole build, so your own `dark:` utilities then key off a `.dark` ancestor as well.
+
+  `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:
@@ -186,11 +217,53 @@ The package ships **two CSS artifacts** — pick the one that matches your host.
   @import "@aiquants/menu-bar/styles/menu-bar.standalone.css";
   ```
 
-  Dark mode keys off the `.dark` class — add `.dark` to `<html>` to enable the dark styles.
+  The utilities in this build are global selectors (`.flex`, `.fixed`, `.hidden`, ...), and it declares the Tailwind theme variables it uses on `:root, :host`, so a host element with one of those class names picks up the rule.
+
+  Dark mode follows the `theme` prop: the menu bar's root carries `.dark` while `theme` is `'dark'`, and this build's `dark:` utilities apply to an element with the `.dark` class or inside one, so `<html>` needs no class. A `SessionInfo` rendered outside `MenuBar` takes its dark styles from a `.dark` ancestor of its own. If you also put `.dark` on `<html>`, keep it in step with `theme`: with `theme="light"` it turns on the `dark:` utilities inside the light menu bar while the light colours of the hand-written rules stay, mixing the two palettes.
+
+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` | `calc(infinity)` | `z-index` of the switch. The default computes to the largest integer the browser supports (2147483647 in Chromium), which keeps the switch above the drawer (`z-index` 2147483642) and the backdrop (2147483640) |
+| `--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 |
+
+The `z-index` default is `calc(infinity)` rather than a number because Lightning CSS, which Tailwind v4 builds pass stylesheets through, writes the numbers of custom-property values and `var()` fallbacks with 6 significant digits: `2147483647` would reach the browser as `2147480000`, below the drawer. An override in a stylesheet that also goes through Lightning CSS is rounded the same way when it has 7 or more significant digits. A small value such as `50` is kept as written, and stacks the switch below the drawer and the backdrop.
+
+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. The hand-written styles are scoped with the `.aiquants-menu-bar` class; the utility classes and Tailwind theme variables of the standalone build are global (see "Styling (CSS)"). The root element carries the theme as a class: `.aiquants-menu-bar.light` or `.aiquants-menu-bar.dark`.
 
 ### Custom Styling
 
@@ -201,11 +274,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 */
 }
 ```
@@ -214,10 +287,10 @@ You can override the default styles by targeting the scoped classes:
 
 ```tsx
 import React, { useState } from 'react';
-import { MenuBar } from '@aiquants/menu-bar';
+import { MenuBar, type Theme } from '@aiquants/menu-bar';
 
 function App() {
-  const [theme, setTheme] = useState('light');
+  const [theme, setTheme] = useState<Theme>('light');
 
   const menuList = [
     {
@@ -247,6 +320,89 @@ 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). When the matched entry is a top-level link, no group opens, and the group that was open closes. 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.
+
+## Pin State
+
+The pin button keeps the drawer open, without the backdrop, while the user navigates. When it mounts and whenever the pin state, `pinnedWidth` or the open state changes, the menu bar reports the state in two ways, and it resets both to "not pinned" when it unmounts:
+
+- **CSS variable**: `--aiquants-menu-pinned-width` on `<html>` holds the pinned width (`pinnedWidth`, default `240`) in pixels while pinned, and `0px` otherwise.
+- **Event**: a `CustomEvent` named by `MENU_PIN_CHANGE_EVENT` (`"aiquants-menu-pin-change"`) on `window`. Its `detail` is a `MenuPinChangeDetail`, `{ pinned, width, active? }`: `width` matches the CSS variable, and `active` tells whether the drawer is open or pinned.
+
+These exports read the state:
+
+| Export | Behaviour |
+| --- | --- |
+| `useMenuPinState(options?)` | Returns the current `MenuPinChangeDetail` and re-renders when it changes. Options: `initialPinned` (default `false`) and `defaultPinnedWidth` (default `240`). During server rendering it returns `{ pinned: initialPinned, width: initialPinned ? defaultPinnedWidth : 0 }`, without `active` |
+| `subscribeMenuPinChange(listener, options?)` | Calls `listener` with the `detail` of every event and returns a function that unsubscribes. Options: `immediate` (default `true`: also calls `listener` once right away with `getInitialPinState(defaultPinnedWidth)`) and `defaultPinnedWidth` (default `240`) |
+| `getInitialPinState(defaultPinnedWidth = 240)` | Reads the CSS variable: pinned when it is a positive number of pixels, which is then the width. When the variable is empty or not a number, it reads the `aiquants-menu-pinned` `localStorage` key instead (`"true"`: pinned at `defaultPinnedWidth`); the package stylesheet declares the variable as `0px`, so this happens only while neither the stylesheet nor a menu bar has set it. `active` is that of the last `dispatchMenuPinChange` call (`false` before the first) |
+| `dispatchMenuPinChange(pinned, width, active = pinned)` | Dispatches the event on `window`. The menu bar calls it itself |
+
+```tsx
+import type { ReactNode } from 'react';
+import { useMenuPinState } from '@aiquants/menu-bar';
+
+function Page({ children }: { children: ReactNode }) {
+  const { width } = useMenuPinState();
+  // The pinned drawer covers the right edge of the viewport
+  return <main style={{ paddingRight: width }}>{children}</main>;
+}
+```
+
+## 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.
+- **Built-in labels**: the names and texts are fixed, and no prop localises them. The switch is named in English ("Open menu" / "Close menu", caption "menu" / "close"); the drawer's pin and theme buttons, the sign-out button and the group pin buttons are named in Japanese (for example "ピン留め", "ダークモードに切り替え", "サインアウト"), and `SessionInfo` shows Japanese texts such as "プロフィール" and "ログインしてください".
+
+## 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 |
+| `data-aqmb-session-card` | The `SessionInfo` card, with or without a `user` |
+
 ## Advanced Usage
 
 ### With Menu Header
@@ -280,7 +436,7 @@ import React from 'react';
   theme={theme}
   toggleTheme={toggleTheme}
   onClickSignout={handleSignout}
-  isMenuhide={shouldHideMenu}
+  isMenuHide={shouldHideMenu}
 />
 ```
 
@@ -290,19 +446,21 @@ 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
 
 A standalone session information component that displays:
 
-- User avatar/profile picture
-- User display name
-- Logout functionality with customizable link component
+- The user's avatar (a default icon when `photo` is empty), display name and a "Google Account" label
+- Two links rendered through the customizable `LinkComponent` (default: `DefaultLink`, a plain `<a>`): a profile link to `/` and a link to `https://myaccount.google.com/`
+- A "please sign in" card ("ログインしてください") when `user` is `null`
+
+The card carries `data-aqmb-session-card` in both states. Sign-out is not part of `SessionInfo`: it is the drawer's sign-out button, which calls `onClickSignout`.
 
 ```tsx
 import { SessionInfo } from '@aiquants/menu-bar';
@@ -322,42 +480,56 @@ 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
-- **Visual Indicators**: Support for special marks (lock icon, etc.) and "new" badges
-- **External Links**: Option to open links in new tabs
+- **Current Page**: Exact or prefix matching per entry, with `aria-current="page"`
+- **Visual Indicators**: An icon per submenu `mark` (`report`, `slip`, `table`, `chart`, `download`, `lock`, `href`); any other value, or none, renders the text only
+- **External Links**: `new: true` opens a submenu item in a new tab (`target="_blank"`, `rel="noopener noreferrer"`); it draws no badge
 
 ## CSS Classes
 
-All CSS classes are scoped with `.aiquants-` prefix:
+Hand-written component classes use the `.aiquants-` prefix (the modifiers are the theme class `light` / `dark` on the root and `pinned` on a pinned group's pin button), 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
+
+The menu list's scroll container also carries `hidden-scrollbar`, a class the package does not define, so a host rule of that name applies to it.
+
+These classes are a styling contract, not DOM hooks — use the `data-aqmb-*` attributes above to select elements.
 
 ## Browser Support
 
-- Chrome/Edge 88+
-- Firefox 78+
-- Safari 14+
-- Node.js 18+
+- Chrome/Edge 111+
+- Firefox 128+
+- Safari 16.4+
+
+These are the versions Tailwind CSS v4, which builds both stylesheets, targets. The stylesheets also sit in cascade layers, which an older browser drops whole, and the closed drawer and the backdrop rely on the HTML `inert` attribute.
 
 ## Development
 
 ```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";