@aiquants/resize-panels 1.8.1 → 2.0.0

package/README.md

@@ -1,36 +1,39 @@
 # @aiquants/resize-panels
 
-React 向けのリサイズ可能なパネルレイアウトコンポーネント集です。`~/components/elements/ResizablePanels` で培ったロジックをパッケージ化し、任意のアプリケーションから再利用できるようにしました。
+Resizable panel layout components for React, built on one rule: **there is a single function that decides panel sizes, and the handle is the boundary rather than a thing positioned near it.**
 
-## 主な特徴
+Every state change — first paint, container resize, drag, collapse, restored layout — runs the same allocator, so the panels always fill the container exactly and the handle can never drift away from the edge it moves.
 
-- `PanelGroup` と `Panel` と `PanelResizeHandle` を中核に、リデューサーでレイアウトと DOM 計測を同期
-- `calculateSnapThreshold` とノイズ除去ロジックでリサイズ時の揺らぎを抑え、意図しない折りたたみを防止
-- 方向指定付き `collapsible` 設定と `usePanelControls` により、ドラッグ操作と UI 操作の両方で折りたたみ / 展開を制御
-- リサイズハンドルはマウス／タッチのドラッグに加え、**矢印キーによるキーボードリサイズ**にも対応（Shift 併用で 5 倍ステップ）。マルチタッチや `pointercancel` の割込みでもドラッグ状態が壊れない
-- `dir="rtl"` の **RTL レイアウト**でも、ドラッグ・キーボード・ハンドル位置が視覚方向に一致
-- `autoSaveId` を指定するとローカルストレージにパネルサイズを自動保存し、再読み込み時に復元（初期化確定後のサイズのみ保存）
-- `showDebugInfo` を使えば `PanelDebugInfo` とグローバルオーバーレイで計測結果や制約違反を可視化（デバッグ UI は遅延読み込みで、未使用時は本番バンドルに含まれない）
+## Key Features
 
-## インストール
+- **One allocator, one geometry**: `allocatePanelSizes` distributes the container among the panels (proportional water-filling with per-panel minimum/maximum bounds). `Σ panel sizes == the group's content box` holds after every transition the declared bounds allow, and the reducer logs a breach of that invariant rather than letting it pass silently — a container the minimums overflow, or that the maximums cannot reach, is reported as a constraint violation instead.
+- **A handle that cannot drift**: the resize handle renders a zero-length in-flow flex item at the boundary and draws its hit area symmetrically around it. Nothing computes its position, so it stays on the boundary in LTR and RTL, horizontal and vertical, with group padding, and during every frame of a live container resize. A drag divides the pointer's travel by the group's visual scale, so the grab point stays under the cursor even below a transformed ancestor.
+- **Predictable proportions**: a flexible panel's size is a weight — only the ratio between weights matters, unless the panel declares `flexAdjustPriority`, which reads the same number as a claim on that share of the container. A dragged layout becomes a fixed point of the allocator, so it survives the next resize as a ratio instead of snapping back.
+- **Directional Collapsible Control**: declarative `collapsible` settings (`from: 'start' | 'end' | 'both'`) and the `usePanelControls` hook support collapsing/expanding from drags and from UI controls; expanding restores the layout the panel had before it closed.
+- **Keyboard & Touch Accessibility**: handles are `role="separator"` widgets whose `aria-valuenow` / `aria-valuemin` / `aria-valuemax` publish the boundary and the travel *this* handle can reach, collapsing included; a collapsed neighbour is reported as length 0 rather than making the values disappear. Arrow keys resize (5x step with Shift), reopen a collapsed neighbour from the side it closed towards and collapse a panel the pair's travel cannot shrink further, while a handle with nowhere to go leaves the key to the page. A drag needs the primary button and survives multi-touch and `pointercancel`.
+- **Auto-Persistence**: set `autoSaveId` to store each panel's open length and collapsed flag in `localStorage` next to its panel id, so a layout saved by a different set of panels is rejected instead of being applied by position.
+- **Debug & Visualization**: enable `showDebugInfo` to inspect allocations through the per-panel `PanelDebugInfo` badge and a global overlay (lazily imported; production bundles without it create no per-panel observers at all). A constraint violation needs no flag: the group draws its own placeholder over the panels whenever the allocator reports one.
 
-ワークスペース内で利用する場合は `pnpm` を利用します。
+## Installation
 
-```bash
-pnpm add @aiquants/resize-panels
-```
+Monorepo workspace dependency:
 
-モノレポ内から参照する場合は `package.json` に次のように記載します。
-
-```json
+```jsonc
+// consumer package.json
 {
-    "dependencies": {
-        "@aiquants/resize-panels": "workspace:*"
-    }
+  "dependencies": {
+    "@aiquants/resize-panels": "workspace:*"
+  }
 }
 ```
 
-## クイックスタート
+Standard package manager installation:
+
+```bash
+pnpm add @aiquants/resize-panels
+```
+
+## Quick Start
 
 ```tsx
 import { useId } from "react"
@@ -40,38 +43,38 @@ export const Example = () => {
     const baseId = useId()
 
     return (
-        <PanelGroup id={`${baseId}-group`} direction="horizontal" className="h-96">
+        <PanelGroup id={`${baseId}-group`} direction="horizontal" style={{ height: "24rem" }}>
             <Panel id={`${baseId}-left`} defaultSize={{ value: 200, unit: "pixels" }} className="bg-slate-100">
-                左パネル
+                Left Panel
             </Panel>
             <PanelResizeHandle id={`${baseId}-handle`} />
             <Panel id={`${baseId}-right`} defaultSize={{ value: 60, unit: "percentage" }} className="bg-slate-50">
-                右パネル
+                Right Panel
             </Panel>
         </PanelGroup>
     )
 }
 ```
 
-### 折りたたみを有効にする
+### Enabling Collapsible Panels
 
-`Panel` に `collapsible={{ from: "start" }}` や `collapsible={{ from: "end" }}` を指定すると、対応する `PanelResizeHandle` を端までドラッグしたタイミングで自動的に折りたたみ・展開が行われます。`defaultCollapsed` を併用すると初期状態を折りたたみ済みに設定できます。方向指定は必須で、各パネルがどちら側から折りたためるかを宣言します。両方向に対応したい場合は `collapsible={{ from: "both" }}` を使用します。
+Specify `collapsible={{ from: "start" }}` or `collapsible={{ from: "end" }}` on a `Panel` to enable automatic collapse/expand when dragging the corresponding handle to container boundaries. Set `defaultCollapsed` to set initial state to collapsed. Use `collapsible={{ from: "both" }}` to allow collapsing from either edge.
 
 ```tsx
-<PanelGroup direction="horizontal" className="h-96">
+<PanelGroup direction="horizontal" style={{ height: "24rem" }}>
     <Panel id="sidebar" defaultSize={{ value: 240, unit: "pixels" }} collapsible={{ from: "end" }}>
-        サイドバー
+        Sidebar
     </Panel>
     <PanelResizeHandle id="handle" />
     <Panel id="main" defaultSize={{ value: 60, unit: "percentage" }}>
-        メインコンテンツ
+        Main Content
     </Panel>
 </PanelGroup>
 ```
 
-### UI から折りたたみ / 展開を切り替える
+### Programmatic Controls via Hook
 
-`usePanelControls(panelId)` フックを使うと、任意の UI から対象パネルを折りたたみ・展開・トグルできます。ボタンを配置するコンポーネントは `PanelGroup` の配下（コンテキスト内）に置いてください。折りたたみ後もボタンを表示したい場合は、別パネルやヘッダーなど常に可視な場所に設置します。API は方向を必須パラメーターとして受け取り、パネル構成に応じて呼び出し側で指定します。
+Use `usePanelControls(panelId)` inside any child component of `PanelGroup` to trigger collapse, expand, or toggle actions:
 
 ```tsx
 import { PanelGroup, Panel, PanelResizeHandle, usePanelControls } from "@aiquants/resize-panels"
@@ -84,134 +87,236 @@ const PanelToggleButtons = ({ panelId, label }: { panelId: string; label: string
         <div className="flex items-center gap-2">
             <span>{label}</span>
             <button onClick={() => collapse(direction)} disabled={(!canCollapseFromStart && !canCollapseFromEnd) || isCollapsed}>
-                折りたたむ
+                Collapse
             </button>
             <button onClick={() => expand(direction)} disabled={!isCollapsed || (!canCollapseFromStart && !canCollapseFromEnd)}>
-                展開する
+                Expand
             </button>
             <button onClick={() => toggle(direction)} disabled={!canCollapseFromStart && !canCollapseFromEnd}>
-                {isCollapsed ? "展開に切り替え" : "折りたたみに切り替え"}
+                {isCollapsed ? "Switch to Expand" : "Switch to Collapse"}
             </button>
         </div>
     )
 }
 
 export const Example = () => (
-    <PanelGroup direction="horizontal" className="h-96">
+    <PanelGroup direction="horizontal" style={{ height: "24rem" }}>
         <Panel id="sidebar" defaultSize={{ value: 240, unit: "pixels" }} collapsible={{ from: "end" }}>
-            <PanelToggleButtons panelId="sidebar" label="サイドバー" />
+            <PanelToggleButtons panelId="sidebar" label="Sidebar" />
         </Panel>
         <PanelResizeHandle id="split" />
         <Panel id="main" defaultSize={{ value: 60, unit: "percentage" }}>
-            <PanelToggleButtons panelId="details" label="詳細パネル" />
+            <PanelToggleButtons panelId="details" label="Details Panel" />
         </Panel>
         <PanelResizeHandle id="split-right" />
         <Panel id="details" defaultSize={{ value: 40, unit: "percentage" }} collapsible={{ from: "start" }}>
-            詳細
+            Details
         </Panel>
     </PanelGroup>
 )
 ```
 
-`collapse(direction)` は指定方向からパネルを非表示にし、`expand(direction)` はドラッグ操作と同じロジックで直前のサイズや推奨サイズを復元します。`toggle(direction)` を使うと現在の状態に応じて自動的に切り替わります。
+## Component API
 
-## コンポーネント API
+### PanelGroup Properties
 
-### PanelGroup の主なプロパティ
-
-| プロパティ | 型 | 説明 |
+| Property | Type | Description |
 | --- | --- | --- |
-| `id` | `string` | `data-panel-group-id` にも反映される識別子。複数グループを並べる場合は指定を推奨 |
-| `direction` | `'horizontal' \| 'vertical'` | パネルの配置方向 |
-| `className` / `style` | `string` / `React.CSSProperties` | コンテナの見た目を調整するための追加スタイル |
-| `children` | `React.ReactNode` | グループ内の `Panel` と `PanelResizeHandle` を並べるための子要素 |
-| `showDebugInfo` | `boolean` | `PanelDebugInfo` とグローバルオーバーレイを表示して計測結果と制約違反を可視化 |
-| `onLayout` | `(sizes: number[]) => void` | リサイズや初期化のたびに最新のピクセルサイズ配列を通知 |
-| `autoSaveId` | `string` | 指定すると `localStorage` にパネルサイズを保存・復元 |
+| `id` | `string` | Group identifier (reflected in `data-panel-group-id`). Recommended when mounting multiple groups |
+| `direction` | `'horizontal' \| 'vertical'` | Panel layout orientation |
+| `className` / `style` | `string` / `React.CSSProperties` | Additional styling for the container |
+| `children` | `React.ReactNode` | `Panel` and `PanelResizeHandle` child elements |
+| `showDebugInfo` | `boolean` | Enables the per-panel `PanelDebugInfo` badge and the global debug overlay |
+| `onLayout` | `(sizes: number[]) => void` | Callback emitting updated pixel size arrays on resize/init |
+| `autoSaveId` | `string` | Key used to automatically persist and restore panel sizes in `localStorage` |
 
-### Panel の主なプロパティ
+### Panel Properties
 
-| プロパティ | 型 | 説明 |
+| Property | Type | Description |
 | --- | --- | --- |
-| `id` | `string` | パネル識別子。省略時はランダム生成だが、SSR との整合のため明示指定を推奨 |
-| `defaultSize` | `{ value: number; unit: 'pixels' \| 'percentage' } \| number` | 初期サイズ。数値のみの場合はパーセンテージとして扱う |
-| `minSize` / `maxSize` | `FlexibleSize` | パネルの最小・最大サイズ制約。ピクセル・割合で指定可能 |
-| `collapsible` | `{ from: 'start' \| 'end' \| 'both' }` | 折りたたみ方向の宣言。ドラッグや API 呼び出しで利用される必須設定 |
-| `defaultCollapsed` | `boolean` | 初期状態を折りたたみ済みにするかどうか |
-| `pixelAdjustPriority` | `number` | 余白調整時にピクセル基準パネルへ割り当てる優先度 |
-| `className` / `style` | `string` / `React.CSSProperties` | パネル本体の見た目をカスタマイズ |
-
-### PanelResizeHandle の主なプロパティ
-
-| プロパティ | 型 | 説明 |
+| `id` | `string` | Panel identifier (reflected in `data-panel-id`). Optional — a `useId`-derived id is generated when omitted — but fixed at mount: a later change is ignored with a warning |
+| `defaultSize` | `{ value: number; unit: 'pixels' \| 'percentage' } \| number` | Initial panel size (numbers parsed as percentages; `50%` when omitted) |
+| `minSize` / `maxSize` | `FlexibleSize` | Panel size boundaries (pixels or percentages) |
+| `collapsible` | `{ from: 'start' \| 'end' \| 'both' }` | Declarative collapsible edge configuration |
+| `defaultCollapsed` | `boolean` | Whether the panel starts collapsed |
+| `pixelAdjustPriority` | `number` | Order in which pixel panels are served when space is scarce (higher first) |
+| `flexAdjustPriority` | `number` | Serving order among flexible panels (higher first); declaring it also reads `defaultSize` as an absolute claim on that share of the container |
+| `contentOverflow` | `React.CSSProperties["overflow"]` | Overflow of the panel's content wrapper (`auto` by default) |
+| `className` / `style` | `string` / `React.CSSProperties` | Panel container styles |
+
+`Panel` and `PanelGroup` forward any other DOM attribute (`data-testid`, `aria-*`, event handlers) to their
+element, except the ones they compute themselves: `Panel` owns `aria-hidden`, which follows the collapsed state,
+and its own `data-panel-*` attributes, while `PanelGroup` owns `data-panel-group-id` and
+`data-panel-group-direction` — the first is what `getPanelGroupElement` looks up, the second is what marks an
+element as a group for `findOwningGroup` and therefore for every handle. `aria-hidden` is removed
+from `PanelProps` to state that ownership, but TypeScript does not type-check JSX attribute names containing a
+hyphen, so neither it nor a `data-panel-*` / `data-panel-group-*` of your own is rejected at compile time: what
+enforces the contract is the runtime override, which applies these attributes after everything you forwarded. A
+`data-panel-group-id` you pass disappears altogether when the group itself has no `id`. Both elements merge your
+`className` with their own (`panel` / `panel-group`) instead of replacing it.
+
+### PanelResizeHandle Properties
+
+| Property | Type | Description |
 | --- | --- | --- |
-| `id` | `string` | ハンドル識別子。省略時はランダム生成 |
-| `disabled` | `boolean` | `true` にするとドラッグ・キーボード操作を無効化 |
-| `onDragging` | `(isDragging: boolean) => void` | ドラッグ開始 / 終了ごとに呼び出されるコールバック（`pointercancel` 等の割込みでも終了時に発火） |
-| `className` / `style` | `string` / `React.CSSProperties` | ハンドル見た目を追加カスタマイズ |
-| `children` | `React.ReactNode` | 独自のハンドルインジケーターを描画する場合に使用 |
-
-> ハンドルは `<button>` としてレンダリングされ、フォーカス時に矢印キー（水平なら `←` / `→`、垂直なら `↑` / `↓`）でリサイズできます。`Shift` 併用で 1 押下あたりの移動量が 5 倍になります。`dir="rtl"` のコンテナ内ではドラッグ・キーボードの方向が視覚方向に合わせて反転します。
-
-## フックとユーティリティ
-
-- `useResizablePanels`: `PanelGroup` 内部実装でも利用しているフック。カスタムコンテナを作る場合に役立ちます。
-- `usePanelGroup`: コンテキストを直接参照し、パネルリストやレイアウト情報を取得できます。
-- `usePanelControls`: 特定パネルに対する折りたたみ / 展開操作を提供します。
-- `saveLayout` と `loadLayout`: 任意のタイミングでレイアウトを永続化 / 復元できます。
-- `getPanelElement`, `getPanelGroupElement`, `getResizeHandleElement`: `data-*` 属性をもとに DOM 要素を取得します。
-
-## レイアウト保存と復元
-
-`PanelGroup` に `autoSaveId` を指定すると、`ResizeObserver` が安定した後のパネルサイズを 200ms デバウンス付きで `localStorage` に保存します。ページを再読み込みすると `loadLayout(autoSaveId)` の結果が自動的に反映され、ピクセル基準パネルと割合基準パネルの両方が復元されます。手動で制御したい場合は公開ユーティリティの `saveLayout` / `loadLayout` を直接呼び出してください。
-
-## デバッグと可視化
-
-`PanelGroup` の `showDebugInfo` を有効にすると、各 `Panel` に `PanelDebugInfo` が表示され、折りたたみ状態・計測サイズ・保持中の割合が即座に確認できます。同時にグローバルオーバーレイが開き、コンテナの実測サイズ、制約違反の有無、ハンドル厚み（`PANEL_HANDLE_THICKNESS` で定義された 8px）なども一覧できます。
-
-グローバルオーバーレイとそのストアは `React.lazy` + dynamic import で遅延読み込みされるため、`showDebugInfo` を一度も使わないアプリの本番バンドルにはデバッグ UI もストア購読も含まれません。
-
-## スナップとノイズ対策・最終整合の挙動
-
-`PanelResizeHandle` と `Panel` の両方で `calculateSnapThreshold` を利用し、コンテナサイズに応じたゼロスナップ閾値を共有しています。`Panel` および `PanelGroup` では、サブピクセル単位の微小なノイズ（0.5px 未満の揺れ）を無視するフィルタリングと、動作停止後に正確な真値を反映する **最終整合メカニズム（デバウンス同期）** を導入しています。これにより、スクロールやリサイズ中のチラつきを抑えつつ、最終的な表示状態と内部状態の完全な一致を保証します。
-
-## スタイル (CSS)
-
-大半のスタイルは JSX ベタ書きの Tailwind ユーティリティで持つため、CSS アーティファクトを **2 種類**配布する。ホストの種類で読み込み方を選ぶ。
-
-- **Tailwind v4 ホスト**: components-only ビルドを `layer(components)` で読み込み、JSX ユーティリティは自アプリの Tailwind ビルドにパッケージ `src` をスキャンさせて生成する。
+| `id` | `string` | Handle identifier (reflected in `data-resize-handle-id`) |
+| `disabled` | `boolean` | Disables mouse dragging and keyboard resizing when `true` |
+| `thickness` | `number` | Primary axis thickness of the handle's interactive area in pixels (`8px` default) |
+| `indicator` | `boolean \| PanelResizeHandleIndicatorConfig` | Toggle indicator visibility or provide custom pill/bar dimensions and CSS classes |
+| `indicatorThickness` | `number` | Shorthand for indicator pill wrapper thickness in pixels (`6px` default) |
+| `indicatorLength` | `number` | Shorthand for indicator pill wrapper length in pixels (`48px` horizontal / `80px` vertical default) |
+| `indicatorBarThickness` | `number` | Shorthand for indicator inner bar thickness in pixels (`2px` default) |
+| `indicatorBarLength` | `number` | Shorthand for indicator inner bar length in pixels (`32px` horizontal / `64px` vertical default) |
+| `title` | `string` | Custom tooltip text for the handle element |
+| `onDragging` | `(isDragging: boolean) => void` | Callback triggered on drag start and end (including `pointercancel`) |
+| `className` / `style` | `string` / `React.CSSProperties` | Additional styling for the resize handle |
+| `children` | `React.ReactNode` | Custom indicator element rendered inside handle (overrides default indicator) |
+
+> Handles render as `<button role="separator">` elements accessible via arrow keys (`←`/`→` for horizontal, `↑`/`↓` for vertical); holding `Shift` increases the step 5x. Under `dir="rtl"` the drag and keyboard directions follow the visual layout. The handle sits inside a zero-length anchor placed by flex layout, so its hit area is centred on the panel boundary without any position arithmetic.
+
+`PanelResizeHandle` forwards any other DOM attribute to its `<button>`, and calls your `onPointerDown` /
+`onKeyDown` before its own handling — calling `preventDefault()` in them stops the library's gesture from starting.
+The attributes it computes from the layout (`role`, `aria-orientation`, `aria-valuenow` / `aria-valuemin` /
+`aria-valuemax`, `aria-disabled`, `aria-hidden`) are removed from `PanelResizeHandleProps`, though only `role` is
+actually caught by the compiler — the hyphenated names are not type-checked in JSX, and it is the runtime override
+that keeps them the library's. `aria-label` stays yours and replaces the built-in description, and `title` defaults
+to that same description.
+
+Your `style` reaches the button between two library layers. The handle's resolved dimensions are published as CSS
+custom properties — `--rp-handle-thickness`, `--rp-indicator-thickness`, `--rp-indicator-length`,
+`--rp-indicator-bar-thickness`, `--rp-indicator-bar-length` — *before* it, so decorations of your own can be sized
+from the same numbers and may redefine them; the declarations that keep the hit area centred on the boundary
+(`position: absolute`, `zIndex: 20`, `touchAction: none`, the logical insets and the thickness / cross-axis `100%`
+box) are applied *after* it and take no override. While the group reports a constraint violation, every handle is
+hidden (`display: none` on its anchor) as well as disabled.
+
+## Hooks & Utilities
+
+- `useResizablePanels`: the hook behind `PanelGroup`. It measures the container, keeps the panel order equal to DOM order, notifies `onLayout`, persists the layout and returns the group's base style — it never computes a panel size.
+- `usePanelGroup` / `PanelGroupContext`: context accessor, and the context itself, for the panel list, the container length, the constraint violation and `layoutOrderKey` — the document order of the panels and handle anchors, which changes even when only a handle moved to another boundary.
+- `usePanelControls`: `collapse`, `expand` and `toggle` for a given panel id.
+- `allocatePanelSizes`, `resolvePanelBounds`, `isPixelPanel`: the layout calculation itself, exported for tests and for hosts that drive their own container.
+- `panelReducer`, `initialPanelGroupLayoutState`, `getPanelPreferenceInPixels`, `findLayoutInvariantBreach`: the state machine around the allocator, the length a layout should persist, and the `Σ sizes == container` check.
+- `getContainerSize`: measure one axis of an element in layout pixels; it returns `{ content, border }`, and `content` (padding and borders removed) is the length the allocator fills.
+- `findOwningGroup`, `getGroupLayoutElements`: resolve the group that owns an element, and that group's panels and handle anchors in document order — across wrapper elements, `display: contents` included, while skipping both a nested group's own elements and any `data-panel-id` that belongs to a panel's content rather than to this group.
+- `saveLayout` & `loadLayout`: persist or restore a layout (`{ id, size, collapsed }[]`).
+- `clamp`, `getConstraintInPixels`, `normalizeSizeConfig`, `percentageToPixels`, `toRoundedPercentage`, `calculateSnapThreshold`: the unit conversions and thresholds the components share.
+- `getPanelElement`, `getPanelGroupElement`, `getResizeHandleElement`: DOM element query helpers via `data-*` attributes.
+
+Every public type (`PanelProps`, `PanelGroupProps`, `PanelResizeHandleProps`, `PanelLayoutData`, `PanelRegistration`, `PersistedPanelSize`, `PanelGroupLayoutState`, `PanelAction`, `LayoutAllocation`, `PanelBounds`, `ContainerAxisMeasurement`, …) is re-exported from the package root; `docs/specs` (`00-architecture-overview.md` §8) lists the surface in full.
+
+## How sizes are decided
+
+| Panel kind | What it declares | What it gets |
+| --- | --- | --- |
+| Flexible (`percentage`, or a bare number) | a weight — only the ratio between such weights matters | its share of what is left after the panels with an absolute target, clamped to its bounds |
+| Flexible with `flexAdjustPriority` | the same number, read as a claim on that share of the container | that claim, served after the pixel panels and clamped to its bounds |
+| Pixel (`pixels`) | an absolute length | that length, clamped to its bounds, once the panels ahead of it in `pixelAdjustPriority` order have been served |
+
+Scarcity and surplus are two ends of one order. While space is scarce, targets are served in that order — pixel
+panels by `pixelAdjustPriority`, then flexible panels by `flexAdjustPriority` — so the panel last in line is the
+one that falls short of its target, even when every declared minimum would fit. While space is left over, it is
+offered to the ratio panels by weight, then to the prioritized flexible panels by weight, then to the pixel panels
+in `pixelAdjustPriority` order up to their `maxSize`, and last, in equal parts, to the flexible panels that have a
+weight of 0 and no `flexAdjustPriority`. A sidebar declared in pixels therefore grows past its declared length when
+nothing else can absorb the surplus: give it a `maxSize` to pin it. When a clamp bites, the residue is
+redistributed among the remaining panels of the same stage in their own ratio, and the container ends up exactly
+filled as long as one panel can still take the surplus; when none can, the gap is reported — as a constraint
+violation when the panels' maximums cannot reach the container, and as a logged invariant breach otherwise. The
+full statement, including the proofs of ratio preservation, continuity and the drag fixed point, is in `docs/specs`
+(`11-layout-allocator.md`).
+
+## Layout Persistence
+
+When `autoSaveId` is provided to `PanelGroup`, the layout is written to `localStorage` under the key
+`panel-layout-<autoSaveId>` as `{ id, size, collapsed }[]`, 200ms after the layout stops changing: a change arriving
+inside that window restarts the timer rather than forcing a write, so a drag never runs synchronous storage I/O once
+per frame. The one write outside that timer is the flush on unmount, which hands over the entries still pending so
+the last layout is not lost to a navigation. The stored `size` is the panel's preference — the length it occupies
+while open — not its allocated size, so a panel saved while collapsed still knows what to reopen to. On the next
+mount, and again whenever `autoSaveId` changes, the payload is applied only if it names exactly the panels that are
+present; a payload from a different panel set is ignored rather than applied by position.
+Restoring into a container of a different length scales a flexible panel by ratio, because its stored length is
+re-read as a share of the current container, while a pixel panel restores the absolute length it had.
+
+## Debugging & Inspection
+
+Enabling `showDebugInfo` on `PanelGroup` renders inspection metrics over each `Panel` (container length, allocated
+size, preference, resolved bounds) along with a global inspector: a header counting the groups, panels and resize
+handles on the page, then one card per group carrying its direction and container box and, for every panel, the
+state size next to the measured size, both percentages, the preference, the unit, the declared bounds and the two
+priorities. Individual handle measurements and constraint violations are not part of that overlay; a violation is
+shown by the placeholder the group draws over its panels, with or without the flag. Debug components are lazily
+imported (`React.lazy`); without the flag no per-panel `ResizeObserver` is created.
+
+## Styling (CSS)
+
+The package provides two CSS consumption options:
+
+- **Tailwind v4 Host**: Import components-only styles into `layer(components)` and configure Tailwind to scan package source files:
 
   ```css
   /* app tailwind.css */
   @import "@aiquants/resize-panels/styles/resize-panels.css" layer(components);
   @source "../node_modules/@aiquants/resize-panels/src/**/*.{ts,tsx}";
-  /* モノレポ: @source "../../../../packages/resize-panels/src/**/*.{ts,tsx}"; */
+  /* monorepo: @source "../../../../packages/resize-panels/src/**/*.{ts,tsx}"; */
   ```
 
-  `resize-panels.css` (Artifact A) は手書きコンポーネントクラスのみで、スタイルの大半が JSX ユーティリティのためほぼ空になる。**preflight・`:root` テーマ変数・Tailwind ユーティリティを含まない**。preflight を Tailwind ホストへ流し込むとホストの base 層を破壊するため、Artifact A には同梱しない (preflight は standalone だけが持つ)。standalone ビルドをここで併用してはならない (同名ユーティリティが重複しカスケードが反転する)。
-
-- **非 Tailwind ホスト**: 自己完結の standalone ビルドを 1 本だけ読み込む。preflight と全ユーティリティを同梱する。
+- **Non-Tailwind Host**: Import the self-contained standalone CSS bundle:
 
   ```css
   @import "@aiquants/resize-panels/styles/resize-panels.standalone.css";
   ```
 
-  ダークは `<html>` の `.dark` クラス基準。
+  Dark mode activates based on the `.dark` class on `<html>`.
+
+### Style ownership
+
+Your `className` and `style` reach all three components, but the declarations the layout itself depends on are
+applied *after* them and do not accept an override:
+
+- **Group**: `display: flex`, `flexDirection`, `alignItems: stretch`, `gap: 0px`, `position: relative`,
+  `boxSizing: border-box`, `writingMode: horizontal-tb`. The presentation defaults (`width`, `height`, `minWidth`,
+  `minHeight`, `overflow`) are yours to change.
+- **Panel**: the flex triple (`flexBasis` / `flexGrow` / `flexShrink`), `order: 0`, `margin: 0`, `display: flex`,
+  `flexDirection: column`, `position: relative`, `boxSizing: border-box`, `minWidth` and `minHeight: 0`,
+  `maxWidth` and `maxHeight: none`, the cross-axis `100%`, and `display: none` while collapsed. The presentation
+  defaults you can override are `overflow: hidden` and `isolation: isolate`.
+- **Handle button**: `position: absolute`, `zIndex: 20`, `touchAction: none`, the logical inset that centres it on
+  the boundary, its primary-axis thickness and its cross-axis `100%`. The `--rp-*` custom properties are placed
+  before your `style`, so those you may redefine.
+
+Both halves of that list are written to the `style` attribute, so a presentation default is overridable by your
+`style` **only** — a utility class loses to the inline declaration it would replace, which is why the examples
+above give the group its height through `style` rather than an `h-*` class. Every property the components do not
+write inline (colour, padding, borders, radius, …) stays entirely yours to set by class.
+
+A panel owns `maxWidth` / `maxHeight` because a single utility class (`max-w-*` and friends) would otherwise draw
+it shorter than the length the allocator handed out, leaving state and rendering disagreeing with the handle stuck.
+It defaults to `isolation: isolate` so that a `z-index` used inside a panel cannot rise above the handles; a panel
+whose content must escape its own box — a `position: fixed` maximised overlay, say — opts out with
+`style={{ isolation: "auto" }}` and accepts that the content may then cover a handle. That trade-off is inherent to
+stacking contexts: nothing can both take part in the panel's own stacking order and paint above its siblings.
+
+A panel renders its children inside an in-flow `flex: 1 1 auto` wrapper, so padding you set on a panel behaves
+normally; `contentOverflow` chooses how that wrapper scrolls. The group keeps `overflow: hidden` so that a handle
+straddling a boundary cannot raise a scrollbar — at the cost that when an edge panel collapses, the outer half of
+the handle now sitting on the group's own edge is clipped (its centre stays on the boundary).
 
-## デモ
+## Demo App
 
-モノレポ内に簡易デモアプリを用意しています。
+Run the included workspace demo app:
 
 ```bash
 pnpm --filter '@aiquants/resize-panels-demo' dev
 ```
 
-`http://localhost:5175` にアクセスすると複数レイアウトを含むデモを確認できます。
+Open `http://localhost:5175` to test interactive layouts.
 
-## ビルド
+## Build
 
 ```bash
 pnpm --filter '@aiquants/resize-panels' build
 ```
 
-生成物は `dist` に出力されます。
+Outputs built artifacts to `dist/`.

package/dist/GlobalDebugOverlay-Cf3GOn2A.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("react/jsx-runtime"),A=require("react"),P=require("react-dom"),x=require("./debugOverlayStore-DY09saU8.cjs"),R=require("./index-DqATP_BA.cjs"),n=(o,i)=>typeof o!="number"||!Number.isFinite(o)?"—":`${(o<0?0:o).toFixed(8)}${i}`,T={position:"fixed",left:"50%",bottom:"20px",transform:"translate(-50%, 0)",zIndex:100,maxWidth:"min(90vw, 1120px)",width:"100%",borderRadius:"14px",backgroundColor:"rgba(15, 23, 42, 0.72)",color:"#e2e8f0",fontFamily:"monospace",fontSize:"11px",lineHeight:1.6,boxShadow:"0 22px 45px rgba(15,23,42,0.45)",border:"1px solid rgba(148, 163, 184, 0.22)",backdropFilter:"blur(10px)",WebkitBackdropFilter:"blur(10px)",pointerEvents:"auto",overflow:"auto"},Y={display:"flex",justifyContent:"space-between",alignItems:"center",flexWrap:"wrap",gap:"12px"},w={display:"flex",flexDirection:"column",gap:"4px"},D={padding:"6px 10px",borderRadius:"9999px",border:"1px solid rgba(148, 163, 184, 0.35)",color:"#e2e8f0",fontWeight:600,fontSize:"10px",letterSpacing:"0.03em",textTransform:"uppercase",cursor:"pointer",transition:"background-color 0.18s ease, border-color 0.18s ease"},C={padding:"10px 12px",borderRadius:"10px",backgroundColor:"rgba(30, 41, 59, 0.55)",border:"1px solid rgba(148, 163, 184, 0.18)",display:"flex",flexDirection:"column",gap:"10px"},N={padding:"8px 10px",borderRadius:"8px",backgroundColor:"rgba(15, 23, 42, 0.55)",border:"1px solid rgba(148, 163, 184, 0.16)",display:"flex",flexDirection:"column",gap:"4px"},p={display:"flex",justifyContent:"space-between",alignItems:"center",gap:"6px"},k={display:"grid",gridTemplateColumns:"auto 1fr",gap:"2px 10px",color:"#e2e8f0"},G={padding:"2px 6px",borderRadius:"9999px",fontSize:"10px",textTransform:"uppercase"},I=({groupId:o})=>x.useDebugOverlayOwnerId()!==o?null:e.jsx(u,{}),u=()=>{const i=x.useDebugOverlaySnapshot().groups,[t,g]=A.useState(!0);if(i.length===0||typeof document>"u")return null;const b=i.reduce((s,a)=>s+a.panels.length,0),h=i.reduce((s,a)=>s+(a.handles?.length??0),0),f=()=>g(s=>!s),m=e.jsxs("div",{style:{...T,padding:t?"10px 18px":"14px 18px",maxHeight:t?"52px":"min(65vh, 520px)",transition:"max-height 0.24s ease, padding 0.24s ease"},children:[e.jsxs("div",{style:{...Y,marginBottom:t?0:"12px"},children:[e.jsxs("div",{style:w,children:[e.jsx("span",{style:{fontWeight:700,fontSize:"12px",letterSpacing:"0.03em"},children:"Panel Overview"}),e.jsxs("span",{style:{color:"#cbd5f5"},children:["groups: ",i.length," / panels: ",b," / resizers: ",h]})]}),e.jsx("button",{type:"button",onClick:f,style:{...D,backgroundColor:t?"rgba(59, 130, 246, 0.2)":"rgba(71, 85, 105, 0.45)"},title:t?"Panel Overview を開く":"Panel Overview を閉じる",children:t?"開く":"閉じる"})]}),!t&&e.jsx("div",{style:{display:"flex",flexDirection:"column",gap:"12px",maxHeight:"45vh",overflowY:"auto",paddingRight:"6px"},children:i.map((s,a)=>{const l=s.direction==="horizontal"?s.containerSize.width:s.containerSize.height;return e.jsxs("div",{style:C,children:[e.jsxs("div",{style:{...p,flexWrap:"wrap",gap:"10px",color:"#dbeafe"},children:[e.jsxs("span",{style:{fontWeight:600,fontSize:"11px",letterSpacing:"0.02em",textTransform:"uppercase"},children:["group ",a+1,": ",s.displayName]}),e.jsxs("span",{children:["direction: ",s.direction," / container: ",n(s.containerSize.width,"px")," × ",n(s.containerSize.height,"px")]})]}),e.jsx("div",{style:{display:"grid",gridTemplateColumns:"repeat(auto-fill, minmax(220px, 1fr))",gap:"10px"},children:s.panels.map((r,y)=>{const d=r.measuredPixelSize??r.size,S=r.size,j=n(S,"px"),v=l>0?r.size/l*100:void 0,E=r.measuredPercentageSize!==void 0?r.measuredPercentageSize:l>0?d/l*100:void 0,c=r.collapsed||d<=R.PANEL_SNAP_THRESHOLD,O=r.collapsed?"collapsed":c?"hidden":"visible",z=n(v,"%"),L=n(E,"%"),_=n(d,"px");return e.jsxs("div",{style:N,children:[e.jsxs("div",{style:p,children:[e.jsx("span",{style:{flex:1,minWidth:0,overflow:"hidden",textOverflow:"ellipsis"},children:r.id}),e.jsx("span",{style:{...G,backgroundColor:r.collapsed?"rgba(251, 113, 133, 0.25)":c?"rgba(250, 204, 21, 0.25)":"rgba(74, 222, 128, 0.25)",color:r.collapsed?"#fecdd3":c?"#fef08a":"#bbf7d0"},children:O})]}),e.jsxs("div",{style:k,children:[e.jsx("span",{children:"size (state):"}),e.jsx("span",{children:j}),e.jsx("span",{children:"size (measured):"}),e.jsx("span",{children:_}),e.jsx("span",{children:"percentage (state):"}),e.jsx("span",{children:z}),e.jsx("span",{children:"preference:"}),e.jsx("span",{children:r.sizeUnit==="pixels"?n(r.preferredPixelSize,"px"):n(r.preferredPercentageSize,"%")}),e.jsx("span",{children:"percentage (measured):"}),e.jsx("span",{children:L}),e.jsx("span",{children:"unit:"}),e.jsx("span",{children:r.sizeUnit}),e.jsx("span",{children:"min:"}),e.jsx("span",{children:r.minSize!==void 0?JSON.stringify(r.minSize):"—"}),e.jsx("span",{children:"max:"}),e.jsx("span",{children:r.maxSize!==void 0?JSON.stringify(r.maxSize):"—"}),e.jsx("span",{children:"priority:"}),e.jsx("span",{children:r.pixelAdjustPriority??"—"}),e.jsx("span",{children:"flex priority:"}),e.jsx("span",{children:r.flexAdjustPriority??"—"})]})]},r.id||y)})})]},s.groupId)})})]});return P.createPortal(m,document.body)};exports.GlobalDebugOverlay=u;exports.GlobalDebugOverlayGate=I;

package/dist/{GlobalDebugOverlay-DYCR0FIu.js → GlobalDebugOverlay-DQtUdNeF.js}

@@ -1,9 +1,9 @@
 import { jsx as e, jsxs as t } from "react/jsx-runtime";
 import { useState as A } from "react";
 import { createPortal as P } from "react-dom";
-import { useDebugOverlayOwnerId as R, useDebugOverlaySnapshot as T } from "./debugOverlayStore-Cntyxboe.js";
-import { P as Y } from "./index-BzgId8aQ.js";
-const a = (s, n) => typeof s != "number" || !Number.isFinite(s) ? "—" : `${(s < 0 ? 0 : s).toFixed(8)}${n}`, w = {
+import { useDebugOverlayOwnerId as R, useDebugOverlaySnapshot as T } from "./debugOverlayStore-D7FT6zPE.js";
+import { P as Y } from "./index-DZ0itiBD.js";
+const s = (a, n) => typeof a != "number" || !Number.isFinite(a) ? "—" : `${(a < 0 ? 0 : a).toFixed(8)}${n}`, w = {
   position: "fixed",
   left: "50%",
   bottom: "20px",
@@ -75,11 +75,11 @@ const a = (s, n) => typeof s != "number" || !Number.isFinite(s) ? "—" : `${(s
   borderRadius: "9999px",
   fontSize: "10px",
   textTransform: "uppercase"
-}, M = ({ groupId: s }) => R() !== s ? null : /* @__PURE__ */ e(W, {}), W = () => {
+}, J = ({ groupId: a }) => R() !== a ? null : /* @__PURE__ */ e(W, {}), W = () => {
   const n = T().groups, [o, g] = A(!0);
   if (n.length === 0 || typeof document > "u")
     return null;
-  const u = n.reduce((r, d) => r + d.panels.length, 0), h = n.reduce((r, d) => r + (d.handles?.length ?? 0), 0), m = () => g((r) => !r), f = /* @__PURE__ */ t(
+  const u = n.reduce((i, d) => i + d.panels.length, 0), h = n.reduce((i, d) => i + (d.handles?.length ?? 0), 0), m = () => g((i) => !i), f = /* @__PURE__ */ t(
     "div",
     {
       style: {
@@ -145,8 +145,8 @@ const a = (s, n) => typeof s != "number" || !Number.isFinite(s) ? "—" : `${(s
               overflowY: "auto",
               paddingRight: "6px"
             },
-            children: n.map((r, d) => {
-              const l = r.direction === "horizontal" ? r.containerSize.width : r.containerSize.height;
+            children: n.map((i, d) => {
+              const l = i.direction === "horizontal" ? i.containerSize.width : i.containerSize.height;
               return /* @__PURE__ */ t("div", { style: k, children: [
                 /* @__PURE__ */ t(
                   "div",
@@ -171,17 +171,17 @@ const a = (s, n) => typeof s != "number" || !Number.isFinite(s) ? "—" : `${(s
                             "group ",
                             d + 1,
                             ": ",
-                            r.displayName
+                            i.displayName
                           ]
                         }
                       ),
                       /* @__PURE__ */ t("span", { children: [
                         "direction: ",
-                        r.direction,
+                        i.direction,
                         " / container: ",
-                        a(r.containerSize.width, "px"),
+                        s(i.containerSize.width, "px"),
                         " × ",
-                        a(r.containerSize.height, "px")
+                        s(i.containerSize.height, "px")
                       ] })
                     ]
                   }
@@ -194,18 +194,18 @@ const a = (s, n) => typeof s != "number" || !Number.isFinite(s) ? "—" : `${(s
                       gridTemplateColumns: "repeat(auto-fill, minmax(220px, 1fr))",
                       gap: "10px"
                     },
-                    children: r.panels.map((i, b) => {
-                      const c = i.measuredPixelSize ?? i.size, y = i.size, S = a(y, "px"), v = i.percentageSize ?? (l > 0 ? i.size / l * 100 : void 0), E = i.measuredPercentageSize !== void 0 ? i.measuredPercentageSize : l > 0 ? c / l * 100 : void 0, p = i.collapsed || c <= Y, z = i.collapsed ? "collapsed" : p ? "hidden" : "visible", O = a(v, "%"), L = a(E, "%"), _ = a(c, "px");
+                    children: i.panels.map((r, b) => {
+                      const p = r.measuredPixelSize ?? r.size, y = r.size, S = s(y, "px"), v = l > 0 ? r.size / l * 100 : void 0, E = r.measuredPercentageSize !== void 0 ? r.measuredPercentageSize : l > 0 ? p / l * 100 : void 0, c = r.collapsed || p <= Y, z = r.collapsed ? "collapsed" : c ? "hidden" : "visible", L = s(v, "%"), O = s(E, "%"), _ = s(p, "px");
                       return /* @__PURE__ */ t("div", { style: I, children: [
                         /* @__PURE__ */ t("div", { style: x, children: [
-                          /* @__PURE__ */ e("span", { style: { flex: 1, minWidth: 0, overflow: "hidden", textOverflow: "ellipsis" }, children: i.id }),
+                          /* @__PURE__ */ e("span", { style: { flex: 1, minWidth: 0, overflow: "hidden", textOverflow: "ellipsis" }, children: r.id }),
                           /* @__PURE__ */ e(
                             "span",
                             {
                               style: {
                                 ...H,
-                                backgroundColor: i.collapsed ? "rgba(251, 113, 133, 0.25)" : p ? "rgba(250, 204, 21, 0.25)" : "rgba(74, 222, 128, 0.25)",
-                                color: i.collapsed ? "#fecdd3" : p ? "#fef08a" : "#bbf7d0"
+                                backgroundColor: r.collapsed ? "rgba(251, 113, 133, 0.25)" : c ? "rgba(250, 204, 21, 0.25)" : "rgba(74, 222, 128, 0.25)",
+                                color: r.collapsed ? "#fecdd3" : c ? "#fef08a" : "#bbf7d0"
                               },
                               children: z
                             }
@@ -217,27 +217,27 @@ const a = (s, n) => typeof s != "number" || !Number.isFinite(s) ? "—" : `${(s
                           /* @__PURE__ */ e("span", { children: "size (measured):" }),
                           /* @__PURE__ */ e("span", { children: _ }),
                           /* @__PURE__ */ e("span", { children: "percentage (state):" }),
-                          /* @__PURE__ */ e("span", { children: O }),
-                          /* @__PURE__ */ e("span", { children: "percentage (measured):" }),
                           /* @__PURE__ */ e("span", { children: L }),
+                          /* @__PURE__ */ e("span", { children: "preference:" }),
+                          /* @__PURE__ */ e("span", { children: r.sizeUnit === "pixels" ? s(r.preferredPixelSize, "px") : s(r.preferredPercentageSize, "%") }),
+                          /* @__PURE__ */ e("span", { children: "percentage (measured):" }),
+                          /* @__PURE__ */ e("span", { children: O }),
                           /* @__PURE__ */ e("span", { children: "unit:" }),
-                          /* @__PURE__ */ e("span", { children: i.sizeUnit }),
+                          /* @__PURE__ */ e("span", { children: r.sizeUnit }),
                           /* @__PURE__ */ e("span", { children: "min:" }),
-                          /* @__PURE__ */ e("span", { children: i.minSize !== void 0 ? JSON.stringify(i.minSize) : "—" }),
-                          /* @__PURE__ */ e("span", { children: "auto min:" }),
-                          /* @__PURE__ */ e("span", { children: i.autoMinSize !== void 0 ? JSON.stringify(i.autoMinSize) : "—" }),
+                          /* @__PURE__ */ e("span", { children: r.minSize !== void 0 ? JSON.stringify(r.minSize) : "—" }),
                           /* @__PURE__ */ e("span", { children: "max:" }),
-                          /* @__PURE__ */ e("span", { children: i.maxSize !== void 0 ? JSON.stringify(i.maxSize) : "—" }),
+                          /* @__PURE__ */ e("span", { children: r.maxSize !== void 0 ? JSON.stringify(r.maxSize) : "—" }),
                           /* @__PURE__ */ e("span", { children: "priority:" }),
-                          /* @__PURE__ */ e("span", { children: i.pixelAdjustPriority ?? "—" }),
+                          /* @__PURE__ */ e("span", { children: r.pixelAdjustPriority ?? "—" }),
                           /* @__PURE__ */ e("span", { children: "flex priority:" }),
-                          /* @__PURE__ */ e("span", { children: i.flexAdjustPriority ?? "—" })
+                          /* @__PURE__ */ e("span", { children: r.flexAdjustPriority ?? "—" })
                         ] })
-                      ] }, i.id || b);
+                      ] }, r.id || b);
                     })
                   }
                 )
-              ] }, r.groupId);
+              ] }, i.groupId);
             })
           }
         )
@@ -248,5 +248,5 @@ const a = (s, n) => typeof s != "number" || !Number.isFinite(s) ? "—" : `${(s
 };
 export {
   W as GlobalDebugOverlay,
-  M as GlobalDebugOverlayGate
+  J as GlobalDebugOverlayGate
 };