@mosaicajs/components 0.1.0-rc.4 → 0.1.0

package/dist/hierarchy.d.ts

@@ -2,64 +2,63 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 import { MosaicaElement } from './base.js';
 import './count.js';
 /**
- * A layer's hierarchy, browsed through `POST /v1/artifacts/browse` independently of the viewport:
- * it opens on the roots at any zoom and does not move with the map. A select chooses among the
- * bundle's hierarchical layers where there are several. Each row is a name, a masked count and,
- * where the server counts children under it, an expander; expanding fetches the children, a page
- * at a time under More. On a layer where a child
- * may have several parents, a row appears under each parent it is served under and names the
- * others. A parent the viewer may not see is absent, so its child reads as a root. The search box
- * lists matching names.
+ * Use the hierarchy when viewers should be able to reach a layer's artifacts at any level, wherever
+ * the camera is. It opens on the top-level artifacts and does not change as the map moves.
+ * Expanding a row loads its children a page at a time.
  *
- * The panel sends the map's filters and, while any is set, shows each row's matched count beside
- * its masked count. A row's presence and its masked count do not change with the filters. A row's
- * buttons put a `member_of` clause on its artifact as a highlight or a filter, and Fit fits the map
- * to it on a layer that draws. Pressing the name highlights it. A row holding a clause is filled,
- * grey for a filter and in the highlight colour for a highlight, and carries a × per clause that
- * takes it off.
+ * The hierarchy offers each layer that depends on no other layer and whose artifacts form a
+ * hierarchy, filter layers among them. When there are several, a select switches between them.
  *
- * The panel asks for nothing while it is hidden. The element keeps which rows are expanded and
- * paged.
+ * Each row shows how many of the artifact's items the viewer may see. While filters are set, it
+ * also shows how many of those items match. A parent the viewer may not see is left out, so its
+ * children appear at the top level.
  *
- * @summary A layer's hierarchy, browsed apart from the viewport.
+ * A row's buttons highlight or filter the map by its artifact. Its Fit button only fires
+ * `mosaica-artifactfit`, so you handle the event by passing its id to the map's `fitTo`. The
+ * explorer does this for a hierarchy you put in one of its slots. `fitTo` finds only the artifacts
+ * the map currently draws, so Fit does nothing for a row whose artifact is not drawn at this zoom.
+ *
+ * The panel makes no requests while it is hidden, so it costs nothing in a closed drawer.
+ *
+ * @summary A tree for browsing a layer's artifacts and filtering by them.
  * @tagname mosaica-hierarchy
  * @category Elements
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-clausechange']>} mosaica-clausechange - A row's
- *   name, highlight or filter button put a `member_of` clause on or took it off.
+ *   name, highlight or filter button added or removed a `member_of` clause.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-artifactfit']>} mosaica-artifactfit - A row's Fit
  *   button was pressed.
  * @csspart title - The heading.
  * @csspart state - The state line, with `data-state`.
- * @csspart refusal - The words "Layer unavailable", with `data-code` set to the refusal's code.
- * @csspart reason - The server's reason for a refusal, on a line under "View refused".
- * @csspart layer - The layer select, shown where there are several layers.
+ * @csspart refusal - The words "View refused" or "Layer unavailable", with `data-code`.
+ * @csspart reason - The server's reason for a refusal, under "View refused".
+ * @csspart layer - The layer select, shown if there are several layers.
  * @csspart search - The search box.
  * @csspart tree - The tree of rows.
- * @csspart row - One row, with `data-id`, and `data-clause` while a clause is on its artifact:
- *   `filter`, `highlight`, or both separated by a space.
- * @csspart expander - A row's expand button, with `data-leaf` and hidden where the row has no
- *   children, so every row's name starts at the same place.
- * @csspart name - A row's name, with `data-unnamed` where it has none, which highlights the artifact
- *   when pressed.
+ * @csspart row - One row, with `data-id`, and `data-clause` (`filter`, `highlight` or both,
+ *   separated by a space) while its artifact is filtered or highlighted.
+ * @csspart expander - A row's expand button. On a row with no children it has `data-leaf` and is
+ *   hidden, keeping the names aligned.
+ * @csspart name - A row's name, with `data-unnamed` if it has none. Pressing it highlights the
+ *   artifact.
  * @csspart counts - A row's counts.
- * @csspart count-matched - A row's matched `<mosaica-count>`, while a filter is set.
- * @csspart count-masked - A row's masked `<mosaica-count>`.
+ * @csspart count-matched - The `<mosaica-count>` of a row's items that match the filters, while a
+ *   filter is set.
+ * @csspart count-masked - The `<mosaica-count>` of a row's items the viewer may see.
  * @csspart actions - A row's buttons.
  * @csspart highlight - A row's highlight button, with `aria-pressed`.
  * @csspart filter - A row's filter button, with `aria-pressed`.
  * @csspart fit - A row's Fit button, on a layer that draws.
- * @csspart dismiss - A × on a row holding a clause, one per clause, with `data-verb`; it takes that
- *   clause off.
- * @csspart also - The other parents a row is served under, or "Children unavailable" with
- *   `data-code` where its children were refused.
+ * @csspart dismiss - A × that removes a row's filter or highlight, one for each, with `data-verb`.
+ * @csspart also - The row's other parents, or "Children unavailable" with `data-code` if its
+ *   children were refused.
  * @csspart children - An expanded row's children.
- * @csspart more - The More button that fetches the next page.
+ * @csspart more - The More button, which loads the next page.
  */
 export declare class MosaicaHierarchy extends MosaicaElement {
     static styles: import("lit").CSSResult[];
-    /** The layer whose hierarchy is shown. Unset or unknown, the first the bundle offers. */
+    /** The layer to browse. Unset or unknown, the first layer the bundle offers. */
     accessor layer: string;
-    /** Rows per page, at least 1 and at most the server's `maxBrowseRows`. */
+    /** Rows per page, from 1 up to the server's `maxBrowseRows`. */
     accessor limit: number;
     private accessor roots;
     private accessor rootsNext;

package/dist/hierarchy.js

@@ -44,58 +44,57 @@ import { chrome, tokens } from './tokens.js';
 import './count.js';
 const masked = (n) => ({ value: Number(n), exact: true });
 /**
- * A layer's hierarchy, browsed through `POST /v1/artifacts/browse` independently of the viewport:
- * it opens on the roots at any zoom and does not move with the map. A select chooses among the
- * bundle's hierarchical layers where there are several. Each row is a name, a masked count and,
- * where the server counts children under it, an expander; expanding fetches the children, a page
- * at a time under More. On a layer where a child
- * may have several parents, a row appears under each parent it is served under and names the
- * others. A parent the viewer may not see is absent, so its child reads as a root. The search box
- * lists matching names.
+ * Use the hierarchy when viewers should be able to reach a layer's artifacts at any level, wherever
+ * the camera is. It opens on the top-level artifacts and does not change as the map moves.
+ * Expanding a row loads its children a page at a time.
  *
- * The panel sends the map's filters and, while any is set, shows each row's matched count beside
- * its masked count. A row's presence and its masked count do not change with the filters. A row's
- * buttons put a `member_of` clause on its artifact as a highlight or a filter, and Fit fits the map
- * to it on a layer that draws. Pressing the name highlights it. A row holding a clause is filled,
- * grey for a filter and in the highlight colour for a highlight, and carries a × per clause that
- * takes it off.
+ * The hierarchy offers each layer that depends on no other layer and whose artifacts form a
+ * hierarchy, filter layers among them. When there are several, a select switches between them.
  *
- * The panel asks for nothing while it is hidden. The element keeps which rows are expanded and
- * paged.
+ * Each row shows how many of the artifact's items the viewer may see. While filters are set, it
+ * also shows how many of those items match. A parent the viewer may not see is left out, so its
+ * children appear at the top level.
  *
- * @summary A layer's hierarchy, browsed apart from the viewport.
+ * A row's buttons highlight or filter the map by its artifact. Its Fit button only fires
+ * `mosaica-artifactfit`, so you handle the event by passing its id to the map's `fitTo`. The
+ * explorer does this for a hierarchy you put in one of its slots. `fitTo` finds only the artifacts
+ * the map currently draws, so Fit does nothing for a row whose artifact is not drawn at this zoom.
+ *
+ * The panel makes no requests while it is hidden, so it costs nothing in a closed drawer.
+ *
+ * @summary A tree for browsing a layer's artifacts and filtering by them.
  * @tagname mosaica-hierarchy
  * @category Elements
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-clausechange']>} mosaica-clausechange - A row's
- *   name, highlight or filter button put a `member_of` clause on or took it off.
+ *   name, highlight or filter button added or removed a `member_of` clause.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-artifactfit']>} mosaica-artifactfit - A row's Fit
  *   button was pressed.
  * @csspart title - The heading.
  * @csspart state - The state line, with `data-state`.
- * @csspart refusal - The words "Layer unavailable", with `data-code` set to the refusal's code.
- * @csspart reason - The server's reason for a refusal, on a line under "View refused".
- * @csspart layer - The layer select, shown where there are several layers.
+ * @csspart refusal - The words "View refused" or "Layer unavailable", with `data-code`.
+ * @csspart reason - The server's reason for a refusal, under "View refused".
+ * @csspart layer - The layer select, shown if there are several layers.
  * @csspart search - The search box.
  * @csspart tree - The tree of rows.
- * @csspart row - One row, with `data-id`, and `data-clause` while a clause is on its artifact:
- *   `filter`, `highlight`, or both separated by a space.
- * @csspart expander - A row's expand button, with `data-leaf` and hidden where the row has no
- *   children, so every row's name starts at the same place.
- * @csspart name - A row's name, with `data-unnamed` where it has none, which highlights the artifact
- *   when pressed.
+ * @csspart row - One row, with `data-id`, and `data-clause` (`filter`, `highlight` or both,
+ *   separated by a space) while its artifact is filtered or highlighted.
+ * @csspart expander - A row's expand button. On a row with no children it has `data-leaf` and is
+ *   hidden, keeping the names aligned.
+ * @csspart name - A row's name, with `data-unnamed` if it has none. Pressing it highlights the
+ *   artifact.
  * @csspart counts - A row's counts.
- * @csspart count-matched - A row's matched `<mosaica-count>`, while a filter is set.
- * @csspart count-masked - A row's masked `<mosaica-count>`.
+ * @csspart count-matched - The `<mosaica-count>` of a row's items that match the filters, while a
+ *   filter is set.
+ * @csspart count-masked - The `<mosaica-count>` of a row's items the viewer may see.
  * @csspart actions - A row's buttons.
  * @csspart highlight - A row's highlight button, with `aria-pressed`.
  * @csspart filter - A row's filter button, with `aria-pressed`.
  * @csspart fit - A row's Fit button, on a layer that draws.
- * @csspart dismiss - A × on a row holding a clause, one per clause, with `data-verb`; it takes that
- *   clause off.
- * @csspart also - The other parents a row is served under, or "Children unavailable" with
- *   `data-code` where its children were refused.
+ * @csspart dismiss - A × that removes a row's filter or highlight, one for each, with `data-verb`.
+ * @csspart also - The row's other parents, or "Children unavailable" with `data-code` if its
+ *   children were refused.
  * @csspart children - An expanded row's children.
- * @csspart more - The More button that fetches the next page.
+ * @csspart more - The More button, which loads the next page.
  */
 let MosaicaHierarchy = (() => {
     let _classSuper = MosaicaElement;
@@ -283,11 +282,11 @@ let MosaicaHierarchy = (() => {
     `
         ];
         #layer_accessor_storage = __runInitializers(this, _layer_initializers, '');
-        /** The layer whose hierarchy is shown. Unset or unknown, the first the bundle offers. */
+        /** The layer to browse. Unset or unknown, the first layer the bundle offers. */
         get layer() { return this.#layer_accessor_storage; }
         set layer(value) { this.#layer_accessor_storage = value; }
         #limit_accessor_storage = (__runInitializers(this, _layer_extraInitializers), __runInitializers(this, _limit_initializers, 50));
-        /** Rows per page, at least 1 and at most the server's `maxBrowseRows`. */
+        /** Rows per page, from 1 up to the server's `maxBrowseRows`. */
         get limit() { return this.#limit_accessor_storage; }
         set limit(value) { this.#limit_accessor_storage = value; }
         #roots_accessor_storage = (__runInitializers(this, _limit_extraInitializers), __runInitializers(this, _roots_initializers, null));

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 /**
- * The `mosaica-*` custom elements. Importing the root entry defines every element. A host that
- * wants one element imports its subpath, such as `@mosaicajs/components/count`. The map, the
- * explorer, the field card, the filter panel and the colour editor import `@mosaicajs/deck`, which
- * depends on deck.gl; the other elements do not.
+ * The `mosaica-*` custom elements: the map, the panels that go around it, and `<mosaica-explorer>`,
+ * which lays them all out together. Import the package root to define every element, or a subpath
+ * such as `@mosaicajs/components/count` to define one. The map, the explorer, the field card, the
+ * filter panel and the colour editor import `@mosaicajs/deck`, which depends on deck.gl; the other
+ * elements do not.
  *
  * @module @mosaicajs/components
  */

package/dist/index.js

@@ -1,8 +1,9 @@
 /**
- * The `mosaica-*` custom elements. Importing the root entry defines every element. A host that
- * wants one element imports its subpath, such as `@mosaicajs/components/count`. The map, the
- * explorer, the field card, the filter panel and the colour editor import `@mosaicajs/deck`, which
- * depends on deck.gl; the other elements do not.
+ * The `mosaica-*` custom elements: the map, the panels that go around it, and `<mosaica-explorer>`,
+ * which lays them all out together. Import the package root to define every element, or a subpath
+ * such as `@mosaicajs/components/count` to define one. The map, the explorer, the field card, the
+ * filter panel and the colour editor import `@mosaicajs/deck`, which depends on deck.gl; the other
+ * elements do not.
  *
  * @module @mosaicajs/components
  */

package/dist/item-card.d.ts

@@ -3,37 +3,22 @@ import type { ItemDetail, Meta, Refusal } from '@mosaicajs/client';
 import type { MosaicaEventDetails } from './events.js';
 import { MosaicaElement, type PickOutcome } from './base.js';
 /**
- * The selected item's record: a headline, the views it is in, its fields as a label and value
- * grid, its group-scoped values, then Open and Copy id. Fields are listed by name in
- * declaration order, then any the schema does not declare; a field the record has no value for is
- * left out. A declared field is captioned in words (`published_at` as "Published at"). A category
- * field shows its value's title where the vocabulary has one, else its key; the titles are asked
- * of the store (`Store.titleOf`), and an answer is shown only while the store's `meta` is the one
- * it was asked under. A timestamp shows in full, as `14 March 2024, 12:00 UTC`.
- * The close button appears only while the card shows something: an item, a refusal or a click's
- * result.
+ * Use the item card to show the record of the item a viewer has picked on the map, so that they can
+ * read its fields and open it elsewhere. It reads the store's selected item, or the `item` you set
+ * when you fetch records yourself.
  *
- * The headline is the field `title-field` names, else the item's `mosaica_id`. Each field has a
- * slot, `field-<name>`, so a host can render one as a link. The item is the store's selection
- * (`Store.pick`), or the `item` property.
+ * The headline is the `title-field` field, or the item's `mosaica_id` when that field is unset or
+ * empty. To render a field your own way, as a link for example, put an element in its
+ * `field-<name>` slot.
  *
- * `compact` shows less: the headline, cut at three lines, the field `subtitle-field` names under
- * it, cut at two, the fields `card-fields` names (else the first three others), then "Show all N
- * fields" beside Open. Show all lists every field, the views and the group-scoped values, and the
- * card grows to hold them; a container that sets the card a height, such as the explorer's card
- * beside a point, scrolls past it. A host's buttons in the `actions` slot sit beside the close
- * button.
+ * The Open button appears only when you set `open-url` or `open`. `open-url` is a link template
+ * such as `https://www.geonames.org/{geonameid}`, in which each `{name}` is replaced by the item's
+ * value for that field. Because the values are URL-encoded, a template cannot open an address that
+ * a field already holds, so set `open` to a function for that. An item gets no Open button when it
+ * has no value for a field the template names. A function in `open` is called with the item's
+ * `mosaica_id` and fields, and it takes precedence over `open-url`.
  *
- * What Open does is the host's to say, and Open is shown only where it says. The `open` property is
- * called with the item's `mosaica_id` and fields. Otherwise `open-url` is a link template, such as
- * `https://www.geonames.org/{geonameid}`: each `{name}` is replaced by the item's value for the
- * field `name`, URL-encoded, and `{mosaica_id}` by its id where the record has no field of that
- * name. Open is then a link to that address, opening in a new tab. An item with no value, or an
- * empty one, for a field the template names, or whose address is not `http:` or `https:` once
- * filled and resolved against the page, has no Open. Where both are set, `open` is called and
- * `open-url` is unused.
- *
- * @summary The selected item's fields, with Open and Copy id.
+ * @summary A card showing an item's fields, with an optional Open button.
  * @tagname mosaica-item-card
  * @category Elements
  * @slot field-<name> - Replaces the value of the field `<name>`, in the grid or the headline.
@@ -42,18 +27,17 @@ import { MosaicaElement, type PickOutcome } from './base.js';
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-close']>} mosaica-close - The close button was
  *   pressed, with `what` set to `item`.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-viewfollow']>} mosaica-viewfollow - A view chip
- *   was pressed: follow the item into that view, at its position there.
+ *   was pressed, asking to show the item in that view.
  * @csspart title - The header row: the headline or the state, and the close button.
  * @csspart close - The close button.
- * @csspart state - The state line, with `data-state`: `shown`, `empty` (no item, or nothing under
- *   the cursor), `refused` or `detached`.
- * @csspart refusal - The words "Item unavailable", with `data-code` set to the refusal's code where
- *   the server refused the record. A broken pick's details are on the map's `lastPick`.
- * @csspart reason - The server's reason for refusing the record, as it sent it, on a line under
- *   "Item unavailable".
+ * @csspart state - The state line, with `data-state`: `shown`, `empty` (no item, or a click that
+ *   found nothing), `refused` or `detached`.
+ * @csspart refusal - The words "Item unavailable", with `data-code` set to the refusal's code if
+ *   the server refused the record. For a broken pick, the details are in the map's `lastPick`.
+ * @csspart reason - The server's reason for refusing the record, under "Item unavailable".
  * @csspart headline - The headline, with `data-name` set to the field it shows.
- * @csspart subtitle - The value of the `subtitle-field` field under the headline, under `compact`.
- * @csspart show-all - The "Show all N fields" button, under `compact`, with `aria-expanded`.
+ * @csspart subtitle - The `subtitle-field` value under the headline, when `compact` is set.
+ * @csspart show-all - The "Show all N fields" button, when `compact` is set, with `aria-expanded`.
  * @csspart view-chip - One view the item is in, with `data-view` and `aria-current` on the current
  *   view.
  * @csspart field - One field, with `data-name`, and `data-prose` on a value over 60 characters.
@@ -66,42 +50,37 @@ import { MosaicaElement, type PickOutcome } from './base.js';
  */
 export declare class MosaicaItemCard extends MosaicaElement {
     static styles: import("lit").CSSResult[];
-    /**
-     * The item to show, for a host that fetches the record itself. Set with `refusal` or alone, it
-     * replaces the store's selection.
-     */
+    /** The item to show, if you fetch the record yourself. It replaces the store's selection. */
     accessor item: {
         id: bigint;
         detail: ItemDetail;
     } | null;
-    /** A refusal to show in place of an item, for a host that fetches the record itself. */
+    /** A refusal to show instead of an item, if you fetch the record yourself. */
     accessor refusal: Refusal | null;
     /**
-     * What the map's last click resolved to (`<mosaica-map>`'s `lastPick`), shown while no item is
-     * selected: `{kind: 'miss'}` shows "No item here", and a broken pick shows "Item unavailable".
+     * What the map's last click found (`<mosaica-map>`'s `lastPick`), shown while no item is
+     * selected. A miss shows "No item here" and a broken pick shows "Item unavailable".
      */
     accessor pick: PickOutcome;
-    /** The schema for field order and view names, where the card has no store to read it from. */
+    /** The server's `/v1/meta`, for the field order and view names, if the card has no store. */
     accessor meta: Meta | null;
-    /** The field the headline shows. Unset, or where the item has no value for it, the headline is the `mosaica_id`. */
+    /** The field the headline shows. Unset, or if the item has no value for it, the headline is the `mosaica_id`. */
     accessor titleField: string;
-    /** Shows the headline, the subtitle and three fields, with the rest under "Show all N fields". */
+    /** Shows a shorter card: the headline, the subtitle and three fields, with the rest under "Show all N fields". */
     accessor compact: boolean;
-    /** The field shown under the headline under `compact`. Unset, there is no subtitle. */
+    /** The field shown under the headline when `compact` is set. Unset, there is no subtitle. */
     accessor subtitleField: string;
     /**
-     * The fields shown under `compact` before "Show all", space- or comma-separated, in this order.
-     * Unset, the first three in declaration order. A name the record has no value for, and the
-     * `title-field` and `subtitle-field` fields, show nothing here. Show all, and the card without
-     * `compact`, list these fields first and then the rest.
+     * The fields a `compact` card shows before "Show all", separated by spaces or commas, in order.
+     * Unset, the first three. The full list shows these fields first, then the rest.
      */
     accessor cardFields: string;
     /**
-     * The address Open goes to, with `{name}` for the value of the field `name` and `{mosaica_id}`
-     * for the item's id. Unset, and without `open`, there is no Open.
+     * The link template for Open, with `{name}` for the value of the field `name` and `{mosaica_id}`
+     * for the item's id. Without it or `open`, there is no Open button.
      */
     accessor openUrl: string;
-    /** Called when Open is pressed, with the item's `mosaica_id` and fields. Set, it wins over `open-url`. */
+    /** A function called with the item's `mosaica_id` and fields when Open is pressed. Takes precedence over `open-url`. */
     accessor open: ((item: MosaicaEventDetails['mosaica-open']) => void) | null;
     /** Whether "Show all" was pressed, for the item it was pressed on. @internal */
     accessor expanded: boolean;

package/dist/item-card.js

@@ -41,37 +41,22 @@ import { icon } from './icons.js';
 import { reasonOf, refusedState, renderState, stateOf } from './states.js';
 import { chrome, tokens } from './tokens.js';
 /**
- * The selected item's record: a headline, the views it is in, its fields as a label and value
- * grid, its group-scoped values, then Open and Copy id. Fields are listed by name in
- * declaration order, then any the schema does not declare; a field the record has no value for is
- * left out. A declared field is captioned in words (`published_at` as "Published at"). A category
- * field shows its value's title where the vocabulary has one, else its key; the titles are asked
- * of the store (`Store.titleOf`), and an answer is shown only while the store's `meta` is the one
- * it was asked under. A timestamp shows in full, as `14 March 2024, 12:00 UTC`.
- * The close button appears only while the card shows something: an item, a refusal or a click's
- * result.
+ * Use the item card to show the record of the item a viewer has picked on the map, so that they can
+ * read its fields and open it elsewhere. It reads the store's selected item, or the `item` you set
+ * when you fetch records yourself.
  *
- * The headline is the field `title-field` names, else the item's `mosaica_id`. Each field has a
- * slot, `field-<name>`, so a host can render one as a link. The item is the store's selection
- * (`Store.pick`), or the `item` property.
+ * The headline is the `title-field` field, or the item's `mosaica_id` when that field is unset or
+ * empty. To render a field your own way, as a link for example, put an element in its
+ * `field-<name>` slot.
  *
- * `compact` shows less: the headline, cut at three lines, the field `subtitle-field` names under
- * it, cut at two, the fields `card-fields` names (else the first three others), then "Show all N
- * fields" beside Open. Show all lists every field, the views and the group-scoped values, and the
- * card grows to hold them; a container that sets the card a height, such as the explorer's card
- * beside a point, scrolls past it. A host's buttons in the `actions` slot sit beside the close
- * button.
+ * The Open button appears only when you set `open-url` or `open`. `open-url` is a link template
+ * such as `https://www.geonames.org/{geonameid}`, in which each `{name}` is replaced by the item's
+ * value for that field. Because the values are URL-encoded, a template cannot open an address that
+ * a field already holds, so set `open` to a function for that. An item gets no Open button when it
+ * has no value for a field the template names. A function in `open` is called with the item's
+ * `mosaica_id` and fields, and it takes precedence over `open-url`.
  *
- * What Open does is the host's to say, and Open is shown only where it says. The `open` property is
- * called with the item's `mosaica_id` and fields. Otherwise `open-url` is a link template, such as
- * `https://www.geonames.org/{geonameid}`: each `{name}` is replaced by the item's value for the
- * field `name`, URL-encoded, and `{mosaica_id}` by its id where the record has no field of that
- * name. Open is then a link to that address, opening in a new tab. An item with no value, or an
- * empty one, for a field the template names, or whose address is not `http:` or `https:` once
- * filled and resolved against the page, has no Open. Where both are set, `open` is called and
- * `open-url` is unused.
- *
- * @summary The selected item's fields, with Open and Copy id.
+ * @summary A card showing an item's fields, with an optional Open button.
  * @tagname mosaica-item-card
  * @category Elements
  * @slot field-<name> - Replaces the value of the field `<name>`, in the grid or the headline.
@@ -80,18 +65,17 @@ import { chrome, tokens } from './tokens.js';
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-close']>} mosaica-close - The close button was
  *   pressed, with `what` set to `item`.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-viewfollow']>} mosaica-viewfollow - A view chip
- *   was pressed: follow the item into that view, at its position there.
+ *   was pressed, asking to show the item in that view.
  * @csspart title - The header row: the headline or the state, and the close button.
  * @csspart close - The close button.
- * @csspart state - The state line, with `data-state`: `shown`, `empty` (no item, or nothing under
- *   the cursor), `refused` or `detached`.
- * @csspart refusal - The words "Item unavailable", with `data-code` set to the refusal's code where
- *   the server refused the record. A broken pick's details are on the map's `lastPick`.
- * @csspart reason - The server's reason for refusing the record, as it sent it, on a line under
- *   "Item unavailable".
+ * @csspart state - The state line, with `data-state`: `shown`, `empty` (no item, or a click that
+ *   found nothing), `refused` or `detached`.
+ * @csspart refusal - The words "Item unavailable", with `data-code` set to the refusal's code if
+ *   the server refused the record. For a broken pick, the details are in the map's `lastPick`.
+ * @csspart reason - The server's reason for refusing the record, under "Item unavailable".
  * @csspart headline - The headline, with `data-name` set to the field it shows.
- * @csspart subtitle - The value of the `subtitle-field` field under the headline, under `compact`.
- * @csspart show-all - The "Show all N fields" button, under `compact`, with `aria-expanded`.
+ * @csspart subtitle - The `subtitle-field` value under the headline, when `compact` is set.
+ * @csspart show-all - The "Show all N fields" button, when `compact` is set, with `aria-expanded`.
  * @csspart view-chip - One view the item is in, with `data-view` and `aria-current` on the current
  *   view.
  * @csspart field - One field, with `data-name`, and `data-prose` on a value over 60 characters.
@@ -296,57 +280,52 @@ let MosaicaItemCard = (() => {
     `
         ];
         #item_accessor_storage = __runInitializers(this, _item_initializers, null);
-        /**
-         * The item to show, for a host that fetches the record itself. Set with `refusal` or alone, it
-         * replaces the store's selection.
-         */
+        /** The item to show, if you fetch the record yourself. It replaces the store's selection. */
         get item() { return this.#item_accessor_storage; }
         set item(value) { this.#item_accessor_storage = value; }
         #refusal_accessor_storage = (__runInitializers(this, _item_extraInitializers), __runInitializers(this, _refusal_initializers, null));
-        /** A refusal to show in place of an item, for a host that fetches the record itself. */
+        /** A refusal to show instead of an item, if you fetch the record yourself. */
         get refusal() { return this.#refusal_accessor_storage; }
         set refusal(value) { this.#refusal_accessor_storage = value; }
         #pick_accessor_storage = (__runInitializers(this, _refusal_extraInitializers), __runInitializers(this, _pick_initializers, null));
         /**
-         * What the map's last click resolved to (`<mosaica-map>`'s `lastPick`), shown while no item is
-         * selected: `{kind: 'miss'}` shows "No item here", and a broken pick shows "Item unavailable".
+         * What the map's last click found (`<mosaica-map>`'s `lastPick`), shown while no item is
+         * selected. A miss shows "No item here" and a broken pick shows "Item unavailable".
          */
         get pick() { return this.#pick_accessor_storage; }
         set pick(value) { this.#pick_accessor_storage = value; }
         #meta_accessor_storage = (__runInitializers(this, _pick_extraInitializers), __runInitializers(this, _meta_initializers, null));
-        /** The schema for field order and view names, where the card has no store to read it from. */
+        /** The server's `/v1/meta`, for the field order and view names, if the card has no store. */
         get meta() { return this.#meta_accessor_storage; }
         set meta(value) { this.#meta_accessor_storage = value; }
         #titleField_accessor_storage = (__runInitializers(this, _meta_extraInitializers), __runInitializers(this, _titleField_initializers, ''));
-        /** The field the headline shows. Unset, or where the item has no value for it, the headline is the `mosaica_id`. */
+        /** The field the headline shows. Unset, or if the item has no value for it, the headline is the `mosaica_id`. */
         get titleField() { return this.#titleField_accessor_storage; }
         set titleField(value) { this.#titleField_accessor_storage = value; }
         #compact_accessor_storage = (__runInitializers(this, _titleField_extraInitializers), __runInitializers(this, _compact_initializers, false));
-        /** Shows the headline, the subtitle and three fields, with the rest under "Show all N fields". */
+        /** Shows a shorter card: the headline, the subtitle and three fields, with the rest under "Show all N fields". */
         get compact() { return this.#compact_accessor_storage; }
         set compact(value) { this.#compact_accessor_storage = value; }
         #subtitleField_accessor_storage = (__runInitializers(this, _compact_extraInitializers), __runInitializers(this, _subtitleField_initializers, ''));
-        /** The field shown under the headline under `compact`. Unset, there is no subtitle. */
+        /** The field shown under the headline when `compact` is set. Unset, there is no subtitle. */
         get subtitleField() { return this.#subtitleField_accessor_storage; }
         set subtitleField(value) { this.#subtitleField_accessor_storage = value; }
         #cardFields_accessor_storage = (__runInitializers(this, _subtitleField_extraInitializers), __runInitializers(this, _cardFields_initializers, ''));
         /**
-         * The fields shown under `compact` before "Show all", space- or comma-separated, in this order.
-         * Unset, the first three in declaration order. A name the record has no value for, and the
-         * `title-field` and `subtitle-field` fields, show nothing here. Show all, and the card without
-         * `compact`, list these fields first and then the rest.
+         * The fields a `compact` card shows before "Show all", separated by spaces or commas, in order.
+         * Unset, the first three. The full list shows these fields first, then the rest.
          */
         get cardFields() { return this.#cardFields_accessor_storage; }
         set cardFields(value) { this.#cardFields_accessor_storage = value; }
         #openUrl_accessor_storage = (__runInitializers(this, _cardFields_extraInitializers), __runInitializers(this, _openUrl_initializers, ''));
         /**
-         * The address Open goes to, with `{name}` for the value of the field `name` and `{mosaica_id}`
-         * for the item's id. Unset, and without `open`, there is no Open.
+         * The link template for Open, with `{name}` for the value of the field `name` and `{mosaica_id}`
+         * for the item's id. Without it or `open`, there is no Open button.
          */
         get openUrl() { return this.#openUrl_accessor_storage; }
         set openUrl(value) { this.#openUrl_accessor_storage = value; }
         #open_accessor_storage = (__runInitializers(this, _openUrl_extraInitializers), __runInitializers(this, _open_initializers, null));
-        /** Called when Open is pressed, with the item's `mosaica_id` and fields. Set, it wins over `open-url`. */
+        /** A function called with the item's `mosaica_id` and fields when Open is pressed. Takes precedence over `open-url`. */
         get open() { return this.#open_accessor_storage; }
         set open(value) { this.#open_accessor_storage = value; }
         #expanded_accessor_storage = (__runInitializers(this, _open_extraInitializers), __runInitializers(this, _expanded_initializers, false));

package/dist/key-picker.d.ts

@@ -1,17 +1,17 @@
 import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 import { MosaicaElement } from './base.js';
 /**
- * Which view of the current view's group: a select over the group's views in creation order, with
- * previous and next buttons that stop at the ends. Each entry shows the view's label and its key.
- * Renders nothing when the current view is in no group.
+ * Use the key picker when the views of a group follow one another, such as one view per year, so
+ * that viewers can step through them in order. The menu lists the group's views in the order they
+ * were created. The picker shows nothing while the current view is in no group.
  *
- * @summary Chooses the view within the current group.
+ * @summary A drop-down with previous and next buttons for stepping through a group of views.
  * @tagname mosaica-key-picker
  * @category Elements
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-viewswitch']>} mosaica-viewswitch - The view
  *   changed.
  * @csspart field - The caption and the row.
- * @csspart label - The caption, which is the group's name.
+ * @csspart label - The caption, the group's name.
  * @csspart entry - The row of buttons and select.
  * @csspart select - The select.
  * @csspart step - A previous or next button, with `data-direction` set to `prev` or `next`.

package/dist/key-picker.js

@@ -6,17 +6,17 @@ import { icon } from './icons.js';
 import { switchView } from './view-switch.js';
 import { chrome, tokens } from './tokens.js';
 /**
- * Which view of the current view's group: a select over the group's views in creation order, with
- * previous and next buttons that stop at the ends. Each entry shows the view's label and its key.
- * Renders nothing when the current view is in no group.
+ * Use the key picker when the views of a group follow one another, such as one view per year, so
+ * that viewers can step through them in order. The menu lists the group's views in the order they
+ * were created. The picker shows nothing while the current view is in no group.
  *
- * @summary Chooses the view within the current group.
+ * @summary A drop-down with previous and next buttons for stepping through a group of views.
  * @tagname mosaica-key-picker
  * @category Elements
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-viewswitch']>} mosaica-viewswitch - The view
  *   changed.
  * @csspart field - The caption and the row.
- * @csspart label - The caption, which is the group's name.
+ * @csspart label - The caption, the group's name.
  * @csspart entry - The row of buttons and select.
  * @csspart select - The select.
  * @csspart step - A previous or next button, with `data-direction` set to `prev` or `next`.