@fusion.dev/helix-headless 0.101.0 → 0.103.0

package/types/jsx.d.ts

@@ -81,6 +81,7 @@ import type {
   HelixHeadlessListItem,
   HelixHeadlessListbox,
   HelixHeadlessLoader,
+  HelixHeadlessMap,
   HelixHeadlessMegamenu,
   HelixHeadlessMenu,
   HelixHeadlessMenuItem,
@@ -150,6 +151,8 @@ import type {
   HelixHeadlessVideoPlaylistMenu,
   HelixHeadlessVirtualList,
   HelixHistoryEvent,
+  HelixMapPanEvent,
+  HelixMapZoomEvent,
   HelixNavigateEvent,
   HelixNextEvent,
   HelixPreviousEvent,
@@ -9380,6 +9383,236 @@ export type HelixHeadlessLoaderSolidJsProps = {
   textContent?: (string | number) | undefined;
 };
 
+/** `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 HelixHeadlessMapProps = {
+  /** 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;
+
+  /** The reader asked the map to move. Answer it against your own map. */
+  "onhelix-map-pan"?: ((e: HelixHeadlessMapHelixMapPanElementEvent) => void) | undefined;
+  /** The reader asked the map to zoom, by a direction rather than to a level. */
+  "onhelix-map-zoom"?: ((e: HelixHeadlessMapHelixMapZoomElementEvent) => void) | undefined;
+};
+
+export type HelixHeadlessMapSolidJsProps = {
+  /** 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. */
+  "prop: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. */
+  "attr: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. */
+  "prop:controlsPlacement"?: (HelixHeadlessMap["controlsPlacement"]) | undefined;
+  /** What the control that fills the screen is called. */
+  "attr:fullscreen-label"?: (HelixHeadlessMap["fullscreenLabel"]) | undefined;
+  /** What the control that fills the screen is called. */
+  "prop: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. */
+  "attr: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. */
+  "prop: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. */
+  "prop:label"?: (HelixHeadlessMap["label"]) | undefined;
+  /** What the controls are called, for a page not in English. */
+  "attr:pan-label"?: (HelixHeadlessMap["panLabel"]) | undefined;
+  /** What the controls are called, for a page not in English. */
+  "prop: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. */
+  "attr: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. */
+  "prop:panStep"?: (HelixHeadlessMap["panStep"]) | undefined;
+  /** What the zoom controls are called. */
+  "attr:zoom-in-label"?: (HelixHeadlessMap["zoomInLabel"]) | undefined;
+  /** What the zoom controls are called. */
+  "prop:zoomInLabel"?: (HelixHeadlessMap["zoomInLabel"]) | undefined;
+  /** What the zoom control that goes the other way is called. */
+  "attr:zoom-out-label"?: (HelixHeadlessMap["zoomOutLabel"]) | undefined;
+  /** What the zoom control that goes the other way is called. */
+  "prop:zoomOutLabel"?: (HelixHeadlessMap["zoomOutLabel"]) | undefined;
+  /** The reader asked the map to move. Answer it against your own map. */
+  "on:helix-map-pan"?: ((e: HelixHeadlessMapHelixMapPanElementEvent) => void) | undefined;
+  /** The reader asked the map to zoom, by a direction rather than to a level. */
+  "on:helix-map-zoom"?: ((e: HelixHeadlessMapHelixMapZoomElementEvent) => void) | undefined;
+
+  /** Set the innerHTML of the element */
+  innerHTML?: (string) | undefined;
+  /** Set the textContent of the element */
+  textContent?: (string | number) | undefined;
+};
+
 /** `HelixHeadlessMegamenu` component event */
 export type HelixHeadlessMegamenuElementEvent<E = Event> = TypedEvent<
   HelixHeadlessMegamenu,
@@ -27354,6 +27587,161 @@ export type CustomElements = {
     HelixHeadlessLoaderProps & BaseProps<HelixHeadlessLoader> & BaseEvents<HelixHeadlessLoader>
   >;
 
+  /**
+   * **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.
+   *
+   * ## Attributes & Properties
+   *
+   * Component attributes and properties that can be applied to the element or by using JavaScript.
+   *
+   * - `controls`: 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-placement`/`controlsPlacement`: 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.
+   * - `fullscreen-label`/`fullscreenLabel`: What the control that fills the screen is called.
+   * - `idle-delay`/`idleDelay`: 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.
+   * - `label`: 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.
+   * - `pan-label`/`panLabel`: What the controls are called, for a page not in English.
+   * - `pan-step`/`panStep`: 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.
+   * - `zoom-in-label`/`zoomInLabel`: What the zoom controls are called.
+   * - `zoom-out-label`/`zoomOutLabel`: What the zoom control that goes the other way is called.
+   * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
+   *
+   * **Named `whenSettled` because `settled` is taken four times over**, by
+   * Image, Splitter and both color controls, none of them about transitions. A
+   * base class takes the name every subclass then cannot use.
+   *
+   * **The state it reports cannot be watched, which is why this exists.** A
+   * custom state is deliberately not in the DOM, so there is no
+   * `MutationObserver` equivalent for `ElementInternals.states`. Await this
+   * instead.
+   *
+   * Separate from `updateComplete`, which resolves in the microtask checkpoint
+   * the suppression is still active in. That is the distinction `readyToMove`
+   * in `@fusion.dev/helix-testing` is written around.
+   *
+   * It never resolves where `requestAnimationFrame` never fires, which is a
+   * server, a hidden tab, and happy-dom. Callers that must not hang there race
+   * it against a timeout, as the happy-dom harness's `readyToMove` does. The
+   * browser harness's awaits it alone: a browser always runs the frame, and a
+   * timer beside it was a bet on how long one takes, which a busy run lost. (property only) (readonly)
+   *
+   * ## Events
+   *
+   * Events that will be emitted by the component.
+   *
+   * - `helix-map-pan`: The reader asked the map to move. Answer it against your own map.
+   * - `helix-map-zoom`: The reader asked the map to zoom, by a direction rather than to a level.
+   *
+   * ## Slots
+   *
+   * Areas where markup can be added to the component.
+   *
+   * - `(default)`: The map, which is the consumer's own.
+   * - `attribution`: Whoever the tiles belong to, which most licenses require you to say.
+   * - `footer`: Chrome below the map, such as a legend or a scale.
+   * - `header`: Chrome above the map, such as a title or a search field.
+   *
+   * ## Methods
+   *
+   * Methods that can be called to access component functionality.
+   *
+   * - `toggleFullscreen() => void`: Fills the screen with the frame, or comes back.
+   * - `pan(to: Way) => void`: Asks for the map to move, which the consumer answers.
+   * - `zoom(by: number) => void`: Asks for the map to zoom, `1` in and `-1` out.
+   *
+   * ## CSS Parts
+   *
+   * Custom selectors for styling elements within the component.
+   *
+   * - `controls`: The group the pan and zoom buttons sit in.
+   * - `fullscreen`: The button that fills the screen.
+   * - `pan-down`: The button that moves the map down.
+   * - `pan-end`: The button that moves the map the way the text ends, which is right on an English page.
+   * - `pan-start`: The button that moves the map the way the text starts, which is left on an English page.
+   * - `pan-up`: The button that moves the map up.
+   * - `region`: The named region the map is slotted into.
+   * - `viewport`: The box the map is drawn in.
+   * - `zoom-in`: The button that zooms in.
+   * - `zoom-out`: The button that zooms out.
+   *
+   * ## CSS States
+   *
+   * These can be used to apply styling when a component is in a given state.
+   *
+   * - `fullscreen`: While the frame fills the screen.
+   * - `idle`: While the reader has been still long enough to hide the chrome.
+   * - `settled`: Set a frame after the first render. Transitions are held off until it is, so an element never animates its own arrival.
+   */
+  "helix-headless-map": Partial<
+    HelixHeadlessMapProps & BaseProps<HelixHeadlessMap> & BaseEvents<HelixHeadlessMap>
+  >;
+
   /**
    * **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,
@@ -45701,6 +46089,164 @@ export type CustomElementsSolidJs = {
       BaseEvents<HelixHeadlessLoader>
   >;
 
+  /**
+   * **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.
+   *
+   * ## Attributes & Properties
+   *
+   * Component attributes and properties that can be applied to the element or by using JavaScript.
+   *
+   * - `controls`: 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-placement`/`controlsPlacement`: 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.
+   * - `fullscreen-label`/`fullscreenLabel`: What the control that fills the screen is called.
+   * - `idle-delay`/`idleDelay`: 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.
+   * - `label`: 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.
+   * - `pan-label`/`panLabel`: What the controls are called, for a page not in English.
+   * - `pan-step`/`panStep`: 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.
+   * - `zoom-in-label`/`zoomInLabel`: What the zoom controls are called.
+   * - `zoom-out-label`/`zoomOutLabel`: What the zoom control that goes the other way is called.
+   * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
+   *
+   * **Named `whenSettled` because `settled` is taken four times over**, by
+   * Image, Splitter and both color controls, none of them about transitions. A
+   * base class takes the name every subclass then cannot use.
+   *
+   * **The state it reports cannot be watched, which is why this exists.** A
+   * custom state is deliberately not in the DOM, so there is no
+   * `MutationObserver` equivalent for `ElementInternals.states`. Await this
+   * instead.
+   *
+   * Separate from `updateComplete`, which resolves in the microtask checkpoint
+   * the suppression is still active in. That is the distinction `readyToMove`
+   * in `@fusion.dev/helix-testing` is written around.
+   *
+   * It never resolves where `requestAnimationFrame` never fires, which is a
+   * server, a hidden tab, and happy-dom. Callers that must not hang there race
+   * it against a timeout, as the happy-dom harness's `readyToMove` does. The
+   * browser harness's awaits it alone: a browser always runs the frame, and a
+   * timer beside it was a bet on how long one takes, which a busy run lost. (property only) (readonly)
+   *
+   * ## Events
+   *
+   * Events that will be emitted by the component.
+   *
+   * - `helix-map-pan`: The reader asked the map to move. Answer it against your own map.
+   * - `helix-map-zoom`: The reader asked the map to zoom, by a direction rather than to a level.
+   *
+   * ## Slots
+   *
+   * Areas where markup can be added to the component.
+   *
+   * - `(default)`: The map, which is the consumer's own.
+   * - `attribution`: Whoever the tiles belong to, which most licenses require you to say.
+   * - `footer`: Chrome below the map, such as a legend or a scale.
+   * - `header`: Chrome above the map, such as a title or a search field.
+   *
+   * ## Methods
+   *
+   * Methods that can be called to access component functionality.
+   *
+   * - `toggleFullscreen() => void`: Fills the screen with the frame, or comes back.
+   * - `pan(to: Way) => void`: Asks for the map to move, which the consumer answers.
+   * - `zoom(by: number) => void`: Asks for the map to zoom, `1` in and `-1` out.
+   *
+   * ## CSS Parts
+   *
+   * Custom selectors for styling elements within the component.
+   *
+   * - `controls`: The group the pan and zoom buttons sit in.
+   * - `fullscreen`: The button that fills the screen.
+   * - `pan-down`: The button that moves the map down.
+   * - `pan-end`: The button that moves the map the way the text ends, which is right on an English page.
+   * - `pan-start`: The button that moves the map the way the text starts, which is left on an English page.
+   * - `pan-up`: The button that moves the map up.
+   * - `region`: The named region the map is slotted into.
+   * - `viewport`: The box the map is drawn in.
+   * - `zoom-in`: The button that zooms in.
+   * - `zoom-out`: The button that zooms out.
+   *
+   * ## CSS States
+   *
+   * These can be used to apply styling when a component is in a given state.
+   *
+   * - `fullscreen`: While the frame fills the screen.
+   * - `idle`: While the reader has been still long enough to hide the chrome.
+   * - `settled`: Set a frame after the first render. Transitions are held off until it is, so an element never animates its own arrival.
+   */
+  "helix-headless-map": Partial<
+    HelixHeadlessMapProps &
+      HelixHeadlessMapSolidJsProps &
+      BaseProps<HelixHeadlessMap> &
+      BaseEvents<HelixHeadlessMap>
+  >;
+
   /**
    * **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,

package/types/svelte.d.ts

@@ -69,6 +69,7 @@ declare module 'svelte/elements' {
     'helix-headless-list': CustomElements['helix-headless-list']
     'helix-headless-listbox': CustomElements['helix-headless-listbox']
     'helix-headless-loader': CustomElements['helix-headless-loader']
+    'helix-headless-map': CustomElements['helix-headless-map']
     'helix-headless-megamenu': CustomElements['helix-headless-megamenu']
     'helix-headless-menu-item': CustomElements['helix-headless-menu-item']
     'helix-headless-menu': CustomElements['helix-headless-menu']