@aiquants/menu-bar 1.17.9 → 1.18.0

package/dist/MenuBar.d.ts

@@ -2,41 +2,46 @@ import { IMenu, MenuNavigationPayload } from './contents/MenuList';
 import { Theme } from './types';
 
 /**
- * @interface IMenuBarProps
- * @description Props for the MenuBar component.
- * @description MenuBar コンポーネントの Props。
- * @property {IMenu[]} menuList - The list of menu items. メニュー項目のリスト。
- * @property {React.ReactNode} [menuHeader] - The header content of the menu. メニューのヘッダーコンテンツ。
- * @property {() => void} onClickSignout - Function to handle sign out. サインアウトを処理する関数。
- * @property {boolean} [isMenuhide] - Whether to hide the menu. メニューを非表示にするかどうか。
- * @property {Theme} theme - The current theme.
- * @property {() => void} toggleTheme - Function to toggle the theme.
- * @property {(payload: MenuNavigationPayload) => void} [onMenuNavigate] - Function to receive menu navigation events. メニュー遷移イベントを受け取る関数。
- * @property {boolean | "auto"} [closeOnEscape] - Controls whether the Escape key closes the menu.
- *   - "auto" (default): closes when NOT pinned, stays open when pinned. ピン留めなしでは閉じ、ピン留め中は閉じない。
- *   - true: always closes on Escape (resets pin if pinned). 常に閉じる。
- *   - false: never closes on Escape. 常に閉じない。
+ * Props interface for the MenuBar component.
+ * MenuBar コンポーネントのプロップスインターフェース。
  */
-interface IMenuBarProps {
+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;
-    onPinChange?(pinned: boolean): 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";
 }
 /**
- * @function MenuBar
- * @description A component that renders the main menu bar.
- * @description メインメニューバーを描画するコンポーネント。
- * @param {IMenuBarProps} props - The props for the component.
- * @returns {React.JSX.Element | null} The rendered menu bar.
+ * 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;
-export {};

package/dist/__tests__/pinEvent.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/contents/MenuContent.d.ts

@@ -5,15 +5,6 @@ import { IMenu, MenuNavigationPayload } from './MenuList';
  * @interface IMenuContentProps
  * @description Props for the MenuContent component.
  * @description MenuContent コンポーネントの Props。
- * @property {IMenu[]} menuList - The list of menu items. メニュー項目のリスト。
- * @property {React.ReactNode} [menuHeader] - The header content of the menu. メニューのヘッダーコンテンツ。
- * @property {boolean} open - Whether the menu is open. メニューが開いているかどうか。
- * @property {(payload: MenuNavigationPayload) => void} onMenuSelected - Function to handle menu item selection. メニュー項目選択を処理する関数。
- * @property {() => void} onClickSignout - Function to handle sign out. サインアウトを処理する関数。
- * @property {Theme} theme - The current theme.
- * @property {() => void} toggleTheme - Function to toggle the theme.
- * @property {boolean} isPinned - Whether the menu is pinned open. メニューがピン留めされているかどうか。
- * @property {() => void} onTogglePin - Function to toggle pin state. ピン留め状態をトグルする関数。
  */
 interface IMenuContentProps {
     menuList: IMenu[];

package/dist/events/pinEvent.d.ts

@@ -0,0 +1,44 @@
+import { MenuPinChangeDetail } from '../types';
+
+/**
+ * Canonical Window CustomEvent name for menu pin state changes.
+ * メニューのピン留め状態変更を通知する正準 CustomEvent 名。
+ */
+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 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

@@ -0,0 +1,21 @@
+import { MenuPinChangeDetail } from '../types';
+
+/**
+ * Options for the useMenuPinState hook.
+ * useMenuPinState フックのオプション。
+ */
+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;

package/dist/index.d.ts

@@ -1,6 +1,21 @@
-export type { LinkProps, SessionInfoProps } from './components/SessionInfo';
+/**
+ * @module index
+ * @description Entry point for @aiquants/menu-bar package exports.
+ * @description @aiquants/menu-bar パッケージのエクスポートエントリーポイント。
+ */
+/** @deprecated Use MenuBarLinkProps instead to avoid namespace collisions. */
+export type { LinkProps as MenuBarLinkProps, LinkProps, SessionInfoProps as MenuBarSessionInfoProps, SessionInfoProps } from './components/SessionInfo';
 export { DefaultLink, SessionInfo } from './components/SessionInfo';
-export type { IMenu, ISubmenu, MenuNavigationPayload } from './contents/MenuList';
+/** @deprecated Use IMenuBarMenu instead to avoid namespace collisions. */
+/** @deprecated Use IMenuBarSubmenu instead to avoid namespace collisions. */
+export type { IMenu as IMenuBarMenu, IMenu, ISubmenu as IMenuBarSubmenu, ISubmenu, 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';
+export { useMenuPinState } from './hooks/useMenuPinState';
+export type { IMenuBarProps } from './MenuBar';
 export { MenuBar } from './MenuBar';
-export type { Theme } from './types';
-export type { UserProfile } from './types/user';
+/** @deprecated Use MenuBarTheme instead to avoid namespace collisions. */
+export type { MenuPinChangeDetail, MenuPinCustomEvent, Theme as MenuBarTheme, Theme } from './types';
+/** @deprecated Use MenuBarUserProfile instead to avoid namespace collisions. */
+export type { UserProfile as MenuBarUserProfile, UserProfile } from './types/user';