@fusion.dev/helix-headless 0.101.0 → 0.103.0

package/dist/element-events.generated.js

@@ -85,6 +85,7 @@ registerElementEvents({
         'toggle',
     ],
     'helix-headless-listbox': ['change', 'helix-before-change', 'helix-filter', 'input'],
+    'helix-headless-map': ['helix-map-pan', 'helix-map-zoom'],
     'helix-headless-megamenu': ['helix-before-close', 'helix-before-open', 'toggle'],
     'helix-headless-menu': ['helix-before-close', 'helix-before-open', 'helix-select', 'toggle'],
     'helix-headless-menu-item': ['helix-select'],

package/dist/index.d.ts

@@ -58,6 +58,7 @@ export * from './line-chart/index.js';
 export * from './list/index.js';
 export * from './listbox/index.js';
 export * from './loader/index.js';
+export * from './map/index.js';
 export * from './megamenu/index.js';
 export * from './menu/index.js';
 export * from './meter/index.js';

package/dist/index.js

@@ -49,6 +49,7 @@ export * from './line-chart/index.js';
 export * from './list/index.js';
 export * from './listbox/index.js';
 export * from './loader/index.js';
+export * from './map/index.js';
 export * from './megamenu/index.js';
 export * from './menu/index.js';
 export * from './meter/index.js';

package/dist/map/index.d.ts

@@ -0,0 +1 @@
+export { HelixHeadlessMap } from './root/map-root.js';

package/dist/map/index.js

@@ -0,0 +1 @@
+export { HelixHeadlessMap } from './root/map-root.js';

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

@@ -0,0 +1,195 @@
+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';
+/** Where the controls sit, in the corner words the rest of the library uses. */
+export type MapControlsPlacement = 'top-start' | 'top-end' | 'bottom-start' | 'bottom-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 {
+    /**
+     * Which of the controls this frame draws, as a list of what to keep.
+     *
+     * **A list rather than a switch, because the overlap is not symmetric.**
+     * Every map library draws zoom controls and none of them draws pan buttons:
+     * MapLibre's navigation control is zoom and a compass, Leaflet's is zoom,
+     * Google's is zoom. So a consumer slotting one of those has our zoom twice
+     * over and our pan pad not at all, and a single switch would make them choose
+     * between a duplicate and nothing.
+     *
+     * `none` draws none of them, which is the right answer where the slotted map
+     * already has controls a reader can find: what this family argues for is that
+     * *a* findable control exists, never that it is ours. The methods stay public
+     * either way, so a consumer drawing their own chrome can still drive the
+     * frame.
+     *
+     * Absent is all three, which is this library's rule that a resting value is an
+     * attribute's absence, and it is what the stylesheet asks about: the layout
+     * rules are written against `[controls]:not([controls~="zoom"])` rather than
+     * the bare negation, or a frame that named no list at all would be laid out as
+     * though it had dropped everything.
+     */
+    controls?: string;
+    /**
+     * Which corner the controls sit in.
+     *
+     * **Configurable because there is no safe default**, and this is a collision
+     * rather than a taste: MapLibre puts its own controls at the top end, Leaflet
+     * and OpenLayers at the top start, Google's zoom at the bottom end. Whichever
+     * corner this took would land on somebody's, which is why every one of those
+     * libraries made it a setting too.
+     *
+     * Logical corners rather than left and right, so a right-to-left page moves
+     * them without a consumer writing a second rule.
+     *
+     * Absent is the top end, which is this library's rule that a resting value is
+     * an attribute's absence: a default that reflected would write an attribute
+     * onto every host that no server sent and nobody asked for.
+     */
+    controlsPlacement?: MapControlsPlacement;
+    /** 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;
+    /** Whether a named group of controls is one this frame draws. */
+    private draws;
+    /** 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;
+    /**
+     * The controls, or nothing where a consumer kept none of them.
+     *
+     * **Written out rather than generated**, 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`.
+     */
+    private renderControls;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-map': HelixHeadlessMap;
+    }
+}
+export {};

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

@@ -0,0 +1,181 @@
+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, nothing } 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);
+            }
+        };
+    }
+    draws(group) {
+        return this.controls === undefined ? true : this.controls.split(/\s+/).includes(group);
+    }
+    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);
+    }
+    renderControls() {
+        const pan = this.draws('pan');
+        const zoom = this.draws('zoom');
+        const fullscreen = this.draws('fullscreen');
+        if (!pan && !zoom && !fullscreen) {
+            return nothing;
+        }
+        return html `<div part="controls" role="group" aria-label="Map controls">
+      ${pan
+            ? html `<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>`
+            : nothing}
+      ${zoom
+            ? html `<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>`
+            : nothing}
+      ${fullscreen
+            ? html `<button
+              part="fullscreen"
+              aria-label=${this.fullscreenLabel}
+              aria-pressed=${this.filled ? 'true' : 'false'}
+              type="button"
+              @click=${this.toggleFullscreen}
+            >
+              ⤢
+            </button>`
+            : nothing}
+    </div>`;
+    }
+    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>
+      ${this.renderControls()}
+      <slot name="footer"></slot>
+      <slot name="attribution"></slot>
+    </div>`;
+    }
+};
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessMap.prototype, "controls", void 0);
+__decorate([
+    property({ attribute: 'controls-placement', reflect: true })
+], HelixHeadlessMap.prototype, "controlsPlacement", void 0);
+__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.101.0",
+  "version": "0.103.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.101.0",
-    "@fusion.dev/helix-icons": "0.101.0",
+    "@fusion.dev/helix-core": "0.103.0",
+    "@fusion.dev/helix-icons": "0.103.0",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.101.0",
-    "@fusion.dev/helix-testing": "0.101.0",
+    "@fusion.dev/helix-cem": "0.103.0",
+    "@fusion.dev/helix-testing": "0.103.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^4.1.0",