@fusion.dev/helix-headless 0.105.0 → 0.106.0

package/dist/map/marker/map-marker.js

@@ -7,12 +7,20 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, HelixMapPartChangeEvent } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
-const BOOKKEEPING = new Set(['current', 'fanned', 'gathered', 'gatheredBy', 'side']);
+const BOOKKEEPING = new Set([
+    'behind',
+    'current',
+    'fanned',
+    'gathered',
+    'gatheredBy',
+    'side',
+]);
 let HelixHeadlessMapMarker = class HelixHeadlessMapMarker extends HelixElement {
     constructor() {
         super(...arguments);
         this.current = false;
         this.gathered = [];
+        this.behind = false;
         this.fanned = false;
         this.gatheredBy = undefined;
         this.isMapMarker = true;
@@ -23,6 +31,7 @@ let HelixHeadlessMapMarker = class HelixHeadlessMapMarker extends HelixElement {
     }
     willUpdate(changed) {
         super.willUpdate(changed);
+        this.toggleState('behind', this.behind);
         this.toggleState('cluster', this.gathered.length > 1);
         this.toggleState('clustered', this.gatheredBy !== undefined);
         this.toggleState('current', this.current);
@@ -64,6 +73,9 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessMapMarker.prototype, "gathered", void 0);
+__decorate([
+    state()
+], HelixHeadlessMapMarker.prototype, "behind", void 0);
 __decorate([
     state()
 ], HelixHeadlessMapMarker.prototype, "fanned", void 0);

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

@@ -1,6 +1,6 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { nothing, type PropertyValues, type TemplateResult } from 'lit';
-/** A place in a points layer, where it is written as a list rather than GeoJSON. */
+/** A place in a points layer, written as an object with coordinates and an optional name. */
 export interface MapPointsPlace {
     /** What pressing it reports, where it is not its label. */
     id?: string | number | undefined;
@@ -88,6 +88,12 @@ export declare class HelixHeadlessMapPoints extends HelixElement {
      * the frame's list.
      */
     description?: string;
+    /**
+     * 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;
     /** Marks this as a layer for the frame and the connector, whatever its tag. */
     readonly isMapLayer = true;
     /** The layer's name, used in the frame's list. */

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

@@ -137,6 +137,9 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessMapPoints.prototype, "description", void 0);
+__decorate([
+    property()
+], HelixHeadlessMapPoints.prototype, "group", void 0);
 __decorate([
     property()
 ], HelixHeadlessMapPoints.prototype, "label", void 0);

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 };

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

@@ -7,19 +7,51 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * imported this before the surface was shared still has it.
  */
 export type MapControlsPlacement = ViewportControlsPlacement;
+/** How the map draws the ground: the themed map, imagery under its roads and names, or imagery alone. */
+export type MapType = 'hybrid' | 'satellite' | 'standard';
 declare const HelixHeadlessMap_base: (new (...args: any[]) => import("@fusion.dev/helix-core").ViewportElement) & typeof HelixElement;
 /**
  * @summary A frame around a map drawn by another library.
  *
  * @description
  * 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.
+ * a name for the map, a column of controls, and a strip for the map credit.
+ * Helix does not draw the map itself.
+ *
+ * The controls are one column, and `controls` names which ones: `fullscreen`,
+ * `layers`, `tilt`, `zoom`, and `compass`, top to bottom. `zoom compass
+ * fullscreen` by default. The compass's needle points north as the map turns,
+ * and pressing it turns the map to face north.
+ *
+ * Add `pan` and `rotate` for buttons around the compass that move and turn the
+ * map. Dragging is otherwise the only way a pointer moves the map, so add them
+ * where the map has to be usable without dragging, as WCAG 2.2 asks at level
+ * AA. The arrow keys pan the map and Shift with Left or Right turns it either
+ * way.
  *
  * 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.
  *
+ * Add `tilt` to `controls` for the 3D button, which a map with 3D buildings
+ * or terrain needs. It is a toggle. Pressed, it tilts the map 50 degrees, and
+ * `connectMap` raises the buildings and the ground. Pressed again, it makes the
+ * map flat, and lays them flat too. Shift with Up or Down tilts the map in
+ * steps. Turning and tilting send `helix-map-rotate` and `helix-map-tilt`,
+ * which `connectMap` answers on MapLibre. Leaflet draws maps flat and does not
+ * rotate.
+ *
+ * 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.
+ *
+ * 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.
+ *
  * Markers, routes, areas, live positions, and points layers go inside the
  * frame as child elements.
  *
@@ -38,48 +70,130 @@ declare const HelixHeadlessMap_base: (new (...args: any[]) => import("@fusion.de
  * @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 {HelixMapRotateEvent} helix-map-rotate - A rotate or Face north button, or Shift with Left or Right, was pressed. Turn your map in response.
+ * @event {HelixMapTiltEvent} helix-map-tilt - The 3D button, or Shift with Up or Down, was pressed. Tilt your map in response.
  * @event {HelixMapZoomEvent} helix-map-zoom - A zoom button or key was pressed, with a direction. Zoom your map in response.
  *
  * @csspart attribution - The strip under the map that holds the credit.
- * @csspart controls - The group of pan and zoom buttons.
+ * @csspart compass - The compass and the pan and rotate buttons around it.
+ * @csspart controls - The column of buttons that move the map.
+ * @csspart face-north - The compass: its needle points north as the map turns, and pressing it turns the map to face north.
  * @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 layer - One entry in the list of the map's layers.
+ * @csspart layer-choice - One layer's tile in the layers menu, pressed while the layer is shown.
+ * @csspart layer-choices - The layer tiles in the layers menu, under the map types.
+ * @csspart layer-icon - The picture on a layer's tile, drawn for its kind: a line for a route, a peak for terrain.
+ * @csspart layer-name - The name on a layer's tile.
+ * @csspart layers - The list of the map's shown layers, such as routes, areas, and points, read by screen readers.
+ * @csspart layers-menu - The menu of the map's layers, which the layers button opens.
+ * @csspart layers-toggle - The button that opens and closes the layers menu.
+ * @csspart map-type - One map type's card in the layers menu: a radio button, its picture, and its name.
+ * @csspart map-type-name - The name on a map type's card.
+ * @csspart map-type-preview - The picture of the map on a map type's card.
+ * @csspart map-types - The map-type cards at the top of the layers menu, where the map has imagery.
+ * @csspart needle - The compass needle, turned to point north.
  * @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 rotate-left - The button that turns the map counterclockwise.
+ * @csspart rotate-right - The button that turns the map clockwise.
+ * @csspart tilt - The 3D button, which tilts the map and makes it flat again. Pressed while the map is tilted.
  * @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.
  *
+ * @cssproperty --map-needle-turn - How far the needle turns to point north, as an angle. The frame writes it from `bearing`.
+ *
  * @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 {
+    /**
+     * The map's rotation, in degrees clockwise from north. `connectMap` keeps it
+     * current, and the Face north button's needle turns with it.
+     */
+    bearing: number;
     /**
      * 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 Face north button's label. */
+    faceNorthLabel: string;
+    /** The Hybrid map type's name. */
+    hybridLabel: string;
     /**
      * 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.
+     * The name of the layers button and menu, and of the list of the map's
+     * layers, such as routes, areas, and points, read by screen readers.
      */
     layersLabel: string;
+    /**
+     * @internal Pictures of the map in each map type, written by the connector
+     * when the layers menu opens.
+     */
+    mapPreviews: Partial<Record<MapType, string>>;
+    /**
+     * How the map draws the ground, where it has imagery: `hybrid` for imagery
+     * under the roads and names, and `satellite` for imagery alone. Absent is
+     * the standard, themed map. The layers menu chooses it.
+     */
+    mapType?: 'hybrid' | 'satellite' | undefined;
+    /** The name of the map types in the layers menu, read by screen readers. */
+    mapTypeLabel: string;
+    /**
+     * How far the map is tilted, in degrees from looking straight down.
+     * `connectMap` keeps it current, and the 3D button is pressed while it is
+     * above `0`.
+     */
+    pitch: number;
+    /** The rotate left button's label. */
+    rotateLeftLabel: string;
+    /** The rotate right button's label. */
+    rotateRightLabel: string;
+    /** The Satellite map type's name. */
+    satelliteLabel: string;
+    /** The Standard map type's name. */
+    standardLabel: string;
+    /** The 3D button's label. */
+    tiltLabel: 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();
+    /** Whether the layers menu is open. */
+    private layersOpen;
+    private hiding?;
+    /** Closes the layers menu on a press anywhere outside the frame. */
+    private readonly handleOutside;
+    /**
+     * Keys pressed in the layers menu. Escape closes it and returns to its
+     * button, and no key reaches the region, where the arrows would pan the map.
+     */
+    private readonly handleMenuKeydown;
+    /**
+     * The imagery among the layers: raster layers drawn as the ground, which the
+     * map types show and hide rather than a tile of their own.
+     */
+    private get imagery();
+    /** A map type's name on its card. */
+    private nameOf;
+    /** Shows or hides layers, which `connectMap` draws or takes off the map. */
+    private showLayers;
+    /**
+     * 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.
+     */
+    private get layerEntries();
     /**
      * A route or area renamed, or its description changed, which the list says
      * and a slot change does not report.
@@ -123,6 +237,54 @@ export declare class HelixHeadlessMap extends HelixHeadlessMap_base {
      * keyboard cannot reach, and every one at `0` is a Tab press per place.
      */
     protected updated(changed: PropertyValues): void;
+    /** Turns the map by some degrees, clockwise where positive. */
+    rotate(by: number): void;
+    /** Turns the map to face north. */
+    faceNorth(): void;
+    /** Tilts the map by some degrees, toward the horizon where positive. */
+    tilt(by: number): void;
+    /** Tilts the map to some degrees from looking straight down. `0` makes it flat. */
+    tiltTo(to: number): void;
+    /**
+     * The layers button and its menu: a tile for each layer or group, in the
+     * order they are written, with its picture and name, pressed while it is
+     * shown. A group's tile is pressed while any of its layers is shown.
+     */
+    private renderLayersMenu;
+    /**
+     * The map types, as cards with a picture of the map in each: Standard,
+     * Hybrid, and Satellite. One is chosen, so they are radio buttons, and the
+     * arrow keys move between them as a group of radios does.
+     */
+    private renderMapTypes;
+    /**
+     * The compass, and the pan and rotate buttons around it where `controls`
+     * names them.
+     *
+     * **One control for which way the map faces and where it goes.** The needle
+     * turns with the map and points north; pressing it turns the map back. The
+     * arrows around it are the way to move and turn the map without dragging,
+     * which a pointer otherwise needs.
+     */
+    private renderCompass;
+    /**
+     * The controls, in one column in the order they are read: fullscreen, the
+     * layers, 3D, zoom, and the compass with the arrows round it, last, where
+     * the room its arrows take is below the column and not inside it.
+     *
+     * **Drawn here, not by the surface**, which lays its pad out for a board:
+     * a map's arrows belong round its compass, and the reading order is the
+     * column's, top to bottom.
+     */
+    protected renderControls(): TemplateResult | typeof nothing;
+    /** The controls the map draws while `controls` is absent. */
+    protected get restingControls(): string;
+    /** Whether the compass is drawn: named, or asked for by the arrows round it. */
+    private get drawsCompass();
+    /** The keys the region answers, which the compass and `tilt` add to. */
+    private get keyShortcuts();
+    /** Shift with the arrow keys: left and right rotate, and up and down tilt in steps. */
+    protected handleMoreKeys(event: KeyboardEvent): boolean;
     /** The events this family names, the surface naming none of its own. */
     protected panEvent(detail: ViewportPanDetail): Event;
     protected zoomEvent(detail: ViewportZoomDetail): Event;