@reliability-design/web 1.4.9 → 1.4.11

package/dist/components/rel-resizable/README.md

@@ -1,199 +1,220 @@
-# rel-resizable
-
-`rel-resizable` is a three-element split-pane system: `<rel-resizable-group>` lays out its direct-child `<rel-resizable-panel>`s along one axis (`direction="horizontal"` side by side, `"vertical"` stacked) and lets the user drag or keyboard-nudge the `<rel-resizable-handle>` between two neighbours to trade percentage size between them, within each panel's `minsize` / `maxsize`. Use it for editor / preview splits, sidebar + content layouts and inspector panes where the user should control the proportions. It has no Figma component of its own; it follows the WAI-ARIA window-splitter pattern. It is not a general grid or an accordion — every panel stays visible and cannot be collapsed below its `minsize`.
-
-## Usage
-
-```html
-<!-- Horizontal split (default direction) -->
-<rel-resizable-group direction="horizontal" style="height: 320px;">
-  <rel-resizable-panel defaultsize="50">
-    <h3>Left</h3>
-  </rel-resizable-panel>
-  <rel-resizable-handle></rel-resizable-handle>
-  <rel-resizable-panel defaultsize="50">
-    <h3>Right</h3>
-  </rel-resizable-panel>
-</rel-resizable-group>
-
-<!-- Vertical split: the group needs an explicit height to divide -->
-<rel-resizable-group direction="vertical" style="height: 480px;">
-  <rel-resizable-panel defaultsize="40">Top</rel-resizable-panel>
-  <rel-resizable-handle></rel-resizable-handle>
-  <rel-resizable-panel defaultsize="60">Bottom</rel-resizable-panel>
-</rel-resizable-group>
-
-<!-- Constraints: percentages of the group -->
-<rel-resizable-group style="height: 320px;">
-  <rel-resizable-panel defaultsize="30" minsize="20" maxsize="50">Sidebar</rel-resizable-panel>
-  <rel-resizable-handle></rel-resizable-handle>
-  <rel-resizable-panel defaultsize="70">Main</rel-resizable-panel>
-</rel-resizable-group>
-
-<!-- Nested: a vertical group inside the right panel of a horizontal one -->
-<rel-resizable-group direction="horizontal" style="height: 480px;">
-  <rel-resizable-panel defaultsize="33">Sidebar</rel-resizable-panel>
-  <rel-resizable-handle></rel-resizable-handle>
-  <rel-resizable-panel defaultsize="67">
-    <rel-resizable-group direction="vertical">
-      <rel-resizable-panel defaultsize="50">Editor</rel-resizable-panel>
-      <rel-resizable-handle></rel-resizable-handle>
-      <rel-resizable-panel defaultsize="50">Preview</rel-resizable-panel>
-    </rel-resizable-group>
-  </rel-resizable-panel>
-</rel-resizable-group>
-
-<!-- Listening for size changes -->
-<rel-resizable-group id="split" style="height: 320px;">
-  <rel-resizable-panel>A</rel-resizable-panel>
-  <rel-resizable-handle></rel-resizable-handle>
-  <rel-resizable-panel>B</rel-resizable-panel>
-</rel-resizable-group>
-<script>
-  const split = document.getElementById('split');
-  // fires continuously while dragging
-  split.addEventListener('rel-resize', (e) => console.log(e.detail.sizes));
-  // fires once per drag, and after every keyboard step — good for persisting
-  split.addEventListener('rel-resize-end', (e) => localStorage.setItem('split', JSON.stringify(e.detail.sizes)));
-</script>
-```
-
-<!-- readme-gen:start -->
-
-<!-- Generated from rel-resizable-group.ts, rel-resizable-handle.ts, rel-resizable-panel.ts — do not edit; run readme-generate.mjs -->
-
-## Elements
-
-| Element | Class | Source |
-| --- | --- | --- |
-| `<rel-resizable-group>` | `RelResizableGroup` | `rel-resizable-group.ts` |
-| `<rel-resizable-handle>` | `RelResizableHandle` | `rel-resizable-handle.ts` |
-| `<rel-resizable-panel>` | `RelResizablePanel` | `rel-resizable-panel.ts` |
-
-## API
-
-### `<rel-resizable-group>`
-
-#### Attributes / Properties
-
-| Property | Attribute | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| `direction` | `direction` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout axis: `horizontal` places panels side by side and resizes widths, `vertical` stacks them and resizes heights; also pushed to every child handle's `orientation`. Reflected. |
-
-### Events
-
-| Event | Detail | Bubbles / composed | Description |
-| --- | --- | --- | --- |
-| `rel-resize` | `{ direction: this.direction, sizes, }` | bubbles / composed | Fired continuously while a handle is dragged. Detail: `{ direction, sizes: number[] }` with one percentage per panel. |
-| `rel-resize-end` | `{ direction: this.direction, sizes, }` | bubbles / composed | Fired once when a drag ends (pointerup) and after every keyboard resize step. Detail: `{ direction, sizes: number[] }` with one percentage per panel. |
-
-### Slots
-
-| Slot | Description |
-| --- | --- |
-| (default) | The panels and handles, as direct children in display order (panel, handle, panel, …) |
-
-### CSS Parts
-
-| Part | Description |
-| --- | --- |
-| — | None exposed. |
-
-### `<rel-resizable-handle>`
-
-#### Attributes / Properties
-
-| Property | Attribute | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| `orientation` | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Axis the handle separates: `horizontal` = 8px-wide vertical bar with `col-resize` cursor, `vertical` = 8px-tall bar with `row-resize`; set automatically from the parent group's `direction` on first render and mirrored to `aria-orientation`. Reflected. |
-
-#### Public fields / accessors
-
-| Name | Type | Description |
-| --- | --- | --- |
-| `splitValue` | `number` | Current split of the two neighbouring panels as a percentage 0–100 (share held by the leading panel); read-only — the parent group updates it and mirrors it to `aria-valuenow`. |
-
-### Events
-
-| Event | Detail | Bubbles / composed | Description |
-| --- | --- | --- | --- |
-| — | — | — | This element emits no custom events. |
-
-### Slots
-
-| Slot | Description |
-| --- | --- |
-| — | This element has no slots. |
-
-### CSS Parts
-
-| Part | Description |
-| --- | --- |
-| — | None exposed. |
-
-### `<rel-resizable-panel>`
-
-#### Attributes / Properties
-
-| Property | Attribute | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| `defaultSize` | `defaultsize` | `number` | `undefined` | Initial size as a percentage of the group; panels without one share whatever is left of 100%, then all sizes are normalised to sum to 100. Attribute is `defaultsize`. |
-| `minSize` | `minsize` | `number` | `10` | Smallest size (percentage) the panel can be resized to. Attribute is `minsize`. |
-| `maxSize` | `maxsize` | `number` | `90` | Largest size (percentage) the panel can be resized to. Attribute is `maxsize`. |
-
-#### Public fields / accessors
-
-| Name | Type | Description |
-| --- | --- | --- |
-| `currentSize` | `number` | Current size as a percentage of the group (also written to the host's `flex-basis`); read-only — the parent group updates it on every resize. |
-
-### Events
-
-| Event | Detail | Bubbles / composed | Description |
-| --- | --- | --- | --- |
-| — | — | — | This element emits no custom events. |
-
-### Slots
-
-| Slot | Description |
-| --- | --- |
-| (default) | The panel's content; slotted `h1`–`h4` get the headings-md role |
-
-### CSS Parts
-
-| Part | Description |
-| --- | --- |
-| — | None exposed. |
-
-<!-- readme-gen:end -->
-
-## Accessibility
-
-- Each `<rel-resizable-handle>` makes itself focusable (`tabindex="0"`) and takes `role="separator"` with `aria-orientation` mirroring its `orientation`. The group writes `aria-valuenow` (the leading panel's share of the pair, rounded, 0–100), `aria-valuemin="0"` and `aria-valuemax="100"` on first render and after every resize, so assistive technology can read the current split before and after any interaction.
-- Handles have no accessible name of their own; when several handles are on a page add `aria-label` to each (e.g. `aria-label="Resize sidebar"`).
-- The group and the panels set no roles and are not focusable; panels are `overflow: auto`, so their content scrolls natively and any interactive content inside keeps its own tab order.
-- A focused handle shows a 2px focus ring (`--rel-border-focus`) and a lighter background; hover and drag states change the background and grab-bar colours only.
-- Keyboard resizing (handled by the group, on a focused handle):
-
-| Key | Direction | Action |
-| --- | --- | --- |
-| `ArrowLeft` / `ArrowRight` | `horizontal` | Shrink / grow the leading panel by 2% (of the group). |
-| `ArrowUp` / `ArrowDown` | `vertical` | Shrink / grow the leading panel by 2%. |
-| `Shift` + arrow | either | Same, in 5% steps. |
-| `Home` | either | Collapse the leading panel to its `minsize` (as far as the neighbour allows). |
-| `End` | either | Grow the leading panel to its `maxsize` (as far as the neighbour allows). |
-
-- Every keyboard step dispatches `rel-resize-end` (not `rel-resize`).
-- Motion: the handle's background transitions are removed under `prefers-reduced-motion: reduce`.
-
-## Notes / Edge Cases
-
-- Panels and handles must be **direct children** of the group (`:scope > rel-resizable-panel`), alternating panel / handle / panel. A handle at the start or end, or two handles in a row, has no valid pair and does nothing.
-- Layout is computed once in `firstUpdated`: panels without `defaultsize` share whatever remains of 100%, then all sizes are normalised to sum to exactly 100 (so `defaultsize="50"` + `defaultsize="70"` ends up as 41.7 / 58.3). Panels or handles added or removed later are **not** observed; re-attach the group to re-initialise.
-- Sizes are always percentages of the group, applied as `flex-basis` with `flex-grow: 0; flex-shrink: 0`. The group itself is `display: flex; width: 100%; height: 100%`, so a `vertical` group needs an ancestor with a definite height or it has nothing to divide.
-- Only the two panels adjacent to the dragged handle change; each is clamped to its own `minsize` / `maxsize`, then the pair is rescaled so their combined share stays constant. A panel therefore cannot go below its `minsize` (default 10) and never collapses to 0 unless you set `minsize="0"`.
-- Attribute names are lowercase with no hyphen: `defaultsize`, `minsize`, `maxsize` (properties `defaultSize`, `minSize`, `maxSize`).
-- While a drag is in progress the active handle carries a `data-dragging` attribute (the group sets and removes it) — the only hook for drag-specific styling from outside.
-- Each handle's `orientation` is overwritten from the group's `direction` on first render; set `direction` on the group, not `orientation` on the handles.
-- `rel-resize` fires on every pointer move during a drag; throttle any expensive listener. `rel-resize-end` fires once on pointer-up and after each keyboard step; both carry `{ direction, sizes }` where `sizes[i]` is panel *i*'s current percentage.
-- Nested groups work because the inner group is ordinary panel content; pointer events are handled by the nearest group whose handle is in the event's composed path.
+# rel-resizable
+
+`rel-resizable` is a three-element split-pane system: `<rel-resizable-group>` lays out its direct-child `<rel-resizable-panel>`s along one axis (`direction="horizontal"` side by side, `"vertical"` stacked) and lets the user drag or keyboard-nudge the `<rel-resizable-handle>` between two neighbours to trade percentage size between them, within each panel's `min-size` / `max-size`. Use it for editor / preview splits, sidebar + content layouts and inspector panes where the user should control the proportions. It has no Figma component of its own; it follows the WAI-ARIA window-splitter pattern. It is not a general grid or an accordion — every panel stays visible and cannot be collapsed below its `min-size`.
+
+## Usage
+
+```html
+<!-- Horizontal split (default direction) -->
+<rel-resizable-group direction="horizontal" style="height: 320px;">
+  <rel-resizable-panel default-size="50">
+    <h3>Left</h3>
+  </rel-resizable-panel>
+  <rel-resizable-handle></rel-resizable-handle>
+  <rel-resizable-panel default-size="50">
+    <h3>Right</h3>
+  </rel-resizable-panel>
+</rel-resizable-group>
+
+<!-- Vertical split: the group needs an explicit height to divide -->
+<rel-resizable-group direction="vertical" style="height: 480px;">
+  <rel-resizable-panel default-size="40">Top</rel-resizable-panel>
+  <rel-resizable-handle></rel-resizable-handle>
+  <rel-resizable-panel default-size="60">Bottom</rel-resizable-panel>
+</rel-resizable-group>
+
+<!-- Constraints: percentages of the group -->
+<rel-resizable-group style="height: 320px;">
+  <rel-resizable-panel default-size="30" min-size="20" max-size="50">Sidebar</rel-resizable-panel>
+  <rel-resizable-handle></rel-resizable-handle>
+  <rel-resizable-panel default-size="70">Main</rel-resizable-panel>
+</rel-resizable-group>
+
+<!-- Nested: a vertical group inside the right panel of a horizontal one -->
+<rel-resizable-group direction="horizontal" style="height: 480px;">
+  <rel-resizable-panel default-size="33">Sidebar</rel-resizable-panel>
+  <rel-resizable-handle></rel-resizable-handle>
+  <rel-resizable-panel default-size="67">
+    <rel-resizable-group direction="vertical">
+      <rel-resizable-panel default-size="50">Editor</rel-resizable-panel>
+      <rel-resizable-handle></rel-resizable-handle>
+      <rel-resizable-panel default-size="50">Preview</rel-resizable-panel>
+    </rel-resizable-group>
+  </rel-resizable-panel>
+</rel-resizable-group>
+
+<!-- Scrollable panel (new in 1.5.0): while the content overflows, the panel is a
+     focusable region named by panel-label, so keyboard users can scroll it -->
+<rel-resizable-group style="height: 240px;">
+  <rel-resizable-panel default-size="30" panel-label="Shipment list">…long list…</rel-resizable-panel>
+  <rel-resizable-handle aria-label="Resize shipment list"></rel-resizable-handle>
+  <rel-resizable-panel default-size="70">Details</rel-resizable-panel>
+</rel-resizable-group>
+
+<!-- Listening for size changes -->
+<rel-resizable-group id="split" style="height: 320px;">
+  <rel-resizable-panel>A</rel-resizable-panel>
+  <rel-resizable-handle></rel-resizable-handle>
+  <rel-resizable-panel>B</rel-resizable-panel>
+</rel-resizable-group>
+<script>
+  const split = document.getElementById('split');
+  // fires continuously while dragging
+  split.addEventListener('rel-resize', (e) => console.log(e.detail.sizes));
+  // fires once per drag, and after every keyboard step — good for persisting
+  split.addEventListener('rel-resize-end', (e) => localStorage.setItem('split', JSON.stringify(e.detail.sizes)));
+</script>
+```
+
+### Deprecated aliases
+
+```html
+<!-- defaultsize / minsize / maxsize → default-size / min-size / max-size (since 1.5.0; still work,
+     log a one-time console notice, removed in 3.0) -->
+<rel-resizable-panel defaultsize="30" minsize="20" maxsize="50">Sidebar</rel-resizable-panel>
+<rel-resizable-panel default-size="30" min-size="20" max-size="50">Sidebar</rel-resizable-panel>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-resizable-group.ts, rel-resizable-handle.ts, rel-resizable-panel.ts — do not edit; run readme-generate.mjs -->
+
+## Elements
+
+| Element | Class | Source |
+| --- | --- | --- |
+| `<rel-resizable-group>` | `RelResizableGroup` | `rel-resizable-group.ts` |
+| `<rel-resizable-handle>` | `RelResizableHandle` | `rel-resizable-handle.ts` |
+| `<rel-resizable-panel>` | `RelResizablePanel` | `rel-resizable-panel.ts` |
+
+## API
+
+### `<rel-resizable-group>`
+
+#### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `direction` | `direction` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout axis: `horizontal` places panels side by side and resizes widths, `vertical` stacks them and resizes heights; also pushed to every child handle's `orientation`. Reflected. |
+
+### Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-resize` | `{ direction: this.direction, sizes, }` | bubbles / composed | Fired continuously while a handle is dragged. Detail: `{ direction, sizes: number[] }` with one percentage per panel. |
+| `rel-resize-end` | `{ direction: this.direction, sizes, }` | bubbles / composed | Fired once when a drag ends (pointerup) and after every keyboard resize step. Detail: `{ direction, sizes: number[] }` with one percentage per panel. |
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | The panels and handles, as direct children in display order (panel, handle, panel, …) |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| — | None exposed. |
+
+### `<rel-resizable-handle>`
+
+#### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `orientation` | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Axis the handle separates: `horizontal` = 8px-wide vertical bar with `col-resize` cursor, `vertical` = 8px-tall bar with `row-resize`; set automatically from the parent group's `direction` on first render and mirrored to `aria-orientation`. Reflected. |
+
+#### Public fields / accessors
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `splitValue` | `number` | Current split of the two neighbouring panels as a percentage 0–100 (share held by the leading panel); read-only — the parent group updates it and mirrors it to `aria-valuenow`. |
+
+### Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| — | None exposed. |
+
+### `<rel-resizable-panel>`
+
+#### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `defaultSize` | `default-size` | `number` | `undefined` | Initial size as a percentage of the group; panels without one share whatever is left of 100%, then all sizes are normalised to sum to 100. The `defaultsize` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+| `minSize` | `min-size` | `number` | `10` | Smallest size (percentage) the panel can be resized to. The `minsize` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+| `maxSize` | `max-size` | `number` | `90` | Largest size (percentage) the panel can be resized to. The `maxsize` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+| `panelLabel` | `panel-label` | `string` | `undefined` | New in 1.5.0. Accessible name the panel carries while its content overflows (it is then a focusable `role="region"`). Defaults to "Panel N", N being its position among the group's panels. Ignored when the page sets its own `aria-label` / `aria-labelledby`. |
+
+#### Public fields / accessors
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `currentSize` | `number` | Current size as a percentage of the group (also written to the host's `flex-basis`); read-only — the parent group updates it on every resize. |
+| `scrollable` | `boolean` | True while the content overflows the panel in either axis; read-only, kept current by a ResizeObserver. |
+
+### Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | The panel's content; slotted `h1`–`h4` get the headings-md role |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| — | None exposed. |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- Each `<rel-resizable-handle>` makes itself focusable (`tabindex="0"`) and takes `role="separator"` with `aria-orientation` mirroring its `orientation`. The group writes `aria-valuenow` (the leading panel's share of the pair, rounded, 0–100), `aria-valuemin="0"` and `aria-valuemax="100"` on first render and after every resize, so assistive technology can read the current split before and after any interaction.
+- Handles have no accessible name of their own; when several handles are on a page add `aria-label` to each (e.g. `aria-label="Resize sidebar"`).
+- The group sets no role and is not focusable. Panels are `overflow: auto`, and any interactive content inside keeps its own tab order.
+- Scrollable panels (new in 1.5.0): while a panel's content overflows it (either axis), the panel gets `tabindex="0"`, `role="region"` and an `aria-label` (`panel-label`, default "Panel 1", "Panel 2"… by position), so a keyboard user can Tab to it and scroll with the arrow keys, Page Up / Page Down and Home / End. Focus shows a 2px `--rel-border-focus` ring drawn inside the panel edge (the group clips anything outside), or the system highlight colour in forced-colors mode. When the content fits again (resized larger, content removed) all three are removed, so a panel that cannot scroll is never a dead tab stop; a panel that is focused at that moment keeps its tab stop until focus leaves. Overflow is re-measured on panel and content resizes and on content changes.
+- A `tabindex` you set yourself is never changed or removed (including `-1`), and the panel then leaves `role` and `aria-label` to you as well. A `role` or `aria-label` / `aria-labelledby` you set is never overridden. Give each scrollable panel a distinct `panel-label` when the defaults would repeat (for example in nested groups, where each group numbers its panels from 1).
+- A focused handle shows a 2px focus ring (`--rel-border-focus`) and a lighter background; hover and drag states change the background and grab-bar colours only.
+- Keyboard resizing (handled by the group, on a focused handle):
+
+| Key | Direction | Action |
+| --- | --- | --- |
+| `ArrowLeft` / `ArrowRight` | `horizontal` | Shrink / grow the leading panel by 2% (of the group). |
+| `ArrowUp` / `ArrowDown` | `vertical` | Shrink / grow the leading panel by 2%. |
+| `Shift` + arrow | either | Same, in 5% steps. |
+| `Home` | either | Collapse the leading panel to its `min-size` (as far as the neighbour allows). |
+| `End` | either | Grow the leading panel to its `max-size` (as far as the neighbour allows). |
+
+- Every keyboard step dispatches `rel-resize-end` (not `rel-resize`).
+- Motion: the handle's background transitions are removed under `prefers-reduced-motion: reduce`.
+
+## Notes / Edge Cases
+
+- Panels and handles must be **direct children** of the group (`:scope > rel-resizable-panel`), alternating panel / handle / panel. A handle at the start or end, or two handles in a row, has no valid pair and does nothing.
+- Layout is computed once in `firstUpdated`: panels without `default-size` share whatever remains of 100%, then all sizes are normalised to sum to exactly 100 (so `default-size="50"` + `default-size="70"` ends up as 41.7 / 58.3). Panels or handles added or removed later are **not** observed; re-attach the group to re-initialise.
+- Sizes are always percentages of the group, applied as `flex-basis` with `flex-grow: 0; flex-shrink: 0`. The group itself is `display: flex; width: 100%; height: 100%`, so a `vertical` group needs an ancestor with a definite height or it has nothing to divide.
+- Only the two panels adjacent to the dragged handle change; each is clamped to its own `min-size` / `max-size`, then the pair is rescaled so their combined share stays constant. A panel therefore cannot go below its `min-size` (default 10) and never collapses to 0 unless you set `min-size="0"`.
+- Attribute names are kebab-case: `default-size`, `min-size`, `max-size` (properties `defaultSize`, `minSize`, `maxSize`). The older lowercase spellings still work since 1.5.0 but log a one-time console notice and are removed in 3.0; see Deprecated aliases.
+- While a drag is in progress the active handle carries a `data-dragging` attribute (the group sets and removes it) — the only hook for drag-specific styling from outside.
+- Each handle's `orientation` is overwritten from the group's `direction` on first render; set `direction` on the group, not `orientation` on the handles.
+- `rel-resize` fires on every pointer move during a drag; throttle any expensive listener. `rel-resize-end` fires once on pointer-up and after each keyboard step; both carry `{ direction, sizes }` where `sizes[i]` is panel *i*'s current percentage.
+- Nested groups work because the inner group is ordinary panel content; pointer events are handled by the nearest group whose handle is in the event's composed path.