@fusion.dev/helix-headless 0.104.1 → 0.106.0

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.
  *
@@ -7,34 +7,53 @@ import { 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 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, a column of controls, 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 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.
  *
- * **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.
+ * 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.
  *
- * **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.
+ * 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.
  *
  * @since 0.100.0
  * @status experimental
@@ -42,47 +61,230 @@ 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 {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 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 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 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.
  *
- * @cssstate fullscreen - While the frame fills the screen.
- * @cssstate idle - While the reader has been still long enough to hide the chrome.
+ * @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 {
     /**
-     * Accessible name for the map, which is the one thing a consumer must write.
+     * 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 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.
+     */
+    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;
+    /** 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.
      *
-     * 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.
+     * **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.
      *
-     * **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.
+     * **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.
      */
-    label: string;
+    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;
@@ -95,6 +297,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.
      *