@fusion.dev/helix-headless 0.113.0 → 0.115.0

package/custom-elements.json

@@ -62448,9 +62448,28 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`connectMap` fills the shape as a layer of the map, under its place names.\nThe frame lists each area by its `label` and `description` for screen\nreaders.",
+          "description": "`connectMap` fills the shape as a layer of the map, under its place names.\nThe frame lists each area by its `label` and `description` for screen\nreaders.\n\nSet `caption` to draw words on the map with the area, such as a letter for a\nsearch sector, in a color that reads on the map. It is drawn rather than\nfocusable, so it adds nothing to the tab order, and a screen reader reads\nthe area's `label` in the frame's list.",
           "name": "HelixHeadlessMapArea",
           "members": [
+            {
+              "kind": "field",
+              "name": "caption",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "Words drawn on the map with the area, such as `A` for a search sector.\nUnset, nothing is drawn. Keep it short: it is a caption on a map, and the\narea's `label` is what a screen reader hears.",
+              "attribute": "caption"
+            },
+            {
+              "kind": "field",
+              "name": "captionPlacement",
+              "type": {
+                "text": "'inside' | 'outside'"
+              },
+              "default": "'inside'",
+              "description": "Where the caption stands. `inside`, the default, at the point of the area\nfurthest from its edges. `outside`, just above the area's northernmost\npoint, clear of the shape, for an area whose caption would cover what is\nin it.",
+              "attribute": "caption-placement"
+            },
             {
               "kind": "field",
               "name": "description",
@@ -62834,6 +62853,23 @@
             }
           ],
           "attributes": [
+            {
+              "name": "caption",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "Words drawn on the map with the area, such as `A` for a search sector.\nUnset, nothing is drawn. Keep it short: it is a caption on a map, and the\narea's `label` is what a screen reader hears.",
+              "fieldName": "caption"
+            },
+            {
+              "name": "caption-placement",
+              "type": {
+                "text": "'inside' | 'outside'"
+              },
+              "default": "'inside'",
+              "description": "Where the caption stands. `inside`, the default, at the point of the area\nfurthest from its edges. `outside`, just above the area's northernmost\npoint, clear of the shape, for an area whose caption would cover what is\nin it.",
+              "fieldName": "captionPlacement"
+            },
             {
               "name": "description",
               "type": {
@@ -67583,6 +67619,44 @@
                 "text": "moved() => void"
               }
             },
+            {
+              "kind": "field",
+              "name": "ready",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Whether the map has been drawn whole, which `drawn()` says. For a page that\nconnects after `helix-map-ready` has been sent, and missed it.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "whole",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "What `ready` reads, written by `drawn()`."
+            },
+            {
+              "kind": "method",
+              "name": "drawn",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "whole",
+                  "default": "true"
+                }
+              ],
+              "description": "Says the map has been drawn whole, or with `false`, that it no longer is.\n\n**Called by whatever draws the map**, as `connectMap` does once its driver\nhas every tile the view needs and the ground where there is terrain, and\nwith `false` when it disconnects. A page drawing its own map calls it when\nthat map is finished. The first call after the map was not drawn sends\n`helix-map-ready` and turns on `:state(ready)`, so a page can wait on the\nevent or select on the state, and a page that connects late reads `ready`.",
+              "type": {
+                "text": "drawn(whole = true) => void"
+              }
+            },
             {
               "kind": "method",
               "name": "say",
@@ -68903,6 +68977,14 @@
               "name": "helix-map-part-change",
               "reactProp": "onhelix-map-part-change"
             },
+            {
+              "type": {
+                "text": "HelixMapReadyEvent"
+              },
+              "description": "The map has been drawn whole: its style, every tile the view needs, and the ground where it has terrain. Sent once per connection. Show a map that is finished on it, where it would otherwise draw in stages.",
+              "name": "helix-map-ready",
+              "reactProp": "onhelix-map-ready"
+            },
             {
               "type": {
                 "text": "HelixMapRotateEvent"
@@ -69306,6 +69388,10 @@
               "description": "The user has been still long enough for the header and footer to fade.",
               "name": "idle"
             },
+            {
+              "description": "The map has been drawn whole, after `helix-map-ready`.",
+              "name": "ready"
+            },
             {
               "description": "Set one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.",
               "name": "settled",

package/dist/element-events.generated.js

@@ -105,6 +105,7 @@ registerElementEvents({
         'helix-map-cluster',
         'helix-map-pan',
         'helix-map-part-change',
+        'helix-map-ready',
         'helix-map-rotate',
         'helix-map-tilt',
         'helix-map-zoom',

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

@@ -9,6 +9,11 @@ import { type MapPoint } from '../route/map-route.js';
  * The frame lists each area by its `label` and `description` for screen
  * readers.
  *
+ * Set `caption` to draw words on the map with the area, such as a letter for a
+ * search sector, in a color that reads on the map. It is drawn rather than
+ * focusable, so it adds nothing to the tab order, and a screen reader reads
+ * the area's `label` in the frame's list.
+ *
  * @since 0.105.0
  * @status experimental
  * @category media
@@ -18,6 +23,19 @@ import { type MapPoint } from '../route/map-route.js';
  * @event {HelixMapPartChangeEvent} helix-map-part-change - The area's points, name, or color changed. Used by `connectMap`; pages do not need to listen for it.
  */
 export declare class HelixHeadlessMapArea extends HelixElement {
+    /**
+     * Words drawn on the map with the area, such as `A` for a search sector.
+     * Unset, nothing is drawn. Keep it short: it is a caption on a map, and the
+     * area's `label` is what a screen reader hears.
+     */
+    caption?: string;
+    /**
+     * Where the caption stands. `inside`, the default, at the point of the area
+     * furthest from its edges. `outside`, just above the area's northernmost
+     * point, clear of the shape, for an area whose caption would cover what is
+     * in it.
+     */
+    captionPlacement: 'inside' | 'outside';
     /** More about the area. Read after its label in the frame's list. */
     description?: string;
     /**

package/dist/map/area/map-area.js

@@ -11,6 +11,7 @@ import { pointsConverter } from '../route/map-route.js';
 let HelixHeadlessMapArea = class HelixHeadlessMapArea extends HelixElement {
     constructor() {
         super(...arguments);
+        this.captionPlacement = 'inside';
         this.isMapLayer = true;
         this.layerKind = 'area';
         this.label = 'Area';
@@ -23,6 +24,12 @@ let HelixHeadlessMapArea = class HelixHeadlessMapArea extends HelixElement {
         return nothing;
     }
 };
+__decorate([
+    property()
+], HelixHeadlessMapArea.prototype, "caption", void 0);
+__decorate([
+    property({ attribute: 'caption-placement' })
+], HelixHeadlessMapArea.prototype, "captionPlacement", void 0);
 __decorate([
     property()
 ], HelixHeadlessMapArea.prototype, "description", void 0);

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

@@ -70,6 +70,7 @@ declare const HelixHeadlessMap_base: (new (...args: any[]) => import("@fusion.de
  * @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 {HelixMapReadyEvent} helix-map-ready - The map has been drawn whole: its style, every tile the view needs, and the ground where it has terrain. Sent once per connection. Show a map that is finished on it, where it would otherwise draw in stages.
  * @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.
@@ -111,6 +112,7 @@ declare const HelixHeadlessMap_base: (new (...args: any[]) => import("@fusion.de
  *
  * @cssstate fullscreen - The map fills the screen.
  * @cssstate idle - The user has been still long enough for the header and footer to fade.
+ * @cssstate ready - The map has been drawn whole, after `helix-map-ready`.
  */
 export declare class HelixHeadlessMap extends HelixHeadlessMap_base {
     /**
@@ -220,6 +222,24 @@ export declare class HelixHeadlessMap extends HelixHeadlessMap_base {
      * say, so it says which way the map moved.
      */
     moved(): void;
+    /**
+     * Whether the map has been drawn whole, which `drawn()` says. For a page that
+     * connects after `helix-map-ready` has been sent, and missed it.
+     */
+    get ready(): boolean;
+    /** What `ready` reads, written by `drawn()`. */
+    private whole;
+    /**
+     * Says the map has been drawn whole, or with `false`, that it no longer is.
+     *
+     * **Called by whatever draws the map**, as `connectMap` does once its driver
+     * has every tile the view needs and the ground where there is terrain, and
+     * with `false` when it disconnects. A page drawing its own map calls it when
+     * that map is finished. The first call after the map was not drawn sends
+     * `helix-map-ready` and turns on `:state(ready)`, so a page can wait on the
+     * event or select on the state, and a page that connects late reads `ready`.
+     */
+    drawn(whole?: boolean): void;
     private say;
     /** Records what a reader asked, so the answer can be said. */
     private ask;

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

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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, fillTemplate, formatNumbers, HelixActivateEvent, HelixElement, HelixMapClusterEvent, HelixMapPanEvent, HelixMapPartChangeEvent, HelixMapRotateEvent, HelixMapTiltEvent, HelixMapZoomEvent, hostAria, KeyboardNavigationController, MixinViewport, } from '@fusion.dev/helix-core';
+import { customElement, fillTemplate, formatNumbers, HelixActivateEvent, HelixElement, HelixMapClusterEvent, HelixMapPanEvent, HelixMapPartChangeEvent, HelixMapReadyEvent, HelixMapRotateEvent, HelixMapTiltEvent, HelixMapZoomEvent, hostAria, KeyboardNavigationController, MixinViewport, } from '@fusion.dev/helix-core';
 import { buildings, cloudRain, dotsNine, leaf, mountains, path, polygon, stack, target, } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -67,6 +67,7 @@ let HelixHeadlessMap = class HelixHeadlessMap extends MixinViewport(HelixElement
         this.said = '';
         this.asked = undefined;
         this.settling = undefined;
+        this.whole = false;
         this.layersOpen = false;
         this.handleOutside = (event) => {
             if (!event.composedPath().includes(this)) {
@@ -141,6 +142,19 @@ let HelixHeadlessMap = class HelixHeadlessMap extends MixinViewport(HelixElement
         clearTimeout(this.settling);
         this.settling = setTimeout(() => this.say(), SETTLES);
     }
+    get ready() {
+        return this.whole;
+    }
+    drawn(whole = true) {
+        if (whole === this.whole) {
+            return;
+        }
+        this.whole = whole;
+        this.toggleState('ready', whole);
+        if (whole) {
+            this.dispatchEvent(new HelixMapReadyEvent());
+        }
+    }
     say() {
         const asked = this.asked;
         this.asked = undefined;

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.113.0",
+  "version": "0.115.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.113.0",
-    "@fusion.dev/helix-icons": "0.113.0",
+    "@fusion.dev/helix-core": "0.115.0",
+    "@fusion.dev/helix-icons": "0.115.0",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.113.0",
-    "@fusion.dev/helix-testing": "0.113.0",
+    "@fusion.dev/helix-cem": "0.115.0",
+    "@fusion.dev/helix-testing": "0.115.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^4.1.0",

package/types/jsx.d.ts

@@ -184,6 +184,7 @@ import type {
   HelixMapClusterEvent,
   HelixMapPanEvent,
   HelixMapPartChangeEvent,
+  HelixMapReadyEvent,
   HelixMapRotateEvent,
   HelixMapTiltEvent,
   HelixMapZoomEvent,
@@ -11473,6 +11474,20 @@ export type HelixHeadlessMapAreaHelixMapPartChangeElementEvent =
   HelixHeadlessMapAreaElementEvent<HelixMapPartChangeEvent>;
 
 export type HelixHeadlessMapAreaProps = {
+  /** Words drawn on the map with the area, such as `A` for a search sector.
+Unset, nothing is drawn. Keep it short: it is a caption on a map, and the
+area's `label` is what a screen reader hears. */
+  caption?: (HelixHeadlessMapArea["caption"]) | undefined;
+  /** Where the caption stands. `inside`, the default, at the point of the area
+furthest from its edges. `outside`, just above the area's northernmost
+point, clear of the shape, for an area whose caption would cover what is
+in it. */
+  "caption-placement"?: (HelixHeadlessMapArea["captionPlacement"]) | undefined;
+  /** Where the caption stands. `inside`, the default, at the point of the area
+furthest from its edges. `outside`, just above the area's northernmost
+point, clear of the shape, for an area whose caption would cover what is
+in it. */
+  captionPlacement?: (HelixHeadlessMapArea["captionPlacement"]) | undefined;
   /** More about the area. Read after its label in the frame's list. */
   description?: (HelixHeadlessMapArea["description"]) | undefined;
   /** A name this layer shares with other layers, such as a route and its
@@ -11493,6 +11508,20 @@ first. */
 };
 
 export type HelixHeadlessMapAreaSolidJsProps = {
+  /** Words drawn on the map with the area, such as `A` for a search sector.
+Unset, nothing is drawn. Keep it short: it is a caption on a map, and the
+area's `label` is what a screen reader hears. */
+  "prop:caption"?: (HelixHeadlessMapArea["caption"]) | undefined;
+  /** Where the caption stands. `inside`, the default, at the point of the area
+furthest from its edges. `outside`, just above the area's northernmost
+point, clear of the shape, for an area whose caption would cover what is
+in it. */
+  "attr:caption-placement"?: (HelixHeadlessMapArea["captionPlacement"]) | undefined;
+  /** Where the caption stands. `inside`, the default, at the point of the area
+furthest from its edges. `outside`, just above the area's northernmost
+point, clear of the shape, for an area whose caption would cover what is
+in it. */
+  "prop:captionPlacement"?: (HelixHeadlessMapArea["captionPlacement"]) | undefined;
   /** More about the area. Read after its label in the frame's list. */
   "prop:description"?: (HelixHeadlessMapArea["description"]) | undefined;
   /** A name this layer shares with other layers, such as a route and its
@@ -12025,6 +12054,9 @@ export type HelixHeadlessMapHelixMapPanElementEvent =
 /** `helix-map-part-change` event type */
 export type HelixHeadlessMapHelixMapPartChangeElementEvent =
   HelixHeadlessMapElementEvent<HelixMapPartChangeEvent>;
+/** `helix-map-ready` event type */
+export type HelixHeadlessMapHelixMapReadyElementEvent =
+  HelixHeadlessMapElementEvent<HelixMapReadyEvent>;
 /** `helix-map-rotate` event type */
 export type HelixHeadlessMapHelixMapRotateElementEvent =
   HelixHeadlessMapElementEvent<HelixMapRotateEvent>;
@@ -12280,6 +12312,8 @@ at any zoom, and a consumer who wants their own units multiplies by them. */
   "onhelix-map-part-change"?: ((
     e: HelixHeadlessMapHelixMapPartChangeElementEvent,
   ) => void) | undefined;
+  /** The map has been drawn whole: its style, every tile the view needs, and the ground where it has terrain. Sent once per connection. Show a map that is finished on it, where it would otherwise draw in stages. */
+  "onhelix-map-ready"?: ((e: HelixHeadlessMapHelixMapReadyElementEvent) => void) | undefined;
   /** A rotate or Face north button, or Shift with Left or Right, was pressed. Turn your map in response. */
   "onhelix-map-rotate"?: ((
     e: HelixHeadlessMapHelixMapRotateElementEvent,
@@ -12534,6 +12568,8 @@ at any zoom, and a consumer who wants their own units multiplies by them. */
   "on:helix-map-part-change"?: ((
     e: HelixHeadlessMapHelixMapPartChangeElementEvent,
   ) => void) | undefined;
+  /** The map has been drawn whole: its style, every tile the view needs, and the ground where it has terrain. Sent once per connection. Show a map that is finished on it, where it would otherwise draw in stages. */
+  "on:helix-map-ready"?: ((e: HelixHeadlessMapHelixMapReadyElementEvent) => void) | undefined;
   /** A rotate or Face north button, or Shift with Left or Right, was pressed. Turn your map in response. */
   "on:helix-map-rotate"?: ((
     e: HelixHeadlessMapHelixMapRotateElementEvent,
@@ -32487,10 +32523,22 @@ export type CustomElements = {
    * The frame lists each area by its `label` and `description` for screen
    * readers.
    *
+   * Set `caption` to draw words on the map with the area, such as a letter for a
+   * search sector, in a color that reads on the map. It is drawn rather than
+   * focusable, so it adds nothing to the tab order, and a screen reader reads
+   * the area's `label` in the frame's list.
+   *
    * ## Attributes & Properties
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
+   * - `caption`: Words drawn on the map with the area, such as `A` for a search sector.
+   * Unset, nothing is drawn. Keep it short: it is a caption on a map, and the
+   * area's `label` is what a screen reader hears.
+   * - `caption-placement`/`captionPlacement`: Where the caption stands. `inside`, the default, at the point of the area
+   * furthest from its edges. `outside`, just above the area's northernmost
+   * point, clear of the shape, for an area whose caption would cover what is
+   * in it.
    * - `description`: More about the area. Read after its label in the frame's list.
    * - `group`: A name this layer shares with other layers, such as a route and its
    * dotted legs. The layers menu shows layers in the same group as one entry,
@@ -33190,6 +33238,8 @@ export type CustomElements = {
    * - `pan-up-label`/`panUpLabel`: The pan up button's label.
    * - `zoom-in-label`/`zoomInLabel`: The zoom in button's label.
    * - `zoom-out-label`/`zoomOutLabel`: The zoom out button's label.
+   * - `ready`: Whether the map has been drawn whole, which `drawn()` says. For a page that
+   * connects after `helix-map-ready` has been sent, and missed it. (property only) (readonly)
    * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
    *
    * **Named `whenSettled` because `settled` is taken four times over**, by
@@ -33219,6 +33269,7 @@ export type CustomElements = {
    * - `helix-map-cluster`: A cluster was pressed. Sent from the marker that shows the cluster, with the names of its places.
    * - `helix-map-pan`: A pan button or arrow key was pressed. Move your map in response.
    * - `helix-map-part-change`: Clustering was turned on or off. Used by `connectMap`; pages do not need to listen for it.
+   * - `helix-map-ready`: The map has been drawn whole: its style, every tile the view needs, and the ground where it has terrain. Sent once per connection. Show a map that is finished on it, where it would otherwise draw in stages.
    * - `helix-map-rotate`: A rotate or Face north button, or Shift with Left or Right, was pressed. Turn your map in response.
    * - `helix-map-tilt`: The 3D button, or Shift with Up or Down, was pressed. Tilt your map in response.
    * - `helix-map-zoom`: A zoom button or key was pressed, with a direction. Zoom your map in response.
@@ -33250,6 +33301,14 @@ export type CustomElements = {
    * animation is one sentence, and it is the view's state where there is one:
    * the zoom level, the way the map faces, its tilt. A pan has no state to
    * say, so it says which way the map moved.
+   * - `drawn(whole = true) => void`: Says the map has been drawn whole, or with `false`, that it no longer is.
+   *
+   * **Called by whatever draws the map**, as `connectMap` does once its driver
+   * has every tile the view needs and the ground where there is terrain, and
+   * with `false` when it disconnects. A page drawing its own map calls it when
+   * that map is finished. The first call after the map was not drawn sends
+   * `helix-map-ready` and turns on `:state(ready)`, so a page can wait on the
+   * event or select on the state, and a page that connects late reads `ready`.
    * - `rotate(by: number) => void`: Turns the map by some degrees, clockwise where positive.
    * - `faceNorth() => void`: Turns the map to face north.
    * - `tilt(by: number) => void`: Tilts the map by some degrees, toward the horizon where positive.
@@ -33307,6 +33366,7 @@ export type CustomElements = {
    *
    * - `fullscreen`: The map fills the screen.
    * - `idle`: The user has been still long enough for the header and footer to fade.
+   * - `ready`: The map has been drawn whole, after `helix-map-ready`.
    * - `settled`: Set one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
    */
   "helix-headless-map": Partial<
@@ -52544,10 +52604,22 @@ export type CustomElementsSolidJs = {
    * The frame lists each area by its `label` and `description` for screen
    * readers.
    *
+   * Set `caption` to draw words on the map with the area, such as a letter for a
+   * search sector, in a color that reads on the map. It is drawn rather than
+   * focusable, so it adds nothing to the tab order, and a screen reader reads
+   * the area's `label` in the frame's list.
+   *
    * ## Attributes & Properties
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
+   * - `caption`: Words drawn on the map with the area, such as `A` for a search sector.
+   * Unset, nothing is drawn. Keep it short: it is a caption on a map, and the
+   * area's `label` is what a screen reader hears.
+   * - `caption-placement`/`captionPlacement`: Where the caption stands. `inside`, the default, at the point of the area
+   * furthest from its edges. `outside`, just above the area's northernmost
+   * point, clear of the shape, for an area whose caption would cover what is
+   * in it.
    * - `description`: More about the area. Read after its label in the frame's list.
    * - `group`: A name this layer shares with other layers, such as a route and its
    * dotted legs. The layers menu shows layers in the same group as one entry,
@@ -53263,6 +53335,8 @@ export type CustomElementsSolidJs = {
    * - `pan-up-label`/`panUpLabel`: The pan up button's label.
    * - `zoom-in-label`/`zoomInLabel`: The zoom in button's label.
    * - `zoom-out-label`/`zoomOutLabel`: The zoom out button's label.
+   * - `ready`: Whether the map has been drawn whole, which `drawn()` says. For a page that
+   * connects after `helix-map-ready` has been sent, and missed it. (property only) (readonly)
    * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
    *
    * **Named `whenSettled` because `settled` is taken four times over**, by
@@ -53292,6 +53366,7 @@ export type CustomElementsSolidJs = {
    * - `helix-map-cluster`: A cluster was pressed. Sent from the marker that shows the cluster, with the names of its places.
    * - `helix-map-pan`: A pan button or arrow key was pressed. Move your map in response.
    * - `helix-map-part-change`: Clustering was turned on or off. Used by `connectMap`; pages do not need to listen for it.
+   * - `helix-map-ready`: The map has been drawn whole: its style, every tile the view needs, and the ground where it has terrain. Sent once per connection. Show a map that is finished on it, where it would otherwise draw in stages.
    * - `helix-map-rotate`: A rotate or Face north button, or Shift with Left or Right, was pressed. Turn your map in response.
    * - `helix-map-tilt`: The 3D button, or Shift with Up or Down, was pressed. Tilt your map in response.
    * - `helix-map-zoom`: A zoom button or key was pressed, with a direction. Zoom your map in response.
@@ -53323,6 +53398,14 @@ export type CustomElementsSolidJs = {
    * animation is one sentence, and it is the view's state where there is one:
    * the zoom level, the way the map faces, its tilt. A pan has no state to
    * say, so it says which way the map moved.
+   * - `drawn(whole = true) => void`: Says the map has been drawn whole, or with `false`, that it no longer is.
+   *
+   * **Called by whatever draws the map**, as `connectMap` does once its driver
+   * has every tile the view needs and the ground where there is terrain, and
+   * with `false` when it disconnects. A page drawing its own map calls it when
+   * that map is finished. The first call after the map was not drawn sends
+   * `helix-map-ready` and turns on `:state(ready)`, so a page can wait on the
+   * event or select on the state, and a page that connects late reads `ready`.
    * - `rotate(by: number) => void`: Turns the map by some degrees, clockwise where positive.
    * - `faceNorth() => void`: Turns the map to face north.
    * - `tilt(by: number) => void`: Tilts the map by some degrees, toward the horizon where positive.
@@ -53380,6 +53463,7 @@ export type CustomElementsSolidJs = {
    *
    * - `fullscreen`: The map fills the screen.
    * - `idle`: The user has been still long enough for the header and footer to fade.
+   * - `ready`: The map has been drawn whole, after `helix-map-ready`.
    * - `settled`: Set one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
    */
   "helix-headless-map": Partial<

package/types/vue.d.ts

@@ -200,6 +200,7 @@ import type {
   HelixMapPartChangeEvent,
   HelixMapClusterEvent,
   HelixMapPanEvent,
+  HelixMapReadyEvent,
   HelixMapRotateEvent,
   HelixMapTiltEvent,
   HelixMapZoomEvent,
@@ -5871,6 +5872,20 @@ export type HelixHeadlessMapAreaHelixMapPartChangeElementEvent =
   HelixHeadlessMapAreaElementEvent<HelixMapPartChangeEvent>;
 
 export type HelixHeadlessMapAreaVueProps = {
+  /** Words drawn on the map with the area, such as `A` for a search sector.
+Unset, nothing is drawn. Keep it short: it is a caption on a map, and the
+area's `label` is what a screen reader hears. */
+  caption?: (HelixHeadlessMapArea["caption"]) | undefined;
+  /** Where the caption stands. `inside`, the default, at the point of the area
+furthest from its edges. `outside`, just above the area's northernmost
+point, clear of the shape, for an area whose caption would cover what is
+in it. */
+  "caption-placement"?: (HelixHeadlessMapArea["captionPlacement"]) | undefined;
+  /** Where the caption stands. `inside`, the default, at the point of the area
+furthest from its edges. `outside`, just above the area's northernmost
+point, clear of the shape, for an area whose caption would cover what is
+in it. */
+  captionPlacement?: (HelixHeadlessMapArea["captionPlacement"]) | undefined;
   /** More about the area. Read after its label in the frame's list. */
   description?: (HelixHeadlessMapArea["description"]) | undefined;
   /** A name this layer shares with other layers, such as a route and its
@@ -6169,6 +6184,9 @@ export type HelixHeadlessMapHelixMapPanElementEvent =
 /** `helix-map-part-change` event type */
 export type HelixHeadlessMapHelixMapPartChangeElementEvent =
   HelixHeadlessMapElementEvent<HelixMapPartChangeEvent>;
+/** `helix-map-ready` event type */
+export type HelixHeadlessMapHelixMapReadyElementEvent =
+  HelixHeadlessMapElementEvent<HelixMapReadyEvent>;
 /** `helix-map-rotate` event type */
 export type HelixHeadlessMapHelixMapRotateElementEvent =
   HelixHeadlessMapElementEvent<HelixMapRotateEvent>;
@@ -6422,6 +6440,8 @@ export type HelixHeadlessMapVueEvents = {
   "helix-map-pan": HelixHeadlessMapHelixMapPanElementEvent;
   /** Clustering was turned on or off. Used by `connectMap`; pages do not need to listen for it. */
   "helix-map-part-change": HelixHeadlessMapHelixMapPartChangeElementEvent;
+  /** The map has been drawn whole: its style, every tile the view needs, and the ground where it has terrain. Sent once per connection. Show a map that is finished on it, where it would otherwise draw in stages. */
+  "helix-map-ready": HelixHeadlessMapHelixMapReadyElementEvent;
   /** A rotate or Face north button, or Shift with Left or Right, was pressed. Turn your map in response. */
   "helix-map-rotate": HelixHeadlessMapHelixMapRotateElementEvent;
   /** The 3D button, or Shift with Up or Down, was pressed. Tilt your map in response. */
@@ -12134,7 +12154,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessLoaderVueProps,
     HelixHeadlessLoaderVueEvents
   >;
-  /** 'connectMap' fills the shape as a layer of the map, under its place names. The frame lists each area by its 'label' and 'description' for screen readers. */
+  /** 'connectMap' fills the shape as a layer of the map, under its place names. The frame lists each area by its 'label' and 'description' for screen readers.  Set 'caption' to draw words on the map with the area, such as a letter for a search sector, in a color that reads on the map. It is drawn rather than focusable, so it adds nothing to the tab order, and a screen reader reads the area's 'label' in the frame's list. */
   "helix-headless-map-area": DefineCustomElement<
     HelixHeadlessMapArea,
     HelixHeadlessMapAreaVueProps,