@mosaicajs/components 0.3.0 → 0.4.0

package/dist/map.d.ts

@@ -114,13 +114,29 @@ export type MapProbe = {
  * A box or lasso drawn with the toolbar becomes the store's selected region, which narrows the map
  * and every count to the items inside it. Shift-drag draws a box without changing tool. With the
  * map focused, the arrow keys pan and `+` and `-` zoom. Escape cancels a shape being drawn, or
- * clears the region when there is no shape, or drops the picked item when there is neither.
+ * clears the region when there is no shape, or drops the picked item when there is neither. With
+ * none of the three, the map leaves Escape to the page, so a dialog holding the map still closes.
  *
- * When the map cannot draw the view, it says why over the canvas.
+ * The hover tooltip follows the pointer and stays inside the map. Escape dismisses it wherever the
+ * focus is, and it stays away until the pointer moves onto another point. With the focus in the
+ * map, or in an element that renders the map inside its own shadow root, such as
+ * `<mosaica-explorer>`, the press does nothing else: the map calls `preventDefault` on it, and
+ * clears no selection on it. With the focus anywhere else on the page, the map leaves the press as
+ * it was, so the page's own Escape still acts.
+ *
+ * When the map cannot draw the view, it says why over the canvas, and screen readers announce it.
+ * Nothing in view is announced as the answer to a change of filters, highlight or selection, and
+ * only shown where a pan went. Screen readers also announce the basemap's note, and how many items
+ * match inside the selected region, once, when the query that counts it has finished loading. Set
+ * `quiet` where another element on the page says the same things, such as a status strip: the map
+ * shows the same, and announces only what it alone knows, the basemap's note and a basemap it
+ * refuses.
+ *
+ * With `ground` unset the map follows the page's colour scheme, and draws again when it changes.
  *
  * The canvas is a single tab stop, and it takes any `tabindex` or `aria-label` you set on the map.
- * Without an `aria-label`, the canvas is labelled with its keys, "map: arrow keys pan, + and -
- * zoom", so that someone using a screen reader knows how to move it.
+ * Without an `aria-label` the canvas is named "Map". Either way its description lists its keys, so
+ * that someone using a screen reader knows how to move it.
  *
  * @summary An interactive map with no panels around it.
  * @tagname mosaica-map
@@ -149,23 +165,26 @@ export type MapProbe = {
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-layerchange']>} mosaica-layerchange - The
  *   `layers` attribute changed.
  * @csspart canvas - The deck.gl canvas's container.
- * @csspart overlay - The message over the canvas when the view is refused, expired or empty, or the
- *   server cannot be reached, did not answer or is too busy. If the viewer may see no item in the
- *   view at all, it says so instead of "Nothing in view".
+ * @csspart overlay - The layer over the canvas that holds the state line.
  * @csspart state - The state line inside the overlay, with `data-state`, and `data-visible="none"`
- *   if the viewer may see no item in the view.
+ *   if the viewer may see no item in the view. It shows a message when the view is refused,
+ *   expired or empty, or the server cannot be reached, did not answer or is too busy; if the viewer
+ *   may see no item in the view at all, it says so instead of "Nothing in view". It is in the page
+ *   in every state, and drawn only while it has a message.
  * @csspart retry - The Retry button in the overlay, after a refusal, no answer or a busy server.
  * @csspart refusal - The words "View refused", or "Server busy", inside the overlay, with
  *   `data-code` set to the refusal's code.
  * @csspart reason - The server's reason for a refusal, as it sent it, on a line under "View
  *   refused".
  * @csspart controls - The toolbar.
- * @csspart region-tag - The tag on the selected region's top-left corner, with how many items
- *   match inside it (or outside it, for its complement) and a button that clears it.
+ * @csspart region-tag - The tag above the selected region's top-left corner, with how many items
+ *   match inside it (or outside it, for its complement) and a button that clears it. It stays
+ *   inside the map when the corner is off it.
  * @csspart tooltip - The hover tooltip.
  * @csspart density-key - The key to density's colours in items per cell, in the bottom-left corner.
  *   Shown while density is drawn in a colour ramp or without the points.
- * @csspart note - Why no basemap is drawn under this view, in the bottom-right corner.
+ * @csspart note - Why no basemap is drawn under this view, in the bottom-right corner. It is in the
+ *   page whether or not there is a note, and drawn only while there is one.
  * @csspart attribution - The tile server's credit, in the bottom-right corner while tiles are drawn.
  * @cssprop --mosaica-map-height - The map's height.
  * @cssprop --mosaica-map-bg - The canvas's background, behind the points and any basemap.
@@ -188,10 +207,20 @@ export declare class MosaicaMap extends MosaicaElement {
     /** How many marks to aim for on screen. `0` keeps the store's budget, which starts at 250000. */
     accessor budget: number;
     /**
-     * The most clusters a `nested` or `dag` layer is cut to (`Store.setClusterBudget`). `0` keeps the
-     * store's setting; setting `0` after another value removes the limit, giving the finest cut.
+     * The side in CSS pixels of the square of the map each cluster is given (`Store.setClusterSpacing`),
+     * so the map shows about one cluster per square whatever its size: at 100, a map 1,200 by 800
+     * pixels shows 96. `0` keeps the store's setting; setting `0` after another value removes the
+     * limit.
+     *
+     * A `nested` or `dag` layer is cut to that many clusters. A `stacked` or `tiered` layer whose
+     * levels declare no zoom range and which `clusterLevels` leaves to follow the zoom is drawn at the
+     * finest level with no more than that many clusters in view and no tile in view holding the most a
+     * tile is served, so the world view shows a broad level and finer ones appear as the camera zooms
+     * in. Without a spacing only a full tile holds a level back, so such a layer is drawn at its
+     * finest level at every zoom until its tiles fill, world zoom included, and a `nested` or `dag`
+     * layer is drawn at its finest cut.
      */
-    accessor clusterBudget: number;
+    accessor clusterSpacing: number;
     /**
      * The columns the hover tooltip shows under the point's title, separated by spaces or commas.
      * Only rendered columns arrive with the points, so another column shows nothing.
@@ -212,10 +241,13 @@ export declare class MosaicaMap extends MosaicaElement {
      */
     accessor palette: PaletteName | '';
     /**
-     * The level of a `stacked` or `tiered` layer at which clusters are coloured, labelled and
-     * outlined. Unset, the coarsest level. A `nested` or `dag` layer ignores it.
+     * The level at which each `stacked` or `tiered` layer's clusters are coloured, labelled and
+     * outlined, keyed by layer name. A layer with no entry is drawn at the level that follows the zoom
+     * where its levels declare no zoom range (see `cluster-spacing`), and otherwise at the coarsest
+     * level the camera's zoom serves. A `nested` or `dag` layer ignores its entry. Set it as a
+     * property; it has no attribute.
      */
-    accessor clusterLevel: number | null;
+    accessor clusterLevels: ReadonlyMap<string, number>;
     /**
      * What is drawn under the points. `world` is the server's outline of land, coastlines and country
      * borders, and needs a view with a map projection. `{tiles, attribution}` is a tile server's URL
@@ -231,8 +263,9 @@ export declare class MosaicaMap extends MosaicaElement {
     accessor basemap: BasemapChoice | null;
     /**
      * Whether the map's background is `light` or `dark`, for when it differs from the page's, such as
-     * a light basemap on a dark page. Labels and density colours follow it; the toolbar and panels
-     * follow the page. Unset, it follows the page's `color-scheme`.
+     * a light basemap on a dark page. The points' single colour, labels and density colours follow
+     * it; the toolbar and panels follow the page. Unset, it follows the page's `color-scheme`, and
+     * the system's where the page allows both.
      */
     accessor ground: 'light' | 'dark' | '';
     /** Hides the points. Density, outlines, labels and the selection are still drawn. */
@@ -337,6 +370,13 @@ export declare class MosaicaMap extends MosaicaElement {
     accessor sizeScale: SizeScale | '';
     /** Hides the toolbar. */
     accessor noControls: boolean;
+    /**
+     * Leaves to another element what that element also says: the view's state over the canvas and
+     * the selected region's count are still shown, and neither is put in a live region. Set it when
+     * another element on the page says the same things, such as a status strip. What only the map
+     * knows is announced either way: the basemap's note, and a basemap it refuses.
+     */
+    accessor quiet: boolean;
     /**
      * The corner the toolbar sits in: `top-left`, `top-right`, `bottom-left` or `bottom-right`.
      * Content in the same corner's slot sits below the toolbar in a top corner, and above it in a
@@ -442,6 +482,11 @@ export declare class MosaicaMap extends MosaicaElement {
      * styles, which is light where the host's `color-scheme` names neither.
      */
     private scheme;
+    /**
+     * Draw for the other ground when the page's or the system's colour scheme changes, which the
+     * colour of the `#ground` element follows: the basemap, the points and names, and the density key.
+     */
+    private onGroundChange;
     protected resetServerData(): void;
     /** Stops following the colour and size choices of the store adopted last. */
     private unwatchChoices;
@@ -457,6 +502,11 @@ export declare class MosaicaMap extends MosaicaElement {
     protected onStoreAdopted(store: Store | null): void;
     /** A store adopted since the last update, to which the host's settings are not yet written. */
     private unpushed;
+    /** Keeps the focus on the map when the overlay's Retry goes with its state. */
+    private readonly actionFocus;
+    private readonly emptyAnswer;
+    /** Whether the view is empty as a query's answer, which is announced, and not where a pan went. */
+    private emptyAnswered;
     /**
      * Write the host's settings to the store before the render: every one to a store adopted since
      * the last update, else those that changed. `layers` set or changed in this update fires
@@ -486,9 +536,15 @@ export declare class MosaicaMap extends MosaicaElement {
     private basemapInput;
     private syncBasemap;
     private paint;
+    /**
+     * What deck's own input handling does. Its keyboard is off in every mode, since the map takes
+     * the keys itself and a key would otherwise move the camera twice. In box and lasso modes the
+     * drag is the selection's; the wheel still zooms.
+     */
+    private controller;
     /**
      * The shapes a hover or click is resolved against ({@link contourShapes}), held until the served
-     * set, the fetched shapes, the level or the roster change. Each is the artifact's box until its
+     * set, the fetched shapes, the levels or the roster change. Each is the artifact's box until its
      * shape is fetched; where boxes overlap, depth and the mark under the pointer decide.
      */
     private contoursHeld;
@@ -524,6 +580,31 @@ export declare class MosaicaMap extends MosaicaElement {
      * the pointer moved on is dropped.
      */
     private describeHovered;
+    /** The mark whose tooltip Escape dismissed, while the pointer stays on it. */
+    private dismissedHover;
+    /** Whether the document is listened to for the Escape that dismisses the tooltip. */
+    private tooltipKeys;
+    /** Listen to the document for Escape while a tooltip shows, wherever the focus is. */
+    private watchTooltipKeys;
+    /**
+     * Escape dismisses the tooltip. Pressed in the map, or in an element whose shadow tree holds the
+     * map, such as an explorer, it does nothing else: it is marked as taken, so the same press clears
+     * no selection there. Pressed anywhere else on the page it is left as it was, for the page.
+     */
+    private onTooltipKey;
+    /** The region's tag as last measured: its size, the map's, and how far in the top-left corner's content starts. */
+    private tagBox;
+    /** Measures the tag again when it or the map changes size, so that placing it as the camera moves reads no layout. */
+    private readonly tagSized;
+    private measureTag;
+    /** Put the region's tag above its region's top-left corner, inside the map, from the sizes last measured. */
+    private placeTag;
+    /**
+     * Move the tooltip beside the pointer and the region's tag above its region's corner, each kept
+     * inside the map. The tooltip is measured each time it is drawn; the tag when it is first drawn
+     * and when it or the map changes size.
+     */
+    private placeFloats;
     /** The element that takes the map's focus: the canvas, a tab stop of its own. @internal */
     get focusTarget(): HTMLElement | null;
     /** Focus the canvas, which takes the map's keys. */
@@ -555,12 +636,27 @@ export declare class MosaicaMap extends MosaicaElement {
     private cameraSet;
     private setViewState;
     /**
-     * The drawn region's tag at its top-left corner: how many items match inside it (or outside, for
-     * its complement) and a button that clears it. A region drawn as an artifact's outline has none.
+     * The drawn region's tag: how many items match inside it (or outside, for its complement) and a
+     * button that clears it. A region drawn as an artifact's outline has none. {@link placeFloats}
+     * puts it above the region's top-left corner.
      */
     private regionTag;
-    /** The level clusters are drawn at: `cluster-level` where set, else the top level of a levelled layer. */
-    private drawnLevel;
+    /** The top-left corner of the drawn region's bounds, in world coordinates; `null` where no shape is drawn. */
+    private regionCorner;
+    /** What the map last announced of the selected region, and the shape it said it of. */
+    private regionHeard;
+    private heardShape;
+    /**
+     * Decide what the map announces of the selected region: how many items match inside it (or
+     * outside), once the query that counts it has finished loading, since the figure a frame gives
+     * first is an estimate. The words change only with the figure or the shape, so a count is
+     * announced once, whatever else the map says in the meantime.
+     */
+    private hearRegion;
+    /** The level the layer `name` is drawn at: its entry in `clusterLevels`, else the level in view of a levelled layer. */
+    private levelOf;
+    /** {@link levelOf} for each layer drawn. */
+    private drawnLevels;
     /** Whether the map is drawn on a light or dark background now: `ground` if set, else the page's scheme. */
     get drawnGround(): 'light' | 'dark';
     /**
@@ -611,6 +707,21 @@ export declare class MosaicaMap extends MosaicaElement {
     private basemapCorner;
     render(): TemplateResult | typeof nothing;
 }
+/**
+ * A box's top-left corner, moved as little as keeps the box between `min` and `max` on each axis.
+ * A box larger than that room starts at `min`.
+ *
+ * @internal
+ */
+export declare function keptInside(at: readonly [number, number], size: readonly [number, number], min: readonly [number, number], max: readonly [number, number]): [number, number];
+/**
+ * The tooltip's top-left corner for a pointer at `pointer` on a map of size `map`: below and right
+ * of the pointer, on the pointer's other side along an axis where it would cross the map's far
+ * edge, and inside the map either way.
+ *
+ * @internal
+ */
+export declare function tooltipCorner(pointer: readonly [number, number], size: readonly [number, number], map: readonly [number, number]): [number, number];
 /** The density scale drawn: `linear` where set, else `log`. */
 export declare function drawnDensityScale(scale: string): DensityScale;
 /** The density colours drawn: those chosen, else warm grey for a wash under the points, else Viridis. */