@fusion.dev/helix-headless 0.100.0 → 0.102.0

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

@@ -0,0 +1,142 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/** Which way a press or a key asked the map to go. */
+type Way = 'up' | 'down' | 'start' | 'end';
+/**
+ * @summary A frame around somebody else's map.
+ *
+ * @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.
+ *
+ * **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 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.
+ *
+ * @since 0.100.0
+ * @status stable
+ * @category media
+ * @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.
+ *
+ * @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.
+ *
+ * @csspart controls - The group the pan and zoom buttons sit in.
+ * @csspart fullscreen - The button that fills the screen.
+ * @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 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.
+ */
+export declare class HelixHeadlessMap extends HelixElement {
+    /** What the control that fills the screen is called. */
+    fullscreenLabel: string;
+    /**
+     * How long the reader may be still before the chrome hides, in milliseconds.
+     *
+     * Zero keeps it up, which is the default: a map's controls are how a keyboard
+     * reader operates it, and chrome that hides itself by default would be this
+     * component undoing its own argument. Set it for a display map nobody drives.
+     */
+    idleDelay: number;
+    /**
+     * 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.
+     */
+    label: string;
+    /**
+     * What the controls are called, for a page not in English.
+     */
+    panLabel: string;
+    /**
+     * How far one press moves the map, as a fraction of what is on screen.
+     *
+     * A fraction rather than a distance, because this frame does not know the
+     * scale of what is inside it: a quarter of the viewport is the same gesture at
+     * street level and at country level, and a consumer who wants metres can
+     * multiply by their own.
+     */
+    panStep: number;
+    /** What the zoom controls are called. */
+    zoomInLabel: string;
+    /** What the zoom control that goes the other way is called. */
+    zoomOutLabel: string;
+    /** Whether the reader has been still long enough to hide the chrome. */
+    private resting;
+    /** Whether the frame is filling the screen. */
+    private filled;
+    private readonly fullscreen;
+    private readonly idle;
+    /** Fills the screen with the frame, or comes back. */
+    toggleFullscreen(): void;
+    /** Asks for the map to move, which the consumer answers. */
+    pan(to: Way): void;
+    /** Asks for the map to zoom, `1` in and `-1` out. */
+    zoom(by: number): void;
+    /**
+     * The arrow keys, which are the second way rather than the only one.
+     *
+     * `inlineStep` rather than a test against `ArrowLeft`, so the reader on a
+     * right-to-left page gets `end` from the key that points the way their text
+     * runs, which is what the pan buttons say too.
+     */
+    private readonly handleKeydown;
+    /**
+     * Starts the wait, so a map nobody has touched counts as still.
+     *
+     * Without this the timer only ever starts on a pointer or a focus, and a frame
+     * rendered on a page the reader never reaches stays awake for as long as the
+     * page is open: the chrome a consumer asked to hide would hide only after
+     * being used once, which is the opposite of what an idle delay is for.
+     */
+    protected firstUpdated(changed: PropertyValues): void;
+    protected willUpdate(changed: PropertyValues): void;
+    /**
+     * What one pan button is called, with the way it goes filled in.
+     *
+     * Left and right rather than start and end, because the label is read aloud
+     * and a reader knows which way left is. The event keeps the reading-order
+     * name, which is the one a right-to-left page needs.
+     */
+    private named;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-map': HelixHeadlessMap;
+    }
+}
+export {};

package/dist/map/root/map-root.js

@@ -0,0 +1,161 @@
+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, FullscreenController, HelixElement, HelixMapPanEvent, HelixMapZoomEvent, hostAria, IdleController, inlineStep, } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property, state } from 'lit/decorators.js';
+let HelixHeadlessMap = class HelixHeadlessMap extends HelixElement {
+    constructor() {
+        super(...arguments);
+        this.fullscreenLabel = 'Fill the screen';
+        this.idleDelay = 0;
+        this.label = '';
+        this.panLabel = 'Pan {way}';
+        this.panStep = 0.25;
+        this.zoomInLabel = 'Zoom in';
+        this.zoomOutLabel = 'Zoom out';
+        this.resting = false;
+        this.filled = false;
+        this.fullscreen = new FullscreenController(this, (full) => {
+            this.filled = full;
+        });
+        this.idle = new IdleController(this, () => this.idleDelay, (resting) => {
+            this.resting = resting;
+        });
+        this.handleKeydown = (event) => {
+            const along = inlineStep(this, event.key);
+            if (along === 1) {
+                event.preventDefault();
+                this.pan('end');
+            }
+            else if (along === -1) {
+                event.preventDefault();
+                this.pan('start');
+            }
+            else if (event.key === 'ArrowUp') {
+                event.preventDefault();
+                this.pan('up');
+            }
+            else if (event.key === 'ArrowDown') {
+                event.preventDefault();
+                this.pan('down');
+            }
+            else if (event.key === '+' || event.key === '=') {
+                event.preventDefault();
+                this.zoom(1);
+            }
+            else if (event.key === '-' || event.key === '_') {
+                event.preventDefault();
+                this.zoom(-1);
+            }
+        };
+    }
+    toggleFullscreen() {
+        void this.fullscreen.toggle();
+    }
+    pan(to) {
+        this.dispatchEvent(new HelixMapPanEvent({ by: this.panStep, to }));
+    }
+    zoom(by) {
+        this.dispatchEvent(new HelixMapZoomEvent({ by }));
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.idle.stir();
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        hostAria(this.internals, { label: this.label });
+        this.toggleState('fullscreen', this.filled);
+        this.toggleState('idle', this.resting);
+    }
+    named(way) {
+        const spoken = way === 'start' ? 'left' : way === 'end' ? 'right' : way;
+        return this.panLabel.replace('{way}', spoken);
+    }
+    render() {
+        return html `<div
+      part="region"
+      role="group"
+      aria-label=${this.label || 'Map'}
+      @focusin=${this.idle.stir}
+      @keydown=${this.handleKeydown}
+      @pointerleave=${this.idle.leave}
+      @pointermove=${this.idle.stir}
+    >
+      <slot name="header"></slot>
+      <div part="viewport">
+        <slot></slot>
+      </div>
+      <div part="controls" role="group" aria-label="Map controls">
+        <!-- **Written out rather than generated in a loop**, because a part name
+             behind an interpolation is a part the manifest cannot see: it would
+             publish \`pan-\` and a consumer's \`::part(pan-up)\` would match
+             nothing. The same cost \`drawIcon\` names for \`Trend\`. -->
+        <button part="pan-up" aria-label=${this.named('up')} type="button" @click=${() => this.pan('up')}>
+          ↑
+        </button>
+        <button part="pan-start" aria-label=${this.named('start')} type="button" @click=${() => this.pan('start')}>
+          ←
+        </button>
+        <button part="pan-end" aria-label=${this.named('end')} type="button" @click=${() => this.pan('end')}>
+          →
+        </button>
+        <button part="pan-down" aria-label=${this.named('down')} type="button" @click=${() => this.pan('down')}>
+          ↓
+        </button>
+        <button part="zoom-in" aria-label=${this.zoomInLabel} type="button" @click=${() => this.zoom(1)}>
+          +
+        </button>
+        <button part="zoom-out" aria-label=${this.zoomOutLabel} type="button" @click=${() => this.zoom(-1)}>
+          −
+        </button>
+        <button
+          part="fullscreen"
+          aria-label=${this.fullscreenLabel}
+          aria-pressed=${this.filled ? 'true' : 'false'}
+          type="button"
+          @click=${this.toggleFullscreen}
+        >
+          ⤢
+        </button>
+      </div>
+      <slot name="footer"></slot>
+      <slot name="attribution"></slot>
+    </div>`;
+    }
+};
+__decorate([
+    property({ attribute: 'fullscreen-label' })
+], HelixHeadlessMap.prototype, "fullscreenLabel", void 0);
+__decorate([
+    property({ attribute: 'idle-delay', type: Number })
+], HelixHeadlessMap.prototype, "idleDelay", void 0);
+__decorate([
+    property()
+], HelixHeadlessMap.prototype, "label", void 0);
+__decorate([
+    property({ attribute: 'pan-label' })
+], HelixHeadlessMap.prototype, "panLabel", void 0);
+__decorate([
+    property({ attribute: 'pan-step', type: Number })
+], HelixHeadlessMap.prototype, "panStep", void 0);
+__decorate([
+    property({ attribute: 'zoom-in-label' })
+], HelixHeadlessMap.prototype, "zoomInLabel", void 0);
+__decorate([
+    property({ attribute: 'zoom-out-label' })
+], HelixHeadlessMap.prototype, "zoomOutLabel", void 0);
+__decorate([
+    state()
+], HelixHeadlessMap.prototype, "resting", void 0);
+__decorate([
+    state()
+], HelixHeadlessMap.prototype, "filled", void 0);
+HelixHeadlessMap = __decorate([
+    customElement('helix-headless-map')
+], HelixHeadlessMap);
+export { HelixHeadlessMap };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-headless",
   "description": "Headless component tier. Structure, accessibility, state, and form participation. No styling.",
-  "version": "0.100.0",
+  "version": "0.102.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -46,13 +46,13 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.100.0",
-    "@fusion.dev/helix-icons": "0.100.0",
+    "@fusion.dev/helix-core": "0.102.0",
+    "@fusion.dev/helix-icons": "0.102.0",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.100.0",
-    "@fusion.dev/helix-testing": "0.100.0",
+    "@fusion.dev/helix-cem": "0.102.0",
+    "@fusion.dev/helix-testing": "0.102.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^4.1.0",