@fusion.dev/helix-headless 0.142.1 → 0.144.0

package/dist/listbox/root/listbox-root.js

@@ -4,14 +4,17 @@ 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, customElement, DisabledCascadeController, HelixFilterEvent, HelixFormElement, hostAria, MixinCollection, MixinControllerValue, MixinField, reportValues, requestChange, scrollItemIntoView, } from '@fusion.dev/helix-core';
+import { AriaForwardController, countLabel, customElement, DelayController, DisabledCascadeController, HelixFilterEvent, HelixFormElement, hostAria, MixinCollection, MixinControllerValue, MixinField, reportValues, requestChange, scrollItemIntoView, Typeahead, typesCharacter, } from '@fusion.dev/helix-core';
 import { magnifyingGlass } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { HelixHeadlessOptionGroup } from '../../option/group/option-group.js';
 import { HelixHeadlessOption } from '../../option/root/option-root.js';
-const MOVES = new Set(['ArrowDown', 'ArrowUp', 'End', 'Home']);
+import { rangeAdd } from '../range.js';
+const MOVES = new Set(['ArrowDown', 'ArrowUp', 'End', 'Home', 'PageDown', 'PageUp']);
+const FIELD_MOVES = new Set(['ArrowDown', 'ArrowUp', 'PageDown', 'PageUp']);
+const PAGE = 10;
 const matched = new Map();
 const HIGHLIGHT = 'helix-filter-match';
 const paintable = () => typeof CSS !== 'undefined' && 'highlights' in CSS && typeof Highlight !== 'undefined';
@@ -66,9 +69,16 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         this.emptyText = 'No matches';
         this.filterState = undefined;
         this.filterable = false;
+        this.filterDelay = 0;
         this.filterLabel = 'Filter';
+        this.manual = false;
         this.multiple = false;
+        this.resultLabel = '{count} result';
+        this.resultsLabel = '{count} results';
         this.activeValue = '';
+        this.parked = false;
+        this.typeahead = new Typeahead();
+        this.seen = new Set();
         this.forwarded = false;
         this.hasMatches = true;
         this.counted = false;
@@ -76,6 +86,9 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
             items: () => this.options,
         });
         this.handleSelection = (event) => {
+            if (event.detail.href !== undefined) {
+                return;
+            }
             event.stopPropagation();
             if (event.defaultPrevented) {
                 return;
@@ -88,57 +101,114 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
             if (shown.length === 0) {
                 return;
             }
-            if (event.key === ' ' || event.key === 'Enter') {
-                event.preventDefault();
-                if (this.activeValue !== '') {
+            const typing = this.forwarded || event.composedPath()[0] === this.partNamed('search-field');
+            if (event.key === 'Enter' || (event.key === ' ' && !typing && !this.typeahead.typing())) {
+                const link = shown.find((option) => option.value === this.activeValue && Boolean(option.href));
+                if (link !== undefined) {
+                    event.preventDefault();
+                    if (event.key === 'Enter') {
+                        link.select(event);
+                    }
+                }
+                else if (this.activeValue !== '') {
+                    event.preventDefault();
                     this.choose(this.activeValue);
                 }
+                else if (event.key === ' ') {
+                    event.preventDefault();
+                }
                 return;
             }
-            if (!MOVES.has(event.key) && event.key !== 'Enter') {
+            if (this.multiple &&
+                !typing &&
+                event.key.toLowerCase() === 'a' &&
+                (event.ctrlKey || event.metaKey) &&
+                !event.altKey) {
+                event.preventDefault();
+                const reachable = shown.map((option) => option.value);
+                const all = reachable.every((value) => this.values.includes(value));
+                const kept = this.values.filter((value) => !reachable.includes(value));
+                this.requestValue((all ? kept : [...kept, ...reachable]).join(','));
+                return;
+            }
+            if (!typing && typesCharacter(event)) {
+                event.preventDefault();
+                const value = this.typeaheadTo(event.key);
+                if (value !== undefined) {
+                    this.arrive(value);
+                }
+                return;
+            }
+            if (!(typing ? FIELD_MOVES : MOVES).has(event.key)) {
                 return;
             }
             event.preventDefault();
+            this.typeahead.reset();
             const from = this.currentValue;
             const at = shown.findIndex((option) => option.value === from);
+            const last = shown.length - 1;
             let next = at;
             if (event.key === 'ArrowDown') {
                 next = at < 0 ? 0 : (at + 1) % shown.length;
             }
             else if (event.key === 'ArrowUp') {
-                next = at < 0 ? shown.length - 1 : (at - 1 + shown.length) % shown.length;
+                next = at < 0 ? last : (at - 1 + shown.length) % shown.length;
             }
             else if (event.key === 'Home') {
                 next = 0;
             }
+            else if (event.key === 'End') {
+                next = last;
+            }
+            else if (event.key === 'PageDown') {
+                next = at < 0 ? 0 : Math.min(at + this.pageSize(), last);
+            }
             else {
-                next = shown.length - 1;
+                next = at < 0 ? last : Math.max(at - this.pageSize(), 0);
             }
             const target = shown[next];
-            if (!target) {
-                return;
-            }
-            this.activeValue = target.value;
-            if (!this.multiple && !this.forwarded) {
-                this.choose(target.value);
+            if (target) {
+                this.arrive(target.value);
+                const ranged = event.key === 'Home' || event.key === 'End';
+                if (this.multiple && !typing && event.shiftKey && ranged) {
+                    const taken = rangeAdd(this.values, shown.map((option) => option.value), at, next);
+                    if (taken) {
+                        this.requestValue(taken.join(','));
+                    }
+                    return;
+                }
+                if (this.multiple && !typing && event.shiftKey && !this.values.includes(target.value)) {
+                    this.choose(target.value);
+                }
             }
         };
         this.handleFilter = (event) => {
             event.stopPropagation();
             const control = event.target;
-            this.requestFilter(control.value);
-            if (control.value !== this.filter) {
-                control.value = this.filter;
+            this.filtering.cancel();
+            if (this.filterDelay > 0) {
+                this.filtering.start(this.filterDelay, () => this.takeFilter(control));
+                return;
             }
+            this.takeFilter(control);
         };
+        this.filtering = new DelayController(this, { renders: false });
         this.handleFilterKeydown = (event) => {
-            if (event.key === 'Escape' && this.filter !== '') {
+            if (event.key === 'Enter' || FIELD_MOVES.has(event.key)) {
+                this.flushFilter();
+            }
+            if (event.key === 'Escape' && (this.filter !== '' || this.filtering.pending)) {
                 event.stopPropagation();
                 event.preventDefault();
+                this.filtering.cancel();
                 this.requestFilter('');
+                const control = this.partNamed('search-field');
+                if (control && control.value !== this.filter) {
+                    control.value = this.filter;
+                }
                 return;
             }
-            if (!MOVES.has(event.key)) {
+            if (!FIELD_MOVES.has(event.key)) {
                 return;
             }
             event.stopPropagation();
@@ -160,6 +230,53 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         const option = this.options[at];
         this.value = option?.value ?? '';
     }
+    highlight(where) {
+        const shown = this.shown.filter((option) => !option.disabled);
+        this.typeahead.reset();
+        this.parked = where === 'none';
+        if (where === 'none') {
+            this.activeValue = '';
+        }
+        else if (where === 'first') {
+            this.activeValue = shown[0]?.value ?? '';
+        }
+        else if (where === 'last') {
+            this.activeValue = shown.at(-1)?.value ?? '';
+        }
+        else {
+            const chosen = shown.find((option) => this.values.includes(option.value));
+            this.activeValue = (chosen ?? shown[0])?.value ?? '';
+        }
+        if (this.childrenKnown) {
+            this.place();
+        }
+    }
+    tell(changed) {
+        if (!changed.has('filter') || !this.hasUpdated) {
+            return;
+        }
+        const count = this.shown.length;
+        if (this.filter.trim() === '' || count === 0) {
+            this.announced = '';
+            return;
+        }
+        this.announced = countLabel(count, this.resultLabel, this.resultsLabel, this.lang);
+    }
+    typeaheadTo(key) {
+        const shown = this.shown.filter((option) => !option.disabled);
+        const from = shown.findIndex((option) => option.value === this.currentValue);
+        const at = this.typeahead.match(key, shown.map((option) => option.text), from);
+        const target = shown[at];
+        if (!target) {
+            return undefined;
+        }
+        this.parked = false;
+        this.activeValue = target.value;
+        return target.value;
+    }
+    get typing() {
+        return this.typeahead.typing();
+    }
     get type() {
         return this.multiple ? 'select-multiple' : 'select-one';
     }
@@ -218,6 +335,20 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         }
         this.requestValue(joined);
     }
+    arrive(value) {
+        this.parked = false;
+        this.activeValue = value;
+        const link = this.options.some((option) => option.value === value && Boolean(option.href));
+        if (!this.multiple && !this.manual && !this.forwarded && !link) {
+            this.choose(value);
+        }
+    }
+    pageSize() {
+        const items = this.partNamed('items');
+        const row = this.shown[0]?.getBoundingClientRect().height ?? 0;
+        const height = items?.clientHeight ?? 0;
+        return row > 0 && height > 0 ? Math.max(1, Math.floor(height / row) - 1) : PAGE;
+    }
     navigate(event) {
         this.forwarded = true;
         try {
@@ -247,6 +378,7 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         }
     }
     place() {
+        this.forgetRemoved();
         const needle = this.filter.trim().toLowerCase();
         const chosen = new Set(this.values);
         for (const option of this.options) {
@@ -258,7 +390,7 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
             group.hidden = inside.length > 0 && inside.every((option) => option.hidden);
         }
         const shown = this.shown;
-        const rescue = needle !== '' || this.activeValue !== '';
+        const rescue = !this.parked && (needle !== '' || this.activeValue !== '');
         if (rescue && !shown.some((option) => option.value === this.activeValue)) {
             this.activeValue = shown.find((option) => !option.disabled)?.value ?? '';
         }
@@ -278,6 +410,21 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         }
         this.counted = true;
     }
+    get owned() {
+        const root = this.getRootNode();
+        return root instanceof ShadowRoot && root.host.localName.startsWith('helix-');
+    }
+    forgetRemoved() {
+        if (this.owned) {
+            return;
+        }
+        const present = new Set(this.options.map((option) => option.value));
+        const gone = this.values.filter((value) => this.seen.has(value) && !present.has(value));
+        this.seen = present;
+        if (gone.length > 0) {
+            this.value = this.values.filter((value) => !gone.includes(value)).join(',');
+        }
+    }
     followActive() {
         const active = this.shown.find((option) => option.value === this.activeValue);
         if (active) {
@@ -309,8 +456,32 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
     willUpdate(changed) {
         super.willUpdate(changed);
         hostAria(this.internals, { role: '' });
+        if (changed.has('value') &&
+            !this.multiple &&
+            this.activeValue !== '' &&
+            !this.values.includes(this.activeValue)) {
+            this.activeValue = '';
+            this.typeahead.reset();
+        }
+        if (this.childrenKnown) {
+            this.seedDeclared();
+        }
         if (this.childrenKnown) {
             this.place();
+            this.tell(changed);
+        }
+        this.toggleState('empty', !this.showsOptions);
+        this.toggleState('loading', this.loading);
+    }
+    seedDeclared() {
+        if (this.owned || this.defaultValue !== '' || this.hasAttribute('default-value')) {
+            return;
+        }
+        const declared = this.options
+            .filter((option) => option.defaultSelected)
+            .map((option) => option.value);
+        if (declared.length > 0) {
+            this.defaultValue = this.multiple ? declared.join(',') : (declared.at(-1) ?? '');
         }
     }
     get currentValue() {
@@ -330,6 +501,16 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         this.sync();
         this.linkActive();
     }
+    takeFilter(control) {
+        this.filtering.cancel();
+        this.requestFilter(control.value);
+        if (control.value !== this.filter) {
+            control.value = this.filter;
+        }
+    }
+    flushFilter() {
+        this.filtering.flush();
+    }
     requestFilter(next) {
         if (next === this.filter) {
             return true;
@@ -338,6 +519,7 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
             apply: (value) => {
                 const previous = this.filter;
                 this.filterState = value;
+                this.parked = false;
                 this.requestUpdate('filter', previous);
             },
             event: (value) => new HelixFilterEvent({ value }),
@@ -356,12 +538,23 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
       </svg>
     </slot>`;
     }
-    render() {
-        const shown = this.counted && !this.loading
+    get showsOptions() {
+        return this.counted && !this.loading
             ? this.filter === ''
                 ? this.options.length > 0
                 : this.hasMatches
             : true;
+    }
+    renderStatus(hasContent) {
+        if (!this.loading && hasContent) {
+            return nothing;
+        }
+        return this.loading
+            ? html `<p part="loading"><slot name="loading">${this.loadingText}</slot></p>`
+            : html `<p part="empty"><slot name="empty">${this.emptyText}</slot></p>`;
+    }
+    render() {
+        const shown = this.showsOptions;
         return html `${this.renderGroupLabel()}
       ${this.filterable
             ? html `<div part="search">
@@ -376,6 +569,7 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
                 .value=${this.filter}
                 placeholder=${this.filterLabel}
                 aria-label=${this.filterLabel}
+                aria-autocomplete="list"
                 aria-controls="items"
                 ?disabled=${this.isDisabled}
                 @input=${this.handleFilter}
@@ -394,7 +588,7 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         aria-multiselectable=${this.multiple ? 'true' : nothing}
         aria-required=${this.required ? 'true' : nothing}
         ${''}
-        tabindex=${this.isDisabled ? -1 : 0}
+        tabindex=${this.filterable ? nothing : this.isDisabled ? -1 : 0}
       >
         <slot @slotchange=${() => this.place()}></slot>
         ${this.renderStatus(shown)}
@@ -417,12 +611,24 @@ __decorate([
 __decorate([
     property({ attribute: 'filterable', reflect: true, type: Boolean })
 ], HelixHeadlessListbox.prototype, "filterable", void 0);
+__decorate([
+    property({ attribute: 'filter-delay', type: Number })
+], HelixHeadlessListbox.prototype, "filterDelay", void 0);
 __decorate([
     property({ attribute: 'filter-label' })
 ], HelixHeadlessListbox.prototype, "filterLabel", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessListbox.prototype, "manual", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessListbox.prototype, "multiple", void 0);
+__decorate([
+    property({ attribute: 'result-label' })
+], HelixHeadlessListbox.prototype, "resultLabel", void 0);
+__decorate([
+    property({ attribute: 'results-label' })
+], HelixHeadlessListbox.prototype, "resultsLabel", void 0);
 __decorate([
     state()
 ], HelixHeadlessListbox.prototype, "activeValue", void 0);

package/dist/loader/busy.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Marks a region busy for as long as something is loading into it, and
+ * counts, so two loaders in one region do not clear each other.
+ *
+ * Beside the family's `index.ts`, because which element is busy and how many
+ * claims it holds is bookkeeping about elements, not about a loader's
+ * template.
+ */
+/**
+ * Adds a claim on the region, setting `aria-busy="true"` on the first.
+ *
+ * Only an `aria-busy` this file wrote is ever taken off again: a region the
+ * page marked busy itself keeps its own attribute.
+ */
+export declare const claimBusy: (region: Element) => void;
+/** Takes a claim back, and the attribute with the last one. */
+export declare const releaseBusy: (region: Element) => void;

package/dist/loader/busy.js

@@ -0,0 +1,24 @@
+const CLAIMS = new WeakMap();
+export const claimBusy = (region) => {
+    const held = CLAIMS.get(region) ?? 0;
+    if (held === 0 && region.getAttribute('aria-busy') === 'true') {
+        return;
+    }
+    CLAIMS.set(region, held + 1);
+    if (held === 0) {
+        region.setAttribute('aria-busy', 'true');
+    }
+};
+export const releaseBusy = (region) => {
+    const held = CLAIMS.get(region);
+    if (held === undefined) {
+        return;
+    }
+    if (held <= 1) {
+        CLAIMS.delete(region);
+        region.removeAttribute('aria-busy');
+    }
+    else {
+        CLAIMS.set(region, held - 1);
+    }
+};

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

@@ -19,6 +19,15 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * a `role` attribute on the host would be missing from React server-rendered
  * markup.
  *
+ * **`for` names the region being loaded**, and the loader sets
+ * `aria-busy="true"` on it for as long as the loader is on the page, so a
+ * screen reader waits for the region rather than reading it half filled. Two
+ * loaders in one region hold it busy until the last one leaves.
+ *
+ * **`delay` keeps a quick load from flashing a loader.** The loader stays
+ * hidden, and silent, for that many milliseconds, and appears only if the work
+ * is still going.
+ *
  * @since 0.1.0
  * @status stable
  * @category feedback
@@ -33,11 +42,39 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @csspart track - The full circle behind the indicator.
  */
 export declare class HelixHeadlessLoader extends HelixElement {
+    /**
+     * How long the loader waits before it shows, in milliseconds, so work that
+     * finishes quickly never flashes one.
+     *
+     * Absent shows it at once. Hidden in the served markup too, so a page that
+     * loads quickly never draws it.
+     */
+    delay: number;
+    /**
+     * The id of the region being loaded, which is marked `aria-busy` while the
+     * loader is on the page.
+     *
+     * Names an element in the same tree. In React it arrives as a property, the
+     * way `Tooltip.for` does.
+     */
+    for: string;
     /**
      * The loader's name, announced by screen readers while the work is in
      * progress.
      */
     label: string;
+    /** The wait `delay` asks for, and whether it has run out. */
+    private readonly due;
+    /** The region this loader marked busy, so it is the one released. */
+    private region;
+    /** Whether the loader is still waiting out its `delay`. */
+    private get waiting();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** Marks the region `for` names busy, releasing one it named before. */
+    private mark;
+    private release;
+    protected updated(changed: PropertyValues<this>): void;
     protected willUpdate(changed: PropertyValues): void;
     protected render(): TemplateResult;
 }

package/dist/loader/root/loader-root.js

@@ -4,27 +4,76 @@ 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, hostAria } from '@fusion.dev/helix-core';
+import { customElement, DelayController, elementById, HelixElement, hostAria, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
+import { claimBusy, releaseBusy } from '../busy.js';
 let HelixHeadlessLoader = class HelixHeadlessLoader extends HelixElement {
     constructor() {
         super(...arguments);
+        this.delay = 0;
+        this.for = '';
         this.label = 'Loading';
+        this.due = new DelayController(this);
+        this.region = null;
+    }
+    get waiting() {
+        return this.delay > 0 && !this.due.elapsed;
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        if (this.delay > 0 && !this.due.elapsed) {
+            this.due.start(this.delay);
+        }
+        requestAnimationFrame(() => this.mark());
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.release();
+    }
+    mark() {
+        const region = this.isConnected && this.for !== '' ? elementById(this, this.for) : null;
+        if (region === this.region) {
+            return;
+        }
+        this.release();
+        if (region) {
+            claimBusy(region);
+            this.region = region;
+        }
+    }
+    release() {
+        if (this.region) {
+            releaseBusy(this.region);
+            this.region = null;
+        }
+    }
+    updated(changed) {
+        super.updated(changed);
+        if (changed.has('for') && changed.get('for') !== undefined) {
+            this.mark();
+        }
     }
     willUpdate(changed) {
         super.willUpdate(changed);
         hostAria(this.internals, { label: this.label, role: 'progressbar' });
         this.internals.ariaBusy = 'true';
+        this.internals.ariaHidden = this.waiting ? 'true' : null;
     }
     render() {
-        return html `<svg part="svg" viewBox="0 0 24 24" aria-hidden="true">
+        return html `<svg part="svg" viewBox="0 0 24 24" aria-hidden="true" ?hidden=${this.waiting}>
         <circle part="track" cx="12" cy="12" r="10" fill="none" />
         <circle part="indicator" cx="12" cy="12" r="10" fill="none" />
       </svg>
-      <span part="mark" aria-hidden="true"><slot></slot></span>`;
+      <span part="mark" aria-hidden="true" ?hidden=${this.waiting}><slot></slot></span>`;
     }
 };
+__decorate([
+    property({ type: Number })
+], HelixHeadlessLoader.prototype, "delay", void 0);
+__decorate([
+    property()
+], HelixHeadlessLoader.prototype, "for", void 0);
 __decorate([
     property()
 ], HelixHeadlessLoader.prototype, "label", void 0);

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

@@ -43,14 +43,17 @@ declare const HelixHeadlessMap_base: (new (...args: any[]) => import("@fusion.de
  *
  * Add `layers` to `controls` for a layers button. It opens a menu with a tile
  * for each layer, which sets the layer's `hidden` attribute. Layers with the
- * same `group`, such as a route and its dotted legs, share one tile.
+ * same `group`, such as a route and its dotted legs, share one tile. A tile
+ * sends `helix-before-toggle` from the layer first, so you can store the
+ * choice or refuse it.
  *
  * Imagery, a `helix-map-raster` with `ground`, is a map type and not a tile.
  * The menu opens with a card for each type, Standard, Hybrid, and Satellite,
  * with a picture of the map in it, and `map-type` says which is chosen.
  * Standard hides the imagery, Hybrid draws it under the roads and names, and
- * Satellite draws it alone. `connectMap` does not draw a hidden layer, so a layer you write with
- * `hidden` starts turned off.
+ * Satellite draws it alone. Choosing one sends `helix-before-change` with its
+ * name, and `change` once `map-type` holds it. `connectMap` does not draw a
+ * hidden layer, so a layer you write with `hidden` starts turned off.
  *
  * Markers, routes, areas, live positions, and points layers go inside the
  * frame as child elements.
@@ -66,7 +69,10 @@ declare const HelixHeadlessMap_base: (new (...args: any[]) => import("@fusion.de
  * @slot footer - Content below the map, such as a legend or a scale.
  * @slot header - Content above the map, such as a title or a search field.
  *
+ * @event {Event} change - The layers menu changed the map type, which `map-type` now holds.
  * @event {HelixActivateEvent} helix-activate - A marker was pressed. The value is the marker's `name`, or its `label` if it has no name. A cluster sends `helix-map-cluster` instead.
+ * @event {HelixBeforeChangeEvent} helix-before-change - A map type was chosen in the layers menu, with its name: `standard`, `hybrid`, or `satellite`. Cancelable: cancel it to keep the current type.
+ * @event {HelixBeforeToggleEvent} helix-before-toggle - A layer's tile in the layers menu was pressed. Sent from the layer, with `checked` true when it is to be shown. Cancelable: cancel it to keep the layer as it is.
  * @event {HelixMapClusterEvent} helix-map-cluster - A cluster was pressed. Sent from the marker that shows the cluster, with the names of its places.
  * @event {HelixMapPanEvent} helix-map-pan - A pan button or arrow key was pressed. Move your map in response.
  * @event {HelixMapPartChangeEvent} helix-map-part-change - Clustering was turned on or off. Used by `connectMap`; pages do not need to listen for it.
@@ -279,8 +285,17 @@ export declare class HelixHeadlessMap extends HelixHeadlessMap_base {
     private shown;
     /** A map type's name on its card. */
     private nameOf;
-    /** Shows or hides layers, which `connectMap` draws or takes off the map. */
+    /**
+     * Shows or hides layers, which `connectMap` draws or takes off the map.
+     *
+     * **Asked first, from the layer.** The tile wrote `hidden` onto the
+     * consumer's element and said nothing, so a page could neither keep the
+     * choice nor keep its own state in step. The request comes from the first
+     * layer of the tile, which is the element the page wrote.
+     */
     private showLayers;
+    /** Asks for a map type, and sends `change` once it holds. */
+    private chooseMapType;
     /**
      * The layers menu's entries, in the order the layers are written: a layer
      * of its own, or every layer in a group, at the place of the first.