panelset 1.0.8 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [1.2.0] - 2026-06-22
+
+### Added
+- PanelControl: a tablist controller with keyboard navigation
+- Web component versions
+- PNavigation on PanelSet: `next()`, `prev()` etc
+- `addPanel()` and `removePanel()`
+- `refresh()`
+- Verb buttons wired by delegation: `data-ps-next`, `data-ps-prev`, `data-ps-close`.
+- Lifecycle events
+- Async content loading
+
+
+## [1.0.9] - 2026-04-10
+
+### Added
+- Added Panel
+- New documentation
+- Added destroy() method
+- Added data-panel-trigger implicit wiring (auto ID assignment)
+
+### Fixed
+- Fixed mid-close reversal bug (smooth re-open from mid-animation)
+- Fixed focus jump when closeSiblings closes a sibling
+
+### Removed
+- Removed Core.measure()
+
+
 
 ## [1.0.8] - 2026-02-18
 

package/README.md

@@ -0,0 +1,213 @@
+# PanelSet
+
+**Flexible panel management with smooth transitions.**
+
+A TypeScript + SCSS library for animating elements between sizes. Three classes share one animation core (a lock / measure / animate / unlock cycle): the browser does the animating, JavaScript only measures and sets pixel values. Accessible by default (managed ARIA and focus), interrupt-safe, and it respects `prefers-reduced-motion`.
+
+> **Documentation:** this README is a quick reference. The full guides, every option, and live examples live in the HTML docs. Source and issues: <https://github.com/martinomagnifico/panelset>.
+
+## The three classes
+
+| Class | What it does |
+|---|---|
+| **`Panel`** | A single element that opens and closes (accordions, show-more, sidebars, drawers). Animates `height` or `width`. |
+| **`PanelSet`** | A container that switches between mutually exclusive panels (tabs, wizards, steppers). Animates its own height to fit the incoming panel. |
+| **`PanelControl`** | Optional. Makes a tab strip or sidebar drive a `PanelSet`: keyboard navigation, roving `tabindex`, `aria-selected`, and tab locking through `setTabState()`. |
+
+`PanelControl` is side-effect-free, so it tree-shakes out of the ESM build when you don’t import it.
+
+## Installation
+
+```bash
+npm install panelset
+```
+
+```js
+import { Panel, PanelSet, PanelControl } from 'panelset';
+import 'panelset/style.css';
+```
+
+Or as a script tag (IIFE bundle):
+
+```html
+<link rel="stylesheet" href="panelset.css">
+<script src="panelset.js"></script>
+<!-- exposes window.Panel / PanelSet / PanelControl and registers
+     <ps-panel> / <ps-panelset> / <ps-panelcontrol> -->
+```
+
+## Panel
+
+Panels are **closed by default** (no class needed). Add `is-open` to start open.
+
+```html
+<button aria-controls="my-panel" aria-expanded="false">Toggle</button>
+
+<div id="my-panel" data-panel>
+  <div class="panel-wrapper">Content here</div>
+</div>
+```
+
+```js
+import { Panel } from 'panelset';
+Panel.init();
+```
+
+Any `[aria-controls]` element is a trigger. As a shortcut, a `[data-panel-trigger]` button placed next to a panel (or as the direct child of a heading next to it) gets its `id` and ARIA set up automatically.
+
+### Accordion (group)
+
+```html
+<div data-panel-group data-panel-close-siblings>
+  <button aria-controls="acc-1" aria-expanded="false">Item 1</button>
+  <div id="acc-1" data-panel><div class="panel-wrapper">Answer 1</div></div>
+
+  <button aria-controls="acc-2" aria-expanded="false">Item 2</button>
+  <div id="acc-2" data-panel><div class="panel-wrapper">Answer 2</div></div>
+</div>
+```
+
+`data-panel-close-siblings` (or `closeSiblings: true`) makes opening one panel close the others.
+
+### Panel options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `axis` | `'vertical' \| 'horizontal'` | `'vertical'` | Which dimension animates (height or width) |
+| `align` | `'start' \| 'center' \| 'end'` | `'start'` | Content alignment within the clipped container |
+| `transitions` | `boolean` | `true` | Enable/disable CSS transitions |
+| `autoFocus` | `false \| true \| 'heading' \| 'first' \| 'input'` | `false` | Move focus into the panel on open |
+| `returnFocus` | `boolean` | `true` | Return focus to the trigger on close |
+| `closeSiblings` | `boolean` | `false` | Close other open panels in the same group |
+| `closeOnResize` | `boolean` | `false` | Close the panel when the window is resized |
+| `interruptible` | `boolean` | `true` | Allow a new open/close to interrupt one in progress |
+| `persist` | `boolean` | `false` | Save open/closed state to `localStorage` |
+| `deepLink` | `boolean` | `false` | Reflect open state in the `?panel=` URL |
+| `loadingDelay` | `number` | `320` | ms before the spinner appears during async loading |
+| `loadingHeight` | `number` | `150` | px reserved while async content loads |
+| `debug` | `boolean` | `false` | Log events to the console |
+
+### Async content
+
+```js
+const panel = new Panel('#my-panel');
+
+panel.onBeforeOpen((el, signal) => {
+  return fetch('/api/content', { signal })
+    .then(r => r.text())
+    .then(html => { el.querySelector('.panel-wrapper').innerHTML = html; });
+}, { once: true });
+```
+
+Or listen for the `panel:beforeopen` event and call `e.detail.waitUntil(promise)` to hold the open until it resolves.
+
+## PanelSet
+
+```html
+<nav role="tablist" data-panelcontrol>
+  <button role="tab" aria-controls="panel-1" aria-selected="true">Tab 1</button>
+  <button role="tab" aria-controls="panel-2">Tab 2</button>
+</nav>
+
+<div data-panelset>
+  <div class="panel-wrapper">
+    <div id="panel-1" role="tabpanel" class="active">Content 1</div>
+    <div id="panel-2" role="tabpanel" hidden>Content 2</div>
+  </div>
+</div>
+```
+
+```js
+import { PanelSet, PanelControl } from 'panelset';
+PanelSet.init();
+PanelControl.init();   // keyboard navigation + state for the tab strip
+```
+
+Mark the starting panel with `class="active"` and every other panel `hidden`.
+
+### PanelSet options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `align` | `'start' \| 'center' \| 'end'` | `'start'` | Alignment while opening/closing |
+| `transitions` | `boolean \| { panels?: boolean, height?: boolean }` | `true` | Enable/disable transitions (or per axis) |
+| `levels` | `boolean` | `false` | Give panels a depth order from DOM position; forward/back slide opposite ways |
+| `loop` | `boolean` | `false` | `next()` / `prev()` wrap around the ends |
+| `closable` | `boolean` | `false` | Allow the whole container to open and close |
+| `closeOnTab` | `boolean` | `false` | Clicking the active tab closes the container (needs `closable`) |
+| `disabledMode` | `'aria' \| 'native'` | `'aria'` | How `data-ps-next` / `-prev` buttons are disabled at the ends |
+| `autoFocus` | `false \| true \| 'heading' \| 'first' \| 'input'` | `false` | Move focus into the panel on activation |
+| `returnFocus` | `boolean` | `false` | Return focus to the trigger on close |
+| `interruptible` | `boolean` | `true` | Allow a new activation to interrupt one in progress |
+| `manageTriggers` | `boolean` | `true` | Reflect `aria-selected` / activating state onto `[aria-controls]` triggers |
+| `manageLabels` | `boolean` | `true` | Link each panel to its tab via `aria-labelledby` (auto-generates a tab id if needed) |
+| `persist` | `boolean` | `false` | Save the active panel id to `localStorage` |
+| `deepLink` | `boolean` | `false` | Reflect the active panel in the `?panel=` URL |
+| `loadingDelay` | `number` | `320` | ms before the spinner appears during async loading |
+| `loadingHeight` | `number` | `150` | px reserved while async content loads |
+| `debug` | `boolean` | `false` | Log events to the console |
+
+### Async content
+
+```js
+const ps = new PanelSet('#my-panelset');
+
+ps.onBeforeOpen((targetPanel, signal) => {
+  return fetch(`/api/${targetPanel.id}`, { signal })
+    .then(r => r.json())
+    .then(data => { targetPanel.innerHTML = render(data); });
+}, { once: true });
+```
+
+## PanelControl
+
+Drives one `PanelSet` from its trigger elements, so you do not hand-write the tab interaction. Put `data-panelcontrol` on the container; add `role="tablist"` (with `role="tab"` buttons) to switch on the keyboard model (arrow keys, `Home` / `End`, roving `tabindex`). It finds its `PanelSet` through the panels the triggers point at, so the control can live anywhere in the DOM.
+
+Lock or unlock a tab from your own code:
+
+```js
+control.setTabState('panel-3', 'disabled');  // lock
+control.setTabState('panel-3', 'enabled');   // unlock
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `activation` | `'manual' \| 'auto'` | `'manual'` | `manual`: arrows move focus, Enter/Space/click activates. `auto`: arrows activate too. |
+| `debug` | `boolean` | `false` | Log to the console |
+
+## Configuration sources
+
+Every option can also be set as a **data attribute** in the markup, or as a plain attribute on the **web component**. When the same option is set more than once, the most specific wins: **defaults -> JS options -> data attribute**. The exact attribute names are listed per option in the docs.
+
+## Web components
+
+`register()` defines `<ps-panel>`, `<ps-panelset>`, and `<ps-panelcontrol>` (the script-tag build calls it for you). On the elements, options are plain attributes, no `data-` prefix.
+
+```js
+import { register } from 'panelset';
+register();            // default 'ps' prefix
+register('acme');      // <acme-panel>, <acme-panelset>, <acme-panelcontrol>
+```
+
+## CSS
+
+Timing and sizing are CSS custom properties, set on the element or any ancestor (all timing values need a unit, e.g. `0.25s` not `0`). For example, on a Panel:
+
+```css
+[data-panel] {
+  --ps-open-speed:   0.25s;
+  --ps-open-timing:  ease-in-out;
+  --ps-close-speed:  0.25s;
+  --ps-close-timing: ease-in-out;
+}
+```
+
+`PanelSet` exposes a similar set for its fade and height timing. See the docs for the full list.
+
+## Support
+
+PanelSet is free and open source. If it saves you time, consider [sponsoring my work](https://ko-fi.com/martinomagnifico).
+
+## License
+
+MIT © [Martinomagnifico](https://github.com/martinomagnifico)