@fusion.dev/helix-headless 0.104.1 → 0.106.0

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/raster/map-raster.d.ts

@@ -0,0 +1,84 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { nothing, type PropertyValues } from 'lit';
+/**
+ * @summary Map tiles laid over a map, such as weather radar.
+ *
+ * @description
+ * `connectMap` draws the tiles over the map's land and roads, and under its
+ * routes, areas, and place names. Set `ground` to draw them under the roads
+ * as well, for imagery of the ground, such as satellite or aerial photographs.
+ * Set `max-zoom` to the deepest zoom the provider has tiles for, and the map
+ * enlarges those tiles past it. Set `src` to one tile URL with `{z}`, `{x}`,
+ * and `{y}` in it, or set `frames` to several, such as the last hour of radar.
+ * While `playing` is set, the layer shows the frames in order, `interval`
+ * milliseconds each, and starts again from the first.
+ *
+ * The frames do not play while the user has asked for reduced motion, and the
+ * layer shows its last frame. Content that moves for more than five seconds
+ * needs a way to pause it, so give `playing` a control on your page.
+ *
+ * Put the tile provider's credit in `attribution`. The frame shows it beside
+ * the map's own credit.
+ *
+ * @since 0.105.0
+ * @status experimental
+ * @category media
+ * @aliases Weather radar, Tile overlay, Raster layer
+ * @documentation https://fusion.dev/helix/components/map
+ *
+ * @event {HelixMapPartChangeEvent} helix-map-part-change - The tiles, the frame shown, the opacity, or where the tiles are drawn changed. Used by `connectMap`; pages do not need to listen for it.
+ */
+export declare class HelixHeadlessMapRaster extends HelixElement {
+    /** The tile provider's credit, shown in the frame's footer. Links in it stay links. */
+    attribution?: string;
+    /** More about the layer. Read after the label in the frame's list. */
+    description?: string;
+    /** Which of `frames` shows, counting from `0`. Starts at the last frame. */
+    frame?: number;
+    /** Tile URLs to show in order, one per frame, as a list separated by spaces. */
+    frames?: string[];
+    /**
+     * Draws the tiles as the ground, under the map's roads and place names, for
+     * imagery such as satellite photographs.
+     */
+    ground: boolean;
+    /**
+     * A name this layer shares with other layers, such as a route and its
+     * dotted legs. The layers menu shows layers in the same group as one entry,
+     * named by the first of them, and its checkbox shows or hides them all.
+     */
+    group?: string;
+    /** How long each frame shows while `playing`, in milliseconds. */
+    interval: number;
+    /** Marks this as a layer for the frame and the connector, whatever its tag. */
+    readonly isMapLayer = true;
+    /** @internal Which kind of layer, which is how the connector draws it. */
+    readonly layerKind: 'raster';
+    /** The layer's name in the frame's list. */
+    label?: string;
+    /**
+     * The deepest zoom the provider has tiles for. The map enlarges those tiles
+     * at deeper zooms, where it would otherwise ask for tiles that do not exist.
+     */
+    maxZoom?: number;
+    /** How opaque the tiles are, from `0` to `1`. */
+    opacity: number;
+    /** Whether the frames play in order. Has no effect with one frame, or under reduced motion. */
+    playing: boolean;
+    /** One tile URL with `{z}`, `{x}`, and `{y}` in it, for a layer of one frame. */
+    src?: string;
+    /** The timer that moves to the next frame while playing. */
+    private timer;
+    disconnectedCallback(): void;
+    private stopTimer;
+    /** Starts or stops the timer when the frames, the interval, or `playing` change. */
+    private schedule;
+    /** Tells the frame and the connector the layer changed, and keeps the timer in step. */
+    protected updated(changed: PropertyValues): void;
+    protected render(): typeof nothing;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-map-raster': HelixHeadlessMapRaster;
+    }
+}

package/dist/map/raster/map-raster.js

@@ -0,0 +1,96 @@
+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 { nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+const framesConverter = {
+    fromAttribute: (value) => value === null ? undefined : value.split(/\s+/).filter((one) => one !== ''),
+    toAttribute: (value) => value?.join(' ') ?? null,
+};
+let HelixHeadlessMapRaster = class HelixHeadlessMapRaster extends HelixElement {
+    constructor() {
+        super(...arguments);
+        this.ground = false;
+        this.interval = 600;
+        this.isMapLayer = true;
+        this.layerKind = 'raster';
+        this.opacity = 0.7;
+        this.playing = false;
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.stopTimer();
+    }
+    stopTimer() {
+        if (this.timer !== undefined) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+    schedule() {
+        this.stopTimer();
+        const count = this.frames?.length ?? 0;
+        const reduced = globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+        if (!this.playing || count < 2 || reduced) {
+            return;
+        }
+        this.timer = setInterval(() => {
+            const at = this.frame ?? count - 1;
+            this.frame = (at + 1) % count;
+        }, Math.max(100, this.interval));
+    }
+    updated(changed) {
+        super.updated(changed);
+        if (changed.has('playing') || changed.has('frames') || changed.has('interval')) {
+            this.schedule();
+        }
+        this.dispatchEvent(new HelixMapPartChangeEvent({ kind: 'layer' }));
+    }
+    render() {
+        return nothing;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessMapRaster.prototype, "attribution", void 0);
+__decorate([
+    property()
+], HelixHeadlessMapRaster.prototype, "description", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessMapRaster.prototype, "frame", void 0);
+__decorate([
+    property({ converter: framesConverter })
+], HelixHeadlessMapRaster.prototype, "frames", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessMapRaster.prototype, "ground", void 0);
+__decorate([
+    property()
+], HelixHeadlessMapRaster.prototype, "group", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessMapRaster.prototype, "interval", void 0);
+__decorate([
+    property()
+], HelixHeadlessMapRaster.prototype, "label", void 0);
+__decorate([
+    property({ attribute: 'max-zoom', type: Number })
+], HelixHeadlessMapRaster.prototype, "maxZoom", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessMapRaster.prototype, "opacity", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessMapRaster.prototype, "playing", void 0);
+__decorate([
+    property()
+], HelixHeadlessMapRaster.prototype, "src", void 0);
+HelixHeadlessMapRaster = __decorate([
+    customElement('helix-headless-map-raster')
+], HelixHeadlessMapRaster);
+export { HelixHeadlessMapRaster };