@mosaicajs/components 0.1.0-rc.4 → 0.1.0

package/dist/field-card.js

@@ -100,59 +100,27 @@ function binsOf(table, timestamp) {
     return out;
 }
 /**
- * One field as a card in the filter panel: a category's commonest values, a layer's largest
- * clusters, a number's or a date's histogram, or a text field's search box, under the field's name.
- * `field` is a column `meta.filterOperands` lists, or `cluster:<layer>` for a layer whose clusters
- * can be filtered by.
+ * Use a field card on its own when you want one field's chart in a place of your choosing.
+ * `<mosaica-filter-panel>` shows one for each field. Set `field` to a column `meta.filterOperands`
+ * lists, or to `cluster:<layer>` for a layer's clusters.
  *
- * The counts are taken over two sets. The subject is what is in view: the items in the camera's box
- * that the filters admit, or the highlighted ones while a highlight is set. The whole match is every
- * item the filters admit. Both leave out the card's own clause in the filter position, so a value
- * its clause excludes keeps its count. The card keeps three aggregates registered with the store
- * while it is drawn (`Store.setAggregate`): the subject's counts (`subject: 'view'` with
- * `highlighted`), the whole match's, and for a number or a date its figures over everything the
- * viewer may see (`subject: 'visible'`). A folded card asks for the subject's alone.
+ * The solid bars count the items in view that the filters match, or the highlighted items while
+ * there is a highlight. The pale bars count every item the filters match. Neither count applies the
+ * card's own filter, so a value the viewer has filtered out keeps its count.
  *
- * A category or cluster card lists five values, those with most items in the subject first and any
- * its own clauses name, with "N more" opening it to twenty. Each row has its name (a cluster's
- * parents in grey after it), a solid bar for its share of the subject and a pale bar for its share
- * of the whole match, each a share of its own total, and the two counts. Under a filter on the
- * field, the values it leaves out are greyed and show only how many items they would add, and the
- * shares are of what the filter keeps. Hovering or focusing a row shows Highlight and Filter, which
- * put the value in or out of the field's clause in that position. A click or tap on the row does
- * what its Filter button does and shows its buttons; the row takes no focus, and the keyboard
- * reaches the buttons. Over the rows is the field's search box, the typeahead of
- * `<mosaica-filter>` or `<mosaica-cluster-filter>`, whose choice joins the filter. A levelled
- * layer's card has a Level choice in its heading, the top (coarsest) level by default, which fires
- * `mosaica-levelchange`. A cluster card ranks a `nested` or `dag` layer's clusters at the cut the
- * map draws (`cut: 'drawn'`), and a flat or levelled layer's at its level.
- * A cluster is named as the aggregate's table names it, which is the name the layer's browse pages
- * give the same viewer. On a `nested` or `dag` layer its path is named from a browse page of its
- * parents and one of its first parent's.
+ * What the card shows depends on the kind of field:
  *
- * A number or date card draws about twenty bins over the values the viewer may see, the pale bar
- * the whole match and the solid one the subject, each bin's height its share of its own set, scaled
- * so the tallest share fills the plot. The counts are taken from a sample of about 100,000 items
- * where a set is larger, and an estimate is marked "≈". Dragging across the bins, or the arrow keys
- * with Shift on the focused plot and then Enter, opens a box naming the range and how many items
- * match in it, with Filter and Highlight, which set the field's range in that position. A range set
- * on the field is outlined on the plot. The heading gives the field's figures: how many items hold
- * a value and their mean, or their range while folded.
+ * - A category or cluster card lists the values with most items in view, each with Highlight and
+ *   Filter buttons.
+ * - A number or date card draws a histogram, and the viewer drags across it to pick a range to
+ *   filter or highlight by. From the keyboard, they press Shift and the arrow keys on the focused
+ *   plot, then Enter. Counts over about 100,000 items come from a sample, so they are marked "≈".
+ * - A text or keyword field's card is a search box, `<mosaica-filter>`.
  *
- * A text or keyword field is its `<mosaica-filter>` search box.
+ * While the paint button colours the map by the field, clicking a value's colour opens a picker
+ * that changes the colour on the map.
  *
- * The paint button colours the map by the field, or by nothing where it already does
- * (`Store.setColourBy`), and is pressed while it does. Then a category or cluster card shows each
- * value's colour beside it, and a number or date card the ramp under its plot. Each colour is a
- * button that opens a colour picker: the palette's colours and a lighter row, a custom area with a
- * hue bar and a hex field, and Reset, which gives the value or the cluster its palette colour back.
- * A choice applies at once and fires `mosaica-valuecolour` for a category value, written to the
- * colour choices every element over the store shares, or `mosaica-clustercolour` for a cluster,
- * set on the store with its other chosen colours (`Store.setArtifactColours`).
- *
- * `folded` draws the heading alone, with a small chart of the subject's counts.
- *
- * @summary One field's counts in view and overall, with its filter and highlight.
+ * @summary A card that charts one field's values and filters or highlights by them.
  * @tagname mosaica-field-card
  * @category Elements
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-filterchange']>} mosaica-filterchange - A row's
@@ -177,11 +145,11 @@ function binsOf(table, timestamp) {
  * @csspart paint - The paint button, with `aria-pressed`.
  * @csspart fold - The fold button, with `aria-expanded`.
  * @csspart rows - A category or cluster card's rows.
- * @csspart row - One row, with `data-key` and `data-state`: `in` for a value the field's filter
- *   keeps, `out` for one it leaves out, `lit` for one its highlight lights, else empty.
- * @csspart swatch - A row's colour, while the map is coloured by the field, a button that opens the
- *   colour picker, with `data-unmet` and drawn as an outline for a category value the map has not
- *   drawn yet and so has given no colour.
+ * @csspart row - One row, with `data-key` and `data-state`: `in` if the field's filter keeps the
+ *   value, `out` if it leaves it out, `lit` if it is highlighted, otherwise empty.
+ * @csspart swatch - A row's colour button, while the map is coloured by the field. It opens the
+ *   colour picker. It carries `data-unmet`, and is drawn as an outline, for a value the map has not
+ *   drawn yet and so has not given a colour.
  * @csspart name - A row's name, with `data-unnamed` for a cluster that has none.
  * @csspart path - A cluster row's parents.
  * @csspart bar-match - A row's or a bin's pale bar, its share of the whole match.
@@ -664,15 +632,15 @@ let MosaicaFieldCard = (() => {
         get field() { return this.#field_accessor_storage; }
         set field(value) { this.#field_accessor_storage = value; }
         #folded_accessor_storage = (__runInitializers(this, _field_extraInitializers), __runInitializers(this, _folded_initializers, false));
-        /** Draws the heading alone, with a small chart of the subject's counts. */
+        /** Shows the heading alone, with a small chart of the counts in view. */
         get folded() { return this.#folded_accessor_storage; }
         set folded(value) { this.#folded_accessor_storage = value; }
         #compact_accessor_storage = (__runInitializers(this, _folded_extraInitializers), __runInitializers(this, _compact_initializers, false));
-        /** Draws the small chart for the compact layout. */
+        /** Draws a folded card in the compact style the explorer uses in narrow containers. */
         get compact() { return this.#compact_accessor_storage; }
         set compact(value) { this.#compact_accessor_storage = value; }
         #level_accessor_storage = (__runInitializers(this, _compact_extraInitializers), __runInitializers(this, _level_initializers, null));
-        /** The level a levelled layer's card counts at; `null` is its top level. */
+        /** The level a card for a layer with levels counts at. `null` is the coarsest level. */
         get level() { return this.#level_accessor_storage; }
         set level(value) { this.#level_accessor_storage = value; }
         #expanded_accessor_storage = (__runInitializers(this, _level_extraInitializers), __runInitializers(this, _expanded_initializers, false));

package/dist/filter-panel.d.ts

@@ -5,59 +5,44 @@ import './field-card.js';
 /** The layers whose clusters a viewer can filter by in `view`: those `meta` lists for it that attach to no other. */
 export declare function clusterFieldLayers(meta: Meta, view: string): Layer[];
 /**
- * The filter panel: what the cards count, the clauses applied, and one `<mosaica-field-card>` per
- * field.
+ * Use the filter panel as the place where viewers narrow the map down, as `<mosaica-explorer>` does
+ * in its sidebar. Each filter or highlight in force shows as a chip above the cards, and pressing a
+ * chip opens its field's card.
  *
- * The subject row names what the cards' solid bars count, In view and the number of matching items
- * in the camera's box (the store's counts in view), or Highlighted and the number highlighted there
- * while a highlight is set, with a × that clears the highlight. Beside it, All matching names what
- * the pale bars count: every item the filters admit, from an aggregate the panel keeps registered.
+ * The row at the top says what the cards' solid bars count. That is the items in view that the
+ * filters match, or the highlighted items while there is a highlight. The pale bars count
+ * everything the filters match, so that viewers can compare what is in view with the whole.
  *
- * While any clause is applied, a line lists each as a chip: a filter clause plain, a highlight
- * clause in the highlight colour, and a `member_of` clause by its cluster's name. Pressing a
- * column's chip opens and focuses its card, or under `chips-only` fires `mosaica-chipopen`; its ×
- * empties that clause, leaving the other position's alone. Clear all empties every clause in both
- * positions and drops every `member_of` clause.
+ * The panel shows a card for each field in `pinned`, for each field that holds a filter or
+ * highlight, and for the field the map is coloured by. Viewers add other fields with Add field.
+ * Taking a card off clears that field's filters and highlights.
  *
- * The fields are the filterable columns and the layers whose clusters can be filtered by: every
- * layer `meta` lists for the current view that attaches to no other. The cards listed are the
- * fields in `pinned` (a layer's as `cluster:<layer>`), the fields holding a clause in either
- * position, the field the map is coloured by, and any field added, in `meta`'s order, the columns
- * then the layers; a field joins the end of the list, so the cards shown do not move. Add field lists every field, the columns then the layers, with a search box,
- * and the listed ones are checked and say Shown; its list opens under the column, as wide as it.
- * Choosing an unchecked field adds its card. Choosing a checked one takes the card off and empties
- * the field's clauses in both positions; a column in `pinned` stays, since the host lists it. Enter
- * in the search box adds the first match not yet listed and never takes one off. Beside Add field,
- * how many fields are not listed.
+ * Set `chips-only` on one panel and `controls-only` on another when you want the chips apart from
+ * the cards.
  *
- * A card folds to one line from its own button. Under `compact` every card is folded but one, and
- * opening one folds the one open before. `chips-only` renders the line of clauses alone, and
- * nothing while none is applied; `controls-only` leaves the subject row and the clauses out.
- *
- * @summary The field cards, what they count, and the clauses applied.
+ * @summary A panel of field cards for filtering and highlighting the map by any field.
  * @tagname mosaica-filter-panel
  * @category Elements
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-filterchange']>} mosaica-filterchange - A
- *   column's chip was removed (with `verb`, the position it was in, and `expr` null), Clear all was
- *   pressed (with `column` and `expr` null), or the highlight was cleared from the subject row (with
- *   `column` and `expr` null and `verb` `highlight`). Removing a `member_of` chip fires nothing. Each
- *   card fires its own as well.
+ *   column's chip was removed, Clear all was pressed, the highlight was cleared from the subject
+ *   row, or a card was taken off in Add field. Removing a `member_of` chip fires nothing. Each card
+ *   fires its own as well.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-chipopen']>} mosaica-chipopen - A column's chip
- *   was pressed under `chips-only`, naming the column and the position of its clause.
+ *   was pressed while `chips-only` is set, so you can show its card.
  * @csspart state - The state line, with `data-state`.
  * @csspart refusal - The words "View refused", with `data-code`, in the refused state.
- * @csspart reason - The server's reason for a refusal, on a line under "View refused".
+ * @csspart reason - The server's reason for a refusal, under "View refused".
  * @csspart subject - The subject row.
- * @csspart subject-key - The subject's colour, as its bars are drawn.
+ * @csspart subject-key - The colour of the subject's bars.
  * @csspart subject-name - In view, or Highlighted while a highlight is set.
  * @csspart subject-count - The number in view, or highlighted.
  * @csspart clear-highlight - The × beside Highlighted, which clears the highlight.
  * @csspart all - All matching and its number.
  * @csspart all-count - The number matching.
- * @csspart chips - The line of clauses applied, while there are any.
- * @csspart chip - One clause, with `data-verb` (`filter` or `highlight`) and `data-column` or
+ * @csspart chips - The line of chips, while any filter or highlight is in force.
+ * @csspart chip - One chip, with `data-verb` (`filter` or `highlight`) and `data-column` or
  *   `data-artifact`.
- * @csspart edit - The button that is a column chip's text, which opens its card.
+ * @csspart edit - A column chip's text, a button that opens its card.
  * @csspart clear - The Clear all button.
  * @csspart card - One `<mosaica-field-card>`, with `data-field`.
  * @csspart add - The Add field button, with `aria-expanded`.
@@ -65,24 +50,25 @@ export declare function clusterFieldLayers(meta: Meta, view: string): Layer[];
  * @csspart add-list - The list of fields to add, while it is open.
  * @csspart add-search - The search box over that list.
  * @csspart add-option - One field in that list, with `data-column` or `data-layer`, `aria-checked`
- *   while it is listed, and `aria-disabled` where it is pinned and so cannot be taken off.
- * @csspart field-card-<part> - A part of a card, forwarded under a `field-card-` prefix.
+ *   while its card is shown, and `aria-disabled` if it is pinned and cannot be taken off.
+ * @csspart field-card-<part> - A part of a card.
  * @csspart filter-<part> - A part of a card's `<mosaica-filter>` search box.
  * @csspart cluster-filter-<part> - A part of a card's `<mosaica-cluster-filter>` search box.
  */
 export declare class MosaicaFilterPanel extends MosaicaElement {
-    /** Renders the line of clauses alone, and nothing while none is applied. */
+    /** Shows only the chips, and nothing while no filter or highlight is in force. */
     accessor chipsOnly: boolean;
-    /** Renders the cards and Add field without the subject row and the clauses. */
+    /** Shows the cards and Add field without the subject row and the chips. */
     accessor controlsOnly: boolean;
     /**
-     * The columns whose cards are listed whether or not they hold a clause, space- or
-     * comma-separated. Unset, only the fields holding a clause are listed until the user adds one.
+     * The columns whose cards always show, even when they hold no filter, separated by spaces or
+     * commas. Write a layer as `cluster:<layer>`. Unset, a card shows only once its field is filtered
+     * or the viewer adds it.
      */
     accessor pinned: string;
-    /** Folds every card but one, and shortens the subject row's figures. */
+    /** Keeps one card open at a time, and shortens the subject row's figures. */
     accessor compact: boolean;
-    /** The level the cards of levelled layers count at, passed to each; `null` is their top level. */
+    /** The level that cards for layers with levels count at. `null` is the coarsest level. */
     accessor clusterLevel: number | null;
     /** The fields the user added, which stay listed. @internal */
     accessor opened: ReadonlySet<string>;
@@ -114,7 +100,7 @@ export declare class MosaicaFilterPanel extends MosaicaElement {
     protected onStoreChange(): void;
     protected onStoreAdopted(): void;
     disconnectedCallback(): void;
-    /** List `field`'s card, open it, and scroll to and focus it once drawn. A host showing the cards after `mosaica-chipopen` calls this. */
+    /** Show `field`'s card, open it, and scroll to and focus it. Call it after `mosaica-chipopen` to show the chip's card. */
     show(field: string): void;
     /** Moves focus to the first card's search box or plot, else Add field. */
     focus(options?: FocusOptions): void;

package/dist/filter-panel.js

@@ -58,59 +58,44 @@ const VERBS = ['filter', 'highlight'];
 /** A figure in the subject row: whole, or shortened in the compact layout. */
 const figure = (n, compact) => (compact ? shortCount(n) : countText(n));
 /**
- * The filter panel: what the cards count, the clauses applied, and one `<mosaica-field-card>` per
- * field.
+ * Use the filter panel as the place where viewers narrow the map down, as `<mosaica-explorer>` does
+ * in its sidebar. Each filter or highlight in force shows as a chip above the cards, and pressing a
+ * chip opens its field's card.
  *
- * The subject row names what the cards' solid bars count, In view and the number of matching items
- * in the camera's box (the store's counts in view), or Highlighted and the number highlighted there
- * while a highlight is set, with a × that clears the highlight. Beside it, All matching names what
- * the pale bars count: every item the filters admit, from an aggregate the panel keeps registered.
+ * The row at the top says what the cards' solid bars count. That is the items in view that the
+ * filters match, or the highlighted items while there is a highlight. The pale bars count
+ * everything the filters match, so that viewers can compare what is in view with the whole.
  *
- * While any clause is applied, a line lists each as a chip: a filter clause plain, a highlight
- * clause in the highlight colour, and a `member_of` clause by its cluster's name. Pressing a
- * column's chip opens and focuses its card, or under `chips-only` fires `mosaica-chipopen`; its ×
- * empties that clause, leaving the other position's alone. Clear all empties every clause in both
- * positions and drops every `member_of` clause.
+ * The panel shows a card for each field in `pinned`, for each field that holds a filter or
+ * highlight, and for the field the map is coloured by. Viewers add other fields with Add field.
+ * Taking a card off clears that field's filters and highlights.
  *
- * The fields are the filterable columns and the layers whose clusters can be filtered by: every
- * layer `meta` lists for the current view that attaches to no other. The cards listed are the
- * fields in `pinned` (a layer's as `cluster:<layer>`), the fields holding a clause in either
- * position, the field the map is coloured by, and any field added, in `meta`'s order, the columns
- * then the layers; a field joins the end of the list, so the cards shown do not move. Add field lists every field, the columns then the layers, with a search box,
- * and the listed ones are checked and say Shown; its list opens under the column, as wide as it.
- * Choosing an unchecked field adds its card. Choosing a checked one takes the card off and empties
- * the field's clauses in both positions; a column in `pinned` stays, since the host lists it. Enter
- * in the search box adds the first match not yet listed and never takes one off. Beside Add field,
- * how many fields are not listed.
+ * Set `chips-only` on one panel and `controls-only` on another when you want the chips apart from
+ * the cards.
  *
- * A card folds to one line from its own button. Under `compact` every card is folded but one, and
- * opening one folds the one open before. `chips-only` renders the line of clauses alone, and
- * nothing while none is applied; `controls-only` leaves the subject row and the clauses out.
- *
- * @summary The field cards, what they count, and the clauses applied.
+ * @summary A panel of field cards for filtering and highlighting the map by any field.
  * @tagname mosaica-filter-panel
  * @category Elements
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-filterchange']>} mosaica-filterchange - A
- *   column's chip was removed (with `verb`, the position it was in, and `expr` null), Clear all was
- *   pressed (with `column` and `expr` null), or the highlight was cleared from the subject row (with
- *   `column` and `expr` null and `verb` `highlight`). Removing a `member_of` chip fires nothing. Each
- *   card fires its own as well.
+ *   column's chip was removed, Clear all was pressed, the highlight was cleared from the subject
+ *   row, or a card was taken off in Add field. Removing a `member_of` chip fires nothing. Each card
+ *   fires its own as well.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-chipopen']>} mosaica-chipopen - A column's chip
- *   was pressed under `chips-only`, naming the column and the position of its clause.
+ *   was pressed while `chips-only` is set, so you can show its card.
  * @csspart state - The state line, with `data-state`.
  * @csspart refusal - The words "View refused", with `data-code`, in the refused state.
- * @csspart reason - The server's reason for a refusal, on a line under "View refused".
+ * @csspart reason - The server's reason for a refusal, under "View refused".
  * @csspart subject - The subject row.
- * @csspart subject-key - The subject's colour, as its bars are drawn.
+ * @csspart subject-key - The colour of the subject's bars.
  * @csspart subject-name - In view, or Highlighted while a highlight is set.
  * @csspart subject-count - The number in view, or highlighted.
  * @csspart clear-highlight - The × beside Highlighted, which clears the highlight.
  * @csspart all - All matching and its number.
  * @csspart all-count - The number matching.
- * @csspart chips - The line of clauses applied, while there are any.
- * @csspart chip - One clause, with `data-verb` (`filter` or `highlight`) and `data-column` or
+ * @csspart chips - The line of chips, while any filter or highlight is in force.
+ * @csspart chip - One chip, with `data-verb` (`filter` or `highlight`) and `data-column` or
  *   `data-artifact`.
- * @csspart edit - The button that is a column chip's text, which opens its card.
+ * @csspart edit - A column chip's text, a button that opens its card.
  * @csspart clear - The Clear all button.
  * @csspart card - One `<mosaica-field-card>`, with `data-field`.
  * @csspart add - The Add field button, with `aria-expanded`.
@@ -118,8 +103,8 @@ const figure = (n, compact) => (compact ? shortCount(n) : countText(n));
  * @csspart add-list - The list of fields to add, while it is open.
  * @csspart add-search - The search box over that list.
  * @csspart add-option - One field in that list, with `data-column` or `data-layer`, `aria-checked`
- *   while it is listed, and `aria-disabled` where it is pinned and so cannot be taken off.
- * @csspart field-card-<part> - A part of a card, forwarded under a `field-card-` prefix.
+ *   while its card is shown, and `aria-disabled` if it is pinned and cannot be taken off.
+ * @csspart field-card-<part> - A part of a card.
  * @csspart filter-<part> - A part of a card's `<mosaica-filter>` search box.
  * @csspart cluster-filter-<part> - A part of a card's `<mosaica-cluster-filter>` search box.
  */
@@ -186,26 +171,27 @@ let MosaicaFilterPanel = (() => {
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
         #chipsOnly_accessor_storage = __runInitializers(this, _chipsOnly_initializers, false);
-        /** Renders the line of clauses alone, and nothing while none is applied. */
+        /** Shows only the chips, and nothing while no filter or highlight is in force. */
         get chipsOnly() { return this.#chipsOnly_accessor_storage; }
         set chipsOnly(value) { this.#chipsOnly_accessor_storage = value; }
         #controlsOnly_accessor_storage = (__runInitializers(this, _chipsOnly_extraInitializers), __runInitializers(this, _controlsOnly_initializers, false));
-        /** Renders the cards and Add field without the subject row and the clauses. */
+        /** Shows the cards and Add field without the subject row and the chips. */
         get controlsOnly() { return this.#controlsOnly_accessor_storage; }
         set controlsOnly(value) { this.#controlsOnly_accessor_storage = value; }
         #pinned_accessor_storage = (__runInitializers(this, _controlsOnly_extraInitializers), __runInitializers(this, _pinned_initializers, ''));
         /**
-         * The columns whose cards are listed whether or not they hold a clause, space- or
-         * comma-separated. Unset, only the fields holding a clause are listed until the user adds one.
+         * The columns whose cards always show, even when they hold no filter, separated by spaces or
+         * commas. Write a layer as `cluster:<layer>`. Unset, a card shows only once its field is filtered
+         * or the viewer adds it.
          */
         get pinned() { return this.#pinned_accessor_storage; }
         set pinned(value) { this.#pinned_accessor_storage = value; }
         #compact_accessor_storage = (__runInitializers(this, _pinned_extraInitializers), __runInitializers(this, _compact_initializers, false));
-        /** Folds every card but one, and shortens the subject row's figures. */
+        /** Keeps one card open at a time, and shortens the subject row's figures. */
         get compact() { return this.#compact_accessor_storage; }
         set compact(value) { this.#compact_accessor_storage = value; }
         #clusterLevel_accessor_storage = (__runInitializers(this, _compact_extraInitializers), __runInitializers(this, _clusterLevel_initializers, null));
-        /** The level the cards of levelled layers count at, passed to each; `null` is their top level. */
+        /** The level that cards for layers with levels count at. `null` is the coarsest level. */
         get clusterLevel() { return this.#clusterLevel_accessor_storage; }
         set clusterLevel(value) { this.#clusterLevel_accessor_storage = value; }
         #opened_accessor_storage = (__runInitializers(this, _clusterLevel_extraInitializers), __runInitializers(this, _opened_initializers, new Set()));
@@ -440,7 +426,7 @@ let MosaicaFilterPanel = (() => {
             this.matching.set(null, null);
             super.disconnectedCallback();
         }
-        /** List `field`'s card, open it, and scroll to and focus it once drawn. A host showing the cards after `mosaica-chipopen` calls this. */
+        /** Show `field`'s card, open it, and scroll to and focus it. Call it after `mosaica-chipopen` to show the chip's card. */
         show(field) {
             this.opened = new Set([...this.opened, field]);
             this.unfold(field);

package/dist/filter.d.ts

@@ -7,54 +7,46 @@ type KeywordOperator = (typeof KEYWORD_OPERATORS)[number];
 /** Each operator as the menu and a chip say it. */
 export declare const OPERATOR_WORDS: Record<KeywordOperator, string>;
 /**
- * The search box of a field card for the column `column`, drawn by the family `/v1/meta` gives the
- * column. It edits the column's clause in the filter position (`Store.setFilters`).
+ * Use `<mosaica-filter>` when you want a search box for one column without the field card around
+ * it. Set `column` to a column `meta.filterOperands` lists. The box takes the form that the
+ * column's kind needs:
  *
- * A text column is one box. Its words must all appear; words in double quotes are a phrase, or
- * plain words where the column takes no phrase; `OR` between terms asks for either. A text clause
- * set from outside that no query writes shows read-only.
+ * - A text column takes words that an item must all contain. Double quotes match a phrase where the
+ *   column supports phrases, and `OR` between terms matches either.
+ * - A category column suggests values as the viewer types. The arrow keys move through the
+ *   suggestions, Enter chooses or removes one, and Escape clears what was typed.
+ * - A keyword column has a menu for choosing how to match, by `contains`, `prefix` or `eq`.
  *
- * A category is a box over `/v1/categories/{column}/suggest`. Its suggestions open over what sits
- * below the box while the box has focus and holds text. Each value suggested shows its count in
- * the current view among the items passing the filter without the column's own clause, so a value
- * counts what choosing it as well would add, and a bar, its share of the total the server counted
- * over. The arrow keys move through the suggestions, and Enter chooses the one reached, the first
- * by default, or takes it out where it is chosen; text that suggests nothing chooses nothing.
- * Emptying the box, or removing the control, has the store stop asking for the column.
+ * The box sets the filter 350 ms after the last keystroke, so that the map does not redraw for
+ * every letter. If your code sets a text filter the box cannot express, the box shows it read-only.
  *
- * A keyword column is a box with its operator (`contains`, `prefix` or `eq`) in a menu.
- *
- * Typing is sent 350 ms after the last keystroke; a choice is sent at once. Each change replaces
- * the column's control in the filter position of the store's draft.
- *
- * @summary A field card's search box.
+ * @summary A search box that filters the map by one column.
  * @tagname mosaica-filter
  * @category Elements
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-filterchange']>} mosaica-filterchange - The box
- *   changed the column's filter, with the expression the filter position composes.
+ *   changed the column's filter.
  * @csspart entry - The box.
  * @csspart mode - The keyword column's operator button, which opens its menu.
  * @csspart operators - The menu of a keyword column's operators.
  * @csspart operator - One operator in the menu, with `aria-checked`.
  * @csspart values - The typeahead's suggestions.
  * @csspart tick - One suggested value, with `aria-selected`.
- * @csspart bar - A suggested value's share of the items its count is taken over.
+ * @csspart bar - A bar for a suggested value's share of the items counted.
  * @csspart value-count - A suggested value's count.
- * @csspart more - The note under the box: nothing starts with the text, or more values match than
- *   one page holds.
- * @csspart refusal - The words "Values unavailable" where the values could not be listed, with
+ * @csspart more - The note under the box when nothing matches, or when more values match than are
+ *   listed.
+ * @csspart refusal - The words "Values unavailable" if the values could not be listed, with
  *   `data-code` set to the refusal's code.
  */
 export declare class MosaicaFilter extends MosaicaElement {
     static styles: import("lit").CSSResult[];
-    /** The column this box filters, a name `meta.filterOperands` lists. Unset or unknown, it renders nothing. */
+    /** The column this box filters, a name `meta.filterOperands` lists. Unset or unknown, the box shows nothing. */
     accessor column: string;
-    /** The box's placeholder, in place of its own. */
+    /** Placeholder text for the box, in place of the default. */
     accessor placeholder: string;
     /**
-     * Where set, a category's box picks a value rather than filtering by it: choosing a suggestion
-     * calls this with its key and its title, changes no filter and empties the box, and no
-     * suggestion shows as chosen.
+     * Turns a category box into a value picker. Choosing a suggestion calls this with its key and
+     * title and empties the box, and no filter changes.
      */
     accessor choose: ((value: {
         key: string;

package/dist/filter.js

@@ -50,42 +50,35 @@ const TYPING_DEBOUNCE_MS = 350;
 /** The narrowest bar a suggested value with any items draws, as a percentage, so it still shows. */
 const BAR_FLOOR = 2;
 /**
- * The search box of a field card for the column `column`, drawn by the family `/v1/meta` gives the
- * column. It edits the column's clause in the filter position (`Store.setFilters`).
+ * Use `<mosaica-filter>` when you want a search box for one column without the field card around
+ * it. Set `column` to a column `meta.filterOperands` lists. The box takes the form that the
+ * column's kind needs:
  *
- * A text column is one box. Its words must all appear; words in double quotes are a phrase, or
- * plain words where the column takes no phrase; `OR` between terms asks for either. A text clause
- * set from outside that no query writes shows read-only.
+ * - A text column takes words that an item must all contain. Double quotes match a phrase where the
+ *   column supports phrases, and `OR` between terms matches either.
+ * - A category column suggests values as the viewer types. The arrow keys move through the
+ *   suggestions, Enter chooses or removes one, and Escape clears what was typed.
+ * - A keyword column has a menu for choosing how to match, by `contains`, `prefix` or `eq`.
  *
- * A category is a box over `/v1/categories/{column}/suggest`. Its suggestions open over what sits
- * below the box while the box has focus and holds text. Each value suggested shows its count in
- * the current view among the items passing the filter without the column's own clause, so a value
- * counts what choosing it as well would add, and a bar, its share of the total the server counted
- * over. The arrow keys move through the suggestions, and Enter chooses the one reached, the first
- * by default, or takes it out where it is chosen; text that suggests nothing chooses nothing.
- * Emptying the box, or removing the control, has the store stop asking for the column.
+ * The box sets the filter 350 ms after the last keystroke, so that the map does not redraw for
+ * every letter. If your code sets a text filter the box cannot express, the box shows it read-only.
  *
- * A keyword column is a box with its operator (`contains`, `prefix` or `eq`) in a menu.
- *
- * Typing is sent 350 ms after the last keystroke; a choice is sent at once. Each change replaces
- * the column's control in the filter position of the store's draft.
- *
- * @summary A field card's search box.
+ * @summary A search box that filters the map by one column.
  * @tagname mosaica-filter
  * @category Elements
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-filterchange']>} mosaica-filterchange - The box
- *   changed the column's filter, with the expression the filter position composes.
+ *   changed the column's filter.
  * @csspart entry - The box.
  * @csspart mode - The keyword column's operator button, which opens its menu.
  * @csspart operators - The menu of a keyword column's operators.
  * @csspart operator - One operator in the menu, with `aria-checked`.
  * @csspart values - The typeahead's suggestions.
  * @csspart tick - One suggested value, with `aria-selected`.
- * @csspart bar - A suggested value's share of the items its count is taken over.
+ * @csspart bar - A bar for a suggested value's share of the items counted.
  * @csspart value-count - A suggested value's count.
- * @csspart more - The note under the box: nothing starts with the text, or more values match than
- *   one page holds.
- * @csspart refusal - The words "Values unavailable" where the values could not be listed, with
+ * @csspart more - The note under the box when nothing matches, or when more values match than are
+ *   listed.
+ * @csspart refusal - The words "Values unavailable" if the values could not be listed, with
  *   `data-code` set to the refusal's code.
  */
 let MosaicaFilter = (() => {
@@ -308,18 +301,17 @@ let MosaicaFilter = (() => {
     `
         ];
         #column_accessor_storage = __runInitializers(this, _column_initializers, '');
-        /** The column this box filters, a name `meta.filterOperands` lists. Unset or unknown, it renders nothing. */
+        /** The column this box filters, a name `meta.filterOperands` lists. Unset or unknown, the box shows nothing. */
         get column() { return this.#column_accessor_storage; }
         set column(value) { this.#column_accessor_storage = value; }
         #placeholder_accessor_storage = (__runInitializers(this, _column_extraInitializers), __runInitializers(this, _placeholder_initializers, ''));
-        /** The box's placeholder, in place of its 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, a category's box picks a value rather than filtering by it: choosing a suggestion
-         * calls this with its key and its title, changes no filter and empties the box, and no
-         * suggestion shows as chosen.
+         * Turns a category box into a value picker. Choosing a suggestion calls this with its key and
+         * title and empties the box, and no filter changes.
          */
         get choose() { return this.#choose_accessor_storage; }
         set choose(value) { this.#choose_accessor_storage = value; }