@fusion.dev/helix-headless 0.101.0 → 0.103.0

package/types/vue.d.ts

@@ -64,6 +64,7 @@ import type {
   HelixHeadlessList,
   HelixHeadlessListbox,
   HelixHeadlessLoader,
+  HelixHeadlessMap,
   HelixHeadlessMegamenu,
   HelixHeadlessMenuItem,
   HelixHeadlessMenu,
@@ -159,6 +160,8 @@ import type {
   HelixShortcutEvent,
   HelixActivateEvent,
   HelixBeforeActivateEvent,
+  HelixMapPanEvent,
+  HelixMapZoomEvent,
   HelixReadEvent,
   HelixCompleteEvent,
   HelixBeforeCollapseEvent,
@@ -4792,6 +4795,127 @@ export type HelixHeadlessLoaderVueProps = {
 
 export type HelixHeadlessLoaderVueEvents = {};
 
+/** `HelixHeadlessMap` component event */
+export type HelixHeadlessMapElementEvent<E = Event> = TypedEvent<
+  HelixHeadlessMap,
+  E
+>;
+/** `helix-map-pan` event type */
+export type HelixHeadlessMapHelixMapPanElementEvent =
+  HelixHeadlessMapElementEvent<HelixMapPanEvent>;
+/** `helix-map-zoom` event type */
+export type HelixHeadlessMapHelixMapZoomElementEvent =
+  HelixHeadlessMapElementEvent<HelixMapZoomEvent>;
+
+export type HelixHeadlessMapVueProps = {
+  /** 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?: (HelixHeadlessMap["controls"]) | undefined;
+  /** 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. */
+  "controls-placement"?: (HelixHeadlessMap["controlsPlacement"]) | undefined;
+  /** 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?: (HelixHeadlessMap["controlsPlacement"]) | undefined;
+  /** What the control that fills the screen is called. */
+  "fullscreen-label"?: (HelixHeadlessMap["fullscreenLabel"]) | undefined;
+  /** What the control that fills the screen is called. */
+  fullscreenLabel?: (HelixHeadlessMap["fullscreenLabel"]) | undefined;
+  /** 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. */
+  "idle-delay"?: (HelixHeadlessMap["idleDelay"] | `${number}`) | undefined;
+  /** 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?: (HelixHeadlessMap["idleDelay"]) | undefined;
+  /** 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?: (HelixHeadlessMap["label"]) | undefined;
+  /** What the controls are called, for a page not in English. */
+  "pan-label"?: (HelixHeadlessMap["panLabel"]) | undefined;
+  /** What the controls are called, for a page not in English. */
+  panLabel?: (HelixHeadlessMap["panLabel"]) | undefined;
+  /** 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. */
+  "pan-step"?: (HelixHeadlessMap["panStep"] | `${number}`) | undefined;
+  /** 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?: (HelixHeadlessMap["panStep"]) | undefined;
+  /** What the zoom controls are called. */
+  "zoom-in-label"?: (HelixHeadlessMap["zoomInLabel"]) | undefined;
+  /** What the zoom controls are called. */
+  zoomInLabel?: (HelixHeadlessMap["zoomInLabel"]) | undefined;
+  /** What the zoom control that goes the other way is called. */
+  "zoom-out-label"?: (HelixHeadlessMap["zoomOutLabel"]) | undefined;
+  /** What the zoom control that goes the other way is called. */
+  zoomOutLabel?: (HelixHeadlessMap["zoomOutLabel"]) | undefined;
+};
+
+export type HelixHeadlessMapVueEvents = {
+  /** The reader asked the map to move. Answer it against your own map. */
+  "helix-map-pan": HelixHeadlessMapHelixMapPanElementEvent;
+  /** The reader asked the map to zoom, by a direction rather than to a level. */
+  "helix-map-zoom": HelixHeadlessMapHelixMapZoomElementEvent;
+};
+
 /** `HelixHeadlessMegamenu` component event */
 export type HelixHeadlessMegamenuElementEvent<E = Event> = TypedEvent<
   HelixHeadlessMegamenu,
@@ -9830,6 +9954,12 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessLoaderVueProps,
     HelixHeadlessLoaderVueEvents
   >;
+  /** **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. */
+  "helix-headless-map": DefineCustomElement<
+    HelixHeadlessMap,
+    HelixHeadlessMapVueProps,
+    HelixHeadlessMapVueEvents
+  >;
   /** **A disclosure, not a menu, and that is the whole design.** 'role="menu"' and 'menuitem' are for an application's commands: they take over the arrow keys, announce "menu" to a reader who asked for navigation, and put every link inside a role that is not a link. This is a button that shows and hides a region of the consumer's own anchors, which leaves a middle click, a modified click and the status bar working. 'Menu' remains right for a row of commands.  **It renders no links.** A router renders its own anchor and cannot render one inside this shadow root, so the panel is a slot and what goes in it is the lists and headings the consumer wrote.  **It opens on hover, and a press is always the fallback.** 'open-on' says which, and hover is the resting value because a nav bar is where a reader expects to sweep along a row and see each section. */
   "helix-headless-megamenu": DefineCustomElement<
     HelixHeadlessMegamenu,