@fusion.dev/helix-headless 0.171.0 → 0.172.0

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

@@ -1,4 +1,4 @@
-import { AriaForwardController, HelixElement, KeyboardNavigationController, type Placement } from '@fusion.dev/helix-core';
+import { AriaForwardController, HelixElement, KeyboardNavigationController, OpenPhaseController, type Placement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.dev/helix-core").CollectionElement) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
@@ -18,7 +18,9 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  *
  * Submenus drill down by default. A submenu replaces the panel's content, and a
  * back row returns to the previous page. One panel stays inside a narrow
- * window, and works on touch screens, which have no hover.
+ * window, and works on touch screens, which have no hover. Focus follows a
+ * mouse resting on a row in either mode, and a drilled page is a `menu` named
+ * by the row that opened it.
  *
  * **`submenus="flyout"` opens each submenu in a panel of its own beside its
  * row**, as React Aria's `SubmenuTrigger` and Radix's `Sub` do. Resting the
@@ -52,6 +54,11 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * trigger's width, for a menu as wide as its trigger:
  * `helix-menu::part(surface) { min-inline-size: var(--floating-anchor-inline-size) }`.
  *
+ * **The choices in one place.** `checkedValues` holds the values of the rows
+ * that are checked, anywhere in the menu, and setting it checks exactly
+ * those rows, as React Aria's `selectedKeys` does. `change` is sent on the
+ * menu when a reader's choice changes it.
+ *
  * With `context`, the trigger is an area and the menu is its context menu: a
  * right-click, a long press, Shift+F10 or the menu key over the area opens it
  * at the pointer, or at the area's corner from the keyboard, as Radix's context
@@ -74,7 +81,8 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * field: Up and Down Arrow move the highlight through the rows that are left,
  * Enter chooses the highlighted row, Right Arrow opens its submenu, Left Arrow
  * on a submenu goes back, and Escape clears the filter and then closes the
- * menu. Home, End and the other keys move the caret and type. The field names
+ * menu. A screen reader hears how many rows the filter keeps
+ * (`results-label`). Home, End and the other keys move the caret and type. The field names
  * the highlighted row with `aria-activedescendant`, and the rows are a `menu`
  * after the field. Cancel `helix-filter` to keep every row
  * showing and narrow the rows yourself, such as by replacing them with rows
@@ -87,9 +95,12 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * @documentation https://fusion.dev/helix/components/menu
  *
  * @slot - The items.
+ * @slot empty - What the menu shows when it has no items, for content richer than `empty-text`.
+ * @slot loading - What the menu shows while its items load, for content richer than `loading-text`.
  * @slot no-results - What the menu shows when the filter keeps no rows, for content richer than `no-results-text`.
  * @slot trigger - The control that opens the menu, or with `context` the area a context menu opens over.
  *
+ * @event {Event} change - A reader's choice checked or unchecked rows. Read `checkedValues` for the rows that are checked now.
  * @event {HelixBeforeCloseEvent} helix-before-close - The menu is about to close. Cancelable: cancel it to keep it open.
  * @event {HelixBeforeOpenEvent} helix-before-open - The menu is about to open. Cancelable: cancel it to keep it closed.
  * @event {HelixFilterEvent} helix-filter - The text in the filter field changed, with the new text in `detail.value`. Cancelable: cancel it to keep every row showing and narrow the rows yourself.
@@ -110,6 +121,8 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * @cssproperty --floating-available-block-size - The room between the panel and the edge of the screen it opens toward, written on the panel while it is open. Read it; a value set here is written over.
  *
  * @cssstate drilled - A submenu's page is showing, so content that is not a row can hide with the top page.
+ * @cssstate entering - From the moment the panel shows until its entrance has finished.
+ * @cssstate exiting - From the moment the panel hides until its exit has finished.
  * @cssstate mark - A row on the current page has a checkbox or a link, so every row keeps the trailing column.
  * @cssstate open - While the menu is open.
  * @cssstate placed-bottom - While the open panel sits below its trigger.
@@ -124,6 +137,7 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      * `registerWords('de', { 'helix-menu': { backLabel: 'Zurück' } })`.
      */
     static words: string;
+    protected statusSlots: boolean;
     /**
      * The text of the row that returns from a submenu.
      */
@@ -204,6 +218,12 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      * Space between the trigger and the surface, in pixels.
      */
     offset: number;
+    /**
+     * What opens the menu from its trigger. `long-press` leaves a press to the
+     * trigger's own action and opens the menu on a press held for half a second,
+     * or on Alt+Down or Alt+Up.
+     */
+    openOn: 'click' | 'long-press';
     /** Whether the trigger opens the menu only on a held press. */
     private get pressHeld();
     /**
@@ -213,18 +233,18 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     private readonly longPress;
     /** Where a held press on a context menu's area is, to open the menu there. */
     private heldAt;
-    /**
-     * What opens the menu from its trigger. `long-press` leaves a press to the
-     * trigger's own action and opens the menu on a press held for half a second,
-     * or on Alt+Down or Alt+Up.
-     */
-    openOn: 'click' | 'long-press';
     /**
      * The side the menu opens on, when there is room.
      *
      * It moves if that side does not fit.
      */
     placement: Placement;
+    /**
+     * What a screen reader hears when the filter narrows the rows. `{count}` is
+     * how many rows are left, written in the locale, and each language writes
+     * the forms it has, as Listbox's `results-label` does.
+     */
+    resultsLabel: string;
     /**
      * How a submenu opens. `drill` shows it in place of the page showing, with
      * a way back. `flyout` opens it in a panel of its own beside its row.
@@ -257,6 +277,7 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      * menu that drills, so those keys are spoken for here rather than unhandled.
      */
     protected readonly keys: KeyboardNavigationController;
+    protected readonly phases: OpenPhaseController;
     /** Carries a host `aria-label` and `aria-labelledby` to the surface. */
     protected readonly aria: AriaForwardController;
     /** Where a context menu was asked for, in the viewport, while it is open. */
@@ -310,6 +331,21 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      * it, the one direction a reference crosses.
      */
     private reach;
+    /** Watches for rows taken away while the menu is open. */
+    private rowWatch;
+    /**
+     * Moves the reader to a neighbor when the page takes away the row they were
+     * on: the row that took its place, or the one before it where it was the
+     * last. A menu with no rows left closes and gives focus to its trigger.
+     *
+     * **Focus went to the body**, and the menu then ignored every key, its
+     * listener being on the host: measured in Chromium, removing the focused
+     * row and pressing ArrowUp did nothing. List and Virtual List move focus to
+     * a neighbor the same way, as React Aria's collections do. With `filterable`,
+     * focus stays in the field and the highlight moves. Focus a reader put
+     * anywhere but the body is left there.
+     */
+    private readonly followRemoved;
     /** Opens the menu. */
     show(): void;
     /** Opens the menu with focus on its first or its last row. */
@@ -327,6 +363,23 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     private enter;
     /** Returns to the page above, or closes when there is none. */
     private leave;
+    /** The choice rows anywhere in the menu, in document order. */
+    private get choiceRows();
+    /**
+     * The values of the choice rows that are checked, anywhere in the menu, in
+     * document order.
+     *
+     * Set it to check exactly those rows and uncheck every other choice row, as
+     * React Aria's `selectedKeys` controls a menu's selection from one place.
+     * Each row keeps its own `checked` too, which this reads and writes. `change`
+     * is sent on the menu when a reader's choice changes it.
+     */
+    get checkedValues(): string[];
+    set checkedValues(values: readonly string[]);
+    /** The checked values `change` last said, joined, so a choice that moved nothing says nothing. */
+    private toldChecked;
+    /** Sends `change` when a reader's choice has changed which rows are checked. */
+    private tellChecked;
     private readonly handleSelect;
     /**
      * Keeps whatever has focus in sight, however it got there.
@@ -390,9 +443,14 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     private grace;
     private stopHover;
     /**
-     * A mouse resting on a row, under `flyout`: focus follows it, and after a
-     * moment the row's submenu opens, or the submenus below the row's own page
+     * A mouse resting on a row: focus follows it, and under `flyout`, after a
+     * moment, the row's submenu opens, or the submenus below the row's own page
      * close. Not while the pointer is crossing toward an open submenu.
+     *
+     * **In every mode**, as the APG's menus, React Aria's and Radix's have it.
+     * Under `drill` the pointer did not move focus, so the row under the
+     * pointer and the row the keys moved from were two rows, measured in
+     * Chromium: hovering Delete left focus on Cut.
      */
     private readonly handleHover;
     /** The pointer leaving a row whose submenu is open, which starts the grace area. */
@@ -402,8 +460,11 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected updated(changed: PropertyValues): void;
+    /** Whether the surface is named by a submenu's page, which `nameSurface` undoes at the top. */
+    private namedByPage;
     /**
-     * Names the surface by its trigger, where nothing else names it.
+     * Names the surface by its trigger, where nothing else names it, and a
+     * submenu's page by its title.
      *
      * By element reference, which is the one direction that crosses: the surface
      * is in this shadow root and the trigger is in the tree around it. A host

package/dist/menu/root/menu-root.js

@@ -4,7 +4,7 @@ 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 { AriaForwardController, anchorElement, customElement, DrilldownController, deepActiveElement, deepContains, filterKeeps, focusTarget, HelixElement, HelixFilterEvent, inlineStep, KeyboardNavigationController, linkDescription, MixinCollection, MixinControllerOpen, markMatches, onUnlessFalse, PopoverController, scrollItemIntoView, sideOf, slottedWords, tellDisclosure, typeaheadBy, unlinkDescription, words, } from '@fusion.dev/helix-core';
+import { AriaForwardController, anchorElement, customElement, DrilldownController, deepActiveElement, deepContains, filterKeeps, focusTarget, formatWords, HelixElement, HelixFilterEvent, inlineStep, KeyboardNavigationController, linkDescription, MixinCollection, MixinControllerOpen, markMatches, OpenPhaseController, onUnlessFalse, PopoverController, scrollItemIntoView, sideOf, slottedWords, tellDisclosure, typeaheadBy, unlinkDescription, words, } from '@fusion.dev/helix-core';
 import { caretLeft } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
@@ -30,6 +30,7 @@ const isSection = (element) => 'isMenuSection' in element && element.isMenuSecti
 let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinControllerOpen(HelixElement)) {
     constructor() {
         super(...arguments);
+        this.statusSlots = true;
         this.backLabel = 'Back';
         this.closeOnSelect = true;
         this.context = false;
@@ -40,6 +41,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         this.longPressLabel = 'Long press or press Alt+Down to show the menu';
         this.noResultsText = 'No matches';
         this.offset = 4;
+        this.openOn = 'click';
         this.longPress = new LongPress(this, {
             onLongPress: () => {
                 if (this.context) {
@@ -54,8 +56,8 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
                 }
             },
         });
-        this.openOn = 'click';
         this.placement = 'bottom-start';
+        this.resultsLabel = '{count, plural, one {# result} other {# results}}';
         this.submenus = 'drill';
         this.drilldown = new DrilldownController(this, {
             isRow: (element) => 'isMenuItem' in element && element.isMenuItem === true,
@@ -70,6 +72,14 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             selects: () => false,
             typeahead: typeaheadBy((item) => slottedWords(item, [''])),
         });
+        this.phases = new OpenPhaseController(this, {
+            mark: {
+                entering: (on) => this.toggleState('entering', on),
+                exiting: (on) => this.toggleState('exiting', on),
+            },
+            open: () => this.open,
+            surface: () => this.partNamed('surface'),
+        });
         this.aria = new AriaForwardController(this, {
             label: true,
             target: () => this.menuBox,
@@ -98,6 +108,37 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             event.stopPropagation();
             this.filterBy(event.target.value);
         };
+        this.followRemoved = (records) => {
+            if (!this.open) {
+                return;
+            }
+            const active = deepActiveElement();
+            const lost = active === null || active === document.body || !active.isConnected;
+            const record = records.find((one) => [...one.removedNodes].some((node) => isItem(node) && (this.filterable ? node === this.highlighted : lost)));
+            if (!record) {
+                return;
+            }
+            const items = this.items;
+            const after = (from, step) => {
+                for (let node = from; node; node = node[step]) {
+                    if (items.includes(node)) {
+                        return node;
+                    }
+                }
+                return undefined;
+            };
+            const next = after(record.nextSibling, 'nextSibling') ??
+                after(record.previousSibling, 'previousSibling') ??
+                items.at(-1);
+            if (this.filterable || next) {
+                this.reach(next);
+                return;
+            }
+            this.hide();
+            if (!this.context) {
+                this.trigger.focus();
+            }
+        };
         this.handleContextMenu = (event) => {
             if (!this.context) {
                 return;
@@ -124,6 +165,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
                 return;
             }
             const chosen = item;
+            this.tellChecked();
             if (chosen.hasSubmenu) {
                 event.stopPropagation();
                 this.enter(chosen);
@@ -141,6 +183,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             if (item) {
                 this.revealRow(item);
             }
+            this.nameSurface();
         };
         this.handleKeydown = (event) => {
             if (!this.open) {
@@ -235,7 +278,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             }
         };
         this.handleHover = (event) => {
-            if (!(this.flies || this.filterable) || !this.open || event.pointerType !== 'mouse') {
+            if (!this.open || event.pointerType !== 'mouse') {
                 return;
             }
             const row = event
@@ -293,6 +336,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
                 until: Date.now() + GRACE,
             };
         };
+        this.namedByPage = false;
     }
     static { this.words = 'helix-menu'; }
     get flies() {
@@ -487,6 +531,27 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         this.drilldown.back();
         this.updateComplete.then(() => this.reach(leaving ?? undefined));
     }
+    get choiceRows() {
+        return [...this.querySelectorAll('*')].filter((node) => isItem(node) && node.choice);
+    }
+    get checkedValues() {
+        return this.choiceRows.filter((row) => row.checked).map((row) => row.value);
+    }
+    set checkedValues(values) {
+        const wanted = new Set(values);
+        for (const row of this.choiceRows) {
+            row.checked = wanted.has(row.value);
+        }
+        this.toldChecked = this.checkedValues.join('\u0000');
+    }
+    tellChecked() {
+        const now = this.checkedValues.join('\u0000');
+        const before = this.toldChecked;
+        this.toldChecked = now;
+        if (before !== undefined && before !== now) {
+            this.dispatchEvent(new Event('change', { bubbles: true }));
+        }
+    }
     revealRow(item) {
         const holder = this.flies ? this.holderOf(item) : null;
         const surface = holder
@@ -555,6 +620,8 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         this.addEventListener('pointercancel', this.handlePointerCancel);
         this.addEventListener('click', this.handleHeldClick, true);
         this.addEventListener('focusin', this.handleTriggerFocusIn);
+        this.rowWatch = new MutationObserver(this.followRemoved);
+        this.rowWatch.observe(this, { childList: true, subtree: true });
         void this.whenSettled.then(() => {
             this.settledOnce = true;
             if (!this.context) {
@@ -581,6 +648,8 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         this.removeEventListener('pointercancel', this.handlePointerCancel);
         this.removeEventListener('click', this.handleHeldClick, true);
         this.removeEventListener('focusin', this.handleTriggerFocusIn);
+        this.rowWatch?.disconnect();
+        this.rowWatch = undefined;
         if (this.described) {
             unlinkDescription(this.described, this);
             this.described = undefined;
@@ -588,6 +657,9 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
     }
     updated(changed) {
         super.updated(changed);
+        if (changed.has('open') && this.open) {
+            this.toldChecked = this.checkedValues.join('\u0000');
+        }
         if (!this.context) {
             this.tellTrigger();
         }
@@ -628,7 +700,20 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
     }
     nameSurface() {
         const surface = this.menuBox;
-        if (!surface || !('ariaLabelledByElements' in surface)) {
+        if (!surface) {
+            return;
+        }
+        if (!this.flies && !this.drilldown.atRoot && this.partNamed('title')) {
+            surface.setAttribute('aria-labelledby', 'title');
+            this.namedByPage = true;
+            return;
+        }
+        if (this.namedByPage) {
+            this.namedByPage = false;
+            surface.removeAttribute('aria-labelledby');
+            this.aria.forward();
+        }
+        if (!('ariaLabelledByElements' in surface)) {
             return;
         }
         if (this.hasAttribute('aria-labelledby')) {
@@ -673,8 +758,15 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
     render() {
         const point = this.context && this.point;
         const filtering = this.filtering;
-        const none = filtering && !this.rowsOf(this.filterPage).some((row) => this.kept(row));
-        this.announced = none ? this.noResultsText : '';
+        const count = filtering
+            ? this.rowsOf(this.filterPage).filter((row) => this.kept(row)).length
+            : 0;
+        const none = filtering && count === 0;
+        this.announced = none
+            ? this.noResultsText
+            : filtering
+                ? formatWords(this, 'resultsLabel', { count })
+                : '';
         const rows = html `${this.flies || this.drilldown.atRoot
             ? nothing
             : html `<div part="header">
@@ -690,7 +782,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
                 ${unsafeSVG(caretLeft.content)}
               </svg>
             </button>
-            <span part="title">${this.drilldown.label}</span>
+            <span part="title" id="title">${this.drilldown.label}</span>
           </div>`}
       <slot @slotchange=${(event) => this.countRows(event)}></slot>
       ${none
@@ -775,6 +867,10 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessMenu.prototype, "placement", void 0);
+__decorate([
+    words,
+    property({ attribute: 'results-label' })
+], HelixHeadlessMenu.prototype, "resultsLabel", void 0);
 __decorate([
     property()
 ], HelixHeadlessMenu.prototype, "submenus", void 0);

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

@@ -22,7 +22,9 @@ declare const HelixHeadlessPopover_base: (new (...args: any[]) => import("@fusio
  *
  * It opens on click and from a command. `command="--show"` and the related
  * commands work as they do on `Dialog` and `Drawer`, so a button anywhere on
- * the page can open the popover with no script.
+ * the page can open the popover with no script. From its first press, a
+ * button that opens it this way says whether the popover is open: a Helix
+ * button through `expanded`, and any other element with `aria-expanded`.
  *
  * **Opening moves focus into the panel**, to the first control in it, or to the
  * panel itself where it holds none, and closing from inside gives it back to
@@ -32,8 +34,12 @@ declare const HelixHeadlessPopover_base: (new (...args: any[]) => import("@fusio
  * `modal` keeps `Tab` inside the panel while it is open and says so with
  * `aria-modal`, for a panel that has to be answered before the page goes on.
  * The rest of the page is hidden from screen readers with `aria-hidden` while
- * it is open, so the virtual cursor stays in the panel too. Without it the
- * popover does not trap focus.
+ * it is open, so the virtual cursor stays in the panel too, and the page does
+ * not scroll behind it. Without it the popover does not trap focus.
+ *
+ * A press outside closes the panel and leaves focus where the press put it.
+ * Where it put focus nowhere, as a press on text or on the page's background
+ * does, focus goes back to the trigger.
  *
  * The panel's name is `label` when you set it. Otherwise it is the first
  * heading in the panel, or the elements an `aria-labelledby` on the host names.
@@ -49,10 +55,17 @@ declare const HelixHeadlessPopover_base: (new (...args: any[]) => import("@fusio
  * | Escape | Closes the panel and puts focus back on the trigger. |
  * | Tab, Shift+Tab | Moves through the controls in the panel. Leaving the panel and the trigger closes it. With `modal`, moves from the last control round to the first and from the first round to the last. |
  *
+ * The panel opens against the trigger, or against the element `anchor` names,
+ * such as a field beside the button that opens it. `offset` moves it away from
+ * that element, `cross-offset` slides it along the side it is on,
+ * `container-padding` keeps it that far from the window's edges, and
+ * `flip="false"` keeps it on its side where the other side has more room.
+ *
  * `arrow` draws a point on the panel's edge facing the trigger. The side the
- * panel landed on is on the host as `:state(placed-top)` and its kin, and the
- * trigger's width is on the panel as `--floating-anchor-inline-size`, for a
- * panel as wide as its trigger:
+ * panel landed on is on the host as `:state(placed-top)` and its kin, its
+ * alignment along that side as `:state(aligned-start)` or
+ * `:state(aligned-end)`, and the trigger's width is on the panel as
+ * `--floating-anchor-inline-size`, for a panel as wide as its trigger:
  *
  * ```css
  * helix-popover::part(popover) {
@@ -84,6 +97,8 @@ declare const HelixHeadlessPopover_base: (new (...args: any[]) => import("@fusio
  * @cssproperty --floating-anchor-inline-size - The trigger's width, written on the panel while it is open, as in `min-inline-size: var(--floating-anchor-inline-size)`. Read it; a value set here is written over.
  * @cssproperty --floating-available-block-size - The room between the panel and the edge of the screen it opens toward, written on the panel while it is open. Read it; a value set here is written over.
  *
+ * @cssstate aligned-end - While the panel is aligned to the end of the side it sits on.
+ * @cssstate aligned-start - While the panel is aligned to the start of the side it sits on.
  * @cssstate entering - From the moment the panel shows until its entrance has finished.
  * @cssstate exiting - From the moment the panel hides until its exit has finished.
  * @cssstate open - While the popover is open.
@@ -98,6 +113,13 @@ export declare class HelixHeadlessPopover extends HelixHeadlessPopover_base {
      * `registerWords('de', { 'helix-popover': { fallbackLabel: 'Popup' } })`.
      */
     static words: string;
+    /**
+     * The element the panel opens against, where that is not the trigger: its
+     * `id` in the same document or shadow root, or the element itself. Left
+     * empty, the panel opens against the trigger, or against the button whose
+     * command opened it.
+     */
+    anchor: Element | string;
     /**
      * Draws a point on the panel's edge facing the trigger.
      *
@@ -105,11 +127,29 @@ export declare class HelixHeadlessPopover extends HelixHeadlessPopover_base {
      * trigger already reads as belonging to it.
      */
     arrow: boolean;
+    /**
+     * How close to the window's edges the panel may come, in pixels, when it
+     * slides, shrinks or moves to the other side to fit. Left unset, it slides
+     * and shrinks to 8 pixels from an edge and moves to the other side only
+     * once it would cross one.
+     */
+    containerPadding?: number;
+    /**
+     * How far to slide the panel along the side it is on, in pixels: to the
+     * right on the top or the bottom, and down on the left or the right.
+     */
+    crossOffset: number;
     /**
      * The panel's name where nothing else names it: no `label`, no heading in
      * the panel, and no `aria-labelledby` on the host.
      */
     fallbackLabel: string;
+    /**
+     * Whether the panel moves to the other side of the trigger when its own
+     * side has no room. On by default. Write `flip="false"` to keep it on its
+     * side, where it shrinks to fit, as React Aria's `shouldFlip` turns off.
+     */
+    flip: boolean;
     /**
      * The panel's name, read by screen readers. Left empty, the first heading in
      * the panel names it, and then `fallback-label`.
@@ -166,7 +206,20 @@ export declare class HelixHeadlessPopover extends HelixHeadlessPopover_base {
     private invoker;
     protected readonly commands: CommandController;
     /** The element the panel opens against. */
+    private get placedAgainst();
+    /** The element that opened the panel, which focus goes back to. */
     private get trigger();
+    /**
+     * A press outside, or Escape, closing the panel.
+     *
+     * **Focus goes back to the trigger where the press put it nowhere.** The
+     * press is heard on `pointerdown`, and the browser moves focus a moment
+     * later: onto what was pressed where that takes focus, and to the body where
+     * it does not. A popover dismissed by a press on text was left with focus on
+     * the body, measured in Chromium, where React Aria's returns it to the
+     * trigger. Read after the press, once the browser has moved it.
+     */
+    private dismiss;
     /** Opens the panel. */
     show(): void;
     /** Closes the panel and puts focus back on the trigger. */

package/dist/popover/root/popover-root.js

@@ -4,15 +4,18 @@ 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 { AriaForwardController, anchorElement, arrowReach, auditName, CommandController, customElement, deepActiveElement, FocusScopeController, HelixElement, headingIn, MixinControllerOpen, OpenPhaseController, PopoverController, reflectElements, sideOf, tellDisclosure, words, } from '@fusion.dev/helix-core';
+import { AriaForwardController, anchorElement, arrowReach, auditName, CommandController, customElement, deepActiveElement, FocusScopeController, HelixElement, headingIn, lockScroll, MixinControllerOpen, OpenPhaseController, onUnlessFalse, PopoverController, reflectElements, sideOf, tellDisclosure, unlockScroll, words, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { hideOutside } from '../hide-outside.js';
 let HelixHeadlessPopover = class HelixHeadlessPopover extends MixinControllerOpen(HelixElement) {
     constructor() {
         super(...arguments);
+        this.anchor = '';
         this.arrow = false;
+        this.crossOffset = 0;
         this.fallbackLabel = 'Popover';
+        this.flip = true;
         this.label = '';
         this.modal = false;
         this.aria = new AriaForwardController(this, {
@@ -29,13 +32,17 @@ let HelixHeadlessPopover = class HelixHeadlessPopover extends MixinControllerOpe
             surface: () => this.partNamed('popover'),
         });
         this.panel = new PopoverController(this, {
-            anchor: () => this.trigger,
+            anchor: () => this.placedAgainst,
             arrow: () => this.partNamed('arrow'),
             boundary: () => [this, this.invoker],
+            crossOffset: () => this.crossOffset,
+            flip: () => this.flip,
             offset: () => this.offset + arrowReach(this.partNamed('arrow')),
-            onDismiss: () => this.hide(),
+            onDismiss: () => this.dismiss(),
             onPlace: (placement) => {
                 const side = sideOf(placement);
+                this.toggleState('aligned-end', placement.endsWith('-end'));
+                this.toggleState('aligned-start', placement.endsWith('-start'));
                 this.toggleState('placed-bottom', side === 'bottom');
                 this.toggleState('placed-left', side === 'left');
                 this.toggleState('placed-right', side === 'right');
@@ -43,6 +50,7 @@ let HelixHeadlessPopover = class HelixHeadlessPopover extends MixinControllerOpe
                 this.side = side;
             },
             open: () => this.open,
+            padding: () => this.containerPadding,
             placement: () => this.placement,
             surface: () => this.partNamed('popover'),
         });
@@ -69,6 +77,7 @@ let HelixHeadlessPopover = class HelixHeadlessPopover extends MixinControllerOpe
                     }
                 },
             },
+            expanded: () => this.open,
         });
         this.closingFromInside = false;
         this.handleFocusOut = (event) => {
@@ -111,10 +120,31 @@ let HelixHeadlessPopover = class HelixHeadlessPopover extends MixinControllerOpe
         const heading = asked ? null : headingIn(this.slotted);
         this.namedByHeading = reflectElements(this.partNamed('popover'), 'ariaLabelledByElements', heading ? [heading] : [], this.namedByHeading);
     }
+    get placedAgainst() {
+        const named = typeof this.anchor === 'string'
+            ? this.anchor === ''
+                ? null
+                : this.getRootNode().getElementById?.(this.anchor)
+            : this.anchor;
+        return named instanceof HTMLElement ? named : this.trigger;
+    }
     get trigger() {
         return (this.invoker ??
             anchorElement(this.renderRoot?.querySelector('slot[name="trigger"]'), this));
     }
+    dismiss() {
+        const inside = this.focusInside;
+        this.hide();
+        if (!inside) {
+            return;
+        }
+        setTimeout(() => {
+            const active = deepActiveElement();
+            if (!this.open && (active === null || active === document.body)) {
+                this.trigger.focus();
+            }
+        });
+    }
     show() {
         if (this.open || !this.requestOpen(true)) {
             return;
@@ -179,6 +209,12 @@ let HelixHeadlessPopover = class HelixHeadlessPopover extends MixinControllerOpe
             this.showOutside();
             this.showOutside = undefined;
         }
+        if (hide) {
+            lockScroll(this);
+        }
+        else {
+            unlockScroll(this);
+        }
     }
     updated(changed) {
         super.updated(changed);
@@ -220,13 +256,25 @@ let HelixHeadlessPopover = class HelixHeadlessPopover extends MixinControllerOpe
       </div>`;
     }
 };
+__decorate([
+    property()
+], HelixHeadlessPopover.prototype, "anchor", void 0);
 __decorate([
     property({ type: Boolean })
 ], HelixHeadlessPopover.prototype, "arrow", void 0);
+__decorate([
+    property({ attribute: 'container-padding', type: Number })
+], HelixHeadlessPopover.prototype, "containerPadding", void 0);
+__decorate([
+    property({ attribute: 'cross-offset', type: Number })
+], HelixHeadlessPopover.prototype, "crossOffset", void 0);
 __decorate([
     words,
     property({ attribute: 'fallback-label' })
 ], HelixHeadlessPopover.prototype, "fallbackLabel", void 0);
+__decorate([
+    property({ converter: onUnlessFalse })
+], HelixHeadlessPopover.prototype, "flip", void 0);
 __decorate([
     property()
 ], HelixHeadlessPopover.prototype, "label", void 0);