@fusion.dev/helix-headless 0.174.0 → 0.176.0

package/dist/command/root/command-root.js

@@ -198,6 +198,7 @@ let HelixHeadlessCommand = class HelixHeadlessCommand extends MixinControllerOpe
             return;
         }
         if (this.open) {
+            this.listbox?.highlight('none');
             this.searchField?.focus();
         }
         else {

package/dist/date-picker/root/date-picker-root.d.ts

@@ -348,6 +348,12 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      * to the first of the month. Measured before today was a candidate: a
      * calendar with no value opened on October 5 with its stop on "Thursday,
      * October 1".
+     *
+     * Today counts only where it can be chosen, and the fallback is the first
+     * day of the month that can, so a reader tabbing in lands on a date they can
+     * pick. Measured before: with `min="2026-03-03"`, the stop sat on "Sunday,
+     * March 1, 2026", unavailable. A month with nothing to choose keeps its
+     * first day, so the grid still has a way in.
      */
     private get anchor();
     /** Six weeks of dates, so a grid does not change height between months. */

package/dist/date-picker/root/date-picker-root.js

@@ -199,15 +199,21 @@ let HelixHeadlessDatePicker = class HelixHeadlessDatePicker extends MixinPickerF
     }
     get anchor() {
         const shown = this.shown;
+        const today = asDate(todayIn(this.timeZone));
         for (const candidate of [
             asDate(this.focused),
             asDate(this.selected[0] ?? ''),
-            asDate(todayIn(this.timeZone)),
+            today && !this.barred(today) ? today : null,
         ]) {
             if (candidate && this.system.same(candidate, shown)) {
                 return candidate;
             }
         }
+        for (let day = shown; this.system.same(day, shown); day = addDays(day, 1)) {
+            if (!this.barred(day)) {
+                return day;
+            }
+        }
         return shown;
     }
     weeksOf(month) {

package/dist/dialog/form-method.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Closes a shadow `<dialog>` on a `<form method="dialog">` submit slotted into
+ * it, the way the platform closes its own. `Dialog` and `Drawer` share it.
+ *
+ * **The platform cannot find the dialog from the form.** A submit with the
+ * `dialog` method closes the nearest `<dialog>` ancestor, and a slotted form's
+ * ancestors are the light DOM, where there is none. So the submit is read on
+ * the host, and the submitter's `value` is the `returnValue`, as it would be.
+ * A form inside a `<dialog>` of its own, or with any other method, is left to
+ * the platform.
+ */
+export declare const closeOnDialogSubmit: (event: SubmitEvent, close: (returnValue?: string) => void) => void;

package/dist/dialog/form-method.js

@@ -0,0 +1,13 @@
+export const closeOnDialogSubmit = (event, close) => {
+    const form = event.target;
+    if (!(form instanceof HTMLFormElement) || form.closest('dialog')) {
+        return;
+    }
+    const submitter = event.submitter;
+    const method = submitter?.hasAttribute('formmethod') ? submitter.formMethod : form.method;
+    if (method !== 'dialog') {
+        return;
+    }
+    event.preventDefault();
+    close(submitter?.hasAttribute('value') ? submitter.value : undefined);
+};

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

@@ -201,15 +201,7 @@ export declare class HelixHeadlessDialog extends HelixHeadlessDialog_base {
      * saying otherwise would be a lie the next `showModal()` would trip over.
      */
     private readonly handleClose;
-    /**
-     * A `<form method="dialog">` slotted into the dialog, closed the way the
-     * platform closes its own.
-     *
-     * **The platform cannot find this dialog from the form.** A submit with the
-     * `dialog` method closes the nearest `<dialog>` ancestor, and a slotted form's
-     * ancestors are the light DOM, where there is none. So the submit is read
-     * here, and the submitter's `value` is the `returnValue`, as it would be.
-     */
+    /** A `<form method="dialog">` slotted into the dialog closes it. */
     private readonly handleSubmit;
     /** Whether the `header` slot's heading is what currently names the dialog. */
     private namedByHeader;

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

@@ -8,6 +8,7 @@ import { AriaForwardController, auditName, CommandController, customElement, dra
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { wordsIn } from '../description.js';
+import { closeOnDialogSubmit } from '../form-method.js';
 let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(HelixElement) {
     constructor() {
         super(...arguments);
@@ -49,17 +50,7 @@ let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(
             this.relayNativeEvent(event);
         };
         this.handleSubmit = (event) => {
-            const form = event.target;
-            if (!(form instanceof HTMLFormElement) || form.closest('dialog')) {
-                return;
-            }
-            const submitter = event.submitter;
-            const method = submitter?.hasAttribute('formmethod') ? submitter.formMethod : form.method;
-            if (method !== 'dialog') {
-                return;
-            }
-            event.preventDefault();
-            this.close(submitter?.hasAttribute('value') ? submitter.value : undefined);
+            closeOnDialogSubmit(event, (value) => this.close(value));
         };
         this.namedByHeader = false;
         this.scope = new FocusScopeController(this, {

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

@@ -321,6 +321,8 @@ export declare class HelixHeadlessDrawer extends HelixHeadlessDrawer_base {
      * comes first.
      */
     private describeByBody;
+    /** A `<form method="dialog">` slotted into the drawer closes it, as in `Dialog`. */
+    private readonly handleSubmit;
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected updated(changed: PropertyValues): void;

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

@@ -8,6 +8,7 @@ import { AriaForwardController, auditName, CommandController, customElement, dra
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { wordsIn } from '../../dialog/description.js';
+import { closeOnDialogSubmit } from '../../dialog/form-method.js';
 import { beyondWindow } from '../reveal.js';
 import { startsSwipe } from '../swipe-start.js';
 let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(HelixElement) {
@@ -111,6 +112,9 @@ let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(
         };
         this.namedByHeader = false;
         this.describedByBody = false;
+        this.handleSubmit = (event) => {
+            closeOnDialogSubmit(event, (value) => this.close(value));
+        };
     }
     static { this.words = 'helix-drawer'; }
     get refusesDismissal() {
@@ -214,10 +218,12 @@ let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(
     connectedCallback() {
         super.connectedCallback();
         this.addEventListener('focusin', this.handleFocusIn);
+        this.addEventListener('submit', this.handleSubmit);
     }
     disconnectedCallback() {
         super.disconnectedCallback();
         this.removeEventListener('focusin', this.handleFocusIn);
+        this.removeEventListener('submit', this.handleSubmit);
         unlockScroll(this);
     }
     updated(changed) {

package/dist/filter-input/index.d.ts

@@ -1,6 +1,5 @@
 export * from './chip/filter-chip.js';
 export * from './field/filter-field.js';
 export * from './grammar.js';
-export * from './menu/filter-menu.js';
 export * from './operator/filter-operator.js';
 export * from './root/filter-input-root.js';

package/dist/filter-input/index.js

@@ -1,6 +1,5 @@
 export * from './chip/filter-chip.js';
 export * from './field/filter-field.js';
 export * from './grammar.js';
-export * from './menu/filter-menu.js';
 export * from './operator/filter-operator.js';
 export * from './root/filter-input-root.js';

package/dist/filter-input/menu/filter-menu.d.ts

@@ -51,6 +51,10 @@ import '../../menu/index.js';
  * `Notification` does for a read. Call `preventDefault()` on `helix-facet` to
  * cancel the change.
  *
+ * Imported from its own entry, `@fusion.dev/helix-headless/filter-input/menu`, which registers
+ * it with the `Menu` it draws its pages with. The family's entry leaves it out,
+ * so a field without a picker does not carry `Menu`.
+ *
  * @since 0.25.0
  * @status stable
  * @category forms

package/dist/filter-input/menu/index.d.ts

@@ -0,0 +1 @@
+export * from './filter-menu.js';

package/dist/filter-input/menu/index.js

@@ -0,0 +1 @@
+export * from './filter-menu.js';

package/dist/filter-input/root/filter-input-root.d.ts

@@ -42,7 +42,7 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * | Enter | Presses the highlighted suggestion. With none highlighted, reads the typed filters into chips, or submits the form when there are none. |
  * | Down, Up | Moves the highlight through the suggestions, wrapping, and opens the panel. |
  * | Home, End | Highlights the first or the last suggestion while the panel is open. |
- * | Escape | Closes the panel and stops there, so a dialog around the field stays open. |
+ * | Escape | Closes the panel and stops there, so a dialog around the field stays open. With the panel closed, empties the text. In an empty field, does nothing, so the page hears it. |
  * | Backspace | In an empty field, asks the last token to go. |
  * | Left | With the caret at the start of the text, moves to the last token's remove button. Right on a right-to-left page. |
  * | Left, Right on a token | Move between the tokens, and past the last back to the text. |
@@ -51,7 +51,8 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * **Typed filters.** The field parses only the fields you declare. Write
  * `FilterField` elements, usually inside the `FilterMenu` slotted into `start`,
  * so the picker and the text share one set. On Enter, the field reads the text
- * against them. `disposition:refunded,settled` and `-disposition:refunded` fire
+ * against them, and a paste is read the same way as soon as it lands.
+ * `disposition:refunded,settled` and `-disposition:refunded` fire
  * `helix-facet` exactly as ticking those values in the picker would, and the
  * parsed text is removed. Everything else stays, so `refund tuesday
  * disposition:settled` is a filter and a search at once. Helix defines the
@@ -64,6 +65,12 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * nothing draws it and the menu has no page for it, and the grammar still reads
  * it.
  *
+ * **The picker has an entry of its own.** `FilterMenu` draws its pages with
+ * `Menu`, which a field without a picker does not need, so this family's entry
+ * leaves it out. A page that writes one imports
+ * `@fusion.dev/helix/filter-input/menu` as well, and a picker written without it
+ * is reported once the page has loaded, with the entry to add.
+ *
  * **Suggestions.** Slot options into `suggestions` and the field shows them,
  * moves through them with the arrow keys, and presses one on Enter. The option
  * fires its own `helix-select`, and you decide what choosing it means. Keys
@@ -408,6 +415,14 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
      *
      * Everything else in the row is untouched: a plain `Tag`, or a chip for
      * something no `FilterField` declares, is the consumer's to answer.
+     *
+     * **Heard on the way down, in the capture phase**, because the chip is a
+     * child of this element and its request passes here before it reaches the
+     * chip's listeners or comes back up. Stopped there, no listener on the chip,
+     * on this element or above it hears it. Heard on the way up, `stopPropagation`
+     * kept it from the ancestors and not from this element's other listeners, so a
+     * consumer listening on the field heard `helix-dismiss` as well as the
+     * `helix-facet` that answered it.
      */
     private readonly handleDismiss;
     /**
@@ -512,6 +527,15 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
     disconnectedCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
+    /**
+     * Says so when a picker is written in the field and never registered.
+     *
+     * The picker has an entry of its own, so a page that imports only the field
+     * gets an inert element there: a trigger that opens nothing. Asked once the
+     * page has loaded and painted, so an entry a later module imports is not
+     * taken for a missing one.
+     */
+    private auditPicker;
     protected updated(changed: PropertyValues): void;
     /**
      * Marks the highlighted suggestion, and tells the control which one it is.

package/dist/filter-input/root/filter-input-root.js

@@ -4,14 +4,15 @@ 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, countLabel, customElement, drawIcon, drawStatus, formatWords, HelixFacetEvent, HelixFormElement, holdCaret, MixinControllerOpen, MixinControllerValue, MixinField, MixinTokens, PopoverController, restoreValue, StatusController, scrollItemIntoView, words, wordsLocale, } from '@fusion.dev/helix-core';
+import { AriaForwardController, countLabel, customElement, drawIcon, drawStatus, formatWords, HelixFacetEvent, HelixFormElement, holdCaret, MixinControllerOpen, MixinControllerValue, MixinField, MixinTokens, PopoverController, reportRuntime, restoreValue, StatusController, scrollItemIntoView, words, wordsLocale, } from '@fusion.dev/helix-core';
 import { x } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { HelixHeadlessFilterField } from '../field/filter-field.js';
 import { readFilterText } from '../grammar.js';
-import { HelixHeadlessFilterMenu } from '../menu/filter-menu.js';
 import { currentTerm, suggests, tokenEntry } from '../suggest.js';
+const picks = (element) => typeof element.apply === 'function' &&
+    Array.isArray(element.fields);
 const asksToGo = (node) => typeof node?.dismiss === 'function';
 const isOption = (node) => 'active' in node && 'value' in node;
 let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinControllerOpen(MixinTokens(MixinControllerValue(MixinField(HelixFormElement)))) {
@@ -58,6 +59,9 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
             restoreValue(control, this.value);
             this.dismissed = false;
             this.settleOpen();
+            if (event.inputType === 'insertFromPaste') {
+                this.readFilters();
+            }
         };
         this.handleChange = (event) => {
             event.stopPropagation();
@@ -111,6 +115,12 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
                 }
                 return;
             }
+            if (event.key === 'Escape' && !this.open && this.value !== '') {
+                event.preventDefault();
+                event.stopPropagation();
+                this.handleClear();
+                return;
+            }
             if (!this.suggesting) {
                 return;
             }
@@ -281,7 +291,7 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
     }
     menuFor(field) {
         for (const menu of this.querySelectorAll('*')) {
-            if (!(menu instanceof HelixHeadlessFilterMenu)) {
+            if (!picks(menu)) {
                 continue;
             }
             if (menu.fields.some((declared) => (declared.name ?? '') === field)) {
@@ -387,12 +397,12 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
     }
     connectedCallback() {
         super.connectedCallback();
-        this.addEventListener('helix-dismiss', this.handleDismiss);
+        this.addEventListener('helix-dismiss', this.handleDismiss, { capture: true });
         this.addEventListener(HelixFacetEvent.eventName, this.handleFacet);
     }
     disconnectedCallback() {
         super.disconnectedCallback();
-        this.removeEventListener('helix-dismiss', this.handleDismiss);
+        this.removeEventListener('helix-dismiss', this.handleDismiss, { capture: true });
         this.removeEventListener(HelixFacetEvent.eventName, this.handleFacet);
     }
     willUpdate(changed) {
@@ -418,6 +428,30 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
         this.finishHydration();
         this.handleTokens();
         this.refreshSuggesting();
+        this.auditPicker();
+    }
+    auditPicker() {
+        const { tier } = this.constructor;
+        const tag = `${tier}filter-menu`;
+        const check = () => {
+            if (this.isConnected && this.querySelector(tag) && !customElements.get(tag)) {
+                const entry = tier === 'helix-' ? '@fusion.dev/helix' : '@fusion.dev/helix-headless';
+                reportRuntime({
+                    kind: 'unregistered-part',
+                    message: `<${tag}> in <${this.localName}> is not registered, so its trigger opens nothing. Import '${entry}/filter-input/menu'.`,
+                    tag: this.localName,
+                });
+            }
+        };
+        const frame = () => {
+            requestAnimationFrame(check);
+        };
+        if (document.readyState === 'complete') {
+            frame();
+        }
+        else {
+            window.addEventListener('load', frame, { once: true });
+        }
     }
     updated(changed) {
         super.updated(changed);

package/dist/icon/all/index.d.ts

@@ -0,0 +1 @@
+export * from '../index.js';

package/dist/icon/all/index.js

@@ -0,0 +1,4 @@
+import { icons } from '@fusion.dev/helix-icons';
+import { registerIcons } from '../registry.js';
+registerIcons(icons);
+export * from '../index.js';

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

@@ -18,8 +18,11 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * a dark background. Shapes that set their own `fill` or `stroke` are
  * unaffected.
  *
- * **A name is looked up in a registry.** The family's entry registers the
- * whole set, so any name in it draws. The element's own entry,
+ * **A name is looked up in a registry.** The family's entry registers a small
+ * set: the four carets, `arrow-left`, `arrow-right`, `check`, `x`, `plus`,
+ * `minus`, `magnifying-glass`, `info` and `warning`. `icon/all` registers the
+ * whole set, so any name in it draws, and a name that resolves to nothing
+ * says to import it. The element's own entry,
  * `@fusion.dev/helix-headless/icon/root`, registers none: a page that imports
  * it and calls `registerIcons` with the glyphs it names ships those and no
  * others. `registerIconLibrary` resolves names under a prefix of your own,
@@ -94,12 +97,10 @@ export declare class HelixHeadlessIcon extends HelixElement {
      * The name of the icon in the Helix set.
      *
      * **A lookup, and the reason both this and `icon` exist.** A name is a string,
-     * so it is what markup can carry, and resolving one means an index of the
-     * whole set that no bundler can shake: 15 kB for a consumer who renders one
-     * mark. An attribute is the only thing an HTML author can write, and that is
-     * worth the index; a consumer who would rather not pay it imports the
-     * element from `icon/root` and registers the glyphs it names, or hands over
-     * the value instead.
+     * so it is what markup can carry, and resolving one means an index that no
+     * bundler can shake. The family's entry indexes a small set, `icon/all`
+     * indexes the whole set at 15 kB, and `icon/root` indexes nothing, for a
+     * page that registers the glyphs it names or hands over the value instead.
      *
      * A name written `prefix:name` asks the library registered under that
      * prefix.

package/dist/icon/root/icon-root.js

@@ -131,8 +131,10 @@ let HelixHeadlessIcon = class HelixHeadlessIcon extends HelixElement {
             kind: 'unknown-icon',
             message: this.src === ''
                 ? `<${this.localName} name="${asked}"> names no registered icon, so it draws ` +
-                    'nothing. Check the name, register the glyph with `registerIcons`, or import it ' +
-                    'and pass it as `icon`.'
+                    `nothing. For a glyph of the Helix set, import '${this.localName.startsWith('helix-headless-')
+                        ? '@fusion.dev/helix-headless'
+                        : '@fusion.dev/helix'}/icon/all', which registers every one. Otherwise check the name, or register ` +
+                    'the glyph with `registerIcons`.'
                 : `<${this.localName} src="${asked}"> could not be fetched as an SVG file, so it ` +
                     'draws nothing. Check the URL, and that the file is an `<svg>`.',
             tag: this.localName,

package/dist/icon/set.js

@@ -1,3 +1,17 @@
-import { icons } from '@fusion.dev/helix-icons';
+import { arrowLeft, arrowRight, caretDown, caretLeft, caretRight, caretUp, check, info, magnifyingGlass, minus, plus, warning, x, } from '@fusion.dev/helix-icons';
 import { registerIcons } from './registry.js';
-registerIcons(icons);
+registerIcons([
+    arrowLeft,
+    arrowRight,
+    caretDown,
+    caretLeft,
+    caretRight,
+    caretUp,
+    check,
+    info,
+    magnifyingGlass,
+    minus,
+    plus,
+    warning,
+    x,
+]);

package/dist/index.d.ts

@@ -46,10 +46,11 @@ export * from './drilldown/index.js';
 export * from './empty/index.js';
 export * from './file-input/index.js';
 export * from './filter-input/index.js';
+export * from './filter-input/menu/index.js';
 export * from './format-date/index.js';
 export * from './graph/index.js';
 export * from './heatmap/index.js';
-export * from './icon/index.js';
+export * from './icon/all/index.js';
 export * from './icon-button/index.js';
 export * from './image/index.js';
 export * from './input/index.js';

package/dist/index.js

@@ -37,10 +37,11 @@ export * from './drilldown/index.js';
 export * from './empty/index.js';
 export * from './file-input/index.js';
 export * from './filter-input/index.js';
+export * from './filter-input/menu/index.js';
 export * from './format-date/index.js';
 export * from './graph/index.js';
 export * from './heatmap/index.js';
-export * from './icon/index.js';
+export * from './icon/all/index.js';
 export * from './icon-button/index.js';
 export * from './image/index.js';
 export * from './input/index.js';

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

@@ -55,6 +55,7 @@ export declare class HelixHeadlessLightboxItem extends HelixElement {
     roleLabel: string;
     /**
      * The item's identifier. The root compares its `active` value against it.
+     * Without one, the item is named by its place in the set, counted from 1.
      */
     value: string;
     /** Whether anything is slotted into `description`, which then describes the group. */

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

@@ -16,7 +16,9 @@ declare const HelixHeadlessLightbox_base: (new (...args: any[]) => import("@fusi
  *
  * A lightbox shows one item at a time and has no scrolling track, so `active`
  * holds the current item, as in `Tabs`. The arrow keys change the item while
- * focus stays in the dialog.
+ * focus stays in the dialog. `active` names an item by its `value`, and an
+ * item with no `value` by its place, counted from 1, as in `Steps`, so a set
+ * written without values moves and `helix-activate` says `1`, `2` and so on.
  *
  * Set `controls` for the viewer's own previous, next and close controls, named
  * by `previous-label`, `next-label` and `dismiss-label`, whose glyphs you can
@@ -33,9 +35,9 @@ declare const HelixHeadlessLightbox_base: (new (...args: any[]) => import("@fusi
  * `--lightbox-pan-x` and `--lightbox-pan-y`, written only while zoomed, and a
  * swipe moves to the next item only while the item is at its own size. With
  * `controls`, the viewer also draws zoom-out and zoom-in controls, for a
- * pointer with no wheel and no second finger. Once a reader stops zooming, the
- * live region says the new scale in the words of `zoom-status-label`, such as
- * "Zoomed to 150%".
+ * pointer with no wheel and no second finger. Once a reader stops zooming, and
+ * at once for a key or a zoom control, the live region says the new scale in
+ * the words of `zoom-status-label`, such as "Zoomed to 150%".
  *
  * Each item is a slide: a `group` with the role description in
  * `slide-role-label`, named by its `label` or by `slide-label`. A touch or a pen
@@ -232,7 +234,14 @@ export declare class HelixHeadlessLightbox extends HelixHeadlessLightbox_base {
     private readonly zoomer;
     /** Writes the zoom on the viewport, and nothing at the item's own size. */
     private drawZoom;
-    /** Says the new scale in the live region, a moment after the last change. */
+    /** Whether the zoom is changing by one discrete step, a key or a control, which is said at once. */
+    private zoomStep;
+    /**
+     * Says the new scale in the live region: a moment after the last change of
+     * a pinch, a drag or the wheel, and at once for a key or a zoom control,
+     * which is one change a reader is waiting to hear. Said only after the
+     * pause, a reader pressing `+` heard nothing until it ended.
+     */
     private sayZoom;
     /**
      * Zooms the shown item to `scale`, held between `1` and `max-zoom`, about
@@ -346,12 +355,23 @@ export declare class HelixHeadlessLightbox extends HelixHeadlessLightbox_base {
     private zoomIn;
     /** Zooms out by as much, as `-` and the zoom-out control do. */
     private zoomOut;
+    /** Changes the zoom by one discrete step, which `sayZoom` says at once. */
+    private stepZoom;
     /** Home and End, which are an index rather than a step. */
     private toEnd;
     /** The item shown at the last update, whose zoom a different item does not keep. */
     private zoomedItem;
     /** The item on screen: the one `active` names, or the first where it names none. */
     private get shown();
+    /** The item `active` names, by `value` or by place, or the first where it names none. */
+    private named;
+    /**
+     * Requests a new shown item, and returns whether it moved.
+     *
+     * Where `active` names nothing, it is first written with the item on
+     * screen, so `helix-activate` names the item you saw as `previous`.
+     */
+    requestActive(next: string, cause?: string): boolean;
     /**
      * A press on the backdrop or on the empty area around the item.
      *

package/dist/lightbox/root/lightbox-root.js

@@ -12,6 +12,7 @@ import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { HelixHeadlessLightboxItem } from '../item/lightbox-item.js';
 import { percentOf } from '../zoom.js';
 import { ZoomController } from '../zoom-controller.js';
+const keyOf = (item, index) => item.value || String(index + 1);
 let HelixHeadlessLightbox = class HelixHeadlessLightbox extends MixinControllerActive(MixinControllerOpen(HelixElement)) {
     constructor() {
         super(...arguments);
@@ -76,6 +77,7 @@ let HelixHeadlessLightbox = class HelixHeadlessLightbox extends MixinControllerA
             onChange: (scale, pan) => this.drawZoom(scale, pan),
             surface: () => this.partNamed('viewport'),
         });
+        this.zoomStep = false;
         this.fullscreen = new FullscreenController(this, (full) => {
             this.filled = full;
         });
@@ -164,7 +166,7 @@ let HelixHeadlessLightbox = class HelixHeadlessLightbox extends MixinControllerA
             this.zoomSaid.cancel();
             return;
         }
-        this.zoomSaid.start(400, () => {
+        this.zoomSaid.start(this.zoomStep ? 0 : 400, () => {
             this.announcement = formatWords(this, 'zoomStatusLabel', {
                 percent: percentOf(this.zoomScale),
                 scale: this.zoomScale,
@@ -225,7 +227,7 @@ let HelixHeadlessLightbox = class HelixHeadlessLightbox extends MixinControllerA
             : Math.min(Math.max(from + by, 0), last);
         const target = items[next];
         if (target && target !== shown) {
-            this.requestActive(target.value);
+            this.requestActive(keyOf(target, next));
         }
     }
     zoomKey(key) {
@@ -239,7 +241,7 @@ let HelixHeadlessLightbox = class HelixHeadlessLightbox extends MixinControllerA
             this.zoomOut();
         }
         else if (key === '0') {
-            this.zoomer.reset();
+            this.stepZoom(() => this.zoomer.reset());
         }
         else {
             return false;
@@ -266,19 +268,40 @@ let HelixHeadlessLightbox = class HelixHeadlessLightbox extends MixinControllerA
         return true;
     }
     zoomIn() {
-        this.zoomer.zoomTo(this.zoomer.scale * 1.5);
+        this.stepZoom(() => this.zoomer.zoomTo(this.zoomer.scale * 1.5));
     }
     zoomOut() {
-        this.zoomer.zoomTo(this.zoomer.scale / 1.5);
+        this.stepZoom(() => this.zoomer.zoomTo(this.zoomer.scale / 1.5));
+    }
+    stepZoom(change) {
+        this.zoomStep = true;
+        try {
+            change();
+        }
+        finally {
+            this.zoomStep = false;
+        }
     }
     toEnd(at) {
         const target = this.items[at];
         if (target && target !== this.shown) {
-            this.requestActive(target.value);
+            this.requestActive(keyOf(target, at));
         }
     }
     get shown() {
-        return resolveActiveItem(this.active ?? '', this.items);
+        return this.named(this.items);
+    }
+    named(items) {
+        const keyed = items.map((item, index) => ({ item, value: keyOf(item, index) }));
+        return resolveActiveItem(this.active ?? '', keyed)?.item;
+    }
+    requestActive(next, cause) {
+        const items = this.items;
+        const shown = this.active === '' ? this.shown : undefined;
+        if (shown) {
+            this.active = keyOf(shown, items.indexOf(shown));
+        }
+        return super.requestActive(next, cause);
     }
     dragged(event) {
         const from = this.pressedAt;
@@ -348,7 +371,7 @@ let HelixHeadlessLightbox = class HelixHeadlessLightbox extends MixinControllerA
     }
     mark() {
         const items = this.items;
-        const current = resolveActiveItem(this.active, items);
+        const current = this.named(items);
         items.forEach((item, at) => {
             item.current = item === current;
             whenHydrated(item, () => {
@@ -376,7 +399,7 @@ let HelixHeadlessLightbox = class HelixHeadlessLightbox extends MixinControllerA
             return;
         }
         const items = this.items;
-        const current = resolveActiveItem(this.active, items);
+        const current = this.named(items);
         const at = current ? items.indexOf(current) : -1;
         this.announcement =
             at === -1 || !current
@@ -389,7 +412,7 @@ let HelixHeadlessLightbox = class HelixHeadlessLightbox extends MixinControllerA
     }
     place() {
         const items = this.items;
-        const current = resolveActiveItem(this.active, items);
+        const current = this.named(items);
         return current
             ? formatWords(this, 'statusLabel', {
                 count: items.length,