@mosaicajs/components 0.1.0-rc.4 → 0.1.0

package/dist/colour-editor.d.ts

@@ -11,40 +11,20 @@ type Found = {
     rung: number;
 };
 /**
- * Edit colours: every value of a category field, or every cluster of a layer, with its colour, to
- * search, choose colours for and reset. `field` is a column `meta.declaredScalars` lists as a
- * rendered category, or `cluster:<layer>` for a layer the points can be coloured by. `show()` opens
- * it as a modal dialog, and Close, Done or Escape closes it and gives focus back to what had it.
+ * Use the colour editor when viewers should choose their own colours while the map is coloured by a
+ * category or a layer. The explorer's Edit colours button opens it. In your own layout, set `field`
+ * to a rendered category column or to `cluster:<layer>`, then call `show()` to open the dialog.
  *
- * The rows are a category's values, a flat layer's clusters, a `stacked` or `tiered` layer's
- * clusters at `cluster-level` (its top level where unset), or on a `nested` or `dag` layer the
- * clusters of the cut the map draws (`cut: 'drawn'`), which the layer's field card ranks too, and
- * which changes as the camera does. Each row has a checkbox, its colour, its name (a cluster's two
- * nearest parents in grey under it) and its count over everything the viewer may see, with no
- * filter and no area, so the rows hold their order, largest first, through a pan or a change of
- * filter. The counts come from one aggregate (`Store.setAggregate`, `subject: 'visible'`) of up to
- * `meta.selection.max_aggregate_top` rows, registered while the dialog is open. A category value
- * the map has not drawn yet has no palette colour, and its swatch is an outline until it has one.
- * Changing `field` or `cluster-level` while the dialog is open lists the new field's rows, and
- * closes the dialog where the field is neither a category nor a layer that colours.
+ * Each row counts the items the viewer may see with that value, ignoring the filters and the
+ * camera, so the rows keep their order as the viewer pans or filters. For a `nested` or `dag`
+ * layer, the rows are the clusters the map currently draws, and the search box reaches the rest. To
+ * recolour several rows at once, viewers tick them and press Set colour.
  *
- * The search box is the field card's: `<mosaica-filter>`'s typeahead over a category's values, or
- * `<mosaica-cluster-filter>`'s over every name in the layer, at any depth of a tree. Choosing a
- * match that the list holds moves focus to its row; any other goes at the top of the list, with
- * its count, until the dialog closes.
+ * The colours are kept in the store, so every element that uses the store shows a change at once.
+ * Each change also fires one `mosaica-valuecolour` or `mosaica-clustercolour` event naming every
+ * value or cluster it changed.
  *
- * A row's colour is a button that opens the colour picker the field cards use. Ticking rows shows
- * how many are ticked, Set colour, which opens the picker and gives the colour chosen to every row
- * ticked, and Deselect. Reset to palette gives every value of the field, or every cluster of the
- * layer, its palette colour back. Under the list is how many colours are chosen for the field or
- * the layer.
- *
- * Each action fires one event: `mosaica-valuecolour` for a category, or `mosaica-clustercolour`
- * for a layer, naming every value or cluster it changed. A category's colours are written to the
- * colour choices every element over the store shares, and a layer's are set on the store with the
- * colours chosen for every layer (`Store.setArtifactColours`); the dialog keeps no colour itself.
- *
- * @summary Every value or cluster's colour, to search, choose and reset.
+ * @summary A dialog for choosing the colour of each category value or cluster.
  * @tagname mosaica-colour-editor
  * @category Elements
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-valuecolour']>} mosaica-valuecolour - Colours
@@ -57,11 +37,11 @@ type Found = {
  * @csspart close - The close button.
  * @csspart columns - The headings over the rows.
  * @csspart rows - The list of rows.
- * @csspart row - One row, with `data-key`, `data-found` where the search box found it, and
+ * @csspart row - One row, with `data-key`, `data-found` if the search box found it, and
  *   `data-ticked` while it is ticked.
  * @csspart check - A row's checkbox.
- * @csspart swatch - A row's colour, a button that opens the colour picker, with `data-unmet` and
- *   drawn as an outline for a category value the map has given no colour yet.
+ * @csspart swatch - A row's colour button, which opens the colour picker. It carries `data-unmet`,
+ *   and is drawn as an outline, for a value the map has not given a colour yet.
  * @csspart name - A row's name, with `data-unnamed` for a cluster that has none.
  * @csspart path - A cluster row's parents.
  * @csspart count - A row's count over everything the viewer may see.
@@ -84,7 +64,7 @@ export declare class MosaicaColourEditor extends MosaicaElement {
     static styles: import("lit").CSSResult[];
     /** What the dialog colours: a rendered category column, or `cluster:<layer>`. */
     accessor field: string;
-    /** The level of a `stacked` or `tiered` layer whose clusters are listed; `null` is its top level. */
+    /** The level of a `stacked` or `tiered` layer whose clusters are listed. `null` is the coarsest level. */
     accessor level: number | null;
     /** Whether the dialog is open. @internal */
     accessor isOpen: boolean;
@@ -103,7 +83,7 @@ export declare class MosaicaColourEditor extends MosaicaElement {
     private pathFrame;
     /** Open the dialog. */
     show(): Promise<void>;
-    /** Close the dialog, giving focus back to what had it as it opened. */
+    /** Close the dialog and return focus to the element that had it before. */
     close(): void;
     protected onStoreAdopted(store: Store | null): void;
     protected resetServerData(): void;

package/dist/colour-editor.js

@@ -54,40 +54,20 @@ const ROW_HEIGHT = 40;
 /** The rows whose paths are asked for before the list has been measured. */
 const FIRST_ROWS = 8;
 /**
- * Edit colours: every value of a category field, or every cluster of a layer, with its colour, to
- * search, choose colours for and reset. `field` is a column `meta.declaredScalars` lists as a
- * rendered category, or `cluster:<layer>` for a layer the points can be coloured by. `show()` opens
- * it as a modal dialog, and Close, Done or Escape closes it and gives focus back to what had it.
+ * Use the colour editor when viewers should choose their own colours while the map is coloured by a
+ * category or a layer. The explorer's Edit colours button opens it. In your own layout, set `field`
+ * to a rendered category column or to `cluster:<layer>`, then call `show()` to open the dialog.
  *
- * The rows are a category's values, a flat layer's clusters, a `stacked` or `tiered` layer's
- * clusters at `cluster-level` (its top level where unset), or on a `nested` or `dag` layer the
- * clusters of the cut the map draws (`cut: 'drawn'`), which the layer's field card ranks too, and
- * which changes as the camera does. Each row has a checkbox, its colour, its name (a cluster's two
- * nearest parents in grey under it) and its count over everything the viewer may see, with no
- * filter and no area, so the rows hold their order, largest first, through a pan or a change of
- * filter. The counts come from one aggregate (`Store.setAggregate`, `subject: 'visible'`) of up to
- * `meta.selection.max_aggregate_top` rows, registered while the dialog is open. A category value
- * the map has not drawn yet has no palette colour, and its swatch is an outline until it has one.
- * Changing `field` or `cluster-level` while the dialog is open lists the new field's rows, and
- * closes the dialog where the field is neither a category nor a layer that colours.
+ * Each row counts the items the viewer may see with that value, ignoring the filters and the
+ * camera, so the rows keep their order as the viewer pans or filters. For a `nested` or `dag`
+ * layer, the rows are the clusters the map currently draws, and the search box reaches the rest. To
+ * recolour several rows at once, viewers tick them and press Set colour.
  *
- * The search box is the field card's: `<mosaica-filter>`'s typeahead over a category's values, or
- * `<mosaica-cluster-filter>`'s over every name in the layer, at any depth of a tree. Choosing a
- * match that the list holds moves focus to its row; any other goes at the top of the list, with
- * its count, until the dialog closes.
+ * The colours are kept in the store, so every element that uses the store shows a change at once.
+ * Each change also fires one `mosaica-valuecolour` or `mosaica-clustercolour` event naming every
+ * value or cluster it changed.
  *
- * A row's colour is a button that opens the colour picker the field cards use. Ticking rows shows
- * how many are ticked, Set colour, which opens the picker and gives the colour chosen to every row
- * ticked, and Deselect. Reset to palette gives every value of the field, or every cluster of the
- * layer, its palette colour back. Under the list is how many colours are chosen for the field or
- * the layer.
- *
- * Each action fires one event: `mosaica-valuecolour` for a category, or `mosaica-clustercolour`
- * for a layer, naming every value or cluster it changed. A category's colours are written to the
- * colour choices every element over the store shares, and a layer's are set on the store with the
- * colours chosen for every layer (`Store.setArtifactColours`); the dialog keeps no colour itself.
- *
- * @summary Every value or cluster's colour, to search, choose and reset.
+ * @summary A dialog for choosing the colour of each category value or cluster.
  * @tagname mosaica-colour-editor
  * @category Elements
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-valuecolour']>} mosaica-valuecolour - Colours
@@ -100,11 +80,11 @@ const FIRST_ROWS = 8;
  * @csspart close - The close button.
  * @csspart columns - The headings over the rows.
  * @csspart rows - The list of rows.
- * @csspart row - One row, with `data-key`, `data-found` where the search box found it, and
+ * @csspart row - One row, with `data-key`, `data-found` if the search box found it, and
  *   `data-ticked` while it is ticked.
  * @csspart check - A row's checkbox.
- * @csspart swatch - A row's colour, a button that opens the colour picker, with `data-unmet` and
- *   drawn as an outline for a category value the map has given no colour yet.
+ * @csspart swatch - A row's colour button, which opens the colour picker. It carries `data-unmet`,
+ *   and is drawn as an outline, for a value the map has not given a colour yet.
  * @csspart name - A row's name, with `data-unnamed` for a cluster that has none.
  * @csspart path - A cluster row's parents.
  * @csspart count - A row's count over everything the viewer may see.
@@ -364,7 +344,7 @@ let MosaicaColourEditor = (() => {
         get field() { return this.#field_accessor_storage; }
         set field(value) { this.#field_accessor_storage = value; }
         #level_accessor_storage = (__runInitializers(this, _field_extraInitializers), __runInitializers(this, _level_initializers, null));
-        /** The level of a `stacked` or `tiered` layer whose clusters are listed; `null` is its top level. */
+        /** The level of a `stacked` or `tiered` layer whose clusters are listed. `null` is the coarsest level. */
         get level() { return this.#level_accessor_storage; }
         set level(value) { this.#level_accessor_storage = value; }
         #isOpen_accessor_storage = (__runInitializers(this, _level_extraInitializers), __runInitializers(this, _isOpen_initializers, false));
@@ -407,7 +387,7 @@ let MosaicaColourEditor = (() => {
             }
             dialog.focus();
         }
-        /** Close the dialog, giving focus back to what had it as it opened. */
+        /** Close the dialog and return focus to the element that had it before. */
         close() {
             if (!this.isOpen)
                 return;

package/dist/context.d.ts

@@ -1,9 +1,9 @@
 import type { Store } from '@mosaicajs/client';
 /**
- * The Lit context the elements find their store by. `<mosaica-store>` and `<mosaica-explorer>`
- * provide it; a host with its own provider (a `ContextProvider` from `@lit/context`) provides a
- * store under this key. The key is `Symbol.for('mosaica.store')`, so two copies of the package
- * on one page share it.
+ * The Lit context through which elements find their store. `<mosaica-store>` and
+ * `<mosaica-explorer>` provide it. To supply a store from your own element, provide it under this
+ * context with a `ContextProvider` from `@lit/context`. The key is `Symbol.for('mosaica.store')`,
+ * so two copies of the package on one page share it.
  */
 export declare const storeContext: {
     __context__: Store | null;

package/dist/context.js

@@ -1,8 +1,8 @@
 import { createContext } from '@lit/context';
 /**
- * The Lit context the elements find their store by. `<mosaica-store>` and `<mosaica-explorer>`
- * provide it; a host with its own provider (a `ContextProvider` from `@lit/context`) provides a
- * store under this key. The key is `Symbol.for('mosaica.store')`, so two copies of the package
- * on one page share it.
+ * The Lit context through which elements find their store. `<mosaica-store>` and
+ * `<mosaica-explorer>` provide it. To supply a store from your own element, provide it under this
+ * context with a `ContextProvider` from `@lit/context`. The key is `Symbol.for('mosaica.store')`,
+ * so two copies of the package on one page share it.
  */
 export const storeContext = createContext(Symbol.for('mosaica.store'));

package/dist/count.d.ts

@@ -1,37 +1,38 @@
 import { LitElement, nothing, type TemplateResult } from 'lit';
 import { type Count, type Masked } from '@mosaicajs/client';
 /**
- * Renders a `Count` or a `Masked` through the client's `formatCount` and `formatMasked`, in the text
- * face with tabular figures. A sample (`count`) shows both figures, as `4,812 of 12,465`, or neither
- * when the count is inexact; a scalar (`masked`) shows one figure, marked `≈` when inexact. Nothing
- * is rendered while `stale` is set. With both properties set, `count` is rendered.
+ * Use `<mosaica-count>` when you build your own panel from the store's projections and want its
+ * counts to look like those of the other elements. It has no store, so you set its properties
+ * yourself.
  *
- * This element takes no store; the host or another element sets its properties.
+ * A sample `Count` set in `count` shows as `4,812 of 12,465`, the marks shown out of those served.
+ * A `Masked` count set in `masked` shows as one figure, marked `≈` when it is an estimate. When
+ * both are set, the element shows `count`. It shows nothing for an inexact sample, or for any count
+ * while `stale` is set.
  *
- * @summary A sample count or a masked count, formatted.
+ * @summary A single formatted count.
  * @tagname mosaica-count
  * @category Elements
- * @csspart count - The figure. Carries `data-kind` (`sample`, `scalar` or `none`), `data-exact`
- *   (`true` or `false`), `data-empty` (`true` when nothing was rendered) and, under
- *   `figure="shown"`, `data-total` with the total.
- * @csspart label - The `label` text after the figure, rendered only when the figure is.
+ * @csspart count - The figure, with `data-kind` (`sample`, `scalar` or `none`), `data-exact` (`true`
+ *   or `false`), `data-empty` (`true` if nothing is shown) and, with `figure="shown"`, `data-total`.
+ * @csspart label - The `label` text after the figure, shown only with the figure.
  */
 export declare class MosaicaCount extends LitElement {
     static styles: import("lit").CSSResult[];
     /** A sample count: how many marks are shown of how many are served. */
     accessor count: Count | null;
-    /** A masked count over the viewer's visible set, rendered where `count` is not set. */
+    /** A masked count over the items the viewer may see. Shown if `count` is not set. */
     accessor masked: Masked | null;
-    /** Renders nothing, since the figures predate a change to the corpus. */
+    /** Shows nothing, for a count that is out of date because the data changed. */
     accessor stale: boolean;
     /** Text rendered after the figure, such as `matched`. */
     accessor label: string;
     /**
-     * `both` renders a sample as `shown of total`; `shown` renders the shown figure alone and puts
-     * the total on the part's `data-total`. The figure is empty exactly when the pair would be.
+     * `both` shows a sample as `shown of total`. `shown` shows the shown figure alone and puts the
+     * total in the `count` part's `data-total`.
      */
     accessor figure: 'both' | 'shown';
-    /** Shortens figures of a thousand or more to one decimal, as `16.8M`, where room is short. */
+    /** Shortens figures of a thousand or more to one decimal, as `16.8M`. */
     accessor compact: boolean;
     render(): TemplateResult | typeof nothing;
 }

package/dist/count.js

@@ -38,20 +38,21 @@ import { formatCount, formatMasked } from '@mosaicajs/client';
 import { attachContextRoot, defineOnce } from './define.js';
 import { tokens } from './tokens.js';
 /**
- * Renders a `Count` or a `Masked` through the client's `formatCount` and `formatMasked`, in the text
- * face with tabular figures. A sample (`count`) shows both figures, as `4,812 of 12,465`, or neither
- * when the count is inexact; a scalar (`masked`) shows one figure, marked `≈` when inexact. Nothing
- * is rendered while `stale` is set. With both properties set, `count` is rendered.
+ * Use `<mosaica-count>` when you build your own panel from the store's projections and want its
+ * counts to look like those of the other elements. It has no store, so you set its properties
+ * yourself.
  *
- * This element takes no store; the host or another element sets its properties.
+ * A sample `Count` set in `count` shows as `4,812 of 12,465`, the marks shown out of those served.
+ * A `Masked` count set in `masked` shows as one figure, marked `≈` when it is an estimate. When
+ * both are set, the element shows `count`. It shows nothing for an inexact sample, or for any count
+ * while `stale` is set.
  *
- * @summary A sample count or a masked count, formatted.
+ * @summary A single formatted count.
  * @tagname mosaica-count
  * @category Elements
- * @csspart count - The figure. Carries `data-kind` (`sample`, `scalar` or `none`), `data-exact`
- *   (`true` or `false`), `data-empty` (`true` when nothing was rendered) and, under
- *   `figure="shown"`, `data-total` with the total.
- * @csspart label - The `label` text after the figure, rendered only when the figure is.
+ * @csspart count - The figure, with `data-kind` (`sample`, `scalar` or `none`), `data-exact` (`true`
+ *   or `false`), `data-empty` (`true` if nothing is shown) and, with `figure="shown"`, `data-total`.
+ * @csspart label - The `label` text after the figure, shown only with the figure.
  */
 let MosaicaCount = (() => {
     let _classSuper = LitElement;
@@ -112,11 +113,11 @@ let MosaicaCount = (() => {
         get count() { return this.#count_accessor_storage; }
         set count(value) { this.#count_accessor_storage = value; }
         #masked_accessor_storage = (__runInitializers(this, _count_extraInitializers), __runInitializers(this, _masked_initializers, null));
-        /** A masked count over the viewer's visible set, rendered where `count` is not set. */
+        /** A masked count over the items the viewer may see. Shown if `count` is not set. */
         get masked() { return this.#masked_accessor_storage; }
         set masked(value) { this.#masked_accessor_storage = value; }
         #stale_accessor_storage = (__runInitializers(this, _masked_extraInitializers), __runInitializers(this, _stale_initializers, false));
-        /** Renders nothing, since the figures predate a change to the corpus. */
+        /** Shows nothing, for a count that is out of date because the data changed. */
         get stale() { return this.#stale_accessor_storage; }
         set stale(value) { this.#stale_accessor_storage = value; }
         #label_accessor_storage = (__runInitializers(this, _stale_extraInitializers), __runInitializers(this, _label_initializers, ''));
@@ -125,13 +126,13 @@ let MosaicaCount = (() => {
         set label(value) { this.#label_accessor_storage = value; }
         #figure_accessor_storage = (__runInitializers(this, _label_extraInitializers), __runInitializers(this, _figure_initializers, 'both'));
         /**
-         * `both` renders a sample as `shown of total`; `shown` renders the shown figure alone and puts
-         * the total on the part's `data-total`. The figure is empty exactly when the pair would be.
+         * `both` shows a sample as `shown of total`. `shown` shows the shown figure alone and puts the
+         * total in the `count` part's `data-total`.
          */
         get figure() { return this.#figure_accessor_storage; }
         set figure(value) { this.#figure_accessor_storage = value; }
         #compact_accessor_storage = (__runInitializers(this, _figure_extraInitializers), __runInitializers(this, _compact_initializers, false));
-        /** Shortens figures of a thousand or more to one decimal, as `16.8M`, where room is short. */
+        /** Shortens figures of a thousand or more to one decimal, as `16.8M`. */
         get compact() { return this.#compact_accessor_storage; }
         set compact(value) { this.#compact_accessor_storage = value; }
         render() {

package/dist/events.d.ts

@@ -10,29 +10,29 @@ export type SelectionShapeDetail = Exclude<SelectionShape, {
     outside?: boolean;
 };
 /**
- * Every event the elements fire, by name, with its `detail`. Each bubbles and is composed, so a
- * host listens on any ancestor, including one outside `<mosaica-explorer>`. A `mosaica_id` crosses
- * as a decimal string, since it is a 64-bit integer.
+ * Every event the elements fire, by name, with the type of its `detail`. Each event bubbles and is
+ * composed, so you can listen on any ancestor, including one outside `<mosaica-explorer>`. A
+ * `mosaica_id` is sent as a decimal string, since it is a 64-bit integer.
  */
 export type MosaicaEventDetails = {
     /**
-     * The panel state moved from `from` to `to`; `from` is null on the first render. `refusal` is
-     * the store's `status.refusal`, whose `code`, `detail` and HTTP `status` say what went wrong
-     * where `to` is `refused`, `unanswered`, `busy` or `expired`, and is null otherwise.
+     * The panel state changed from `from` to `to`; `from` is null on the first render. If `to` is
+     * `refused`, `unanswered`, `busy` or `expired`, `refusal` says what went wrong; otherwise it is
+     * null.
      */
     'mosaica-statechange': {
         from: PanelState | null;
         to: PanelState;
         refusal: Refusal | null;
     };
-    /** The session expired; `refusal` is the refusal that ended it, where one did. */
+    /** The session expired. `refusal` is the server's refusal that ended it, if there was one. */
     'mosaica-expired': {
         refusal: Refusal | null;
     };
     /**
-     * The camera moved. `bbox` is `[x0, y0, x1, y1]` in the view's data coordinates, `zoom` the
-     * map's zoom (0 when the 512-unit world fills 512 pixels, one more per doubling), and `width` and
-     * `height` the canvas in CSS pixels.
+     * The camera moved. `bbox` is the area shown, `[x0, y0, x1, y1]` in the view's data coordinates.
+     * `zoom` is 0 when the 512-unit world is 512 pixels wide, and 1 more per doubling. `width` and
+     * `height` are the canvas size in CSS pixels.
      */
     'mosaica-viewchange': {
         bbox: [number, number, number, number];
@@ -40,14 +40,14 @@ export type MosaicaEventDetails = {
         width: number;
         height: number;
     };
-    /** A point was clicked: `id` is its `mosaica_id`. The record follows in `mosaica-itemopen`. */
+    /** A point was clicked. `id` is its `mosaica_id`. Its record follows in `mosaica-itemopen`. */
     'mosaica-pick': {
         id: string;
     };
     /**
-     * The selected item's record arrived, as `record`, for the item `id`, whether it was selected by
-     * a click or by `Store.pick`. Where the server refuses the record, this does not fire; the
-     * refusal is the store's `selection.itemRefusal`.
+     * The record of the selected item `id` arrived, whether it was selected by a click or by
+     * `Store.pick`. If the server refuses the record, this does not fire, and the refusal is in the
+     * store's `selection.itemRefusal`.
      */
     'mosaica-itemopen': {
         id: string;
@@ -62,7 +62,7 @@ export type MosaicaEventDetails = {
         y: number;
     };
     /**
-     * The artifact `id` was opened and its drill-down arrived, as `detail`, with `maskedCount` as a
+     * The artifact `id` was opened and its details arrived in `detail`, with `maskedCount` as a
      * decimal string.
      */
     'mosaica-artifactopen': {
@@ -71,16 +71,15 @@ export type MosaicaEventDetails = {
             maskedCount: string;
         };
     };
-    /** Fit was asked for the artifact `id`. `<mosaica-explorer>` fits its map to it. */
+    /** Fit was pressed for the artifact `id`. `<mosaica-explorer>` fits its map to it. */
     'mosaica-artifactfit': {
         id: string;
     };
     /**
-     * The selection changed. `shape` is the new shape in data coordinates, or null where the
-     * selection was cleared. `status` is `loading` as the shape is sent and `cleared` as it is
-     * dropped; once the server answers, it is the region's `shown` or `refused`, and `visible`,
-     * `matched`, `served` and `verdict` carry the region's counts and whether they are exact for the
-     * shape.
+     * The selected region changed. `shape` is the new shape in data coordinates, or null if the
+     * selection was cleared. It fires with `status` `loading` when a shape is selected or `cleared`
+     * when it is cleared, then again with `shown` or `refused` when the server answers. Then `visible`, `matched` and
+     * `served` carry the region's counts, and `verdict` says whether they are exact for the shape.
      */
     'mosaica-selectchange': {
         shape: SelectionShapeDetail | null;
@@ -90,19 +89,19 @@ export type MosaicaEventDetails = {
         served?: Count;
         verdict?: RegionProjection['verdict'];
     };
-    /** The layers chosen are now `layers`; the store also draws the layers each depends on, which the list leaves out. */
+    /** The chosen layers are now `layers`. The map also draws the layers each depends on, which the list leaves out. */
     'mosaica-layerchange': {
         layers: string[];
     };
-    /** The points are now coloured by `colourBy`: a column, `cluster:<layer>`, or null for one colour. */
+    /** The points are now coloured by `colourBy`: a column, `cluster:<layer>`, or null for a single colour. */
     'mosaica-colourchange': {
         colourBy: string | null;
     };
     /**
-     * The size choices changed in the explorer's Layers popover; the detail is all four as they now
-     * stand. `sizeBy` is the number column the points are sized by, or null for one size; `min` and
-     * `max` are the radii in pixels of its smallest and largest value, and `scale` how values are
-     * placed between them.
+     * A size setting changed in the explorer's Layers popover. The detail holds all four as they now
+     * stand: `sizeBy` is the number column that sizes the points, or null for a single size, `min`
+     * and `max` are the radii in pixels of its smallest and largest value, and `scale` is how values
+     * are placed between them.
      */
     'mosaica-sizechange': {
         sizeBy: string | null;
@@ -115,24 +114,23 @@ export type MosaicaEventDetails = {
         field: string;
         folded: boolean;
     };
-    /** Most points was let go: the store now aims to draw `budget` marks on screen. */
+    /** The Most points slider was released. The store now aims to draw `budget` marks on screen. */
     'mosaica-budgetchange': {
         budget: number;
     };
-    /** Most clusters was let go: a `nested` or `dag` layer is now cut to at most `budget` clusters. */
+    /** The Most clusters slider was released. A `nested` or `dag` layer is now cut to at most `budget` clusters. */
     'mosaica-clusterbudgetchange': {
         budget: number;
     };
-    /** The level to colour and label at is now `level`; null is the level drawn by default. */
+    /** The level that clusters are coloured and labelled at is now `level`. Null is the default level. */
     'mosaica-levelchange': {
         level: number | null;
     };
     /**
-     * Colours were chosen for values of the column `column`, in one action: one value's in a colour
-     * picker, the selected values' in Edit colours, or every value's by Reset to palette there. Each
-     * change names a value (a category key) and its colour as `#rrggbb`, or `null` where its chosen
-     * colour was reset so it takes its palette colour again. The map already draws them; a host that
-     * keeps the choices sets them back through the map's or the explorer's `valueColours`.
+     * The viewer chose or reset colours for values of the category column `column`, in a colour
+     * picker or in Edit colours. Each change names a category key and its new colour as `#rrggbb`, or
+     * `null` if it was reset to its palette colour. The map already draws the new colours. To restore
+     * them in a later session, save them and set the map's or explorer's `valueColours`.
      */
     'mosaica-valuecolour': {
         column: string;
@@ -142,11 +140,10 @@ export type MosaicaEventDetails = {
         }[];
     };
     /**
-     * Colours were chosen for clusters of the layer `layer`, in one action, as for
-     * `mosaica-valuecolour`. Each change names a cluster by its `mosaica_id` and its colour as
-     * `#rrggbb`, or `null` where its chosen colour was reset so it takes its palette colour again.
-     * The map already draws them; a host that keeps the choices sets them back through the map's or
-     * the explorer's `clusterColours`.
+     * The viewer chose or reset colours for clusters of the layer `layer`. Each change names a cluster
+     * by its `mosaica_id` and its new colour as `#rrggbb`, or `null` if it was reset to its palette
+     * colour. The map already draws the new colours. To restore them in a later session, save them
+     * and set the map's or explorer's `clusterColours`.
      */
     'mosaica-clustercolour': {
         layer: string;
@@ -155,26 +152,22 @@ export type MosaicaEventDetails = {
             colour: string | null;
         }[];
     };
-    /** The palette, the ramp, the ramp's scale or its direction was chosen in the explorer's Colour section; the detail is all four as they now stand. */
+    /** The palette, ramp, ramp scale or ramp direction was changed in the explorer's Colour section. The detail holds all four as they now stand. */
     'mosaica-palettechange': {
         palette: CategoryPaletteName;
         ramp: RampName;
         scale: RampScale;
         reverse: boolean;
     };
-    /**
-     * A palette was chosen for a layer's clusters in the explorer's Colour section, and set on the
-     * store (`Store.setPalette`).
-     */
+    /** A palette was chosen for a layer's clusters in the explorer's Colour section and set on the store (`Store.setPalette`). */
     'mosaica-clusterpalettechange': {
         palette: PaletteName;
     };
     /**
-     * A display setting was changed in the explorer's Layers popover; the detail is every setting as
-     * it now stands. `radius` and `pointOpacity` are null where the map sizes and fades the points by
-     * how many are drawn, and `densityColours` is null where the map chooses. `densityResolution` is
-     * the cell size chosen on the Resolution slider, in CSS pixels, and `densityScale` the scale
-     * density's colours follow, `linear` or `log`.
+     * A display setting changed in the explorer's Layers popover. The detail holds every setting as it
+     * now stands. `points` is the opposite of the map's `noPoints`; the other fields match the map's
+     * properties of the same name. `radius`, `pointOpacity` and `densityColours` are null while the
+     * map chooses them itself.
      */
     'mosaica-displaychange': {
         points: boolean;
@@ -187,33 +180,33 @@ export type MosaicaEventDetails = {
         densityScale: DensityScale;
     };
     /**
-     * A filter changed. `column` is the column whose control changed, or null for Clear all and for
-     * clearing the highlight. After an edit in a control or on a field card, `expr` is the expression
-     * the edited position now composes, null for none, and `verb` names that position (`filter` where
-     * absent). Where a chip was removed, `verb` is the position it was in and `expr` is null; after
-     * Clear all, `expr` is null, and after clearing the highlight `verb` is `highlight`.
+     * A filter or highlight changed. `column` is the column whose control changed, or null for Clear
+     * all and for clearing the highlight. `verb` is `filter` or `highlight` (`filter` if absent).
+     * After an edit, `expr` is the combined expression of every control's clause for that `verb`, or
+     * null if there are none. When a chip is removed, or Clear all is pressed, `expr` is null.
+     * `member_of` clauses are reported by `mosaica-clausechange`.
      */
     'mosaica-filterchange': {
         column: string | null;
         expr?: FilterExpr | null;
         verb?: ClauseVerb;
     };
-    /** A column's chip was pressed under `chips-only`: its card is to be shown; `verb` is the chip's position. */
+    /** A column's chip was pressed in a filter panel with `chips-only`, so you can show its card. `verb` is `filter` or `highlight`. */
     'mosaica-chipopen': {
         column: string;
         verb: ClauseVerb;
     };
     /**
-     * Open was pressed on the item `id`: `fields` is its record's fields. It fires whether Open calls
-     * the card's `open` or follows its `open-url`.
+     * Open was pressed on the item `id`, whose record's fields are `fields`. It fires both when Open
+     * calls the card's `open` and when it follows `open-url`.
      */
     'mosaica-open': {
         id: string;
         fields: Record<string, unknown>;
     };
     /**
-     * The view changed from `from` to `to`. `sameFrame` is true where both views are quantised
-     * against one extent, so the camera keeps its place; otherwise the map refits.
+     * The view changed from `from` to `to`. `sameFrame` is true if both views share one extent, in
+     * which case the camera stays where it is; otherwise the map refits.
      */
     'mosaica-viewswitch': {
         from: string;
@@ -221,8 +214,9 @@ export type MosaicaEventDetails = {
         sameFrame: boolean;
     };
     /**
-     * Follow an item into the view `view`, where it sits at `x`, `y` in that view's data coordinates.
-     * `<mosaica-explorer>` switches to the view and centres the map there.
+     * A view chip on the item card asked to show the item in the view `view`, where it sits at `x`,
+     * `y` in that view's data coordinates. `<mosaica-explorer>` switches to the view and centres the
+     * map there.
      */
     'mosaica-viewfollow': {
         view: string;
@@ -230,21 +224,22 @@ export type MosaicaEventDetails = {
         y: number;
     };
     /**
-     * What the map says about its basemap changed. `refusal` is why the value given cannot be drawn
-     * under the view it was given for, shown over the map; `note` is why nothing is drawn under this
-     * view, shown in its corner. Each is `null` where there is none.
+     * The map's message about its basemap changed. `refusal` says why the `basemap` value cannot be
+     * drawn under its view, and is shown over the map. `note` says why nothing is drawn under the
+     * current view, and is shown in a corner. Each is null if there is none.
      */
     'mosaica-basemapchange': {
         refusal: string | null;
         note: string | null;
     };
-    /** A card's close button was pressed: `what` says which card. */
+    /** A card's close button was pressed. `what` says which card. */
     'mosaica-close': {
         what: 'item' | 'artifact';
     };
     /**
-     * A `member_of` clause on the artifact `id` of layer `layer` was put on (`on` true) or taken off,
-     * in the position `verb`, selecting its members or, where `outside` is true, everything else.
+     * A `member_of` clause, which keeps the map to the members of the artifact `id` in layer `layer`,
+     * was added (`on` true) or removed. `verb` is `filter` or `highlight`, and `outside` is true if the
+     * clause keeps everything outside the artifact instead.
      */
     'mosaica-clausechange': {
         id: string;