@reliability-design/web 1.4.6 → 1.4.8

package/dist/components/rel-range-picker/README.md

@@ -0,0 +1,165 @@
+# rel-range-picker
+
+`<rel-range-picker>` is the date-range form field of the Reliability Design System (Figma "Date Range Picker"). It is a text field you can type a "from → to" range into, backed by a two-pane panel: quick-select presets with single-key shortcuts and From / To readouts on the left, a month grid with live range preview on the right, and a Reset / Cancel / Apply footer. The grid and presets edit a draft; only Apply (or typed entry / clear) commits `from`/`to` as ISO `YYYY-MM-DD` strings. Use it for filters and reports that need a start and an end. For a single date use `<rel-date-picker>`, for an always-visible grid use `<rel-calendar>`.
+
+## Usage
+
+```html
+<!-- Basic -->
+<rel-range-picker placeholder="Select date range"></rel-range-picker>
+
+<!-- Preselected range with a clear icon -->
+<rel-range-picker from="2026-01-05" to="2026-01-09" clearable></rel-range-picker>
+
+<!-- Bounded, Monday-first grid -->
+<rel-range-picker min-date="2026-01-01" max-date="2026-12-31" week-start="mon"></rel-range-picker>
+
+<!-- Centred popup with a dimmed backdrop instead of an anchored popover -->
+<rel-range-picker mode="popup"></rel-range-picker>
+
+<!-- Icon-only trigger (no typed entry, no clear icon) -->
+<rel-range-picker trigger-variant="icon" placeholder="Filter by date"></rel-range-picker>
+
+<!-- Sizing the host: explicit width, or fill the parent -->
+<rel-range-picker width="320px" min-width="240px"></rel-range-picker>
+<rel-range-picker fullwidth></rel-range-picker>
+
+<!-- Disabled -->
+<rel-range-picker from="2026-01-05" to="2026-01-09" disabled></rel-range-picker>
+```
+
+```js
+const picker = document.querySelector("rel-range-picker");
+
+picker.addEventListener("rel-change", (e) => {
+  e.detail.from;  // "2026-01-05" ("" when cleared)
+  e.detail.to;    // "2026-01-09"
+  e.detail.label; // "01/05/2026 → 01/09/2026"
+});
+picker.addEventListener("rel-open-change", (e) => e.detail.open);
+picker.addEventListener("rel-blur", () => {/* run validation */});
+
+picker.displayLabel; // same formatted label for the committed range
+```
+
+### Typed entry
+
+With the default trigger the field is editable and commits on Enter or when focus leaves the component. Two dates are separated by `→`, `..`, a spaced `-`, or the word `to` (`2026-01-05 to 2026-01-09`, `21/7 .. 28/7`, `t - t+7`); a single date gives a one-day range and a reversed pair is normalised so `from` ≤ `to`. Each side accepts everything `rel-date-picker` parses — ISO, numeric, month names, partial `21/7` / `21`, and the `t` / `today` / `t±N` shortcuts — with ambiguous `a/b` always read as month/day, matching the `MM/DD/YYYY` display. Unparseable text shows "Invalid date range" and a date outside `min-date`/`max-date` shows "Date not available"; the text stays for correction and the committed range is untouched. Escape reverts the text; committing an empty field clears the range like the clear icon.
+
+### Presets and shortcuts
+
+The left pane lists Today (`T`), Tomorrow (`M`), Yesterday (`Y`), This Week (`W`), Next Week (`N`), Next 7 Days (`7`) and Next 30 Days (`3`), one per row. Weeks in the presets always run Sunday–Saturday regardless of `week-start`. While the panel is open, pressing the key (no modifier, focus not in an editable field) selects that preset; a preset only fills the draft — Apply still commits it. Following Figma's ".Suggested Range" row, the key is not printed on the row: each preset carries it as `aria-keyshortcuts` and a `title` tooltip instead.
+
+> **Changed in this release.** The `Before Today` preset (`B`, `1970-01-01` → yesterday) has been replaced by `Yesterday` (`Y`, yesterday → yesterday) to match Figma. The `B` key no longer selects anything; use typed entry (for example `1970-01-01 to t-1`) if you need the old open-ended range.
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-range-picker.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `from` | `from` | `string` | `""` | Committed range start as an ISO `YYYY-MM-DD` string; empty string when no range is set. |
+| `to` | `to` | `string` | `""` | Committed range end as an ISO `YYYY-MM-DD` string; empty string when no range is set. Always ≥ `from`. |
+| `locale` | `locale` | `string` | `"en-US"` | Locale used to match month names in typed input; the visible trigger text and calendar labels are always `en-US` (`MM/DD/YYYY`). |
+| `weekStart` | `week-start` | `"mon" \| "sun"` | `"sun"` | First column of the calendar grid: `"sun"` (default) or `"mon"`. Presets always compute weeks Sunday–Saturday. |
+| `minDate` | `min-date` | `string` | `""` | Earliest selectable date (ISO `YYYY-MM-DD`); earlier days are disabled and typed ranges starting before it are rejected. |
+| `maxDate` | `max-date` | `string` | `""` | Latest selectable date (ISO `YYYY-MM-DD`); later days are disabled and typed ranges ending after it are rejected. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the trigger, the icons and the panel controls; the host dims to 60% opacity. Reflected. |
+| `open` | `open` | `boolean` | `false` | Whether the panel is open. Setting it directly shows/hides the panel but does not seed the draft from `from`/`to` or fire `rel-open-change` — user interaction does both. Reflected. |
+| `mode` | `mode` | `"popover" \| "popup"` | `"popover"` | `popover` anchors the panel below the trigger; `popup` centres it in the viewport behind a dimmed backdrop (part `overlay`). |
+| `width` | `width` | `string` | `""` | CSS width applied to the host (any CSS length, e.g. `320px`); empty leaves the intrinsic width. |
+| `minWidth` | `min-width` | `string` | `""` | CSS `min-width` applied to the host. |
+| `maxWidth` | `max-width` | `string` | `""` | CSS `max-width` applied to the host. |
+| `height` | `height` | `string` | `""` | CSS height applied to the host. |
+| `minHeight` | `min-height` | `string` | `""` | CSS `min-height` applied to the host. |
+| `maxHeight` | `max-height` | `string` | `""` | CSS `max-height` applied to the host. |
+| `placeholder` | `placeholder` | `string` | `"Select date range"` | Placeholder shown in the empty field; also the accessible name of the input (and of the icon trigger while no range is set). |
+| `triggerVariant` | `trigger-variant` | `"default" \| "icon"` | `"default"` | `default` renders the text field; `icon` renders a single calendar icon button instead (no typed entry, no clear button, parts `trigger`/`value` absent). |
+| `clearable` | `clearable` | `boolean` | `false` | Shows a clear (×) icon while a range is set; clearing fires `rel-change` with empty `from`/`to`. Only with the default trigger. |
+| `fullWidth` | `fullwidth` | `boolean` | `false` | Stretches the host to fill its parent's width (attribute `fullwidth`), mirroring rel-time-picker / rel-date-picker. Off by default so the existing intrinsic-width (`inline-block`) rendering is unchanged. Reflected. |
+| `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | Trigger height on the shared field scale — `small` 32 / `medium` 40 / `large` 48px border-box — matching rel-textfield, rel-date-picker and rel-time-picker so the four align in a form row. Also ramps the trigger's text and inline padding. The panel is unaffected: Figma specifies one panel size. `sm` / `md` / `lg` are alternative spellings and stay supported — normalised to the full words, not deprecated. Reflected. |
+
+### Public fields / accessors
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `displayLabel` | `string` | Formatted "MM/DD/YYYY → MM/DD/YYYY" (or single date / "") for the current committed `from`/`to`. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-blur` | — | bubbles / composed | Fired when the text input loses focus (before any typed text is committed). No detail. |
+| `rel-change` | `{ from: this.from, to: this.to, label: this.displayLabel } / { from: "", to: "", label: "" }` | bubbles / composed | Fired when the committed range changes — Apply, typed entry, or clear. Detail: `{ from: string, to: string, label: string }` (ISO dates and the formatted `MM/DD/YYYY → MM/DD/YYYY` label; all empty strings when cleared). |
+| `rel-open-change` | `{ open: true } / { open: false }` | bubbles / composed | Fired when the panel opens or closes (open, Cancel, Escape, outside click, Apply). Detail: `{ open: boolean }`. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `trigger` | The field box that wraps the text input and the clear/calendar icons (default trigger variant only) |
+| `value` | The editable text input inside the trigger |
+| `overlay` | The full-screen backdrop rendered in `mode="popup"` while open |
+| `panel` | The floating panel (`role="dialog"`) holding presets and calendar |
+| `list` | The preset column and the day grid |
+| `option` | Each quick-select preset button |
+| `action` | The header's previous and next buttons; they step a month, a year or a 12-year page depending on which view the panel is showing |
+| `footer` | The Reset / Cancel / Apply button row |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- Default trigger: the input is a `role="combobox"` with `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` pointing at the panel, `aria-label` = `placeholder`, `aria-invalid` while typed text is in error and `aria-describedby` pointing at the error line. The icon buttons are labelled "Clear date range" and "Open date range panel" (with `aria-expanded`).
+- Icon trigger (`trigger-variant="icon"`): a `<rel-button>` with `aria-haspopup="dialog"`, `aria-expanded`, and an `aria-label` of the current range label or the `placeholder`.
+- The panel is a `role="dialog"` named "Select date range". Presets sit in a `role="group"` named "Quick date selections"; each preset button carries `aria-pressed` plus an `aria-keyshortcuts` naming its single-key shortcut. The From / To readouts are groups named "From date" / "To date". Focus is not trapped inside the panel.
+- The calendar is a `role="grid"` named "Select date range" with `role="columnheader"` weekday names, `role="row"` weeks and `role="gridcell"` days whose `aria-label` is the full long date plus ", range start" / ", range end" for the endpoints; `aria-selected` is true for the endpoints and every day between them, `aria-disabled` marks unavailable days. Exactly one cell is a Tab stop (last arrowed date → draft start → today → first enabled day).
+- Focus: opening the panel does not move focus; Escape closes it and returns focus to the input. Keyboard navigation in the grid previews the range exactly like mouse hover does.
+- Screen readers hear "<Month> <Year>" after every month change and "From date MM/DD/YYYY" / "To date MM/DD/YYYY" when an endpoint is chosen, through the shared `announce()` region (`utils/announce.ts`).
+
+| Key (in the field) | Action |
+| --- | --- |
+| Enter | Nothing typed: open the panel. Text typed: commit it |
+| ArrowDown | Open the panel |
+| Escape | Revert uncommitted text; close the panel and refocus the input |
+
+| Key (panel open, focus outside an editable field) | Action |
+| --- | --- |
+| T / M / Y / W / N / 7 / 3 | Select the matching preset into the draft |
+| Escape | Cancel: discard the draft, close, refocus the input |
+
+| Key (in the grid) | Action |
+| --- | --- |
+| ArrowLeft / ArrowRight | Previous / next day (switches month at the edge) |
+| ArrowUp / ArrowDown | Same weekday one week earlier / later |
+| Home / End | First / last day of the row, honouring `week-start` |
+| PageUp / PageDown | Same day previous / next month |
+| Shift + PageUp / Shift + PageDown | Same day previous / next year |
+| Enter / Space | Pick the day as range start, then as range end |
+
+## Notes / Edge Cases
+
+- **The header month and year are buttons.** Clicking the month opens a 12-month grid; clicking the year opens a 12-year page that pages back indefinitely with the chevrons, so a date years in the past is a few clicks rather than a few dozen. Picking a year drills to Months, picking a month returns to the day grid. The chevrons step whatever the current view shows — a month, a year or a whole page — and the panel always reopens on the day grid.
+- **Navigating does not select.** The switcher moves the VIEW only: it writes to the month and year on display and never to the draft or the committed range, so Reset, Cancel and Apply behave exactly as they did, and reopening still seeds the view from the committed start date.
+- Draft vs committed: grid picks and presets only change the draft shown in the From / To readouts. Apply commits it (fires `rel-change`, closes); Cancel, Escape, an outside click, or the popup backdrop discard it; Reset empties the draft. Reset followed by Apply clears the committed range (`rel-change` with empty strings) — Apply is disabled only when both the draft and the committed range are empty.
+- Second-click ordering: picking a day before the current draft start makes it the new start and the old start the end.
+- Setting `open = true` from code shows the panel but neither seeds the draft from `from`/`to` nor fires `rel-open-change`; only user interaction does both.
+- The trigger text, From / To readouts, month names and day labels are always rendered in `en-US` (`MM/DD/YYYY`); `locale` only affects month-name matching in typed input.
+- Leading and trailing cells of adjacent months are visible but never selectable, and render at 40% label opacity (Figma "Day of a week = Other Month"). Today gets a 1 px brand ring; weekend cells render at 70% opacity (Figma "Day of a week = Weekend") unless they are range endpoints.
+- Range styling follows Figma ".Date Range Days": the selected run is an `elevated-1` band across the full cell, rounded at the two ends (a one-day range is a single rounded pill), and the two endpoints are `inverse-2` discs with inverse semibold labels. Days between the endpoints keep their normal label on the band.
+- The panel (and the popup backdrop) is promoted to the browser top layer (`popover="manual"`), so it works inside `rel-modal` / `rel-drawer` and above transformed or `overflow: hidden` ancestors. In `popover` mode it anchors below the host, flips above when there is no room, stays 8 px inside the viewport and repositions on scroll/resize; in `popup` mode it is fixed-centred behind a 40% black backdrop (part `overlay`) whose click cancels. It never exceeds the viewport and scrolls internally.
+- `width`, `min-width`, `max-width`, `height`, `min-height` and `max-height` are copied to the host's inline style on every update, so they override stylesheet rules on the host.
+- The icon trigger has no typed entry, no clear icon and no error line; parts `trigger` and `value` are not rendered in that variant.
+- There is no helper-text or external error API; the only text below the field is the typed-entry error.
+- The footer buttons are `<rel-button>` instances — `ghost` for Reset, `secondary` for Cancel and `primary tone="brand"` for Apply — and the icon trigger uses `<rel-button>` with `<rel-icon name="calendar-range">`, so `@reliability-design/icons` is loaded by this component.
+- The host is `inline-block` with an intrinsic width by default; `fullwidth` switches it to a block that fills the parent.

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

@@ -1,140 +1,199 @@
-# Resizable Components
-
-A flexible resizable panel system built with Lit web components for the Reliability Design System.
-
-## Components
-
-### `<rel-resizable-group>`
-Container for resizable panels. Manages layout direction and coordinates resizing between panels.
-
-**Attributes:**
-- `direction` (string): Layout direction - `"horizontal"` (default) or `"vertical"`
-
-**Events:**
-- `rel-resize`: Emitted during resize with detail `{ direction, sizes: number[] }`
-- `rel-resize-end`: Emitted when resize completes with detail `{ direction, sizes: number[] }`
-
-### `<rel-resizable-panel>`
-Individual resizable panel within a group.
-
-**Attributes:**
-- `defaultsize` (number): Initial size in percentage (optional)
-- `minsize` (number): Minimum size in percentage (default: 10)
-- `maxsize` (number): Maximum size in percentage (default: 90)
-
-### `<rel-resizable-handle>`
-Draggable separator between panels.
-
-**Features:**
-- Pointer drag support (click and drag to resize)
-- Keyboard navigation:
-  - Horizontal: ArrowLeft/ArrowRight (2% step, 5% with Shift)
-  - Vertical: ArrowUp/ArrowDown (2% step, 5% with Shift)
-- Accessible with `role="separator"` and ARIA attributes
-- Visual feedback on hover/focus/drag
-
-## Usage
-
-### Basic Horizontal Layout
-```html
-<rel-resizable-group direction="horizontal">
-  <rel-resizable-panel defaultsize="50">
-    Left Panel
-  </rel-resizable-panel>
-  <rel-resizable-handle></rel-resizable-handle>
-  <rel-resizable-panel defaultsize="50">
-    Right Panel
-  </rel-resizable-panel>
-</rel-resizable-group>
-```
-
-### Vertical Layout
-```html
-<rel-resizable-group direction="vertical">
-  <rel-resizable-panel defaultsize="40">
-    Top Panel
-  </rel-resizable-panel>
-  <rel-resizable-handle></rel-resizable-handle>
-  <rel-resizable-panel defaultsize="60">
-    Bottom Panel
-  </rel-resizable-panel>
-</rel-resizable-group>
-```
-
-### Nested Layout
-```html
-<rel-resizable-group direction="horizontal">
-  <rel-resizable-panel defaultsize="33">
-    Left 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">
-        Top Content
-      </rel-resizable-panel>
-      <rel-resizable-handle></rel-resizable-handle>
-      <rel-resizable-panel defaultsize="50">
-        Bottom Content
-      </rel-resizable-panel>
-    </rel-resizable-group>
-  </rel-resizable-panel>
-</rel-resizable-group>
-```
-
-### With Constraints
-```html
-<rel-resizable-group direction="horizontal">
-  <rel-resizable-panel defaultsize="30" minsize="20" maxsize="50">
-    Constrained Panel
-  </rel-resizable-panel>
-  <rel-resizable-handle></rel-resizable-handle>
-  <rel-resizable-panel defaultsize="70">
-    Main Panel
-  </rel-resizable-panel>
-</rel-resizable-group>
-```
-
-## How It Works
-
-### Size Calculation
-1. **Initialization**: On first render, the group reads all direct child panels and handles
-2. **Default Sizes**: If panels specify `defaultsize`, those are used; otherwise space is distributed evenly
-3. **Normalization**: All sizes are normalized to total 100% across all panels
-4. **Percentage-Based**: Sizes are always in percentages, ensuring responsive layouts
-
-### Resizing Behavior
-- **Pointer Drag**: Click and drag a handle to resize adjacent panels
-- **Keyboard**: Focus a handle and use arrow keys (direction-aware)
-- **Constraints**: Min/max sizes are enforced; total percentage is always preserved
-- **Pair Adjustment**: Only the two panels adjacent to a handle are resized
-
-### Events
-- Use `rel-resize` to track live resizing (useful for updating dependent content)
-- Use `rel-resize-end` to react after resize completes (useful for saving preferences)
-
-## Accessibility
-
-- Handles are keyboard focusable with `tabindex="0"`
-- `role="separator"` with appropriate `aria-orientation`
-- `aria-valuenow`, `aria-valuemin`, `aria-valuemax` reflect current split
-- Visual focus indicators using design tokens
-- Standard cursor changes (col-resize/row-resize)
-
-## Styling
-
-All styling uses Reliability Design System tokens:
-- Borders: `--rel-stroke-sm`
-- Colors: `--rel-bg-neutral-elevated-*`, `--rel-bg-info`, `--rel-bg-surface`
-- Spacing: `--rel-spacing-*`
-- Border radius: `--rel-border-radius-*`
-
-Panels have `overflow: auto` by default for scrollable content.
-
-## Limitations
-
-1. **Direct Children Only**: Panels and handles must be direct children of the group
-2. **Handle Placement**: Handles should be placed between panels in the expected order
-3. **No Collapse**: Panels cannot collapse to 0% (use min/max to control)
-4. **Single Direction**: Each group has one direction; nest groups for complex layouts
-5. **Manual Updates**: Group doesn't automatically observe DOM changes after initialization
+# 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.