@aiquants/menu-bar 1.18.2 → 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/MenuBar.d.ts

@@ -1,47 +1,20 @@
-import { IMenu, MenuNavigationPayload } from './contents/MenuList';
-import { Theme } from './types';
-
-/**
- * Props interface for the MenuBar component.
- * MenuBar コンポーネントのプロップスインターフェース。
- */
+import { IMenu, MenuNavigationPayload } from "./contents/MenuList";
+import { Theme } from "./types";
 export interface IMenuBarProps {
-    /** List of menu items. メニュー項目のリスト。 */
     menuList: IMenu[];
-    /** Optional header content rendered at top of menu drawer. メニューヘッダー要素。 */
     menuHeader?: React.ReactNode;
-    /** Callback handler for sign out button click. サインアウト処理ハンドラー。 */
     onClickSignout(): void;
-    /** Whether to hide the menu bar (legacy camelCase). メニュー非表示フラグ（旧表記）。 */
     isMenuhide?: boolean;
-    /** Whether to hide the menu bar. メニュー非表示フラグ。 */
     isMenuHide?: boolean;
-    /** Current active color theme. 現在のテーマ。 */
     theme: Theme;
-    /** Toggle handler for switching color theme. テーマ切り替えハンドラー。 */
     toggleTheme: () => void;
-    /** Navigation callback when a menu item is selected. メニュー遷移ハンドラー。 */
     onMenuNavigate?(payload: MenuNavigationPayload): void;
-    /** Controlled pinning state (optional). ピン留め状態制御プロップ。 */
     isPinned?: boolean;
-    /** Custom width in pixels when menu is pinned (default: 240). ピン留め時の幅(px)。 */
     pinnedWidth?: number;
-    /** Callback invoked when menu pin state changes. ピン留め状態変更時のコールバック。 */
     onPinChange?(pinned: boolean, widthPx: number): void;
-    /** Controlled list of pinned submenu IDs. ピン留めサブメニューIDリスト（制御）。 */
     pinnedSubmenuIds?: number[];
-    /** Initial list of pinned submenu IDs for uncontrolled mode. ピン留めサブメニューID初期リスト。 */
     initialPinnedSubmenuIds?: number[];
-    /** Callback invoked when submenu pin state changes. サブメニューピン留め変更時コールバック。 */
     onSubmenuPinChange?(pinnedIds: number[]): void;
-    /** Controls whether the Escape key closes the menu drawer. Escape キーによるメニュー閉鎖制御。 */
     closeOnEscape?: boolean | "auto";
 }
-/**
- * Renders the primary collapsible and pinnable menu bar with drawer navigation.
- * 折りたたみ・ピン留め対応のプライマリメニューバーコンポーネント。
- *
- * @param props - MenuBarProps configuration.
- * @returns Rendered JSX element or null.
- */
 export declare const MenuBar: (props: IMenuBarProps) => React.JSX.Element | null;

package/dist/components/SessionInfo.d.ts

@@ -1,37 +1,12 @@
-import { UserProfile } from '../types/user';
-
-/**
- * Link component props interface.
- * リンクコンポーネントのプロパティ。
- */
+import { UserProfile } from "../types/user";
 export interface LinkProps {
-    /** Link destination URL */
     to: string;
-    /** CSS class name */
     className?: string;
-    /** Link content */
     children: React.ReactNode;
 }
-/**
- * Generic Link component that can be replaced with router-specific implementation.
- * ルーター固有の実装で置き換え可能な汎用リンクコンポーネント。
- */
 export declare const DefaultLink: ({ to, className, children }: LinkProps) => React.JSX.Element;
-/**
- * SessionInfo component props interface.
- * ユーザーセッション情報を表示するコンポーネントのプロパティ。
- */
 export interface SessionInfoProps {
-    /** User profile information from Google OAuth */
     user: UserProfile | null;
-    /** Custom Link component (optional, defaults to DefaultLink) */
     LinkComponent?: React.ComponentType<LinkProps>;
 }
-/**
- * SessionInfo component for displaying user session information.
- * Displays user profile photo, navigation links, and user name when authenticated.
- *
- * ユーザーセッション情報を表示するコンポーネント。
- * 認証時にプロフィール写真、ナビゲーションリンク、ユーザー名を表示する。
- */
 export declare const SessionInfo: (props: SessionInfoProps) => React.JSX.Element;

package/dist/contents/MenuContent.d.ts

@@ -1,11 +1,5 @@
-import { Theme } from '../types';
-import { IMenu, MenuNavigationPayload } from './MenuList';
-
-/**
- * @interface IMenuContentProps
- * @description Props for the MenuContent component.
- * @description MenuContent コンポーネントの Props。
- */
+import { Theme } from "../types";
+import { IMenu, MenuNavigationPayload } from "./MenuList";
 interface IMenuContentProps {
     menuList: IMenu[];
     menuHeader?: React.ReactNode;
@@ -18,12 +12,7 @@ interface IMenuContentProps {
     onTogglePin(): void;
     pinnedSubmenuIds: number[];
     onToggleSubmenuPin(id: number): void;
+    ref: React.Ref<HTMLDivElement>;
 }
-/**
- * Renders the content of the menu bar.
- * メニューバーのコンテンツを描画します。
- * @param {IMenuContentProps} props - The properties for the MenuContent component.
- * @returns {React.JSX.Element} The rendered menu content.
- */
 export declare const MenuContent: (props: IMenuContentProps) => React.JSX.Element;
 export {};

package/dist/contents/MenuList.d.ts

@@ -1,58 +1,23 @@
-/**
- * @module MenuList
- * @description This module provides the list of menu items.
- * @description このモジュールは、メニュー項目のリストを提供します。
- */
-/**
- * @interface ISubmenu
- * @description Interface for a submenu item.
- * @description サブメニュー項目のインターフェース。
- * @property {number} subid - The unique ID of the submenu item. サブメニュー項目の一意の ID。
- * @property {string} [title] - The title of the submenu item. サブメニュー項目のタイトル。
- * @property {string} href - The URL for the submenu item. サブメニュー項目の URL。
- * @property {string} [mark] - The type of mark to display next to the item. 項目の横に表示するマークの種類。
- * @property {boolean} [new] - Whether the item is a new link. 新しいリンクかどうか。
- */
+export type MenuBarPathMatch = "exact" | "prefix";
 export interface ISubmenu {
     subid: number;
     title?: string;
     href: string;
     mark?: string;
     new?: boolean;
+    match?: MenuBarPathMatch;
 }
-/**
- * @interface IMenu
- * @description Interface for a menu item.
- * @description メニュー項目のインターフェース。
- * @property {number} id - The unique ID of the menu item. メニュー項目の一意の ID。
- * @property {string} title - The title of the menu item. メニュー項目のタイトル。
- * @property {string} [href] - The URL for the menu item. メニュー項目の URL。
- * @property {ISubmenu[]} submenu - The list of submenu items. サブメニュー項目のリスト。
- */
 export interface IMenu {
     id: number;
     title: string;
     href?: string;
     submenu: ISubmenu[];
+    match?: MenuBarPathMatch;
 }
-/**
- * @typedef MenuNavigationPayload
- * @description Payload emitted when a menu or submenu item is selected.
- * @description メニューまたはサブメニューが選択された際に発火するペイロード。
- * @property {{ id: number; title: string; href?: string }} menu - Selected menu metadata.
- * @property {{ subid: number; title?: string; href: string; mark?: string; new?: boolean }} [submenu] - Selected submenu metadata.
- */
 export type MenuNavigationPayload = {
     menu: Pick<IMenu, "id" | "title" | "href">;
     submenu?: Pick<ISubmenu, "subid" | "title" | "href" | "mark" | "new">;
 };
-/**
- * @interface IMenuListProps
- * @description Props for the MenuList component.
- * @description MenuList コンポーネントの Props。
- * @property {IMenu[]} menuList - The list of menu items. メニュー項目のリスト。
- * @property {(payload: MenuNavigationPayload) => void} [onMenuSelected] - Function to handle menu item selection. メニュー項目選択を処理する関数。
- */
 interface IMenuListProps {
     menuList: IMenu[];
     onMenuSelected?(payload: MenuNavigationPayload): void;

package/dist/contents/OverlayShadow.d.ts

@@ -1,25 +1,6 @@
-/**
- * @module OverlayShadow
- * @description This module provides an overlay shadow component.
- * @description このモジュールは、オーバーレイシャドウコンポーネントを提供します。
- */
-/**
- * @interface IOverlayProps
- * @description Props for the OverlayShadow component.
- * @description OverlayShadow コンポーネントの Props。
- * @property {boolean} isOverlay - Whether the overlay is visible. オーバーレイが表示されているかどうか。
- * @property {() => void} [onOverlayClick] - Function to handle overlay click. オーバーレイのクリックを処理する関数。
- */
 interface IOverlayProps {
     isOverlay: boolean;
-    onOverlayClick?(): void;
+    onOverlayClick(): void;
 }
-/**
- * @function OverlayShadow
- * @description A component that renders an overlay shadow.
- * @description オーバーレイシャドウを描画するコンポーネント。
- * @param {IOverlayProps} props - The props for the component.
- * @returns {React.JSX.Element} The rendered overlay shadow.
- */
 export declare const OverlayShadow: (props: IOverlayProps) => React.JSX.Element;
 export {};

package/dist/elements/MenuSwitch.d.ts

@@ -1,22 +1,8 @@
-import { Theme } from '../types';
-
-export interface IMenuSwitchProps {
-    /**
-     * MenuBar コンポーネントからの指示:
-     * open === true (または !isOpen): メニューは「閉じている」状態 ➔ 4本線ハンバーガーを表示
-     * open === false (または isOpen): メニューは「開いている」状態 ➔ ✕印を表示
-     */
-    open?: boolean;
-    isOpen?: boolean;
-    onMenuOpen?: () => void;
-    onMenuClose?: () => void;
-    onToggle?: (nextOpen: boolean) => void;
-    theme?: Theme;
-    pinned?: boolean;
-    isPinned?: boolean;
-    className?: string;
-}
-/**
- * 4本線バーと✕印アニメーションの従前の仕様の MenuSwitch コンポーネント。
- */
-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/events/pinEvent.d.ts

@@ -1,44 +1,9 @@
-import { MenuPinChangeDetail } from '../types';
-
-/**
- * Canonical Window CustomEvent name for menu pin state changes.
- * メニューのピン留め状態変更を通知する正準 CustomEvent 名。
- */
+import { MenuPinChangeDetail } from "../types";
 export declare const MENU_PIN_CHANGE_EVENT = "aiquants-menu-pin-change";
-/**
- * Reads initial pin state safely from document CSS variable or localStorage.
- * document の CSS 変数または localStorage から初期のピン留め状態を安全に読み取ります。
- *
- * @param defaultPinnedWidth - Default width in pixels when pinned (default: 240).
- * @returns Current MenuPinChangeDetail object.
- */
 export declare const getInitialPinState: (defaultPinnedWidth?: number) => MenuPinChangeDetail;
-/**
- * Dispatches a CustomEvent on window with menu pin state details.
- * window に対してメニューピン留め状態変更カスタムイベントを発行します。
- *
- * @param pinned - Whether the menu is pinned.
- * @param width - The pinned width in pixels.
- */
-export declare const dispatchMenuPinChange: (pinned: boolean, width: number) => void;
-/**
- * Options for subscribing to menu pin state changes.
- * メニューピン留め状態購読時のオプション。
- */
+export declare const dispatchMenuPinChange: (pinned: boolean, width: number, active?: boolean) => void;
 export interface SubscribeMenuPinOptions {
-    /** Whether to immediately invoke the listener with the current state upon subscription (default: true). 購読開始時に即座に現在の状態を通知するかどうか。 */
     immediate?: boolean;
-    /** Default width when pinned (default: 240). ピン留め時のデフォルト幅。 */
     defaultPinnedWidth?: number;
 }
-/**
- * Subscribes a listener to menu pin state changes on window.
- * Returns an unsubscription cleanup function.
- * window 上のメニューピン留め状態変更イベントを購読します。
- * クリーンアップ関数を返します。
- *
- * @param listener - Callback invoked on pin state changes.
- * @param options - Subscription options (e.g. immediate notification).
- * @returns Cleanup function to unsubscribe.
- */
 export declare const subscribeMenuPinChange: (listener: (detail: MenuPinChangeDetail) => void, options?: SubscribeMenuPinOptions) => (() => void);

package/dist/hooks/useMenuPinState.d.ts

@@ -1,21 +1,6 @@
-import { MenuPinChangeDetail } from '../types';
-
-/**
- * Options for the useMenuPinState hook.
- * useMenuPinState フックのオプション。
- */
+import { MenuPinChangeDetail } from "../types";
 export interface UseMenuPinStateOptions {
-    /** Initial pinned state for server-side rendering (default: false). SSR 時の初期ピン留め状態。 */
     initialPinned?: boolean;
-    /** Default width when pinned in pixels (default: 240). デフォルトのピン留め幅。 */
     defaultPinnedWidth?: number;
 }
-/**
- * React hook for consuming components to seamlessly subscribe to menu pin state changes.
- * Hydration-safe, re-render optimized via React 18 useSyncExternalStore.
- * 利用側 React コンポーネントがメニューのピン留め状態および幅をシームレスに購読するためのカスタムフック。
- *
- * @param options - Optional initial pin state and width configuration.
- * @returns Current MenuPinChangeDetail ({ pinned: boolean, width: number }).
- */
 export declare const useMenuPinState: (options?: UseMenuPinStateOptions) => MenuPinChangeDetail;