@mosaicajs/components 0.1.0-rc.4 → 0.1.0

package/dist/artifact-card.d.ts

@@ -3,48 +3,45 @@ import { type ArtifactDetail, type Refusal } from '@mosaicajs/client';
 import { MosaicaElement } from './base.js';
 import './count.js';
 /**
- * The opened artifact: its name, its masked count, its description, layer and key, the kind of
- * shape its layer draws, its parents and its children in this view, Fit to cluster, and buttons
- * that put a `member_of` clause on it as a filter, as a highlight, or as a filter to what is
- * outside it. A `member_of` clause selects by membership, where a drawn region selects by shape;
- * they differ for an artifact whose members are spread across the map. Fit is absent on a filter
- * layer, which draws nothing. Pressing a parent or child opens it.
+ * Use the artifact card to show an artifact the viewer has opened on the map, such as a cluster. An
+ * artifact is a named group of items in an annotation layer. The card's count covers every member
+ * the viewer may see, so it does not change as the map moves. Pressing one of the artifact's
+ * parents or children opens that one instead.
  *
- * A host's buttons in the `actions` slot sit beside the close button.
+ * The card reads the store's opened artifact, or the `artifact` you set.
  *
- * The count is over the artifact's whole membership as the viewer sees it and does not change with
- * the view. An artifact with no name shows a dash in the headline and its key in its own field.
- * The server gives the same refusal for every artifact it withholds. The artifact is the store's
- * (`Store.openArtifact`), or the `artifact` property.
+ * The card's buttons filter or highlight the map by the artifact's members wherever they are, or
+ * filter to everything outside it. Fit to cluster fires `mosaica-artifactfit`, and
+ * `<mosaica-explorer>` responds by fitting its map to the artifact. A filter layer draws nothing,
+ * so its artifacts have no Fit button.
  *
- * @summary The opened artifact, with its lineage and its filter buttons.
+ * @summary A card showing an artifact's details, parents and children.
  * @tagname mosaica-artifact-card
  * @category Elements
  * @slot actions - Buttons beside the close button, such as the explorer's Pin.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-artifactfit']>} mosaica-artifactfit - Fit to
  *   cluster was pressed. `<mosaica-explorer>` fits its map to the artifact.
- * @fires {CustomEvent<MosaicaEventDetails['mosaica-clausechange']>} mosaica-clausechange - A clause
- *   button put a `member_of` clause on or took it off.
+ * @fires {CustomEvent<MosaicaEventDetails['mosaica-clausechange']>} mosaica-clausechange - A filter
+ *   or highlight button added or removed a `member_of` clause.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-close']>} mosaica-close - The close button was
  *   pressed, with `what` set to `artifact`.
- * @csspart title - The heading: the level's or the layer's title, holding the close button while
- *   the card shows an artifact or a refusal.
+ * @csspart title - The heading, with the level's or layer's title and the close button.
  * @csspart close - The close button.
  * @csspart state - The state line, with `data-state`.
  * @csspart refusal - The words "Not available", with `data-code` set to the refusal's code.
- * @csspart reason - The server's reason for the refusal, on a line under "Not available".
- * @csspart headline - The artifact's name, with `data-unnamed` where it has none.
- * @csspart count - The masked count.
+ * @csspart reason - The server's reason for the refusal, under "Not available".
+ * @csspart headline - The artifact's name, with `data-unnamed` if it has none.
+ * @csspart count - The count of items the viewer may see.
  * @csspart content - The artifact's description, or its attached topic.
  * @csspart value - The layer and the key.
- * @csspart shape - What the layer's shape is, with `data-kind` (`derived`, `predicate` or
+ * @csspart shape - How the layer's shapes are made, with `data-kind` (`derived`, `predicate` or
  *   `authored`).
  * @csspart label - The headings above the parents and the children.
  * @csspart parents - The list of parents.
  * @csspart parent - One parent, with `data-id`.
  * @csspart children - The list of children in this view.
  * @csspart child - One child, with `data-id`.
- * @csspart name - A parent's or a child's name, with `data-unnamed` where it has none.
+ * @csspart name - A parent's or child's name, with `data-unnamed` if it has none.
  * @csspart fit - The Fit to cluster button.
  * @csspart verbs - The clause buttons.
  * @csspart filter - The Filter to this button, with `aria-pressed` while its clause is on.
@@ -53,15 +50,12 @@ import './count.js';
  */
 export declare class MosaicaArtifactCard extends MosaicaElement {
     static styles: import("lit").CSSResult[];
-    /**
-     * The artifact to show, for a host that fetches the drill-down itself. Set with `refusal` or
-     * alone, it replaces the store's opened artifact.
-     */
+    /** The artifact to show, if you fetch its details yourself. It replaces the store's opened artifact. */
     accessor artifact: {
         id: bigint;
         detail: ArtifactDetail;
     } | null;
-    /** A refusal to show in place of an artifact, for a host that fetches the drill-down itself. */
+    /** A refusal to show instead of an artifact, if you fetch its details yourself. */
     accessor refusal: Refusal | null;
     private get shown();
     /**

package/dist/artifact-card.js

@@ -57,48 +57,45 @@ const SHAPE_TEXT = {
     authored: 'The same for everyone'
 };
 /**
- * The opened artifact: its name, its masked count, its description, layer and key, the kind of
- * shape its layer draws, its parents and its children in this view, Fit to cluster, and buttons
- * that put a `member_of` clause on it as a filter, as a highlight, or as a filter to what is
- * outside it. A `member_of` clause selects by membership, where a drawn region selects by shape;
- * they differ for an artifact whose members are spread across the map. Fit is absent on a filter
- * layer, which draws nothing. Pressing a parent or child opens it.
+ * Use the artifact card to show an artifact the viewer has opened on the map, such as a cluster. An
+ * artifact is a named group of items in an annotation layer. The card's count covers every member
+ * the viewer may see, so it does not change as the map moves. Pressing one of the artifact's
+ * parents or children opens that one instead.
  *
- * A host's buttons in the `actions` slot sit beside the close button.
+ * The card reads the store's opened artifact, or the `artifact` you set.
  *
- * The count is over the artifact's whole membership as the viewer sees it and does not change with
- * the view. An artifact with no name shows a dash in the headline and its key in its own field.
- * The server gives the same refusal for every artifact it withholds. The artifact is the store's
- * (`Store.openArtifact`), or the `artifact` property.
+ * The card's buttons filter or highlight the map by the artifact's members wherever they are, or
+ * filter to everything outside it. Fit to cluster fires `mosaica-artifactfit`, and
+ * `<mosaica-explorer>` responds by fitting its map to the artifact. A filter layer draws nothing,
+ * so its artifacts have no Fit button.
  *
- * @summary The opened artifact, with its lineage and its filter buttons.
+ * @summary A card showing an artifact's details, parents and children.
  * @tagname mosaica-artifact-card
  * @category Elements
  * @slot actions - Buttons beside the close button, such as the explorer's Pin.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-artifactfit']>} mosaica-artifactfit - Fit to
  *   cluster was pressed. `<mosaica-explorer>` fits its map to the artifact.
- * @fires {CustomEvent<MosaicaEventDetails['mosaica-clausechange']>} mosaica-clausechange - A clause
- *   button put a `member_of` clause on or took it off.
+ * @fires {CustomEvent<MosaicaEventDetails['mosaica-clausechange']>} mosaica-clausechange - A filter
+ *   or highlight button added or removed a `member_of` clause.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-close']>} mosaica-close - The close button was
  *   pressed, with `what` set to `artifact`.
- * @csspart title - The heading: the level's or the layer's title, holding the close button while
- *   the card shows an artifact or a refusal.
+ * @csspart title - The heading, with the level's or layer's title and the close button.
  * @csspart close - The close button.
  * @csspart state - The state line, with `data-state`.
  * @csspart refusal - The words "Not available", with `data-code` set to the refusal's code.
- * @csspart reason - The server's reason for the refusal, on a line under "Not available".
- * @csspart headline - The artifact's name, with `data-unnamed` where it has none.
- * @csspart count - The masked count.
+ * @csspart reason - The server's reason for the refusal, under "Not available".
+ * @csspart headline - The artifact's name, with `data-unnamed` if it has none.
+ * @csspart count - The count of items the viewer may see.
  * @csspart content - The artifact's description, or its attached topic.
  * @csspart value - The layer and the key.
- * @csspart shape - What the layer's shape is, with `data-kind` (`derived`, `predicate` or
+ * @csspart shape - How the layer's shapes are made, with `data-kind` (`derived`, `predicate` or
  *   `authored`).
  * @csspart label - The headings above the parents and the children.
  * @csspart parents - The list of parents.
  * @csspart parent - One parent, with `data-id`.
  * @csspart children - The list of children in this view.
  * @csspart child - One child, with `data-id`.
- * @csspart name - A parent's or a child's name, with `data-unnamed` where it has none.
+ * @csspart name - A parent's or child's name, with `data-unnamed` if it has none.
  * @csspart fit - The Fit to cluster button.
  * @csspart verbs - The clause buttons.
  * @csspart filter - The Filter to this button, with `aria-pressed` while its clause is on.
@@ -214,14 +211,11 @@ let MosaicaArtifactCard = (() => {
     `
         ];
         #artifact_accessor_storage = __runInitializers(this, _artifact_initializers, null);
-        /**
-         * The artifact to show, for a host that fetches the drill-down itself. Set with `refusal` or
-         * alone, it replaces the store's opened artifact.
-         */
+        /** The artifact to show, if you fetch its details yourself. It replaces the store's opened artifact. */
         get artifact() { return this.#artifact_accessor_storage; }
         set artifact(value) { this.#artifact_accessor_storage = value; }
         #refusal_accessor_storage = (__runInitializers(this, _artifact_extraInitializers), __runInitializers(this, _refusal_initializers, null));
-        /** A refusal to show in place of an artifact, for a host that fetches the drill-down itself. */
+        /** A refusal to show instead of an artifact, if you fetch its details yourself. */
         get refusal() { return this.#refusal_accessor_storage; }
         set refusal(value) { this.#refusal_accessor_storage = value; }
         get shown() {

package/dist/base.d.ts

@@ -2,9 +2,9 @@ import { LitElement, type PropertyValues } from 'lit';
 import { type SelectionShape, type Store, type TokenSupplier } from '@mosaicajs/client';
 import type { SelectionShapeDetail, MosaicaEventDetails } from './events.js';
 /**
- * Where an element's store came from: its `store` property, a `<mosaica-store>` or
- * `<mosaica-explorer>` above it (`context`), one it built itself from `viewer-url`, `token` or
- * `authorise` (`own`), or none (`detached`), in which case it renders its detached state.
+ * Where an element's store came from: `property` is its `store` property, `context` a
+ * `<mosaica-store>` or `<mosaica-explorer>` above it, and `own` a store it built from `viewer-url`,
+ * `token` or `authorise`. `detached` means it has none and shows its detached state.
  */
 export type StoreSource = 'property' | 'context' | 'own' | 'detached';
 /**
@@ -23,39 +23,32 @@ export type StoreSource = 'property' | 'context' | 'own' | 'detached';
  * refetch the view. An own store lives until `dispose()` or until its attributes change.
  */
 export declare abstract class MosaicaElement extends LitElement {
-    /**
-     * The store to read, which outranks a store from context and the element's own. The element does
-     * not dispose a store it was given.
-     */
+    /** The store to use, ahead of one from context or one the element would build. The element never disposes it. */
     accessor store: Store | null;
     /**
-     * The viewer plane's base URL. Only `<mosaica-map>`, `<mosaica-explorer>` and `<mosaica-store>`
-     * read it, to build their own store where no `store` property or context supplies one. Each route
-     * is appended to it after any trailing slash is dropped, so a full URL such as
-     * `https://maps.example.org` and a path on the page's own server such as `/mosaica` both work.
-     * Unset, requests go to `/v1/...` on the page's own origin. Changing it builds a new store. With
-     * no `token`, a store built before `authorise` is set asks once with no token, and is replaced
-     * when `authorise` arrives.
+     * The base URL of the Mosaica viewer server, for the store the element builds: a full URL such as
+     * `https://maps.example.org`, or a path such as `/mosaica`. Unset, the page's own origin. Read only
+     * by the map, the explorer and `<mosaica-store>`. Changing it builds a new store.
      */
     accessor viewerUrl: string;
     /**
-     * A viewer token for the store the element builds from `viewer-url`. Only the map, the explorer
-     * and `<mosaica-store>` read it. Without it or `authorise`, the store sends no token, which an
-     * open server (`serve.open`) serves. Changing it builds a new store.
+     * A viewer token for the store the element builds. Without `token` or `authorise`, only an open
+     * server (`serve.open`) answers. Read only by the map, the explorer and `<mosaica-store>`.
+     * Changing it builds a new store.
      */
     accessor token: string;
     /**
-     * A token supplier, used in place of `token`, which the store calls to renew the token before it
-     * expires. Setting another function builds a new store, since a store serves one viewer (see
-     * `Store` in `@mosaicajs/client`), so a framework keeps the function stable across renders.
+     * A function that returns a viewer token, used instead of `token` and called again before the
+     * token expires. A different function builds a new store, so keep it stable across renders. Set
+     * it together with `viewer-url`: a store built from `viewer-url` alone first sends a request with
+     * no token, and is replaced when `authorise` arrives.
      */
     accessor authorise: TokenSupplier | null;
     /**
-     * The most artifacts one level of a drawn layer shows in one tile, for the store the element
-     * builds; at most `/v1/meta`'s `selection.max_artifacts_per_tile`. Only the map, the explorer
-     * and `<mosaica-store>` read it. Unset, the store asks for 50, or the server's maximum where
-     * that is smaller.
-     * Changing it builds a new store.
+     * The most artifacts one level of a layer shows per map tile, for the store the element builds.
+     * Unset, 50, or the server's `selection.max_artifacts_per_tile` if lower. A value above that
+     * maximum is refused. Read only by the map, the explorer and `<mosaica-store>`. Changing it
+     * builds a new store.
      */
     accessor artifactsPerTile: number | null;
     /** Whether this element builds its own store from attributes when nothing else supplies one. */
@@ -70,7 +63,7 @@ export declare abstract class MosaicaElement extends LitElement {
     private metaHeld;
     private consumer;
     private unsubscribe;
-    /** The store this element reads, from whichever source won; `null` while detached. */
+    /** The store this element is using, or `null` if it has none. */
     get activeStore(): Store | null;
     /** Where `activeStore` came from. */
     get source(): StoreSource;
@@ -100,9 +93,8 @@ export declare abstract class MosaicaElement extends LitElement {
     /** Every projection change lands here; the default asks for a render. */
     protected onStoreChange(): void;
     /**
-     * Dispose of the store this element built and detach from it. Disconnecting does not do this, so
-     * a host that removes an element for good calls it. A store handed in by property or context is
-     * left for its owner to dispose.
+     * Dispose of the store this element built. Removing the element from the page does not, so call
+     * this when you are done with the element. A store you passed in is left to you.
      */
     dispose(): void;
 }

package/dist/base.js

@@ -85,47 +85,40 @@ let MosaicaElement = (() => {
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
         #store_accessor_storage = __runInitializers(this, _store_initializers, null);
-        /**
-         * The store to read, which outranks a store from context and the element's own. The element does
-         * not dispose a store it was given.
-         */
+        /** The store to use, ahead of one from context or one the element would build. The element never disposes it. */
         get store() { return this.#store_accessor_storage; }
         set store(value) { this.#store_accessor_storage = value; }
         #viewerUrl_accessor_storage = (__runInitializers(this, _store_extraInitializers), __runInitializers(this, _viewerUrl_initializers, ''));
         /**
-         * The viewer plane's base URL. Only `<mosaica-map>`, `<mosaica-explorer>` and `<mosaica-store>`
-         * read it, to build their own store where no `store` property or context supplies one. Each route
-         * is appended to it after any trailing slash is dropped, so a full URL such as
-         * `https://maps.example.org` and a path on the page's own server such as `/mosaica` both work.
-         * Unset, requests go to `/v1/...` on the page's own origin. Changing it builds a new store. With
-         * no `token`, a store built before `authorise` is set asks once with no token, and is replaced
-         * when `authorise` arrives.
+         * The base URL of the Mosaica viewer server, for the store the element builds: a full URL such as
+         * `https://maps.example.org`, or a path such as `/mosaica`. Unset, the page's own origin. Read only
+         * by the map, the explorer and `<mosaica-store>`. Changing it builds a new store.
          */
         get viewerUrl() { return this.#viewerUrl_accessor_storage; }
         set viewerUrl(value) { this.#viewerUrl_accessor_storage = value; }
         #token_accessor_storage = (__runInitializers(this, _viewerUrl_extraInitializers), __runInitializers(this, _token_initializers, ''));
         /**
-         * A viewer token for the store the element builds from `viewer-url`. Only the map, the explorer
-         * and `<mosaica-store>` read it. Without it or `authorise`, the store sends no token, which an
-         * open server (`serve.open`) serves. Changing it builds a new store.
+         * A viewer token for the store the element builds. Without `token` or `authorise`, only an open
+         * server (`serve.open`) answers. Read only by the map, the explorer and `<mosaica-store>`.
+         * Changing it builds a new store.
          */
         get token() { return this.#token_accessor_storage; }
         set token(value) { this.#token_accessor_storage = value; }
         #authorise_accessor_storage = (__runInitializers(this, _token_extraInitializers), __runInitializers(this, _authorise_initializers, null));
         /**
-         * A token supplier, used in place of `token`, which the store calls to renew the token before it
-         * expires. Setting another function builds a new store, since a store serves one viewer (see
-         * `Store` in `@mosaicajs/client`), so a framework keeps the function stable across renders.
+         * A function that returns a viewer token, used instead of `token` and called again before the
+         * token expires. A different function builds a new store, so keep it stable across renders. Set
+         * it together with `viewer-url`: a store built from `viewer-url` alone first sends a request with
+         * no token, and is replaced when `authorise` arrives.
          */
         get authorise() { return this.#authorise_accessor_storage; }
         set authorise(value) { this.#authorise_accessor_storage = value; }
         #artifactsPerTile_accessor_storage = (__runInitializers(this, _authorise_extraInitializers), __runInitializers(this, _artifactsPerTile_initializers, null));
         /**
-         * The most artifacts one level of a drawn layer shows in one tile, for the store the element
-         * builds; at most `/v1/meta`'s `selection.max_artifacts_per_tile`. Only the map, the explorer
-         * and `<mosaica-store>` read it. Unset, the store asks for 50, or the server's maximum where
-         * that is smaller.
-         * Changing it builds a new store.
+         * The most artifacts one level of a layer shows per map tile, for the store the element builds.
+         * Unset, 50, or the server's `selection.max_artifacts_per_tile` if lower. A value above that
+         * maximum is refused. Read only by the map, the explorer and `<mosaica-store>`. Changing it
+         * builds a new store.
          */
         get artifactsPerTile() { return this.#artifactsPerTile_accessor_storage; }
         set artifactsPerTile(value) { this.#artifactsPerTile_accessor_storage = value; }
@@ -141,7 +134,7 @@ let MosaicaElement = (() => {
         metaHeld = false;
         consumer = null;
         unsubscribe = null;
-        /** The store this element reads, from whichever source won; `null` while detached. */
+        /** The store this element is using, or `null` if it has none. */
         get activeStore() {
             return this.resolvedStore;
         }
@@ -285,9 +278,8 @@ let MosaicaElement = (() => {
             this.requestUpdate();
         }
         /**
-         * Dispose of the store this element built and detach from it. Disconnecting does not do this, so
-         * a host that removes an element for good calls it. A store handed in by property or context is
-         * left for its owner to dispose.
+         * Dispose of the store this element built. Removing the element from the page does not, so call
+         * this when you are done with the element. A store you passed in is left to you.
          */
         dispose() {
             const own = this.ownStore;

package/dist/basemap.d.ts

@@ -2,8 +2,8 @@ import type { Layer } from '@deck.gl/core';
 import type { Store } from '@mosaicajs/client';
 import { type BasemapValue, type DensityCamera } from '@mosaicajs/deck';
 /**
- * What `<mosaica-map>`'s `basemap` takes: one {@link BasemapValue} for every view, a mapping from
- * view id to one, or a deck.gl layer the host built, drawn as it is.
+ * The value of `<mosaica-map>`'s `basemap`: one {@link BasemapValue} for every view, an object
+ * mapping view ids to one each, or a deck.gl layer you built, which is drawn as it is.
  */
 export type BasemapChoice = BasemapValue | Readonly<Record<string, BasemapValue>> | Layer;
 /**

package/dist/cluster-filter.d.ts

@@ -8,48 +8,42 @@ type Offer = {
     beyond: boolean;
 };
 /**
- * The search box of a layer's field card: its list offers the layer's artifacts, and choosing one
- * puts its `member_of` clause on in the filter position (`Store.setMembers`).
+ * Use `<mosaica-cluster-filter>` when you want to search a layer's clusters without the field card
+ * around it. Set `layer` to a layer `meta.layers` lists.
  *
- * With the box empty, the list offers the layer's top-level clusters (its roots, or its first level
- * on a levelled layer), largest first. Typing searches the layer's names through
- * `POST /v1/artifacts/browse`, every level on a levelled layer, and each match shows its path, the
- * names of its nearest parents in grey, cut from the left so the nearest stay. On a levelled layer
- * the path names only parents the list has already met. Each row's count is exact, from the
- * aggregate route (`Store.setAggregate`) over the rows listed, one grouping per level on a layer
- * with several, under the store's filters without this layer's own filter clauses, so a cluster
- * its clauses exclude is still counted. A row shows no count until the answer lands. The list opens
- * over what sits below the box, in the top layer.
+ * With the box empty, the list offers the layer's top-level clusters, largest first. Typing
+ * searches the cluster names at every level. In the list, the arrow keys move between rows, Enter
+ * chooses one, and Escape closes the list.
  *
- * Choosing a row puts its clause on, with the row's name as the clause's label, and pressing a
- * chosen row takes it off. The arrow keys move through the list, Enter chooses the row reached, the
- * first by default, and Escape closes the list.
+ * Each row counts the items the filters match in that cluster without applying this layer's own
+ * filter, so a cluster the viewer has filtered out still shows its count. Choosing a row filters
+ * the map to the cluster's members, and choosing it again removes that filter.
  *
- * @summary A layer's field card's search box.
+ * @summary A search box that filters the map by a layer's clusters.
  * @tagname mosaica-cluster-filter
  * @category Elements
- * @fires {CustomEvent<MosaicaEventDetails['mosaica-clausechange']>} mosaica-clausechange - A row put
- *   a `member_of` clause on or took it off.
+ * @fires {CustomEvent<MosaicaEventDetails['mosaica-clausechange']>} mosaica-clausechange - Choosing a
+ *   row added or removed a `member_of` clause.
  * @csspart entry - The search box.
  * @csspart values - The list, while it is open.
  * @csspart option - One cluster in the list, with `data-id` and `aria-selected` while its clause is
  *   on.
- * @csspart name - A row's name, with `data-unnamed` where it has none.
+ * @csspart name - A row's name, with `data-unnamed` if the cluster has none.
  * @csspart path - A row's path of parents' names.
  * @csspart value-count - A row's exact count.
- * @csspart more - The note under the box: no match, or that more match than the list holds.
- * @csspart refusal - The words "Clusters unavailable", with `data-code`, where the list was refused.
+ * @csspart more - The note under the box when nothing matches, or when more match than are listed.
+ * @csspart refusal - The words "Clusters unavailable", with `data-code`, if the list was refused.
  */
 export declare class MosaicaClusterFilter extends MosaicaElement {
     static styles: import("lit").CSSResult[];
-    /** The layer whose clusters are offered, a name `meta.layers` lists. Unset or unknown, the field renders nothing. */
+    /** The layer whose clusters are offered, a name `meta.layers` lists. Unset or unknown, the box shows nothing. */
     accessor layer: string;
-    /** The search box's placeholder, in place of the field's own. */
+    /** Placeholder text for the box, in place of the default. */
     accessor placeholder: string;
     /**
-     * Where set, the box picks a cluster rather than filtering by it: choosing a row calls this with
-     * its `mosaica_id` as a decimal string, its name, its path of parents' names as the list shows
-     * it and its `rung`, changes no clause and empties the box, and no row shows as chosen.
+     * Turns the box into a cluster picker. Choosing a row calls this with the cluster's `mosaica_id`
+     * (as a decimal string), its name, its parents' names as the list shows them, and its level
+     * (`rung`), then empties the box. No filter changes.
      */
     accessor choose: ((cluster: {
         id: string;

package/dist/cluster-filter.js

@@ -57,37 +57,31 @@ function pathText(path, beyond, n) {
 /** How many parents a match's path is walked up, nearest first. */
 const PATH_DEPTH = 3;
 /**
- * The search box of a layer's field card: its list offers the layer's artifacts, and choosing one
- * puts its `member_of` clause on in the filter position (`Store.setMembers`).
+ * Use `<mosaica-cluster-filter>` when you want to search a layer's clusters without the field card
+ * around it. Set `layer` to a layer `meta.layers` lists.
  *
- * With the box empty, the list offers the layer's top-level clusters (its roots, or its first level
- * on a levelled layer), largest first. Typing searches the layer's names through
- * `POST /v1/artifacts/browse`, every level on a levelled layer, and each match shows its path, the
- * names of its nearest parents in grey, cut from the left so the nearest stay. On a levelled layer
- * the path names only parents the list has already met. Each row's count is exact, from the
- * aggregate route (`Store.setAggregate`) over the rows listed, one grouping per level on a layer
- * with several, under the store's filters without this layer's own filter clauses, so a cluster
- * its clauses exclude is still counted. A row shows no count until the answer lands. The list opens
- * over what sits below the box, in the top layer.
+ * With the box empty, the list offers the layer's top-level clusters, largest first. Typing
+ * searches the cluster names at every level. In the list, the arrow keys move between rows, Enter
+ * chooses one, and Escape closes the list.
  *
- * Choosing a row puts its clause on, with the row's name as the clause's label, and pressing a
- * chosen row takes it off. The arrow keys move through the list, Enter chooses the row reached, the
- * first by default, and Escape closes the list.
+ * Each row counts the items the filters match in that cluster without applying this layer's own
+ * filter, so a cluster the viewer has filtered out still shows its count. Choosing a row filters
+ * the map to the cluster's members, and choosing it again removes that filter.
  *
- * @summary A layer's field card's search box.
+ * @summary A search box that filters the map by a layer's clusters.
  * @tagname mosaica-cluster-filter
  * @category Elements
- * @fires {CustomEvent<MosaicaEventDetails['mosaica-clausechange']>} mosaica-clausechange - A row put
- *   a `member_of` clause on or took it off.
+ * @fires {CustomEvent<MosaicaEventDetails['mosaica-clausechange']>} mosaica-clausechange - Choosing a
+ *   row added or removed a `member_of` clause.
  * @csspart entry - The search box.
  * @csspart values - The list, while it is open.
  * @csspart option - One cluster in the list, with `data-id` and `aria-selected` while its clause is
  *   on.
- * @csspart name - A row's name, with `data-unnamed` where it has none.
+ * @csspart name - A row's name, with `data-unnamed` if the cluster has none.
  * @csspart path - A row's path of parents' names.
  * @csspart value-count - A row's exact count.
- * @csspart more - The note under the box: no match, or that more match than the list holds.
- * @csspart refusal - The words "Clusters unavailable", with `data-code`, where the list was refused.
+ * @csspart more - The note under the box when nothing matches, or when more match than are listed.
+ * @csspart refusal - The words "Clusters unavailable", with `data-code`, if the list was refused.
  */
 let MosaicaClusterFilter = (() => {
     let _classSuper = MosaicaElement;
@@ -225,18 +219,18 @@ let MosaicaClusterFilter = (() => {
     `
         ];
         #layer_accessor_storage = __runInitializers(this, _layer_initializers, '');
-        /** The layer whose clusters are offered, a name `meta.layers` lists. Unset or unknown, the field renders nothing. */
+        /** The layer whose clusters are offered, a name `meta.layers` lists. Unset or unknown, the box shows nothing. */
         get layer() { return this.#layer_accessor_storage; }
         set layer(value) { this.#layer_accessor_storage = value; }
         #placeholder_accessor_storage = (__runInitializers(this, _layer_extraInitializers), __runInitializers(this, _placeholder_initializers, ''));
-        /** The search box's placeholder, in place of the field's own. */
+        /** Placeholder text for the box, in place of the default. */
         get placeholder() { return this.#placeholder_accessor_storage; }
         set placeholder(value) { this.#placeholder_accessor_storage = value; }
         #choose_accessor_storage = (__runInitializers(this, _placeholder_extraInitializers), __runInitializers(this, _choose_initializers, null));
         /**
-         * Where set, the box picks a cluster rather than filtering by it: choosing a row calls this with
-         * its `mosaica_id` as a decimal string, its name, its path of parents' names as the list shows
-         * it and its `rung`, changes no clause and empties the box, and no row shows as chosen.
+         * Turns the box into a cluster picker. Choosing a row calls this with the cluster's `mosaica_id`
+         * (as a decimal string), its name, its parents' names as the list shows them, and its level
+         * (`rung`), then empties the box. No filter changes.
          */
         get choose() { return this.#choose_accessor_storage; }
         set choose(value) { this.#choose_accessor_storage = value; }