@aiquants/menu-bar 1.19.0 → 1.20.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## Unreleased
+
+### Added
+
+- **`--aqmb-switch-target-size` sets the minimum side T of the switch's box (default `0px`).** The box you press is
+  B = max(S, T), where S is `--aqmb-switch-size`; the drawing keeps the side S and stands centred across the box (an
+  inline padding of (B − S) / 2), and the caption's column stands centred in the box when it fits. With the default the
+  box is the drawing, exactly as before, so a host that sets nothing sees no change, also under a coarse pointer: the
+  package never raises T on its own, since the band around the switch belongs to the host. To meet WCAG 2.5.5 (AAA) on
+  touch screens, set T to at least 44px under `@media (pointer: coarse)` where the band holds the box (the README shows
+  a 56px band holding a 48px box), and derive anything laid out beside the switch from the box
+  `max(var(--aqmb-switch-size), var(--aqmb-switch-target-size))` rather than from S.
+
+### Changed
+
+- **The drawer's controls are 44px targets under a coarse pointer.** Under `@media (pointer: coarse)` the footer's pin,
+  theme and sign-out buttons, every link of the menu list (which then fills its row), the group headings and their pin
+  buttons, and the links of `SessionInfo` are at least 2.75rem × 2.75rem (44 × 44px at the default root font size, WCAG
+  2.5.5). The rows lose their block padding there, so a row is exactly its target. With a fine pointer every size stays
+  as it was. Tailwind hosts generate these `pointer-coarse:` utilities from the package's `dist` like the others (they
+  need Tailwind CSS v4.1 or later); the standalone stylesheet carries them.

package/README.md

@@ -13,7 +13,7 @@ A React menu bar component with authentication support and theming for modern we
 - **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
 
@@ -21,6 +21,8 @@ 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, functions and types:
@@ -52,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 = [
     {
@@ -111,7 +113,7 @@ 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 (renders nothing) |
+| `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 |
 | `isPinned` | `boolean` | No | Controlled pin state. When omitted, the menu bar keeps the pin state itself and stores it in `localStorage` |
@@ -193,15 +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's built JavaScript (the published package ships `dist`, not `src`; the class names stay intact in the bundle):
+- **Tailwind v4 host** (Tailwind CSS v4.1 or later) — 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/dist/**/*.js";
-  /* the package as a workspace sibling: @source "../../../../packages/menu-bar/src/**/*.{ts,tsx}"; */
+  /* consuming the package's sources from a workspace: point @source at its src/**/*.{ts,tsx} instead */
+  @custom-variant dark (&:where(.dark, .dark *));
   ```
 
+  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.
+
+  The drawer's sizes under a coarse pointer (see the end of "Menu Switch Custom Properties") are `pointer-coarse:` utilities, a variant Tailwind CSS v4.1 introduced. A v4.0 build drops those classes without an error, and the drawer's controls then keep their fine-pointer sizes on touch screens.
+
   `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.
@@ -212,13 +219,15 @@ 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).
+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. The drawing has the side S; the box you press has the side B = max(S, T), where T is a target size you may set, with the drawing centred across it. 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 |
 | --- | --- | --- |
@@ -227,16 +236,19 @@ The open/close switch is a square box with four bars that turn into a cross whil
 | `--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-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 drawing; every length of the drawing derives from it |
+| `--aqmb-switch-target-size` | `0px` | Minimum side T of the box you press: the box is B = max(S, T), and the drawing keeps its size, centred across the box by an inline padding of (B − S) / 2. The default leaves B = S. The package never raises it on its own, under a coarse pointer either: only you know whether a larger box fits the band around the switch |
 | `--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 column of bars and caption is S/2 + 1.5rem tall. With the caption shown (the default) and a box B below that (B = S below 48px at a 16px root font size), the column is taller than the box: it starts at the box's top and the caption hangs below the box. In a box that holds it (the default S = 27px in a 44px box, for one), the column stands centred in the box.
+- With `--aqmb-switch-caption-display: none`, the bars are centred in the box (their stack starts (B − 7S/9) / 2 below its top) 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.
 
@@ -252,9 +264,31 @@ Example — fit the switch into a 32px header bar (4px + 24px line box + 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.
 
+Example — a 44px target on touch screens (WCAG 2.5.5, AAA). Under a coarse pointer, set the target size to at least 44px where your band allows it, and grow the band to hold the box. A 32px bar built as 4px + line box + 4px on a 4px lattice keeps its height on that lattice when the line box becomes the smallest multiple of 8px that is at least 44px, 48px, so the band becomes 4px + 48px + 4px = 56px:
+
+```css
+:root {
+  --aqmb-switch-size: 24px;
+  --aqmb-switch-caption-display: none;
+  --aqmb-switch-top: 4px;
+  --aqmb-switch-target-size: 24px;
+}
+
+@media (pointer: coarse) {
+  :root {
+    --aqmb-switch-target-size: 48px;
+  }
+}
+```
+
+The drawing stays 24px and the box becomes 48 × 48 with 12px of inline padding, at 4px from the top; its focus ring spans 0 to 56px, exactly the band. Anything you lay out beside the switch should reserve the box B rather than the drawing S (for example `max(var(--aqmb-switch-size), var(--aqmb-switch-target-size))`).
+
+Under a coarse pointer the drawer's own controls are at least 2.75rem × 2.75rem (44 × 44 px at the default root font size): the footer's pin, theme and sign-out buttons, every link of the list (it then fills its row), the group headings and their pin buttons, and the links of `SessionInfo`.
+With a fine pointer they are sized by their content: the footer's buttons are 1.75rem tall; a list link is its text, in a row with 0.25rem of block padding (0.125rem inside a group); a group heading is its text with 0.25rem of block padding, and its pin button a 13px icon with 0.15rem of padding; a `SessionInfo` link is one line of 11px text with 0.25rem of block padding.
+
 ## 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 root element carries the theme as a class: `.aiquants-menu-bar.light` or `.aiquants-menu-bar.dark`.
+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
 
@@ -278,10 +312,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 = [
     {
@@ -337,7 +371,34 @@ The rule:
 - 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.
+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
 
@@ -349,6 +410,7 @@ The group of the matched entry opens once per route change, and only one group i
 - **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
 
@@ -364,6 +426,7 @@ Select the menu bar's elements in scripts and tests by these attributes (or by r
 | `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
 
@@ -418,9 +481,11 @@ The main menu bar component that includes:
 
 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';
@@ -441,12 +506,12 @@ 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
+- **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 hand-written CSS classes use the `.aiquants-` prefix, for example:
+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 (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`)
@@ -454,14 +519,17 @@ All hand-written CSS classes use the `.aiquants-` prefix, for example:
 - `.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