@fusion.dev/helix-headless 0.158.0 → 0.160.0

package/dist/app-header/root/app-header-root.d.ts

@@ -1,5 +1,6 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
+declare const HelixHeadlessAppHeader_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
  * @summary Page-level banner holding brand, navigation, and actions.
  *
@@ -26,12 +27,21 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * **Set `fold-below` to fold the middle region on a narrow screen.** Below that
  * many pixels of the bar's own width, the middle region is hidden behind a
- * toggle at the end of the bar, named by `menu-label`. The toggle says whether
- * the region is open with `aria-expanded`, and the region opens below the row.
- * Escape closes it and puts focus back on the toggle. The custom state
- * `folded` is on the host while the bar is that narrow, and `open` while the
- * folded region is open. A server serves the bar unfolded, and the browser
- * folds it once it has measured it.
+ * toggle at the end of the bar, named by `menu-label`, or at its start with
+ * `toggle-placement="start"`. The toggle says whether the region is open with
+ * `aria-expanded`, and the region opens below the row. The region follows the
+ * toggle's region in focus order, so Tab from the toggle at the end goes into
+ * the open region. The custom state `folded` is on the host while the bar is
+ * that narrow, and `open` while the folded region is open. A server serves the
+ * bar unfolded, and the browser folds it once it has measured it.
+ *
+ * **`open` says whether the folded region is open, and setting it opens or
+ * closes the region.** `requestOpen(true)` and `requestOpen(false)` do the same
+ * and send `helix-before-open` or `helix-before-close` first, which you can
+ * cancel, and `toggleOpen()` asks for the opposite. `toggle` follows every
+ * change. The region closes on Escape, which puts focus back on the toggle,
+ * when focus moves to something outside the header, and on a press outside
+ * it. A bar that widens past `fold-below` closes its region.
  *
  * The host is the page's `banner` landmark. Placed inside `main`, `article`,
  * `aside`, `nav` or `section`, it is a plain box instead, as a native
@@ -53,11 +63,14 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @slot menu-icon - Replaces the glyph inside the toggle that opens a folded middle region.
  * @slot start - Leading content, usually a wordmark.
  *
+ * @event {HelixBeforeCloseEvent} helix-before-close - The folded region is about to close. Cancelable: cancel it to keep it open.
+ * @event {HelixBeforeOpenEvent} helix-before-open - The folded region is about to open. Cancelable: cancel it to keep it closed.
  * @event {HelixScrolledEvent} helix-scrolled - Fired when the page crosses the
  * scroll threshold, with the new state. A custom state cannot be observed the
  * way an attribute can, so listen for this event to follow it. The event uses
  * the header's own threshold and hysteresis, so you do not need a second scroll
  * listener.
+ * @event {ToggleEvent} toggle - The folded region opened or closed. The event carries `newState` and `oldState`.
  *
  * @csspart content - The middle region.
  * @csspart end - The trailing region.
@@ -71,7 +84,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @cssstate open - While the folded middle region is open.
  * @cssstate scrolled - While the page is scrolled down from the top, which is when the bar lifts off it.
  */
-export declare class HelixHeadlessAppHeader extends HelixElement {
+export declare class HelixHeadlessAppHeader extends HelixHeadlessAppHeader_base {
     /**
      * The key this family's words are registered under, its styled tag:
      * `registerWords('de', { 'helix-app-header': { menuLabel: 'Menü' } })`.
@@ -103,20 +116,37 @@ export declare class HelixHeadlessAppHeader extends HelixElement {
      * page scrolls up.
      */
     hideOnScroll: boolean;
+    /** The name of the toggle that opens a folded middle region. */
+    menuLabel: string;
     /** Whether the bar is narrower than `fold-below`, which only the observer sets. */
     private folded;
-    /** Whether the folded middle region is open. */
-    private unfolded;
+    /** Whether the folded middle region is open and showing. */
+    private get unfolded();
     /** Watches the bar's own width while `fold-below` is set. */
     private widths;
     /** Starts or stops watching the width, according to `fold-below`. */
     private watchWidth;
-    /** Folds the middle region where the bar is narrower than `fold-below`. */
+    /**
+     * Folds the middle region where the bar is narrower than `fold-below`. A bar
+     * that widens closes its region, so it starts closed when it folds again;
+     * one that narrows keeps an `open` you set.
+     */
     private fold;
     /** Opens or closes the folded middle region. */
     private readonly handleToggle;
     /** Escape in the open region closes it and puts focus back on the toggle. */
     private readonly handleKeydown;
+    /**
+     * Closes the open region when focus moves to something outside the header.
+     * Focus leaving the window has no `relatedTarget`, and closes nothing.
+     */
+    private readonly handleFocusOut;
+    /** Closes the open region on a press outside the header. */
+    private readonly handleOutsidePress;
+    /** Whether the outside press is listened for, which is while the region is open. */
+    private pressing;
+    /** Listens for a press outside while the folded region is open, and only then. */
+    private watchPresses;
     /** Whether the bar is out of the way, under `hide-on-scroll`. */
     private away;
     /** Where the page was last scrolled to, to tell down from up. */
@@ -132,13 +162,19 @@ export declare class HelixHeadlessAppHeader extends HelixElement {
      * or its folded region is open, which a reader is using.
      */
     private follow;
-    /** The name of the toggle that opens a folded middle region. */
-    menuLabel: string;
     /**
      * The id of the element whose scrolling lifts the bar, for an app shell that
      * scrolls a container instead of the window. Unset is the window.
      */
     scroller?: string;
+    /**
+     * Where the toggle that opens a folded middle region sits: at the end of the
+     * bar, after the trailing content, or with `start`, before the leading
+     * content.
+     *
+     * Optional, so the resting bar writes no attribute onto the host.
+     */
+    togglePlacement?: 'start';
     private landmark;
     private scrolled;
     /** What scroll is listened to now, so a change of `scroller` moves it. */
@@ -187,6 +223,16 @@ export declare class HelixHeadlessAppHeader extends HelixElement {
      * tier above replaces it by overriding.
      */
     protected renderMenuIcon(): TemplateResult;
+    /**
+     * The row, with the middle region between the leading and the trailing
+     * content while the bar is wide, and after both while it is folded.
+     *
+     * **Folded, the region comes last in the markup**, because it opens below
+     * the row and focus order follows the markup. Between the two, as it is
+     * drawn on a wide bar, Tab from the toggle at the end left the header and
+     * the links it had just revealed were reached only by going back. The grid
+     * puts it on its own row either way.
+     */
     protected render(): TemplateResult;
 }
 declare global {
@@ -194,3 +240,4 @@ declare global {
         'helix-headless-app-header': HelixHeadlessAppHeader;
     }
 }
+export {};

package/dist/app-header/root/app-header-root.js

@@ -4,35 +4,47 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, deepActiveElement, deepContains, elementById, HelixElement, HelixScrolledEvent, hostAria, words, } from '@fusion.dev/helix-core';
+import { customElement, deepActiveElement, deepContains, elementById, HelixElement, HelixScrolledEvent, hostAria, MixinControllerOpen, words, } from '@fusion.dev/helix-core';
 import { list } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { inSectioningContent } from '../sectioning.js';
-let HelixHeadlessAppHeader = class HelixHeadlessAppHeader extends HelixElement {
+let HelixHeadlessAppHeader = class HelixHeadlessAppHeader extends MixinControllerOpen(HelixElement) {
     constructor() {
         super(...arguments);
         this.hideOnScroll = false;
+        this.menuLabel = 'Menu';
         this.folded = false;
-        this.unfolded = false;
         this.handleToggle = () => {
-            this.unfolded = !this.unfolded;
+            this.toggleOpen();
         };
         this.handleKeydown = (event) => {
             if (event.key !== 'Escape' || !this.unfolded || event.defaultPrevented) {
                 return;
             }
             event.preventDefault();
-            this.unfolded = false;
-            void this.updateComplete.then(() => this.partNamed('toggle')?.focus());
+            if (this.requestOpen(false)) {
+                void this.updateComplete.then(() => this.partNamed('toggle')?.focus());
+            }
+        };
+        this.handleFocusOut = (event) => {
+            const next = event.relatedTarget;
+            if (this.unfolded && next instanceof Node && !deepContains(this, next)) {
+                this.requestOpen(false);
+            }
         };
+        this.handleOutsidePress = (event) => {
+            if (this.unfolded && !event.composedPath().includes(this)) {
+                this.requestOpen(false);
+            }
+        };
+        this.pressing = false;
         this.away = false;
         this.lastY = 0;
         this.handleFocusIn = () => {
             this.hide(false);
         };
-        this.menuLabel = 'Menu';
         this.landmark = 'banner';
         this.scrolled = false;
         this.handleScroll = () => {
@@ -49,6 +61,9 @@ let HelixHeadlessAppHeader = class HelixHeadlessAppHeader extends HelixElement {
         };
     }
     static { this.words = 'helix-app-header'; }
+    get unfolded() {
+        return this.folded && this.open;
+    }
     watchWidth() {
         if (!this.foldBelow || typeof ResizeObserver === 'undefined') {
             this.widths?.disconnect();
@@ -71,7 +86,22 @@ let HelixHeadlessAppHeader = class HelixHeadlessAppHeader extends HelixElement {
         const folded = this.foldBelow !== undefined && width < this.foldBelow;
         if (folded !== this.folded) {
             this.folded = folded;
-            this.unfolded = false;
+            if (!folded && this.open) {
+                this.open = false;
+            }
+        }
+    }
+    watchPresses() {
+        const want = this.unfolded && this.isConnected;
+        if (want === this.pressing) {
+            return;
+        }
+        this.pressing = want;
+        if (want) {
+            document.addEventListener('pointerdown', this.handleOutsidePress, true);
+        }
+        else {
+            document.removeEventListener('pointerdown', this.handleOutsidePress, true);
         }
     }
     hide(away) {
@@ -119,7 +149,7 @@ let HelixHeadlessAppHeader = class HelixHeadlessAppHeader extends HelixElement {
         super.willUpdate(changed);
         hostAria(this.internals, { role: this.landmark });
         this.toggleState('folded', this.folded);
-        this.toggleState('open', this.folded && this.unfolded);
+        this.toggleState('open', this.unfolded);
     }
     connectedCallback() {
         super.connectedCallback();
@@ -131,9 +161,11 @@ let HelixHeadlessAppHeader = class HelixHeadlessAppHeader extends HelixElement {
         });
         this.listen();
         this.addEventListener('focusin', this.handleFocusIn);
+        this.addEventListener('focusout', this.handleFocusOut);
         this.addEventListener('keydown', this.handleKeydown);
         if (this.hasUpdated) {
             this.watchWidth();
+            this.watchPresses();
         }
     }
     readLandmark() {
@@ -145,9 +177,11 @@ let HelixHeadlessAppHeader = class HelixHeadlessAppHeader extends HelixElement {
         this.source?.removeEventListener('scroll', this.handleScroll);
         this.source = undefined;
         this.removeEventListener('focusin', this.handleFocusIn);
+        this.removeEventListener('focusout', this.handleFocusOut);
         this.removeEventListener('keydown', this.handleKeydown);
         this.widths?.disconnect();
         this.widths = undefined;
+        this.watchPresses();
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
@@ -170,6 +204,7 @@ let HelixHeadlessAppHeader = class HelixHeadlessAppHeader extends HelixElement {
         if (changed.has('hideOnScroll') && !this.hideOnScroll) {
             this.hide(false);
         }
+        this.watchPresses();
     }
     renderMenuIcon() {
         return html `<slot name="menu-icon">
@@ -179,22 +214,26 @@ let HelixHeadlessAppHeader = class HelixHeadlessAppHeader extends HelixElement {
     </slot>`;
     }
     render() {
+        const toggle = this.folded
+            ? html `<button
+          part="toggle"
+          type="button"
+          aria-controls="content"
+          aria-expanded=${this.unfolded ? 'true' : 'false'}
+          aria-label=${this.menuLabel}
+          @click=${this.handleToggle}
+        >
+          ${this.renderMenuIcon()}
+        </button>`
+            : nothing;
+        const first = this.togglePlacement === 'start';
+        const content = html `<div part="content" id="content" ?hidden=${this.folded && !this.unfolded}><slot></slot></div>`;
         return html `
       <div part="row">
-        <div part="start"><slot name="start"></slot></div>
-        <div part="content" id="content" ?hidden=${this.folded && !this.unfolded}><slot></slot></div>
-        <div part="end"><slot name="end"></slot>${this.folded
-            ? html `<button
-                part="toggle"
-                type="button"
-                aria-controls="content"
-                aria-expanded=${this.unfolded ? 'true' : 'false'}
-                aria-label=${this.menuLabel}
-                @click=${this.handleToggle}
-              >
-                ${this.renderMenuIcon()}
-              </button>`
-            : nothing}</div>
+        <div part="start">${first ? toggle : nothing}<slot name="start"></slot></div>
+        ${this.folded ? nothing : content}
+        <div part="end"><slot name="end"></slot>${first ? nothing : toggle}</div>
+        ${this.folded ? content : nothing}
       </div>
     `;
     }
@@ -208,19 +247,19 @@ __decorate([
 __decorate([
     property({ attribute: 'hide-on-scroll', type: Boolean })
 ], HelixHeadlessAppHeader.prototype, "hideOnScroll", void 0);
-__decorate([
-    state()
-], HelixHeadlessAppHeader.prototype, "folded", void 0);
-__decorate([
-    state()
-], HelixHeadlessAppHeader.prototype, "unfolded", void 0);
 __decorate([
     words,
     property({ attribute: 'menu-label' })
 ], HelixHeadlessAppHeader.prototype, "menuLabel", void 0);
+__decorate([
+    state()
+], HelixHeadlessAppHeader.prototype, "folded", void 0);
 __decorate([
     property()
 ], HelixHeadlessAppHeader.prototype, "scroller", void 0);
+__decorate([
+    property({ attribute: 'toggle-placement', reflect: true })
+], HelixHeadlessAppHeader.prototype, "togglePlacement", void 0);
 HelixHeadlessAppHeader = __decorate([
     customElement('helix-headless-app-header')
 ], HelixHeadlessAppHeader);

package/dist/button/root/button-root.d.ts

@@ -57,6 +57,7 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * @csspart text - The button's words, which the styled button trims to their capitals and baseline so the letters sit at the middle in any font.
  *
  * @cssstate pending - The button is pending: `pending` is set.
+ * @cssstate pressed - A Button Group in a selection mode has this button pressed.
  */
 export declare class HelixHeadlessButton extends HelixFormElement {
     /**
@@ -206,6 +207,13 @@ export declare class HelixHeadlessButton extends HelixFormElement {
      * reported collapsed and expanded and no popup.
      */
     popup?: 'dialog' | 'grid' | 'listbox' | 'menu' | 'tree';
+    /**
+     * @internal Set by a Button Group in a selection mode: whether the group has
+     * this button pressed. Recorded as `:state(pressed)`, so a page can style a
+     * pressed button from its own element. The group says it to screen readers
+     * on the control.
+     */
+    pressed?: boolean | undefined;
     /**
      * The status region, rendered from the first time the button is pending, so
      * a button that never waits carries no live region.

package/dist/button/root/button-root.js

@@ -140,6 +140,7 @@ let HelixHeadlessButton = class HelixHeadlessButton extends HelixFormElement {
     willUpdate(changed) {
         super.willUpdate(changed);
         this.toggleState('pending', this.pending);
+        this.toggleState('pressed', this.pressed === true);
     }
     updated(changed) {
         super.updated(changed);
@@ -238,6 +239,9 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessButton.prototype, "popup", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessButton.prototype, "pressed", void 0);
 __decorate([
     property()
 ], HelixHeadlessButton.prototype, "type", void 0);

package/dist/button-group/root/button-group-root.d.ts

@@ -16,11 +16,15 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * appearance and size.
  *
  * **Buttons that stay pressed.** With `selection-mode`, each button with a
- * `value` is a toggle button: a press presses or releases it, and it says so
- * with `aria-pressed`. `single` keeps one pressed at a time, and a press on the
- * pressed one releases it. `multiple` lets any number be pressed. `value` is
- * the pressed values, comma separated. A press sends a cancelable
- * `helix-before-change` with the value it would leave, then `change`.
+ * `value` is a toggle button: a press presses or releases it. `multiple` lets
+ * any number be pressed, and each button says so with `aria-pressed`. `single`
+ * keeps one pressed at a time: the group is a `radiogroup` and each button a
+ * `radio` that says so with `aria-checked`, as React Aria's toggle button
+ * group is. A press on the pressed one releases it, unless
+ * `disallow-empty-selection` keeps one pressed. `value` is the pressed values,
+ * comma separated. A press sends a cancelable `helix-before-change` with the
+ * value it would leave, then `change`. A pressed Helix button has
+ * `:state(pressed)` on its own element.
  *
  * The pressed state is written on the control inside each button's shadow
  * root, so the markup you rendered is never changed and a framework hydrating
@@ -48,10 +52,10 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * | Space, Enter | Presses or releases the focused button. |
  *
  * Left and Right swap on a right-to-left page, and a disabled button is
- * passed over. In a selection mode the group is a `toolbar`, with
+ * passed over. Under `multiple` the group is a `toolbar`, with
  * `aria-orientation` under `orientation="vertical"`. Inside a toolbar it stays
  * a named `group`, and the toolbar's own arrow keys walk its buttons, so a
- * reader meets one toolbar.
+ * reader meets one toolbar. Under `single` it is a `radiogroup` either way.
  *
  * @since 0.1.0
  * @status stable
@@ -69,6 +73,12 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @cssstate pressed - While a group with `selection-mode` has a button pressed.
  */
 export declare class HelixHeadlessButtonGroup extends HelixElement {
+    /**
+     * Keeps at least one button pressed once one is, as React Aria's
+     * `disallowEmptySelection`: a press that would leave none pressed is
+     * refused.
+     */
+    disallowEmptySelection: boolean;
     /**
      * The group's name, read by screen readers.
      *
@@ -172,6 +182,9 @@ export declare class HelixHeadlessButtonGroup extends HelixElement {
      * Says on a button's control whether it is pressed, or that it is no toggle
      * at all where `pressed` is undefined. A styled tier draws the look here.
      *
+     * Under `single` the control is a `radio` that says so with `aria-checked`,
+     * and under `multiple` a toggle button that says so with `aria-pressed`.
+     *
      * @param control The focusable control inside the button's shadow root.
      * @param pressed Whether the button is pressed, or undefined where it is not a toggle.
      */

package/dist/button-group/root/button-group-root.js

@@ -12,6 +12,7 @@ const isGroupButton = (child) => child instanceof HTMLElement && 'focusable' in
 let HelixHeadlessButtonGroup = class HelixHeadlessButtonGroup extends HelixElement {
     constructor() {
         super(...arguments);
+        this.disallowEmptySelection = false;
         this.label = '';
         this.value = '';
         this.lastFocused = undefined;
@@ -21,8 +22,12 @@ let HelixHeadlessButtonGroup = class HelixHeadlessButtonGroup extends HelixEleme
             const mode = this.selectionMode;
             const button = this.buttons.find((one) => event.composedPath().includes(one));
             if (mode && button && button.value !== '') {
-                requestValue(this, pressedValue(mode, this.value, button.value), (next) => {
-                    this.value = next;
+                const next = pressedValue(mode, this.value, button.value);
+                if (this.disallowEmptySelection && commaList(next).length === 0) {
+                    return;
+                }
+                requestValue(this, next, (value) => {
+                    this.value = value;
                 });
             }
         };
@@ -107,17 +112,30 @@ let HelixHeadlessButtonGroup = class HelixHeadlessButtonGroup extends HelixEleme
             const control = button.shadowRoot?.querySelector('button');
             if (control && !button.hasAttribute('aria-pressed')) {
                 const toggle = this.told.has(button) && button.value !== '';
-                this.markPressed(control, toggle ? this.pressed(button) : undefined);
+                const pressed = toggle ? this.pressed(button) : undefined;
+                if ('pressed' in button && button.pressed !== pressed) {
+                    button.pressed = pressed;
+                }
+                this.markPressed(control, pressed);
             }
         });
     }
     markPressed(control, pressed) {
-        if (pressed === undefined) {
+        const radio = pressed !== undefined && this.selectionMode === 'single';
+        if (pressed === undefined || radio) {
             control.removeAttribute('aria-pressed');
         }
         else {
             control.setAttribute('aria-pressed', String(pressed));
         }
+        if (radio) {
+            control.setAttribute('role', 'radio');
+            control.setAttribute('aria-checked', String(pressed));
+        }
+        else {
+            control.removeAttribute('role');
+            control.removeAttribute('aria-checked');
+        }
         control.style.setProperty('--button-group-pressed', pressed === undefined ? '' : pressed ? '1' : '0');
     }
     connectedCallback() {
@@ -143,7 +161,11 @@ let HelixHeadlessButtonGroup = class HelixHeadlessButtonGroup extends HelixEleme
     willUpdate(changed) {
         super.willUpdate(changed);
         const toolbar = this.roving;
-        hostAria(this.internals, { label: this.label, role: toolbar ? 'toolbar' : 'group' });
+        const radios = this.selectionMode === 'single';
+        hostAria(this.internals, {
+            label: this.label,
+            role: radios ? 'radiogroup' : toolbar ? 'toolbar' : 'group',
+        });
         this.internals.ariaOrientation = toolbar ? (this.orientation ?? null) : null;
         this.toggleState('pressed', Boolean(this.selectionMode) && commaList(this.value).length > 0);
     }
@@ -159,6 +181,9 @@ let HelixHeadlessButtonGroup = class HelixHeadlessButtonGroup extends HelixEleme
         return html `<slot></slot>`;
     }
 };
+__decorate([
+    property({ attribute: 'disallow-empty-selection', type: Boolean })
+], HelixHeadlessButtonGroup.prototype, "disallowEmptySelection", void 0);
 __decorate([
     property()
 ], HelixHeadlessButtonGroup.prototype, "label", void 0);