@fusion.dev/helix-headless 0.150.0 → 0.152.0

package/dist/dialog/description.d.ts

@@ -1,3 +1,13 @@
+/**
+ * The elements at the start of a list that hold words and no control, up to the
+ * first one that is or holds a control.
+ *
+ * `skip` is an element whose words are said elsewhere, such as the heading
+ * that names a panel. It is left out, and an element holding it is read for
+ * its other children, so a card's title names the panel and the card's text
+ * describes it.
+ */
+export declare const wordsAmong: (elements: readonly Element[], skip?: Element | null) => Element[];
 /**
  * The elements at the start of a slot that hold words and no control, up to the
  * first one that is or holds a control.

package/dist/dialog/description.js

@@ -14,15 +14,29 @@ const isControl = (element) => {
         root?.delegatesFocus === true ||
         root?.querySelector(CONTROL) != null);
 };
-export const wordsIn = (slot) => {
+export const wordsAmong = (elements, skip = null) => {
     const words = [];
-    for (const one of slot?.assignedElements({ flatten: true }) ?? []) {
-        if (isControl(one) || [...one.querySelectorAll('*')].some(isControl)) {
-            break;
+    const read = (list) => {
+        for (const one of list) {
+            if (one === skip) {
+                continue;
+            }
+            if (skip && one.contains(skip)) {
+                if (!read([...one.children])) {
+                    return false;
+                }
+                continue;
+            }
+            if (isControl(one) || [...one.querySelectorAll('*')].some(isControl)) {
+                return false;
+            }
+            if ((one.textContent ?? '').trim() !== '') {
+                words.push(one);
+            }
         }
-        if ((one.textContent ?? '').trim() !== '') {
-            words.push(one);
-        }
-    }
+        return true;
+    };
+    read(elements);
     return words;
 };
+export const wordsIn = (slot) => wordsAmong(slot?.assignedElements({ flatten: true }) ?? []);

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

@@ -39,6 +39,16 @@ declare const HelixHeadlessDialog_base: (new (...args: any[]) => import("@fusion
  * announces with its description as it opens. Set `dismissible` to draw a
  * close control, labeled by `dismiss-label`.
  *
+ * **Keyboard.** Opening moves focus to the first control in the dialog.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Tab, Shift+Tab | Moves through the controls in the dialog, from the last round to the first and from the first round to the last. |
+ * | Escape | Asks to close the dialog. A `helix-before-close` listener can refuse, and `persistent` or `closedby="none"` keeps it open. |
+ * | Enter, Space | On the close control, closes the dialog. |
+ *
+ * Closing puts focus back on the element that had it before the dialog opened.
+ *
  * @since 0.1.0
  * @status stable
  * @category overlays
@@ -94,8 +104,14 @@ export declare class HelixHeadlessDialog extends HelixHeadlessDialog_base {
      * `closedby="any"` gains light dismiss without giving up the refusal, which is
      * the property this component exists to keep.
      *
+     * The press on the backdrop that this element handles itself follows it too:
+     * `closerequest` and `none` leave the dialog open on that press, as the
+     * platform does, and `none` also keeps it open on Escape in a browser without
+     * `closedby`.
+     *
      * Absent by default, which is the platform's `auto` and this library's rule
-     * that a resting value is an attribute's absence.
+     * that a resting value is an attribute's absence. Absent, a press on the
+     * backdrop closes the dialog.
      */
     closedBy?: 'any' | 'closerequest' | 'none';
     /**

package/dist/dialog/root/dialog-root.js

@@ -36,7 +36,7 @@ let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(
         this.returned = '';
         this.handleCancel = (event) => {
             event.preventDefault();
-            if (this.persistent) {
+            if (this.persistent || this.closedBy === 'none') {
                 return;
             }
             this.requestOpen(false);
@@ -84,7 +84,7 @@ let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(
                 event.clientY <= box.bottom) {
                 return;
             }
-            if (this.persistent) {
+            if (this.persistent || this.closedBy === 'none' || this.closedBy === 'closerequest') {
                 this.refuse();
                 return;
             }

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

@@ -12,9 +12,10 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * **The line is a separator**, as `<hr>` is, and as Radix Separator, React
  * Aria Separator, and Web Awesome's divider are. It is named by any content
  * set into it, so a screen reader says "Or, separator" where you wrote "Or" on
- * the line. Set `decorative` on a rule that separates nothing, such as one
- * under a heading or between the facts of a byline, and it leaves the
- * accessibility tree.
+ * the line, and the words are read once, as that name. Set words into a
+ * separator and no controls, which are hidden with them. Set `decorative` on
+ * a rule that separates nothing, such as one under a heading or between the
+ * facts of a byline, and it leaves the accessibility tree.
  *
  * Use `orientation="vertical"` between items on one line. A vertical divider
  * stretches to fit its flex parent and sets no height of its own.
@@ -44,9 +45,10 @@ export declare class HelixHeadlessDivider extends HelixElement {
      * Whether screen readers announce the line as a separator, which they now do
      * by default.
      *
-     * It dates from when the line was decorative by default. It is still read,
-     * and it wins over `decorative`, so a divider written with it stays a
-     * separator.
+     * @deprecated Remove it: a divider is a separator unless `decorative` is
+     * set. It dates from when the line was decorative by default, and it is
+     * still read and wins over `decorative`, so a divider written with it stays
+     * a separator.
      */
     announced: boolean;
     /**

package/dist/divider/root/divider-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 { customElement, HelixElement, markRegion, toolbarAround, toolbarAxis, } from '@fusion.dev/helix-core';
+import { customElement, HelixElement, markRegion, reportRuntime, toolbarAround, toolbarAxis, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 let HelixHeadlessDivider = class HelixHeadlessDivider extends HelixElement {
@@ -38,6 +38,14 @@ let HelixHeadlessDivider = class HelixHeadlessDivider extends HelixElement {
     updated(changed) {
         super.updated(changed);
         this.markEmpty();
+        if (changed.has('announced') && this.announced && changed.get('announced') === undefined) {
+            reportRuntime({
+                kind: 'deprecated',
+                message: `<${this.localName} announced> is deprecated: remove it. A divider is a separator ` +
+                    'unless `decorative` is set.',
+                tag: this.localName,
+            });
+        }
     }
     render() {
         const separator = this.announced || !this.decorative;
@@ -47,7 +55,7 @@ let HelixHeadlessDivider = class HelixHeadlessDivider extends HelixElement {
       aria-labelledby=${separator ? 'content' : nothing}
       aria-orientation=${separator ? this.drawn : nothing}
     ></div>
-      <span id="content" part="content"><slot @slotchange=${() => this.markEmpty()}></slot></span>
+      <span id="content" part="content" aria-hidden=${separator ? 'true' : nothing}><slot @slotchange=${() => this.markEmpty()}></slot></span>
       <div part="line" role="presentation"></div>`;
     }
 };

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

@@ -20,6 +20,11 @@ declare const HelixHeadlessDrawer_base: (new (...args: any[]) => import("@fusion
  * A drawer with `modal="false"` leaves the page usable and still closes on
  * Escape, in a browser without `closedby` as well.
  *
+ * Set `persistent` for a drawer that has to be answered: Escape, a press
+ * outside, and a swipe leave it open, and the close control and `close()`
+ * still close it. `closedby="none"` keeps it open on all three as well, and
+ * `closedby="closerequest"` keeps it open on a press outside.
+ *
  * **A touch or a pen swipes it away**, toward the edge it came from, resolved
  * against the writing direction. A swipe past halfway, or a quick one, closes
  * it through the same request as every other way out. `snap-points` lists the
@@ -40,7 +45,20 @@ declare const HelixHeadlessDrawer_base: (new (...args: any[]) => import("@fusion
  *
  * The panel's name is `label` when you set it. Otherwise it is the heading in
  * the `header` slot, or the elements an `aria-labelledby` on the host names,
- * and `fallback-label` where nothing names it.
+ * and `fallback-label` where nothing names it. A development build warns
+ * when a drawer opens with nothing but `fallback-label` to name it.
+ *
+ * The panel is described by the words at the start of its body, as `Dialog`
+ * is: the elements in the default slot before the first one that is or holds
+ * a control. An `aria-describedby` on the host replaces it.
+ *
+ * **Keyboard.** Opening moves focus to the first control in the panel.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Tab, Shift+Tab | In a modal drawer, moves through the controls in the panel, from the last round to the first and from the first round to the last. In a drawer that is not modal, moves on to the page. |
+ * | Escape | Asks to close the drawer. A `helix-before-close` listener can refuse, and `persistent` or `closedby="none"` keeps it open. |
+ * | Enter, Space | On the close control, closes the drawer. |
  *
  * Content stays mounted when the drawer is closed, so it is in the server
  * markup and can animate. A closed `<dialog>` is already out of the tab order
@@ -114,6 +132,8 @@ export declare class HelixHeadlessDrawer extends HelixHeadlessDrawer_base {
      * way out.
      */
     dismissible: boolean;
+    /** Whether a request to dismiss the drawer, by Escape or a swipe, is refused. */
+    private get refusesDismissal();
     /**
      * The close control's accessible name. Translate it with the rest of your
      * interface.
@@ -129,7 +149,6 @@ export declare class HelixHeadlessDrawer extends HelixHeadlessDrawer_base {
      * `header` slot names the panel.
      */
     label: string;
-    protected readonly aria: AriaForwardController;
     /**
      * Whether the drawer blocks the page behind it.
      *
@@ -144,6 +163,15 @@ export declare class HelixHeadlessDrawer extends HelixHeadlessDrawer_base {
      * not, rather than shown or hidden by CSS.
      */
     modal: boolean;
+    protected readonly aria: AriaForwardController;
+    /**
+     * Stops Escape, a press outside, and a swipe from closing the drawer, for a
+     * drawer that has to be answered.
+     *
+     * The close control and `close()` still close it, as on `Dialog`: a panel
+     * with no way out at all is a trap.
+     */
+    persistent: boolean;
     /**
      * Which edge the drawer comes from.
      *
@@ -281,6 +309,14 @@ export declare class HelixHeadlessDrawer extends HelixHeadlessDrawer_base {
      * reflection keeps the fallback name.
      */
     private nameByHeader;
+    /** Whether the body's words are what currently describe the panel. */
+    private describedByBody;
+    /**
+     * Describes the panel by the words at the start of its body, where nothing
+     * else describes it, as `Dialog` does. An `aria-describedby` on the host
+     * comes first.
+     */
+    private describeByBody;
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected updated(changed: PropertyValues): void;

package/dist/drawer/root/drawer-root.js

@@ -4,9 +4,10 @@ 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, CommandController, customElement, drawDismiss, drawDismissGlyph, edgeOffset, FocusScopeController, HelixElement, headingsIn, isRtl, lockScroll, MixinControllerOpen, nearest, OpenPhaseController, onUnlessFalse, parseSnapPoints, reflectElements, SwipeController, settleSwipe, snapTravel, swipeAxis, swipeEdge, towardEdge, unlockScroll, words, } from '@fusion.dev/helix-core';
+import { AriaForwardController, auditName, CommandController, customElement, drawDismiss, drawDismissGlyph, edgeOffset, FocusScopeController, HelixElement, headingsIn, isRtl, lockScroll, MixinControllerOpen, nearest, OpenPhaseController, onUnlessFalse, parseSnapPoints, reflectElements, SwipeController, settleSwipe, snapTravel, swipeAxis, swipeEdge, towardEdge, unlockScroll, words, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
+import { wordsIn } from '../../dialog/description.js';
 import { beyondWindow } from '../reveal.js';
 import { startsSwipe } from '../swipe-start.js';
 let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(HelixElement) {
@@ -23,8 +24,9 @@ let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(
         this.dismissLabel = 'Close';
         this.fallbackLabel = 'Drawer';
         this.label = '';
-        this.aria = new AriaForwardController(this, { target: () => this.panel });
         this.modal = true;
+        this.aria = new AriaForwardController(this, { target: () => this.panel });
+        this.persistent = false;
         this.snapPoints = '';
         this.swipe = true;
         this.returned = '';
@@ -63,7 +65,9 @@ let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(
                 return;
             }
             event.preventDefault();
-            this.requestOpen(false);
+            if (!this.refusesDismissal) {
+                this.requestOpen(false);
+            }
         };
         this.scope = new FocusScopeController(this, {
             contain: () => this.open && this.modal,
@@ -77,7 +81,9 @@ let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(
         });
         this.handleCancel = (event) => {
             event.preventDefault();
-            this.requestOpen(false);
+            if (!this.refusesDismissal) {
+                this.requestOpen(false);
+            }
         };
         this.handleClose = (event) => {
             if (this.open) {
@@ -97,11 +103,18 @@ let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(
                 event.clientY <= box.bottom) {
                 return;
             }
+            if (this.refusesDismissal || this.closedBy === 'closerequest') {
+                return;
+            }
             this.requestOpen(false);
         };
         this.namedByHeader = false;
+        this.describedByBody = false;
     }
     static { this.words = 'helix-drawer'; }
+    get refusesDismissal() {
+        return this.persistent || this.closedBy === 'none';
+    }
     get returnValue() {
         return this.panel?.returnValue ?? this.returned;
     }
@@ -138,7 +151,7 @@ let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(
             travel: Math.max(0, this.rest + towardEdge(edge, dx, dy)),
             velocity: towardEdge(edge, vx, vy),
         });
-        if (shown === 0 && this.requestOpen(false)) {
+        if (shown === 0 && !this.refusesDismissal && this.requestOpen(false)) {
             return;
         }
         if (shown !== 0) {
@@ -192,6 +205,11 @@ let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(
             : headingsIn(slot?.assignedElements({ flatten: true }) ?? []);
         this.namedByHeader = reflectElements(this.panel, 'ariaLabelledByElements', heading, this.namedByHeader);
     }
+    describeByBody() {
+        const slot = this.renderRoot.querySelector('slot:not([name])');
+        const said = this.hasAttribute('aria-describedby') ? [] : wordsIn(slot);
+        this.describedByBody = reflectElements(this.panel, 'ariaDescribedByElements', said, this.describedByBody);
+    }
     connectedCallback() {
         super.connectedCallback();
         this.addEventListener('focusin', this.handleFocusIn);
@@ -204,6 +222,7 @@ let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(
     updated(changed) {
         super.updated(changed);
         this.nameByHeader();
+        this.describeByBody();
         if (changed.has('open') && !this.open) {
             this.rest = 0;
             this.shown = 1;
@@ -221,6 +240,11 @@ let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(
             return;
         }
         if (this.open && !panel.open) {
+            auditName(this, () => null, 'Give it a `label`, or a heading in the `header` slot.', () => this.label !== '' ||
+                this.namedByHeader ||
+                headingsIn(this.renderRoot
+                    .querySelector('slot[name="header"]')
+                    ?.assignedElements({ flatten: true }) ?? []).length > 0);
             if (this.modal) {
                 panel.showModal();
             }
@@ -245,7 +269,7 @@ let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(
       @keydown=${this.handleKeydown}
     >
       <div part="header"><slot name="header" @slotchange=${this.nameByHeader}></slot></div>
-      <div part="content"><slot></slot></div>
+      <div part="content"><slot @slotchange=${this.describeByBody}></slot></div>
       <div part="footer"><slot name="footer"></slot></div>
       ${this.dismissible
             ? drawDismiss({
@@ -282,6 +306,9 @@ __decorate([
 __decorate([
     property({ converter: onUnlessFalse })
 ], HelixHeadlessDrawer.prototype, "modal", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessDrawer.prototype, "persistent", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessDrawer.prototype, "placement", void 0);

package/dist/element-events.generated.js

@@ -3,7 +3,9 @@ registerElementEvents({
     'helix-headless-accordion-item': ['helix-before-close', 'helix-before-open', 'toggle'],
     'helix-headless-announcement': ['helix-dismiss'],
     'helix-headless-app-header': ['helix-scrolled'],
+    'helix-headless-area-chart': ['helix-reading-change', 'helix-reading-press'],
     'helix-headless-avatar': ['error', 'load'],
+    'helix-headless-bar-chart': ['helix-reading-change', 'helix-reading-press'],
     'helix-headless-button': ['helix-press'],
     'helix-headless-button-group': ['change', 'helix-before-change'],
     'helix-headless-callout': ['helix-dismiss'],
@@ -132,6 +134,7 @@ registerElementEvents({
         'helix-before-open',
         'toggle',
     ],
+    'helix-headless-line-chart': ['helix-reading-change', 'helix-reading-press'],
     'helix-headless-list': [
         'change',
         'helix-action',
@@ -208,6 +211,7 @@ registerElementEvents({
         'helix-preview',
         'input',
     ],
+    'helix-headless-scatter-chart': ['helix-reading-change', 'helix-reading-press'],
     'helix-headless-scroll-area': ['scroll', 'scrollend'],
     'helix-headless-select': [
         'change',

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

@@ -23,6 +23,11 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * the shortcut with the control. A chord the page wrote there itself is left
  * alone, and the key takes back only what it added.
  *
+ * A chord is drawn with the platform's modifiers first, in its order, so one
+ * `keys` value is right everywhere: `mod+shift+p` is `⇧⌘P` on an Apple
+ * keyboard and `Ctrl+Shift+P` elsewhere. Where it is drawn in glyphs, it is
+ * read in words, such as `Shift Command P`.
+ *
  * `caps` draws a chord as a key per key: each is a `key` part and the `+`
  * between two a `separator` part, so a sheet can draw a cap for each.
  * `key-labels` renames any key, on every platform, such as
@@ -141,7 +146,8 @@ export declare class HelixHeadlessKbd extends HelixElement {
     /**
      * The chord under `caps`, a part for each key and for each `+` between two,
      * so a sheet can draw a cap per key. Written with no space between, so a
-     * chord reads as the one label it was.
+     * chord reads as the one label it was. Where the chord is said in words,
+     * the parts are hidden from a screen reader, which reads the words.
      */
     protected renderChord(): TemplateResult;
 }

package/dist/kbd/root/kbd-root.js

@@ -135,12 +135,16 @@ let HelixHeadlessKbd = class HelixHeadlessKbd extends HelixElement {
         if (this.keys === '') {
             return html `<kbd part="kbd"><slot></slot></kbd>`;
         }
-        const { keys, separator } = this.label;
-        return html `<kbd part="kbd">${this.caps ? this.renderChord() : keys.join(separator)}</kbd>`;
+        const { keys, separator, spoken } = this.label;
+        if (spoken === '') {
+            return html `<kbd part="kbd">${this.caps ? this.renderChord() : keys.join(separator)}</kbd>`;
+        }
+        return html `<kbd part="kbd">${this.caps ? this.renderChord() : html `<span aria-hidden="true">${keys.join(separator)}</span>`}<span data-spoken>${spoken}</span></kbd>`;
     }
     renderChord() {
-        const { keys, separator } = this.label;
-        return html `${keys.map((key, index) => html `${index > 0 && separator !== '' ? html `<span part="separator">${separator}</span>` : nothing}<span part="key">${key}</span>`)}`;
+        const { keys, separator, spoken } = this.label;
+        const hidden = spoken === '' ? nothing : 'true';
+        return html `${keys.map((key, index) => html `${index > 0 && separator !== '' ? html `<span part="separator" aria-hidden=${hidden}>${separator}</span>` : nothing}<span part="key" aria-hidden=${hidden}>${key}</span>`)}`;
     }
 };
 __decorate([

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

@@ -1,4 +1,4 @@
-import { CommandController, HelixElement, SwipeController } from '@fusion.dev/helix-core';
+import { CommandController, FocusScopeController, HelixElement, SwipeController } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessLightbox_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerActiveInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
@@ -41,6 +41,25 @@ declare const HelixHeadlessLightbox_base: (new (...args: any[]) => import("@fusi
  * swiped across the picture shows the next or the previous item, the way the
  * line of text runs.
  *
+ * A press on the empty area around the item closes the viewer, as a press on
+ * the backdrop does. Under `max-zoom`, a press beside the item zooms on a
+ * double press and closes nothing, and only the space outside the viewport
+ * closes the viewer. A press that dragged closes nothing.
+ *
+ * **Keyboard.** Opening moves focus to the viewer itself, which a screen
+ * reader names.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Right, Down | Shows the next item. On a right-to-left page, Left does. While the item is zoomed, the arrows move about it instead. |
+ * | Left, Up | Shows the previous item. |
+ * | Home, End | Shows the first or the last item. |
+ * | `+`, `-`, `0` | Zooms in, zooms out, and puts the item back at its own size, where `max-zoom` allows zooming. |
+ * | Tab, Shift+Tab | Moves through the controls in the viewer, from the last round to the first and from the first round to the last. |
+ * | Escape | Closes the viewer. A `helix-before-close` listener can refuse. |
+ *
+ * A development build warns when a viewer opens with no `label`.
+ *
  * The chrome hides when there is no input, through `IdleController`, and comes
  * back on a pointer move, a key press, or a focus. It stays while focus is on a
  * control in the header or the footer, so a keyboard reader is never left on
@@ -205,6 +224,7 @@ export declare class HelixHeadlessLightbox extends HelixHeadlessLightbox_base {
     /** Whether the zoom is being put back because the item changed, which says nothing. */
     private quietZoom;
     protected readonly swipes: SwipeController;
+    protected readonly scope: FocusScopeController;
     private readonly zoomer;
     /** Writes the zoom on the viewport, and nothing at the item's own size. */
     private drawZoom;
@@ -287,6 +307,11 @@ export declare class HelixHeadlessLightbox extends HelixHeadlessLightbox_base {
     private readonly handleKeydown;
     /** `+` and `-` zoom in and out by half again, and `0` puts the item back. Returns whether it was one. */
     private zoomKey;
+    /**
+     * The arrow keys on a zoomed item, which move about it rather than to
+     * another item. Returns whether it was one.
+     */
+    private panKey;
     /** Zooms in by half again, as `+` and the zoom-in control do. */
     private zoomIn;
     /** Zooms out by as much, as `-` and the zoom-out control do. */
@@ -296,14 +321,27 @@ export declare class HelixHeadlessLightbox extends HelixHeadlessLightbox_base {
     /** The item on screen: the one `active` names, or the first where it names none. */
     private get shown();
     /**
-     * A press on the backdrop, which lands on the dialog element itself.
+     * A press on the backdrop or on the empty area around the item.
      *
-     * The point is compared against the panel's box rather than trusting the
-     * target alone, for the reason `Dialog` gives: a modal `<dialog>` attributes
-     * backdrop presses to itself, so any padding the styled tier gives the panel
-     * is a strip where a press on the panel looks like a press outside it.
+     * A modal `<dialog>` attributes backdrop presses to itself, and the styled
+     * tier draws the viewer over the whole screen, so a press beside the item
+     * lands on the dialog, the viewport, or the item's own box. Any of those is
+     * a reader done with the viewer, as a press on a dark room around a picture
+     * is. Not a press that dragged, which was a swipe or a pan.
      */
     private readonly handleBackdrop;
+    /** Where the last press began, so a press that dragged closes nothing. */
+    private pressedAt;
+    private readonly handlePointerDown;
+    /** Whether the press moved further than a click does, as a swipe or a pan does. */
+    private dragged;
+    /**
+     * Whether a press landed on the empty area around the item: the viewer's
+     * own surface, the viewport, or an item's box beside what it holds. The
+     * last two not where `max-zoom` lets a reader zoom, since a double press
+     * there zooms.
+     */
+    private onEmptyArea;
     protected willUpdate(changed: PropertyValues): void;
     disconnectedCallback(): void;
     protected updated(changed: PropertyValues): void;

package/dist/lightbox/root/lightbox-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 { CommandController, customElement, DelayController, deepActiveElement, deepContains, drawDismiss, drawDismissGlyph, FullscreenController, formatWords, HelixElement, hostAria, IdleController, inlineStep, isRtl, keyClaimed, lockScroll, MixinControllerActive, MixinControllerOpen, resolveActiveItem, SwipeController, swipeStep, unlockScroll, whenHydrated, words, } from '@fusion.dev/helix-core';
+import { auditName, CommandController, customElement, DelayController, deepActiveElement, deepContains, drawDismiss, drawDismissGlyph, FocusScopeController, FullscreenController, formatWords, HelixElement, hostAria, IdleController, inlineStep, isRtl, keyClaimed, lockScroll, MixinControllerActive, MixinControllerOpen, resolveActiveItem, SwipeController, swipeStep, unlockScroll, whenHydrated, words, } from '@fusion.dev/helix-core';
 import { caretLeft, caretRight, minus, plus } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -53,6 +53,16 @@ let HelixHeadlessLightbox = class HelixHeadlessLightbox extends MixinControllerA
             start: (_target, event) => event.pointerType !== 'mouse',
             surface: () => this.dialog,
         });
+        this.scope = new FocusScopeController(this, {
+            contain: () => this.open,
+            contents: () => [
+                ...['header', '', 'footer'].flatMap((name) => this.renderRoot
+                    ?.querySelector(name ? `slot[name="${name}"]` : 'slot:not([name])')
+                    ?.assignedElements({ flatten: true }) ?? []),
+                ...[...(this.dialog?.children ?? [])].filter((one) => one.localName === 'button'),
+            ],
+            surface: () => this.dialog,
+        });
         this.zoomer = new ZoomController(this, {
             max: () => (this.open ? this.maxZoom : 1),
             onChange: (scale, pan) => this.drawZoom(scale, pan),
@@ -89,7 +99,7 @@ let HelixHeadlessLightbox = class HelixHeadlessLightbox extends MixinControllerA
             if (keyClaimed(event) || event.altKey || event.ctrlKey || event.metaKey) {
                 return;
             }
-            if (this.zoomKey(event.key)) {
+            if (this.zoomKey(event.key) || this.panKey(event.key)) {
                 event.preventDefault();
                 return;
             }
@@ -112,19 +122,14 @@ let HelixHeadlessLightbox = class HelixHeadlessLightbox extends MixinControllerA
             }
         };
         this.handleBackdrop = (event) => {
-            const panel = this.dialog;
-            if (!panel || event.target !== panel) {
-                return;
-            }
-            const box = panel.getBoundingClientRect();
-            if (event.clientX >= box.left &&
-                event.clientX <= box.right &&
-                event.clientY >= box.top &&
-                event.clientY <= box.bottom) {
+            if (this.dragged(event) || !this.onEmptyArea(event)) {
                 return;
             }
             this.requestOpen(false);
         };
+        this.handlePointerDown = (event) => {
+            this.pressedAt = { x: event.clientX, y: event.clientY };
+        };
     }
     static { this.words = 'helix-lightbox'; }
     drawZoom(scale, pan) {
@@ -217,6 +222,25 @@ let HelixHeadlessLightbox = class HelixHeadlessLightbox extends MixinControllerA
         }
         return true;
     }
+    panKey(key) {
+        if (this.zoomer.scale <= 1) {
+            return false;
+        }
+        const box = this.partNamed('viewport')?.getBoundingClientRect();
+        const across = Math.max(40, (box?.width ?? 0) / 10);
+        const down = Math.max(40, (box?.height ?? 0) / 10);
+        const by = {
+            ArrowDown: { x: 0, y: -down },
+            ArrowLeft: { x: across, y: 0 },
+            ArrowRight: { x: -across, y: 0 },
+            ArrowUp: { x: 0, y: down },
+        }[key];
+        if (!by) {
+            return false;
+        }
+        this.zoomer.panBy(by);
+        return true;
+    }
     zoomIn() {
         this.zoomer.zoomTo(this.zoomer.scale * 1.5);
     }
@@ -232,6 +256,28 @@ let HelixHeadlessLightbox = class HelixHeadlessLightbox extends MixinControllerA
     get shown() {
         return resolveActiveItem(this.active ?? '', this.items);
     }
+    dragged(event) {
+        const from = this.pressedAt;
+        this.pressedAt = undefined;
+        return from !== undefined && Math.hypot(event.clientX - from.x, event.clientY - from.y) > 8;
+    }
+    onEmptyArea(event) {
+        const pressed = event.composedPath()[0];
+        if (!(pressed instanceof Element)) {
+            return false;
+        }
+        if (pressed === this.dialog) {
+            return true;
+        }
+        if (this.maxZoom > 1) {
+            return false;
+        }
+        const root = pressed.getRootNode();
+        const inItem = root instanceof ShadowRoot &&
+            root.host instanceof HelixHeadlessLightboxItem &&
+            pressed.getAttribute('part') === 'item';
+        return inItem || pressed === this.partNamed('viewport');
+    }
     willUpdate(changed) {
         super.willUpdate(changed);
         hostAria(this.internals, { label: this.label });
@@ -263,6 +309,7 @@ let HelixHeadlessLightbox = class HelixHeadlessLightbox extends MixinControllerA
             return;
         }
         if (this.open && !dialog.open) {
+            auditName(this, () => null, 'Give it a `label`, such as "Project photos".', () => this.label !== '');
             dialog.showModal();
             dialog.focus({ preventScroll: true });
             this.idle.stir();
@@ -334,6 +381,7 @@ let HelixHeadlessLightbox = class HelixHeadlessLightbox extends MixinControllerA
       @close=${this.handleClose}
       @focusin=${this.idle.stir}
       @keydown=${this.handleKeydown}
+      @pointerdown=${this.handlePointerDown}
       @pointerleave=${this.idle.leave}
       @pointermove=${this.idle.stir}
     >