@mosaicajs/components 0.1.0-rc.4 → 0.1.0

package/dist/map.js

@@ -56,37 +56,29 @@ const VIEW = new OrthographicView({ id: 'ortho', flipY: true });
 /** How many maps have been made, which numbers each one's ask for point columns. */
 let mapsMade = 0;
 /**
- * The map: the points, the density wash, the artifacts' outlines and labels, hover, pick and the
- * selection, drawn with deck.gl in an orthographic view. The refused, expired and empty states, and
- * a server that cannot be reached, did not answer or is too busy, are drawn over the canvas, so
- * none of them reads as an empty corpus. A refusal shows the server's reason under its words. The
- * toolbar switches between pan, box select and lasso select, and fits the camera to the items the
- * filters match; shift-drag in pan mode draws a box. A settled box or lasso becomes the store's
- * selection, a filter every count narrows to; a tag on its top-left corner gives the count matched
- * inside it and a button that clears it.
+ * Use the map on its own when you lay out your own panels around it. It draws one view's points,
+ * density and annotation layers. When the viewer picks a point or draws a region, the map records
+ * it in the store, so the other elements on the page follow.
  *
- * The map owns the camera and tells the store where it is looking on every move. When it is given
- * a store, and when the store switches to a view with another extent, it opens framed on the items
- * the store's filters match, as the Fit button frames them ({@link MosaicaMap.fit}). It sends the
- * store no camera until then, so no points are fetched for a camera it is about to leave. A camera
- * the user or the host moves first is kept, and a later change of filter leaves the camera where
- * it is. Density is asked for once the camera has rested for 200 ms, as counts by cell over the
- * view and a margin round it, with coarser counts reaching further for a zoom out, and the last
- * counts are drawn at their own positions until the next land. Keys, with the map focused: the
- * arrow keys pan, `+` and `-` zoom, and Escape cancels a shape being drawn, else
- * clears the selected region, else drops the picked point or artifact and its ring. A click on
- * empty map drops them too; a selected region stays. A press hides
- * the hover tooltip until the pointer is released, and the point whose record is selected, which
- * its item card shows, has no tooltip. The canvas is one tab stop, after the toolbar
- * and before the content of the other corners: it carries `role="application"`, the `tabindex`
- * the host set on the map, else 0, and the host's `aria-label` where the host set one, else one
- * naming the keys. A `tabindex` the host sets moves to the canvas, leaving -1 on the map, so the
- * map is never a second stop. `focus()` focuses the canvas.
+ * The map takes its store from its `store` property or from an enclosing `<mosaica-store>`. It can
+ * also build its own from `viewer-url` and `token` or `authorise`.
  *
- * The host element is `display: block`; its height comes from `--mosaica-map-height`. A map that
- * is disconnected and not reconnected releases its GPU resources a quarter of a second later.
+ * When the map first gets a store, it frames the items the filters match unless the camera has
+ * already been moved. It frames them again when the view switches to one with a different extent,
+ * but a change of filter leaves the camera where it is.
  *
- * @summary The map canvas.
+ * 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.
+ *
+ * When the map cannot draw the view, it says why over the canvas.
+ *
+ * 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.
+ *
+ * @summary An interactive map with no panels around it.
  * @tagname mosaica-map
  * @category Elements
  * @slot top-left - Content in the top-left corner, below the toolbar when it is there.
@@ -102,42 +94,39 @@ let mapsMade = 0;
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-itemopen']>} mosaica-itemopen - The selected
  *   item's record arrived, however the item was selected.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-miss']>} mosaica-miss - A click found no point
- *   and no artifact. The map has dropped the selection, as {@link MosaicaMap.clearPick} does.
+ *   and no artifact. The map has already dropped the picked item.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-hover']>} mosaica-hover - The pointer moved onto
  *   or over a point.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-artifactopen']>} mosaica-artifactopen - An
- *   artifact was opened and its drill-down arrived.
+ *   artifact was opened and its details arrived.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-selectchange']>} mosaica-selectchange - A
  *   selection was drawn or cleared (`status` `loading` or `cleared`), and again when its counts
  *   arrive.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-layerchange']>} mosaica-layerchange - The
  *   `layers` attribute changed.
  * @csspart canvas - The deck.gl canvas's container.
- * @csspart overlay - The state drawn over the canvas when refused, expired or empty, when the
- *   server cannot be reached, when it did not answer, and when it is too busy. Where the
- *   viewer can see no item in the view at all, it says so in place of Nothing in view.
+ * @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 state - The state line inside the overlay, with `data-state`, and `data-visible="none"`
- *   where the viewer can see no item in the view.
- * @csspart retry - The Retry button in the overlay, when the view was refused or the server did
- *   not answer or is too busy.
+ *   if the viewer may see no item in the view.
+ * @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 drawn region's tag on its top-left corner: how many items match inside
- *   it, or outside it for its complement, and a button that clears the selection.
+ * @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 tooltip - The hover tooltip.
- * @csspart density-key - The key to density's colours, items per cell from 0 to the largest count
- *   drawn with the count at the scale's midpoint, in the bottom-left corner while density is drawn
- *   in a ramp or without the points.
- * @csspart note - Why no basemap is drawn under this view, in the bottom-right corner: the value
- *   given does not fit it, or the basemap did not load.
+ * @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 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.
- * @cssprop --mosaica-map-inset-left - Extra space between the top-left corner's content and the
- *   map's left edge, for a panel floated over the map's left side. Defaults to 0.
+ * @cssprop --mosaica-map-inset-left - Extra space to the left of the top-left corner's content, to
+ *   clear a panel you float over the map's left side. Defaults to 0.
  */
 let MosaicaMap = (() => {
     let _classSuper = MosaicaElement;
@@ -150,12 +139,6 @@ let MosaicaMap = (() => {
     let _budget_decorators;
     let _budget_initializers = [];
     let _budget_extraInitializers = [];
-    let _budgetMin_decorators;
-    let _budgetMin_initializers = [];
-    let _budgetMin_extraInitializers = [];
-    let _budgetMax_decorators;
-    let _budgetMax_initializers = [];
-    let _budgetMax_extraInitializers = [];
     let _clusterBudget_decorators;
     let _clusterBudget_initializers = [];
     let _clusterBudget_extraInitializers = [];
@@ -264,8 +247,6 @@ let MosaicaMap = (() => {
                     converter: { fromAttribute: (v) => (v ? v.split(/[\s,]+/).filter(Boolean) : []), toAttribute: (v) => v.join(' ') }
                 })];
             _budget_decorators = [property({ type: Number })];
-            _budgetMin_decorators = [property({ type: Number, attribute: 'budget-min' })];
-            _budgetMax_decorators = [property({ type: Number, attribute: 'budget-max' })];
             _clusterBudget_decorators = [property({ type: Number, attribute: 'cluster-budget' })];
             _tooltipFields_decorators = [property({ attribute: 'tooltip-fields' })];
             _titleField_decorators = [property({ attribute: 'title-field' })];
@@ -302,8 +283,6 @@ let MosaicaMap = (() => {
             __esDecorate(this, null, _colourBy_decorators, { kind: "accessor", name: "colourBy", static: false, private: false, access: { has: obj => "colourBy" in obj, get: obj => obj.colourBy, set: (obj, value) => { obj.colourBy = value; } }, metadata: _metadata }, _colourBy_initializers, _colourBy_extraInitializers);
             __esDecorate(this, null, _layers_decorators, { kind: "accessor", name: "layers", static: false, private: false, access: { has: obj => "layers" in obj, get: obj => obj.layers, set: (obj, value) => { obj.layers = value; } }, metadata: _metadata }, _layers_initializers, _layers_extraInitializers);
             __esDecorate(this, null, _budget_decorators, { kind: "accessor", name: "budget", static: false, private: false, access: { has: obj => "budget" in obj, get: obj => obj.budget, set: (obj, value) => { obj.budget = value; } }, metadata: _metadata }, _budget_initializers, _budget_extraInitializers);
-            __esDecorate(this, null, _budgetMin_decorators, { kind: "accessor", name: "budgetMin", static: false, private: false, access: { has: obj => "budgetMin" in obj, get: obj => obj.budgetMin, set: (obj, value) => { obj.budgetMin = value; } }, metadata: _metadata }, _budgetMin_initializers, _budgetMin_extraInitializers);
-            __esDecorate(this, null, _budgetMax_decorators, { kind: "accessor", name: "budgetMax", static: false, private: false, access: { has: obj => "budgetMax" in obj, get: obj => obj.budgetMax, set: (obj, value) => { obj.budgetMax = value; } }, metadata: _metadata }, _budgetMax_initializers, _budgetMax_extraInitializers);
             __esDecorate(this, null, _clusterBudget_decorators, { kind: "accessor", name: "clusterBudget", static: false, private: false, access: { has: obj => "clusterBudget" in obj, get: obj => obj.clusterBudget, set: (obj, value) => { obj.clusterBudget = value; } }, metadata: _metadata }, _clusterBudget_initializers, _clusterBudget_extraInitializers);
             __esDecorate(this, null, _tooltipFields_decorators, { kind: "accessor", name: "tooltipFields", static: false, private: false, access: { has: obj => "tooltipFields" in obj, get: obj => obj.tooltipFields, set: (obj, value) => { obj.tooltipFields = value; } }, metadata: _metadata }, _tooltipFields_initializers, _tooltipFields_extraInitializers);
             __esDecorate(this, null, _titleField_decorators, { kind: "accessor", name: "titleField", static: false, private: false, access: { has: obj => "titleField" in obj, get: obj => obj.titleField, set: (obj, value) => { obj.titleField = value; } }, metadata: _metadata }, _titleField_initializers, _titleField_extraInitializers);
@@ -550,51 +529,41 @@ let MosaicaMap = (() => {
         canBuildOwn = true;
         #colourBy_accessor_storage = __runInitializers(this, _colourBy_initializers, '');
         /**
-         * What the points are coloured by: a declared column that is rendered, `cluster:<layer>` for a
-         * layer that can colour, or `none` for one colour. Unset, the store's choice stands.
+         * What colours the points: a rendered column (one sent with the points), `cluster:<layer>` for a
+         * layer that can colour, or `none` for a single colour. Unset, the store's choice stands.
          */
         get colourBy() { return this.#colourBy_accessor_storage; }
         set colourBy(value) { this.#colourBy_accessor_storage = value; }
         #layers_accessor_storage = (__runInitializers(this, _colourBy_extraInitializers), __runInitializers(this, _layers_initializers, null));
         /**
-         * The annotation layers to draw, space- or comma-separated; each is drawn with the layers it
+         * The annotation layers to draw, separated by spaces or commas. Each also draws the layers it
          * depends on. Unset, the store's choice stands.
          */
         get layers() { return this.#layers_accessor_storage; }
         set layers(value) { this.#layers_accessor_storage = value; }
         #budget_accessor_storage = (__runInitializers(this, _layers_extraInitializers), __runInitializers(this, _budget_initializers, 0));
-        /** How many marks to aim for on screen. `0` leaves the store's budget, which starts at 250000. */
+        /** How many marks to aim for on screen. `0` keeps the store's budget, which starts at 250000. */
         get budget() { return this.#budget_accessor_storage; }
         set budget(value) { this.#budget_accessor_storage = value; }
-        #budgetMin_accessor_storage = (__runInitializers(this, _budget_extraInitializers), __runInitializers(this, _budgetMin_initializers, 1_000));
-        /** The fewest marks a control for `budget` offers. The map sets no budget from it. */
-        get budgetMin() { return this.#budgetMin_accessor_storage; }
-        set budgetMin(value) { this.#budgetMin_accessor_storage = value; }
-        #budgetMax_accessor_storage = (__runInitializers(this, _budgetMin_extraInitializers), __runInitializers(this, _budgetMax_initializers, 2_000_000));
-        /** The most marks a control for `budget` offers. The map sets no budget from it. */
-        get budgetMax() { return this.#budgetMax_accessor_storage; }
-        set budgetMax(value) { this.#budgetMax_accessor_storage = value; }
-        #clusterBudget_accessor_storage = (__runInitializers(this, _budgetMax_extraInitializers), __runInitializers(this, _clusterBudget_initializers, 0));
+        #clusterBudget_accessor_storage = (__runInitializers(this, _budget_extraInitializers), __runInitializers(this, _clusterBudget_initializers, 0));
         /**
-         * The most clusters a `nested` or `dag` layer is cut to (`Store.setClusterBudget`). `0` at first
-         * leaves the store's; `0` after a budget was set clears it, to the finest cut.
+         * 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.
          */
         get clusterBudget() { return this.#clusterBudget_accessor_storage; }
         set clusterBudget(value) { this.#clusterBudget_accessor_storage = value; }
         #tooltipFields_accessor_storage = (__runInitializers(this, _clusterBudget_extraInitializers), __runInitializers(this, _tooltipFields_initializers, ''));
         /**
-         * Columns shown beneath a hovered point's title, space- or comma-separated. The map asks the
-         * store for them with `setPointColumns`. Only a rendered column's value is in the marks; another
-         * shows nothing.
+         * 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.
          */
         get tooltipFields() { return this.#tooltipFields_accessor_storage; }
         set tooltipFields(value) { this.#tooltipFields_accessor_storage = value; }
         #titleField_accessor_storage = (__runInitializers(this, _tooltipFields_extraInitializers), __runInitializers(this, _titleField_initializers, ''));
         /**
-         * The field a hovered point is titled by, read from the marks where they carry it (the map asks
-         * the store for a rendered one with `setPointColumns`), else from the item's record once the
-         * pointer has rested on it for 140 ms. Unset, the title is the point's
-         * `mosaica_id`.
+         * The field that titles a point in the hover tooltip. A rendered column shows at once; any other
+         * field is read from the item's record once the pointer rests on the point. Unset, the title is
+         * the point's `mosaica_id`.
          */
         get titleField() { return this.#titleField_accessor_storage; }
         set titleField(value) { this.#titleField_accessor_storage = value; }
@@ -604,50 +573,39 @@ let MosaicaMap = (() => {
         set mode(value) { this.#mode_accessor_storage = value; }
         #palette_accessor_storage = (__runInitializers(this, _mode_extraInitializers), __runInitializers(this, _palette_initializers, ''));
         /**
-         * The palette clusters are coloured from under colour by cluster: `okabe-ito`, `tableau10`,
-         * `tableau20` or `kelly`, set on the store (`Store.setPalette`). Each cluster's colour is the
-         * palette's colour at the slot the server gives it. Unset, the store's palette stands, which is
-         * Tableau 10 until one is chosen.
+         * The palette clusters are coloured from when the points are coloured by a layer: `okabe-ito`,
+         * `tableau10`, `tableau20` or `kelly`. It is set on the store (`Store.setPalette`). Unset, the
+         * store's palette stands, which starts as `tableau10`.
          */
         get palette() { return this.#palette_accessor_storage; }
         set palette(value) { this.#palette_accessor_storage = value; }
         #clusterLevel_accessor_storage = (__runInitializers(this, _palette_extraInitializers), __runInitializers(this, _clusterLevel_initializers, null));
         /**
-         * The level of a `stacked` or `tiered` layer to colour, name and outline clusters at. Unset, the
-         * layer's top (coarsest) level. A `nested` or `dag` layer draws the cut served.
+         * 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.
          */
         get clusterLevel() { return this.#clusterLevel_accessor_storage; }
         set clusterLevel(value) { this.#clusterLevel_accessor_storage = value; }
         #basemap_accessor_storage = (__runInitializers(this, _clusterLevel_extraInitializers), __runInitializers(this, _basemap_initializers, null));
         /**
-         * What is drawn under the points: `world` (the server's world outline: land, coastlines and
-         * country borders), `none`, `{tiles, attribution}` (a tile server's URL template, with `{z}`,
-         * `{x}` and `{y}`, and its credit, shown in the bottom-right corner), `{image, bounds}` (one
-         * image over `[x0, y0, x1, y1]` in the view's coordinates, degrees on a geographic view, or over
-         * the whole frame), a mapping from view id to one of those, or a deck.gl layer the host built in
-         * the map's 512-unit world. The attribute takes `world` and `none`. Unset, or for a view a
-         * mapping leaves out, `world` on a view with a map projection and nothing on one without.
-         *
-         * An object with a `tiles` or `image` key is one value, and takes only the keys its form names;
-         * any other object is a mapping. A mapping's keys are view ids as `meta.views` lists them, so a
-         * view named `tiles` or `image` cannot be named in one; a key that names no view this viewer may
-         * reach is ignored, and every value must be one of the forms.
-         *
-         * The world outline needs a projection and tiles need the view's `tileScheme`. A value that does
-         * not fit the view it was given on, or that a mapping names for a view, is refused over the map
-         * with what to write instead; one value that does not fit a view switched to later draws nothing
-         * there, and a note in the bottom-right corner says why. The points are drawn either way. The
-         * code that draws a basemap is loaded the first time one is drawn.
+         * 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
+         * template with `{z}`, `{x}` and `{y}` and the credit to show, and needs a view with a
+         * `tileScheme`. `{image, bounds}` is one image over `[x0, y0, x1, y1]` in the view's coordinates
+         * (degrees on a geographic view), or over the whole frame without `bounds`. You can also pass
+         * `none`, a deck.gl layer you built in the map's 512-unit world, or an object mapping view ids to
+         * any of these for a different basemap per view. The attribute takes only `world` and `none`.
+         * Unset, a view with a map projection gets `world` and any other view gets nothing. A value that
+         * does not fit the view is shown as an error over the map; one that stops fitting after a switch
+         * of view draws nothing, and a note says why. The points are drawn either way.
          */
         get basemap() { return this.#basemap_accessor_storage; }
         set basemap(value) { this.#basemap_accessor_storage = value; }
         #ground_accessor_storage = (__runInitializers(this, _basemap_extraInitializers), __runInitializers(this, _ground_initializers, ''));
         /**
-         * The ground the map draws on, `light` or `dark`, where it differs from the page's, such as a
-         * light basemap under a dark page. The labels and the density colours follow it, and the
-         * toolbar and panels follow the page. Unset, the scheme the elements render in: the one the
-         * host's `color-scheme` names, the system preference where it names both, and light where it
-         * names neither.
+         * 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`.
          */
         get ground() { return this.#ground_accessor_storage; }
         set ground(value) { this.#ground_accessor_storage = value; }
@@ -657,35 +615,33 @@ let MosaicaMap = (() => {
         set noPoints(value) { this.#noPoints_accessor_storage = value; }
         #pointOpacity_accessor_storage = (__runInitializers(this, _noPoints_extraInitializers), __runInitializers(this, _pointOpacity_initializers, null));
         /**
-         * A fixed point alpha from 0.1 to 1. Unset, points are more transparent the more of them are
-         * drawn, so a dense region reads as a density.
+         * A fixed point opacity from 0.1 to 1. Unset, points get more transparent the more of them are
+         * drawn.
          */
         get pointOpacity() { return this.#pointOpacity_accessor_storage; }
         set pointOpacity(value) { this.#pointOpacity_accessor_storage = value; }
         #density_accessor_storage = (__runInitializers(this, _pointOpacity_extraInitializers), __runInitializers(this, _density_initializers, 'none'));
         /**
-         * How density is drawn under the points, from exact counts by cell (`POST /v1/aggregate`) and
-         * never from the points, which are a sample: `none`, `smooth` (a soft wash), `hex` (hexagons),
-         * `grid` (square cells) or `contours` (lines of equal density). It counts the highlighted items
-         * under a highlight, the matched items under a filter or selection, else the visible items.
+         * How density is drawn under the points: `none`, `smooth` (a soft wash), `hex` (hexagons),
+         * `grid` (square cells) or `contours` (lines of equal density). Density is counted by the server
+         * over every matching item, so it covers more than the sampled points drawn. It counts the
+         * highlighted items if there is a highlight, otherwise the items the filters and selection match.
          */
         get density() { return this.#density_accessor_storage; }
         set density(value) { this.#density_accessor_storage = value; }
         #densityResolution_accessor_storage = (__runInitializers(this, _density_extraInitializers), __runInitializers(this, _densityResolution_initializers, DEFAULT_DENSITY_CELL_PX));
         /**
-         * How large density's cells are on screen, in CSS pixels: 32, 24, 16, 12, 8, 6 or 4, and any
-         * other size is taken as the nearest of them. The cells asked for are those of the depth nearest
-         * that size at the current zoom. Where that depth's cells over the area asked for are more than
-         * the server's `selection.maxAggregateCells`, the finest size that fits is drawn instead;
-         * {@link MosaicaMap.densityStops} says which sizes fit.
+         * The size of density's cells on screen, in CSS pixels: 32, 24, 16, 12, 8, 6 or 4. Other values
+         * are rounded to the nearest of these. If the server's `selection.maxAggregateCells` does not
+         * allow that many cells, the finest size that fits is drawn; `densityStops()` says
+         * which sizes fit.
          */
         get densityResolution() { return this.#densityResolution_accessor_storage; }
         set densityResolution(value) { this.#densityResolution_accessor_storage = value; }
         #densityColours_accessor_storage = (__runInitializers(this, _densityResolution_extraInitializers), __runInitializers(this, _densityColours_initializers, ''));
         /**
          * The colours density is drawn in: `warm-grey`, `viridis`, `cividis`, `magma` or `greys`. Unset,
-         * the smooth wash under the points is warm grey and every other density is Viridis. While density
-         * is drawn in a ramp, or without the points, a key to the colours sits in the bottom-left corner.
+         * a `smooth` wash under the points is warm grey and anything else is `viridis`.
          */
         get densityColours() { return this.#densityColours_accessor_storage; }
         set densityColours(value) { this.#densityColours_accessor_storage = value; }
@@ -695,34 +651,29 @@ let MosaicaMap = (() => {
         set densityStrength(value) { this.#densityStrength_accessor_storage = value; }
         #densityScale_accessor_storage = (__runInitializers(this, _densityStrength_extraInitializers), __runInitializers(this, _densityScale_initializers, DEFAULT_DENSITY_SCALE));
         /**
-         * How a cell's count is placed between no items and the largest count drawn, which picks its
-         * colour: `linear`, in proportion to the count, or `log`, in proportion to `log(1 + count)`,
-         * which spreads counts that span several orders of magnitude. Log is the default because counts
-         * are skewed on most maps, and under linear only the densest few cells stand out from the rest.
-         * The largest count is that of the densest cell in the area counted, which is the view and a
-         * margin around it; the contours take it among the cells they merge to, and a hexagon is
-         * coloured by the densest cell under it. Any other value is taken as `log`.
+         * How a cell's count maps to a colour, from zero to the densest cell in and around the view:
+         * `linear`, or `log` on `log(1 + count)`. `log` is the default because counts are skewed on most
+         * maps, and on a linear scale only the densest few cells stand out. Any other value is taken as
+         * `log`.
          */
         get densityScale() { return this.#densityScale_accessor_storage; }
         set densityScale(value) { this.#densityScale_accessor_storage = value; }
         #categoryPalette_accessor_storage = (__runInitializers(this, _densityScale_extraInitializers), __runInitializers(this, _categoryPalette_initializers, ''));
         /**
-         * The palette a category column's values are coloured from: `tableau10`, `okabe-ito`, `set2` or
-         * `dark2`. Unset, the choice made in the explorer's Colour section stands, Tableau 10 until one
-         * is made.
+         * The palette for colouring by a category column: `tableau10`, `okabe-ito`, `set2` or `dark2`.
+         * Unset, the current choice stands, which starts as `tableau10`.
          */
         get categoryPalette() { return this.#categoryPalette_accessor_storage; }
         set categoryPalette(value) { this.#categoryPalette_accessor_storage = value; }
         #ramp_accessor_storage = (__runInitializers(this, _categoryPalette_extraInitializers), __runInitializers(this, _ramp_initializers, ''));
         /**
-         * The ramp a number column's values are coloured on: `viridis`, `cividis`, `magma`, `greys` or
-         * `red-blue`. Unset, the choice made in the explorer's Colour section stands, Viridis until one
-         * is made.
+         * The colour ramp for colouring by a number column: `viridis`, `cividis`, `magma`, `greys` or
+         * `red-blue`. Unset, the current choice stands, which starts as `viridis`.
          */
         get ramp() { return this.#ramp_accessor_storage; }
         set ramp(value) { this.#ramp_accessor_storage = value; }
         #rampScale_accessor_storage = (__runInitializers(this, _ramp_extraInitializers), __runInitializers(this, _rampScale_initializers, ''));
-        /** How numbers are placed on the ramp, `linear` or `log`. Unset, the Colour section's choice stands. */
+        /** How numbers are placed on the ramp, `linear` or `log`. Unset, the current choice stands. */
         get rampScale() { return this.#rampScale_accessor_storage; }
         set rampScale(value) { this.#rampScale_accessor_storage = value; }
         #rampReverse_accessor_storage = (__runInitializers(this, _rampScale_extraInitializers), __runInitializers(this, _rampReverse_initializers, false));
@@ -731,21 +682,19 @@ let MosaicaMap = (() => {
         set rampReverse(value) { this.#rampReverse_accessor_storage = value; }
         #valueColours_accessor_storage = (__runInitializers(this, _rampReverse_extraInitializers), __runInitializers(this, _valueColours_initializers, null));
         /**
-         * Colours for single category values, per column, per category key, as `#rrggbb`, such as
-         * `{field: {'cs.CV': '#f28e2b'}}`. Setting it replaces every value colour chosen before,
-         * including those chosen on a field card; a host restores a viewer's saved choices this way,
-         * having kept them from `mosaica-valuecolour`. Unset, the choices made on the cards stand.
+         * Colours for individual category values, by column and category key, as `#rrggbb`, such as
+         * `{field: {'cs.CV': '#f28e2b'}}`. Setting it replaces every value colour chosen before, including
+         * those chosen on a field card. Use it to restore choices you saved from `mosaica-valuecolour`.
          */
         get valueColours() { return this.#valueColours_accessor_storage; }
         set valueColours(value) { this.#valueColours_accessor_storage = value; }
         #clusterColours_accessor_storage = (__runInitializers(this, _valueColours_extraInitializers), __runInitializers(this, _clusterColours_initializers, null));
         /**
-         * Colours for single clusters, per layer, per `mosaica_id` as a decimal string, as `#rrggbb`, such
-         * as `{topics: {'4021': '#f28e2b'}}`, set on the store in place of their palette colours
+         * Colours for individual clusters, by layer and `mosaica_id` (as a decimal string), as `#rrggbb`,
+         * such as `{topics: {'4021': '#f28e2b'}}`. They replace the palette colours
          * (`Store.setArtifactColours`). Setting it replaces every cluster colour chosen before, including
-         * those chosen on a field card or in Edit colours; a host restores a viewer's saved choices this
-         * way, having kept them from `mosaica-clustercolour`. An entry that is not a `mosaica_id` and a
-         * `#rrggbb` colour is skipped. Unset, the choices made on the cards stand.
+         * those chosen on a field card or in Edit colours. Use it to restore choices you saved from
+         * `mosaica-clustercolour`. Invalid entries are skipped.
          */
         get clusterColours() { return this.#clusterColours_accessor_storage; }
         set clusterColours(value) { this.#clusterColours_accessor_storage = value; }
@@ -761,39 +710,40 @@ let MosaicaMap = (() => {
         set measure(value) { this.#measure_accessor_storage = value; }
         #radius_accessor_storage = (__runInitializers(this, _measure_extraInitializers), __runInitializers(this, _radius_initializers, null));
         /**
-         * A fixed point radius in pixels. Unset, points are sized by how many are drawn and by the zoom.
-         * Under `size-by`, the size column sizes the points in its place.
+         * A fixed point radius in pixels. Unset, the radius depends on how many points are drawn and on
+         * the zoom. Ignored while `size-by` names a column.
          */
         get radius() { return this.#radius_accessor_storage; }
         set radius(value) { this.#radius_accessor_storage = value; }
         #sizeBy_accessor_storage = (__runInitializers(this, _radius_extraInitializers), __runInitializers(this, _sizeBy_initializers, ''));
         /**
-         * What the points are sized by: a declared number column that is rendered, or `none` for one
-         * size. Each point's value is placed between `size-min` and `size-max` on `size-scale`, against
-         * the range of the values drawn, or under rank a sample of them; a point with no value, NaN or an
-         * infinity draws as a ring, at `size-min` or 3 px, whichever is larger. The column arrives with
-         * the points, so choosing one sends no request. Unset, the store's choice stands.
+         * The rendered number column that sizes the points, or `none` for a single size. Each value is
+         * placed between `size-min` and `size-max` on `size-scale`, against the range of the values
+         * drawn. A point with no value, NaN or an infinity is drawn as a ring. Unset, the store's choice
+         * stands.
          */
         get sizeBy() { return this.#sizeBy_accessor_storage; }
         set sizeBy(value) { this.#sizeBy_accessor_storage = value; }
         #sizeMin_accessor_storage = (__runInitializers(this, _sizeBy_extraInitializers), __runInitializers(this, _sizeMin_initializers, null));
         /**
-         * The radius in pixels of the smallest value under `size-by`. A value that is not a finite number
-         * above zero is ignored. Unset, the choice made in the explorer stands, 2 until one is made.
+         * The radius in pixels of the smallest value under `size-by`. A value that is not above zero is
+         * ignored. Unset, the
+         * current choice stands, which starts at 2.
          */
         get sizeMin() { return this.#sizeMin_accessor_storage; }
         set sizeMin(value) { this.#sizeMin_accessor_storage = value; }
         #sizeMax_accessor_storage = (__runInitializers(this, _sizeMin_extraInitializers), __runInitializers(this, _sizeMax_initializers, null));
         /**
-         * The radius in pixels of the largest value under `size-by`. A value that is not a finite number
-         * above zero is ignored. Unset, the choice made in the explorer stands, 9 until one is made.
+         * The radius in pixels of the largest value under `size-by`. A value that is not above zero is
+         * ignored. Unset, the
+         * current choice stands, which starts at 9.
          */
         get sizeMax() { return this.#sizeMax_accessor_storage; }
         set sizeMax(value) { this.#sizeMax_accessor_storage = value; }
         #sizeScale_accessor_storage = (__runInitializers(this, _sizeMax_extraInitializers), __runInitializers(this, _sizeScale_initializers, ''));
         /**
          * How values are placed between the two sizes: `linear`, `log`, or `rank` among a sample of the
-         * values drawn. Unset, the choice made in the explorer stands, linear until one is made.
+         * values drawn. Unset, the current choice stands, which starts as `linear`.
          */
         get sizeScale() { return this.#sizeScale_accessor_storage; }
         set sizeScale(value) { this.#sizeScale_accessor_storage = value; }
@@ -803,8 +753,9 @@ let MosaicaMap = (() => {
         set noControls(value) { this.#noControls_accessor_storage = value; }
         #controlsCorner_accessor_storage = (__runInitializers(this, _noControls_extraInitializers), __runInitializers(this, _controlsCorner_initializers, 'top-left'));
         /**
-         * Which corner the toolbar sits in: `top-left`, `top-right`, `bottom-left` or `bottom-right`. In
-         * a top corner the corner's slotted content is below the toolbar; in a bottom corner, above it.
+         * 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
+         * bottom corner.
          */
         get controlsCorner() { return this.#controlsCorner_accessor_storage; }
         set controlsCorner(value) { this.#controlsCorner_accessor_storage = value; }
@@ -825,15 +776,15 @@ let MosaicaMap = (() => {
         get dragPolygon() { return this.#dragPolygon_accessor_storage; }
         set dragPolygon(value) { this.#dragPolygon_accessor_storage = value; }
         /**
-         * What the last click found where it found no item: `{kind: 'miss'}`, or a broken pick, a fault
-         * in the layer, with its details. `null` after a hit. `<mosaica-item-card>`'s `pick` takes it.
+         * What the last click found if it found no item: `{kind: 'miss'}`, or `{kind: 'broken', ...}`
+         * with details of a fault in the layer. `null` after a hit. Pass it to `<mosaica-item-card>`'s
+         * `pick`.
          */
         lastPick = (__runInitializers(this, _dragPolygon_extraInitializers), null);
         /**
-         * What the last click picked and where: an item or an artifact, by `mosaicaId`, and the world
-         * position the card for it points at, the picked point's own or, for an artifact, where the click
-         * landed. `null` before a pick, after a miss and after a switch of view. `<mosaica-explorer>`
-         * places its callout from it through {@link MosaicaMap.screenOf}.
+         * What the last click picked, an item or an artifact, and where in world coordinates: the point's
+         * position, or where the click landed on an artifact. `null` before a pick, after a miss and after
+         * a switch of view. Pass `world` to `screenOf()` to place a card beside it.
          */
         pickedAt = null;
         /** The map's probe, one object mutated in place, for instruments and tests. @internal */
@@ -1081,9 +1032,8 @@ let MosaicaMap = (() => {
             this.densityCounter?.set({ on: this.density !== 'none', cellPx: this.densityResolution });
         }
         /**
-         * The resolution stops at the camera as it stands: each cell size, the depth it asks for, and
-         * whether that depth's cells over the area asked for fit the server's
-         * `selection.maxAggregateCells`. Every stop is enabled before `meta` has arrived.
+         * The density cell sizes `density-resolution` offers at the current camera, each with whether the
+         * server's `selection.maxAggregateCells` allows it. Every size is allowed before `meta` has loaded.
          */
         densityStops() {
             return this.densityCounter?.stops() ?? [];
@@ -1336,7 +1286,7 @@ let MosaicaMap = (() => {
             }
             return { layer, layersOn: a.layers, coverage: a.coverage, servedIds: rows.map((x) => idString(x.mosaicaId)), sample, coloured };
         }
-        /** Dispose of the store this map built, as on every element, and release its GPU resources now. */
+        /** Dispose of the store this map built and release its GPU resources now. */
         dispose() {
             this.densityCounter?.dispose();
             this.densityCounter = null;
@@ -1617,9 +1567,8 @@ let MosaicaMap = (() => {
                 super.focus(options);
         }
         /**
-         * Drop the selection: forget the last pick and the ring drawn round the picked point, and clear
-         * the store's selection, which closes the card it opened. A click on empty map and Escape call
-         * it. A selected region stays.
+         * Drop the picked item or artifact and the ring around it, and clear the store's selection, which
+         * closes its card. A click on an empty part of the map does the same. A selected region stays.
          */
         clearPick() {
             this.lastPick = null;
@@ -1828,13 +1777,13 @@ let MosaicaMap = (() => {
             const s = this.resolvedStore;
             return drawnLevel(s?.get('meta') ?? null, s?.get('artifacts') ?? null, s?.get('legend').colourBy, this.clusterLevel ?? undefined);
         }
-        /** The ground the map draws on now: `ground` where it is set, else the page's colour scheme. */
+        /** Whether the map is drawn on a light or dark background now: `ground` if set, else the page's scheme. */
         get drawnGround() {
             return this.scheme();
         }
         /**
-         * A world position in the map's pixels, from its top-left corner, under the camera as it stands.
-         * A position off the map falls outside `[0, width] × [0, height]`.
+         * Convert a world position to pixels from the map's top-left corner, under the current camera. A
+         * position off the map falls outside `[0, width] × [0, height]`.
          */
         screenOf(world) {
             // The orthographic camera, y down: world units scale by 2^zoom about the target at the centre.
@@ -1843,7 +1792,7 @@ let MosaicaMap = (() => {
             const [tx, ty] = this.viewState.target;
             return [(world[0] - tx) * scale + width / 2, (world[1] - ty) * scale + height / 2];
         }
-        /** The camera's zoom: 0 when the 512-unit world fills 512 px, +1 per doubling. */
+        /** The camera's zoom: 0 when the 512-unit world is 512 pixels wide, and 1 more per doubling. */
         get zoom() {
             return this.viewState.zoom;
         }
@@ -1852,11 +1801,10 @@ let MosaicaMap = (() => {
         /** Whether the map frames the matches when it is next connected: it left the page with a framing pending. */
         frameOnConnect = false;
         /**
-         * Frame the items the store's filters and selected region match: the box {@link frameMatches}
-         * gives, which holds every one of them, fitted to 92% of the map along the side that limits it.
-         * Where nothing matches, or the server refuses the count, the whole extent is fitted instead.
-         * The camera moves once the count lands, unless it is moved before then. A map off the page
-         * frames once it is back on it. Resolves when the camera has moved or the framing was cancelled.
+         * Move the camera to frame every item the filters and selected region match, filling 92% of the
+         * map. If nothing matches, or the server refuses, it frames the whole extent. The camera moves
+         * when the server answers, unless it is moved first. Resolves when the camera has moved or
+         * the move was cancelled.
          */
         async fit() {
             const s = this.resolvedStore;
@@ -1881,10 +1829,7 @@ let MosaicaMap = (() => {
             this.framing = null;
             this.frameOnConnect = false;
         }
-        /**
-         * Centre the camera on a data coordinate at the current zoom. Returns false before `meta`, when
-         * there is no frame to convert against.
-         */
+        /** Centre the camera on a point in data coordinates, keeping the zoom. Returns false before `meta` has loaded. */
         lookAt(x, y) {
             const q = this.resolvedStore?.frame();
             if (!q)
@@ -1893,7 +1838,10 @@ let MosaicaMap = (() => {
             this.setViewState({ target: [wx, wy, 0] });
             return true;
         }
-        /** Fit a served artifact's box into the map. Returns false where the store holds no box for it. */
+        /**
+         * Fit the camera to an artifact's bounding box. Returns false if the artifact is not among those
+         * currently drawn (`artifacts.served`) or has no box.
+         */
         fitTo(artifactId) {
             const extent = this.resolvedStore?.extentOf(artifactId);
             if (!extent)
@@ -1901,11 +1849,11 @@ let MosaicaMap = (() => {
             return this.fitBbox(extent);
         }
         /**
-         * Fit a box `[x0, y0, x1, y1]` in data coordinates, the space `mosaica-viewchange` reports, into
-         * the map. The camera keeps the canvas's aspect, so the box shown contains the one asked for,
-         * and the next `mosaica-viewchange` reports the box shown. `fill` is the share of the map the
-         * box takes along the side that limits it, 2^-0.3 (about 81%) unless given; at 1 a box
-         * `mosaica-viewchange` reported is fitted back to the same camera. Returns false before `meta`.
+         * Fit the camera to a box `[x0, y0, x1, y1]` in data coordinates, as `mosaica-viewchange`
+         * reports them. The canvas keeps its aspect ratio, so the area shown contains the box. `fill` is
+         * the share of the map the box fills along its tighter side, about 81% by default; pass `1` to
+         * restore a camera from a box `mosaica-viewchange` reported. Returns false before `meta` has
+         * loaded.
          */
         fitBbox(extent, fill = 2 ** -0.3) {
             const q = this.resolvedStore?.frame();