@fusion.dev/helix-headless 0.104.0 → 0.105.0

package/dist/map/points/map-points.js

@@ -0,0 +1,158 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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, HelixActivateEvent, HelixElement, HelixMapClusterEvent, HelixMapPartChangeEvent, isRtl, } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { repeat } from 'lit/directives/repeat.js';
+let HelixHeadlessMapPoints = class HelixHeadlessMapPoints extends HelixElement {
+    constructor() {
+        super(...arguments);
+        this.cluster = false;
+        this.countLabel = '{count} places';
+        this.isMapLayer = true;
+        this.layerKind = 'points';
+        this.nameKey = 'name';
+        this.walk = [];
+        this.handleKeydown = (event) => {
+            const key = event.composedPath()[0]?.dataset?.key;
+            const at = this.walk.findIndex((one) => one.key === key);
+            const here = this.walk[at];
+            if (!here) {
+                return;
+            }
+            const forward = isRtl(this) ? 'ArrowLeft' : 'ArrowRight';
+            const back = isRtl(this) ? 'ArrowRight' : 'ArrowLeft';
+            const last = this.walk.length - 1;
+            const to = event.key === forward || event.key === 'ArrowDown'
+                ? Math.min(at + 1, last)
+                : event.key === back || event.key === 'ArrowUp'
+                    ? Math.max(at - 1, 0)
+                    : event.key === 'Home'
+                        ? 0
+                        : event.key === 'End'
+                            ? last
+                            : undefined;
+            if (to !== undefined) {
+                event.preventDefault();
+                this.reach(this.walk[to]);
+                return;
+            }
+            if (event.key === 'Enter' || event.key === ' ') {
+                event.preventDefault();
+                if (event.key === 'Enter' && !event.repeat) {
+                    this.press(here);
+                }
+            }
+        };
+        this.handleKeyup = (event) => {
+            const key = event.composedPath()[0]?.dataset?.key;
+            const here = this.walk.find((one) => one.key === key);
+            if (here && event.key === ' ') {
+                event.preventDefault();
+                this.press(here);
+            }
+        };
+        this.handleFocusin = (event) => {
+            const key = event.composedPath()[0]?.dataset?.key;
+            if (key !== undefined) {
+                this.stop = key;
+            }
+        };
+    }
+    nameOf(one) {
+        if (one.count !== undefined) {
+            const lang = this.closest('[lang]')?.getAttribute('lang') || undefined;
+            return this.countLabel.replace('{count}', new Intl.NumberFormat(lang).format(one.count));
+        }
+        return one.label || one.value || '';
+    }
+    buttonOf(key) {
+        return key === undefined
+            ? null
+            : (this.renderRoot.querySelector(`[data-key="${CSS.escape(key)}"]`) ?? null);
+    }
+    reach(one) {
+        if (!one) {
+            return;
+        }
+        this.stop = one.key;
+        void this.updateComplete.then(() => this.buttonOf(one.key)?.focus());
+    }
+    press(one) {
+        if (one.count !== undefined) {
+            this.dispatchEvent(new HelixMapClusterEvent({ key: one.key, labels: [] }));
+        }
+        else {
+            this.dispatchEvent(new HelixActivateEvent({ value: one.value || one.label || '' }));
+        }
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        if (changed.has('walk')) {
+            const key = this.shadowRoot?.activeElement?.dataset?.key;
+            const was = changed.get('walk') ?? [];
+            this.held = was.find((one) => one.key === key);
+        }
+    }
+    updated(changed) {
+        super.updated(changed);
+        const held = this.held;
+        this.held = undefined;
+        if (held && !this.walk.some((one) => one.key === held.key)) {
+            const nearest = [...this.walk].sort((a, b) => Math.hypot(a.x - held.x, a.y - held.y) - Math.hypot(b.x - held.x, b.y - held.y))[0];
+            this.reach(nearest);
+        }
+        if ([...changed.keys()].some((key) => key !== 'walk' && key !== 'stop')) {
+            this.dispatchEvent(new HelixMapPartChangeEvent({ kind: 'layer' }));
+        }
+    }
+    render() {
+        if (this.walk.length === 0) {
+            return nothing;
+        }
+        const stop = this.walk.some((one) => one.key === this.stop) ? this.stop : this.walk[0]?.key;
+        return html `<span part="places" role="group" aria-label=${this.label ?? ''} @focusin=${this.handleFocusin} @keydown=${this.handleKeydown} @keyup=${this.handleKeyup}>${repeat(this.walk, (one) => one.key, (one) => {
+            const tabindex = one.key === stop ? '0' : '-1';
+            const at = `--_map-place-x: ${one.x}px; --_map-place-y: ${one.y}px`;
+            const name = html `<span part="label">${this.nameOf(one)}</span>`;
+            return one.count === undefined
+                ? html `<span part="place" role="button" data-key=${one.key} tabindex=${tabindex} style=${at}>${name}</span>`
+                : html `<span part="place count" role="button" data-key=${one.key} tabindex=${tabindex} style=${at}>${name}</span>`;
+        })}</span>`;
+    }
+};
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessMapPoints.prototype, "cluster", void 0);
+__decorate([
+    property({ attribute: 'count-label' })
+], HelixHeadlessMapPoints.prototype, "countLabel", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessMapPoints.prototype, "data", void 0);
+__decorate([
+    property()
+], HelixHeadlessMapPoints.prototype, "description", void 0);
+__decorate([
+    property()
+], HelixHeadlessMapPoints.prototype, "label", void 0);
+__decorate([
+    property({ attribute: 'name-key' })
+], HelixHeadlessMapPoints.prototype, "nameKey", void 0);
+__decorate([
+    property()
+], HelixHeadlessMapPoints.prototype, "src", void 0);
+__decorate([
+    state()
+], HelixHeadlessMapPoints.prototype, "walk", void 0);
+__decorate([
+    state()
+], HelixHeadlessMapPoints.prototype, "stop", void 0);
+HelixHeadlessMapPoints = __decorate([
+    customElement('helix-headless-map-points')
+], HelixHeadlessMapPoints);
+export { HelixHeadlessMapPoints };

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

@@ -0,0 +1,70 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary A moving point on a map, such as a vehicle or a person.
+ *
+ * @description
+ * `lat` and `lng` set where it is, `heading` points it in a direction, in
+ * degrees clockwise from north, and `accuracy` draws a ring with a radius of
+ * that many meters. `connectMap` positions it and resizes the ring as the map
+ * zooms.
+ *
+ * Screen readers announce its `description` when it changes, at most once
+ * every `announce-every` milliseconds. Its movement is not announced. Set the
+ * description when something worth hearing happens, such as "Two stops away".
+ *
+ * @since 0.105.0
+ * @status experimental
+ * @category media
+ * @aliases Current location, Live position, Tracker, You are here
+ * @documentation https://fusion.dev/helix/components/map
+ *
+ * @event {HelixMapPartChangeEvent} helix-map-part-change - It moved, turned, or its accuracy changed. Used by `connectMap`; pages do not need to listen for it.
+ *
+ * @csspart accuracy - The ring that shows how accurate the position is.
+ * @csspart arrow - The arrow shown when the position has a heading.
+ * @csspart dot - The point shown when the position has no heading.
+ * @csspart heading - The cone that shows its direction.
+ * @csspart position - The image of the position, named by its label.
+ * @csspart pulse - A ring that spreads out from the point, showing that the position is live.
+ * @csspart status - The description, announced when it changes.
+ */
+export declare class HelixHeadlessMapPosition extends HelixElement {
+    /** How accurate the position is, in meters. Drawn as a ring with this radius. */
+    accuracy?: number;
+    /**
+     * The least time between announcements, in milliseconds. A change during the
+     * wait is announced when the wait ends.
+     */
+    announceEvery: number;
+    /** What screen readers announce when it changes, such as "Two stops away". */
+    description?: string;
+    /** The direction it faces, in degrees clockwise from north. Shows an arrow. */
+    heading?: number;
+    /** Marks this as a position for the connector, whatever its tag. */
+    readonly isMapPosition = true;
+    /** What it is, such as "Van 12". Read by screen readers. */
+    label?: string;
+    /** Latitude, in degrees. */
+    lat?: number;
+    /** Longitude, in degrees. */
+    lng?: number;
+    /** The words last spoken, which is what the status holds. */
+    private spoken;
+    /** When they were spoken, for the interval. */
+    private spokenAt;
+    /** The latest words, waiting out the interval. */
+    private waiting;
+    protected willUpdate(changed: PropertyValues<this>): void;
+    /** Tells the connector it moved, turned or grew less sure: not what it said, which is its own. */
+    protected updated(changed: PropertyValues): void;
+    /** Puts the latest words in the status, which is what makes them heard. */
+    private speak;
+    disconnectedCallback(): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-map-position': HelixHeadlessMapPosition;
+    }
+}

package/dist/map/position/map-position.js

@@ -0,0 +1,89 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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, HelixMapPartChangeEvent } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property, state } from 'lit/decorators.js';
+let HelixHeadlessMapPosition = class HelixHeadlessMapPosition extends HelixElement {
+    constructor() {
+        super(...arguments);
+        this.announceEvery = 5000;
+        this.isMapPosition = true;
+        this.spoken = '';
+        this.spokenAt = Number.NEGATIVE_INFINITY;
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        if (!changed.has('description') || !this.hasUpdated) {
+            if (!this.hasUpdated) {
+                this.spoken = this.description ?? '';
+            }
+            return;
+        }
+        const wait = this.spokenAt + this.announceEvery - Date.now();
+        if (wait <= 0) {
+            this.speak();
+        }
+        else if (this.waiting === undefined) {
+            this.waiting = setTimeout(() => this.speak(), wait);
+        }
+    }
+    updated(changed) {
+        super.updated(changed);
+        if ([...changed.keys()].some((key) => key !== 'spoken' && key !== 'announceEvery')) {
+            this.dispatchEvent(new HelixMapPartChangeEvent({ kind: 'place' }));
+        }
+    }
+    speak() {
+        clearTimeout(this.waiting);
+        this.waiting = undefined;
+        this.spokenAt = Date.now();
+        this.spoken = this.description ?? '';
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        clearTimeout(this.waiting);
+        this.waiting = undefined;
+    }
+    render() {
+        return html `<span part="position" role="img" aria-label=${this.label ?? ''}>
+        <span part="accuracy"></span>
+        <span part="heading"></span>
+        <span part="pulse"></span>
+        <span part="dot"></span>
+        <svg part="arrow" viewBox="0 0 24 24"><path d="M12 2.5 20.5 20.5 12 16.5 3.5 20.5Z"></path></svg>
+      </span>
+      <span part="status" role="status">${this.spoken}</span>`;
+    }
+};
+__decorate([
+    property({ type: Number })
+], HelixHeadlessMapPosition.prototype, "accuracy", void 0);
+__decorate([
+    property({ attribute: 'announce-every', type: Number })
+], HelixHeadlessMapPosition.prototype, "announceEvery", void 0);
+__decorate([
+    property()
+], HelixHeadlessMapPosition.prototype, "description", void 0);
+__decorate([
+    property({ reflect: true, type: Number })
+], HelixHeadlessMapPosition.prototype, "heading", void 0);
+__decorate([
+    property()
+], HelixHeadlessMapPosition.prototype, "label", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessMapPosition.prototype, "lat", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessMapPosition.prototype, "lng", void 0);
+__decorate([
+    state()
+], HelixHeadlessMapPosition.prototype, "spoken", void 0);
+HelixHeadlessMapPosition = __decorate([
+    customElement('helix-headless-map-position')
+], HelixHeadlessMapPosition);
+export { HelixHeadlessMapPosition };

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

@@ -1,5 +1,5 @@
-import { HelixElement, type ViewportControlsPlacement, type ViewportPanDetail, type ViewportZoomDetail } from '@fusion.dev/helix-core';
-import { type PropertyValues, type TemplateResult } from 'lit';
+import { HelixElement, KeyboardNavigationController, type ViewportControlsPlacement, type ViewportPanDetail, type ViewportZoomDetail } from '@fusion.dev/helix-core';
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 /**
  * What `ViewportControlsPlacement` is called for a map.
  *
@@ -9,32 +9,19 @@ import { type PropertyValues, type TemplateResult } from 'lit';
 export type MapControlsPlacement = ViewportControlsPlacement;
 declare const HelixHeadlessMap_base: (new (...args: any[]) => import("@fusion.dev/helix-core").ViewportElement) & typeof HelixElement;
 /**
- * @summary A frame around somebody else's map.
+ * @summary A frame around a map drawn by another library.
  *
  * @description
- * **Helix draws no map.** There are no tiles here, no projection and no
- * network, and there should not be: a tile renderer is a library, and what a
- * design system can add to MapLibre or Leaflet is the frame. The consumer slots
- * their map and this owns the box, the name, the controls and the way out,
- * which is the shape `VideoPlaylist` uses for a player it never renders.
+ * Wraps a map drawn by MapLibre, Leaflet, or another renderer. The frame adds
+ * a name for the map, pan and zoom buttons, a fullscreen button, and a strip
+ * for the map credit. Helix does not draw the map itself.
  *
- * **The accessibility argument is the reason this exists**, and it was measured
- * rather than assumed: a map embedded the ordinary way is a canvas with no role
- * and no name, and it has *no node at all* in the accessibility tree. A reader
- * using a screen reader does not walk past it so much as never meet it. A named
- * region with controls in it is the whole of the difference.
+ * The pan and zoom buttons and the arrow keys send `helix-map-pan` and
+ * `helix-map-zoom`. Move your map in response, or connect it with
+ * `connectMap` from `@fusion.dev/helix-map`, which does this for you.
  *
- * **The controls are buttons, and that is a deliberate choice against arrow
- * keys.** Arrows work here too, but what a screen reader does with them is not
- * ours to decide: macOS passes them through, Windows readers hold them for
- * their own reading mode unless a page takes `role="application"`, which costs
- * the reader their normal way of reading everything else in the frame. A button
- * is findable and operable in every screen reader on every platform without
- * that bargain, so panning and zooming are buttons first and keys second.
- *
- * **Nothing here moves the map.** Both controls ask, through `helix-map-pan`
- * and `helix-map-zoom`, and the consumer answers against whatever they slotted.
- * A frame that moved the map would have to know whose map it was.
+ * Markers, routes, areas, live positions, and points layers go inside the
+ * frame as child elements.
  *
  * @since 0.100.0
  * @status experimental
@@ -42,47 +29,100 @@ declare const HelixHeadlessMap_base: (new (...args: any[]) => import("@fusion.de
  * @aliases Map frame, Map container, Geo
  * @documentation https://fusion.dev/helix/components/map
  *
- * @slot - The map, which is the consumer's own.
- * @slot attribution - Whoever the tiles belong to, which most licenses require you to say.
- * @slot footer - Chrome below the map, such as a legend or a scale.
- * @slot header - Chrome above the map, such as a title or a search field.
+ * @slot - The element your renderer draws the map in, and the map's markers, routes, areas, positions, and points layers.
+ * @slot attribution - The map credit, which most tile licenses require.
+ * @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 {HelixMapPanEvent} helix-map-pan - The reader asked the map to move. Answer it against your own map.
- * @event {HelixMapZoomEvent} helix-map-zoom - The reader asked the map to zoom, by a direction rather than to a level.
+ * @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 {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.
+ * @event {HelixMapZoomEvent} helix-map-zoom - A zoom button or key was pressed, with a direction. Zoom your map in response.
  *
- * @csspart attribution - The strip the credit sits in, under the map.
- * @csspart controls - The group the pan and zoom buttons sit in.
- * @csspart footer - The strip below the map, for what a consumer slots there.
- * @csspart fullscreen - The button that fills the screen.
- * @csspart header - The strip above the map, for what a consumer slots there.
- * @csspart pan-down - The button that moves the map down.
- * @csspart pan-end - The button that moves the map the way the text ends, which is right on an English page.
- * @csspart pan-start - The button that moves the map the way the text starts, which is left on an English page.
- * @csspart pan-up - The button that moves the map up.
- * @csspart region - The named region the map is slotted into.
+ * @csspart attribution - The strip under the map that holds the credit.
+ * @csspart controls - The group of pan and zoom buttons.
+ * @csspart footer - The strip below the map.
+ * @csspart fullscreen - The button that makes the map fill the screen.
+ * @csspart header - The strip above the map.
+ * @csspart layer - One entry in the list of routes, areas, and points layers.
+ * @csspart layers - The list of routes, areas, and points layers, read by screen readers.
+ * @csspart pan-down - The button that pans the map down.
+ * @csspart pan-end - The button that pans toward the end of a line of text: right in English.
+ * @csspart pan-start - The button that pans toward the start of a line of text: left in English.
+ * @csspart pan-up - The button that pans the map up.
+ * @csspart region - The named region the map sits in.
  * @csspart viewport - The box the map is drawn in.
  * @csspart zoom-in - The button that zooms in.
  * @csspart zoom-out - The button that zooms out.
  *
- * @cssstate fullscreen - While the frame fills the screen.
- * @cssstate idle - While the reader has been still long enough to hide the chrome.
+ * @cssstate fullscreen - The map fills the screen.
+ * @cssstate idle - The user has been still long enough for the header and footer to fade.
  */
 export declare class HelixHeadlessMap extends HelixHeadlessMap_base {
     /**
-     * Accessible name for the map, which is the one thing a consumer must write.
-     *
-     * There is no sensible default. "Map" names the widget rather than the place,
-     * and a reader meeting three of them on a page learns nothing from hearing the
-     * same word three times.
-     *
-     * **The region is a tab stop**, so the keys are reachable however the controls
-     * are configured: the listener is on the region, and without a stop of its own
-     * a frame at `controls="none"` around a map with nothing focusable in it had
-     * arrow keys no reader could ever press. `aria-keyshortcuts` says which keys
-     * rather than spelling them into the name, which would otherwise be read out
-     * at every encounter.
+     * Combines markers that would overlap into one count. Counts split apart as
+     * the map zooms in, and pressing one zooms in to its places.
+     */
+    cluster: boolean;
+    /**
+     * The map's name, read by screen readers. Name the place, such as "Delivery
+     * area", so that several maps on one page can be told apart. Required.
      */
     label: string;
+    /**
+     * The name of the list of routes, areas, and points layers, read by screen
+     * readers.
+     */
+    layersLabel: string;
+    /**
+     * The routes and areas among the frame's children, in the order they are
+     * written, which is the order the list names them in.
+     */
+    private get layers();
+    /**
+     * A route or area renamed, or its description changed, which the list says
+     * and a slot change does not report.
+     */
+    private readonly handlePartChange;
+    /**
+     * The markers among the frame's children, in the order they are written,
+     * which is the order the arrow keys walk them in.
+     */
+    private get markers();
+    /**
+     * The marker the map's one tab stop is on, by position among the markers:
+     * the one a reader last reached, and the first before they have reached any.
+     */
+    private stop;
+    protected readonly keys: KeyboardNavigationController;
+    /** The marker a press or a click came from, where it came from one. */
+    private markerOf;
+    /** Moves the tab stop to the marker focus arrived at. */
+    private readonly handleFocusIn;
+    /**
+     * Says a marker was pressed, by click, Enter or Space: a place by its name,
+     * and a cluster as a cluster, from the marker it is drawn as.
+     */
+    private activate;
+    private readonly handleClick;
+    /**
+     * **Enter on the press and Space on the release**, as a native button
+     * takes them, and a key held down says it once: auto-repeat sent a travel
+     * thirty times a second, each restarting the last.
+     */
+    private readonly handleMarkerKeydown;
+    private readonly handleMarkerKeyup;
+    /** A marker added or taken away is a walk of a different length. */
+    private readonly handleSlotChange;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Puts the tab stop on one marker and takes it off the rest, the roving
+     * pattern the toolbar uses: every marker at `-1` is a map whose places the
+     * keyboard cannot reach, and every one at `0` is a Tab press per place.
+     */
+    protected updated(changed: PropertyValues): void;
     /** The events this family names, the surface naming none of its own. */
     protected panEvent(detail: ViewportPanDetail): Event;
     protected zoomEvent(detail: ViewportZoomDetail): Event;
@@ -95,6 +135,21 @@ export declare class HelixHeadlessMap extends HelixHeadlessMap_base {
      */
     protected get restingControlsLabel(): string;
     protected willUpdate(changed: PropertyValues): void;
+    /**
+     * The routes and areas, named, for a reader who cannot see the map.
+     *
+     * **What the renderer draws is a picture to a screen reader**, so a route
+     * from the depot or a delivery zone is not on the page at all until this
+     * says it is. A list rather than a live region, because the reader should
+     * find it when they come to the map rather than be told about it as it
+     * changes. Nothing where there are none, so a map with only markers says
+     * no more than it did.
+     *
+     * **Written once the frame knows its children**, which is in the browser:
+     * the server renders the frame before it has any, and a route is only on
+     * the page once a renderer has drawn it, which is later still.
+     */
+    protected renderLayers(): TemplateResult | typeof nothing;
     /**
      * The frame, with each region in a box of its own.
      *