@mosaicajs/components 0.3.0 → 0.4.0

package/dist/explorer.d.ts

@@ -59,7 +59,20 @@ type Pinned = {
  * HTML.
  *
  * Below 1000 px the explorer uses the overlay layout whatever `layout` says. At 720 px or less it
- * opens its panels as sheets from a tab bar.
+ * opens its panels as sheets from a bar of buttons under the map, and a picked item's card opens
+ * in the Item sheet. A sheet that reaches up over the map's tools makes the map behind it inert
+ * until it closes.
+ *
+ * The status strip speaks for the explorer: its map and its selection card are set `quiet`, so a
+ * change is announced once. Where you put something other than a `<mosaica-status>` in the
+ * `status` slot, they announce for themselves.
+ *
+ * An `aria-label` on the explorer names its map, so a page with several explorers can tell them
+ * apart.
+ *
+ * A dataset title, a view's name or a layer's name too long for its line is cut with an ellipsis
+ * and keeps all of it in its `title`. Set `--mosaica-long-text: normal` to wrap them. The narrow
+ * layout wraps them itself.
  *
  * @summary A complete map application in a single element.
  * @tagname mosaica-explorer
@@ -69,7 +82,7 @@ type Pinned = {
  * @slot filters - Replaces the filter panel.
  * @slot selection - Replaces the selection panel, shown while a region is selected.
  * @slot detail - Replaces the item and artifact cards, in the card beside the point.
- * @slot status - Replaces the status strip drawn on the map.
+ * @slot status - Replaces the status strip: on the map, or under it in the narrow layout.
  * @slot tooltip - Replaces the map's hover tooltip.
  * @slot top-right - Content in the map's top-right corner, above the selection's card.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-viewchange']>} mosaica-viewchange - The map's camera moved.
@@ -82,11 +95,11 @@ type Pinned = {
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-selectchange']>} mosaica-selectchange - A selection was drawn, changed or cleared, or its counts arrived.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-layerchange']>} mosaica-layerchange - The layers chosen changed.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-colourchange']>} mosaica-colourchange - Colour by changed, in the Layers popover or by a card's paint button.
- * @fires {CustomEvent<MosaicaEventDetails['mosaica-levelchange']>} mosaica-levelchange - The level a layer is coloured and labelled at changed.
+ * @fires {CustomEvent<MosaicaEventDetails['mosaica-levelchange']>} mosaica-levelchange - The level one layer is counted, coloured and labelled at changed.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-displaychange']>} mosaica-displaychange - A setting in the Points or Density section changed.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-sizechange']>} mosaica-sizechange - Size by, the size range or the scale changed in the Points section.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-budgetchange']>} mosaica-budgetchange - Most points was let go at a new number.
- * @fires {CustomEvent<MosaicaEventDetails['mosaica-clusterbudgetchange']>} mosaica-clusterbudgetchange - Most clusters was let go at a new number.
+ * @fires {CustomEvent<MosaicaEventDetails['mosaica-clusterspacingchange']>} mosaica-clusterspacingchange - Cluster density was let go at a new spacing.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-fold']>} mosaica-fold - A field card was folded to one line or opened.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-valuecolour']>} mosaica-valuecolour - Colours were chosen or reset for values of a category, on a field card or in Edit colours.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-clustercolour']>} mosaica-clustercolour - Colours were chosen or reset for clusters of a layer, on a field card or in Edit colours.
@@ -123,8 +136,9 @@ type Pinned = {
  * @csspart points-toggle - The Points switch, with `aria-checked`.
  * @csspart most-points - The Most points slider.
  * @csspart most-points-value - The number of points it stands at, such as "250K".
- * @csspart most-clusters - The Most clusters slider, while a `nested` or `dag` layer is drawn.
- * @csspart most-clusters-value - The number of clusters it stands at, such as "1K".
+ * @csspart cluster-density - The Cluster density slider, while a `nested` or `dag` layer is drawn, or a
+ *   levelled layer whose level follows the zoom is drawn or coloured by.
+ * @csspart cluster-density-value - How many clusters it gives the map at its size, such as "96".
  * @csspart size-by - The Size by button, naming the column the points are sized by or None, with
  *   `aria-expanded` while its menu is open.
  * @csspart size-menu - The Size by menu, while it is open.
@@ -141,7 +155,8 @@ type Pinned = {
  *   `aria-expanded` while its menu is open.
  * @csspart colour-menu - The Colour by menu, while it is open.
  * @csspart colour-option - An entry in the Colour by menu, with `data-value` (empty for None,
- *   `cluster:<layer>@<level>` for one level of a levelled layer) and `aria-checked`.
+ *   `cluster:<layer>@<level>` for one level of a levelled layer, `cluster:<layer>@` for Follow zoom
+ *   on one whose levels declare no zoom range) and `aria-checked`.
  * @csspart palette - The Palette button, while the points are coloured by a layer or a category.
  * @csspart palette-menu - The Palette menu, while it is open.
  * @csspart palette-option - A palette in that menu, with `data-value` and `aria-checked`.
@@ -165,9 +180,10 @@ type Pinned = {
  * @csspart detail - The item or artifact card in the map's top-right corner, used when the picked
  *   item or artifact has no position on the map, such as after following an item into another
  *   view.
- * @csspart sheet - The open sheet, in the narrow layout.
+ * @csspart sheet - The open sheet, over the map in the narrow layout.
  * @csspart strip-row - The full-width status strip, in the narrow layout.
- * @csspart tabs - The tab bar, in the narrow layout.
+ * @csspart tabs - The bar of buttons that open the sheets, in the narrow layout, each with
+ *   `data-sheet` and `aria-expanded`.
  * @csspart map-<part> - A part of the inner `<mosaica-map>`, such as `map-controls`.
  * @csspart status-<part> - A part of an inner `<mosaica-status>`.
  * @csspart view-picker-<part> - A part of the inner `<mosaica-view-picker>`.
@@ -227,14 +243,16 @@ export declare class MosaicaExplorer extends MosaicaElement {
     /** The highest value of the Most points slider. */
     accessor budgetMax: number;
     /**
-     * The most clusters a `nested` or `dag` layer is cut to; `0` removes the limit. Most clusters in
-     * the Layers popover changes it.
+     * The side in CSS pixels of the square of the map each cluster is given, as for `<mosaica-map>`'s
+     * `cluster-spacing`: at 100, a map 1,200 by 800 pixels cuts a `nested` or `dag` layer to 96
+     * clusters, and a level that follows the zoom may have 96 in view. `0` removes the limit. Most
+     * clusters in the Layers popover changes it.
      */
-    accessor clusterBudget: number;
-    /** The lowest value of the Most clusters slider. */
-    accessor clusterBudgetMin: number;
-    /** The highest value of the Most clusters slider. */
-    accessor clusterBudgetMax: number;
+    accessor clusterSpacing: number;
+    /** The smallest spacing Cluster density offers, at its More end. */
+    accessor clusterSpacingMin: number;
+    /** The largest spacing Cluster density offers, at its Fewer end. */
+    accessor clusterSpacingMax: number;
     /**
      * What is drawn under the points, as for `<mosaica-map>`'s `basemap`. The attribute takes `world`
      * and `none`. Unset, a view with a map projection gets the world outline and any other view gets
@@ -297,16 +315,32 @@ export declare class MosaicaExplorer extends MosaicaElement {
     accessor menu: Menu | null;
     /** Where Most points is being dragged, before it is let go. @internal */
     accessor pointsDragged: number | null;
-    /** Where Most clusters is being dragged, before it is let go. @internal */
+    /** The cluster spacing Cluster density is being dragged to, before it is let go. @internal */
     accessor clustersDragged: number | null;
     /** Whether the list of density colours in the Layers popover is open. @internal */
     accessor densityColoursOpen: boolean;
     /** @internal */
     accessor sheet: Sheet | null;
-    /** The narrow layout's tab focused last, which keeps the tab list's one place in the tab order. */
+    /** The narrow layout's button focused last, which keeps the bar's one place in the tab order. */
     private accessor tabFocus;
-    /** The level a layer is coloured and labelled at, chosen on its card or in Colour by. @internal */
-    accessor level: number | null;
+    /**
+     * What the selection's card shows, as last seen: the record or the refusal the store holds, or
+     * the map's broken pick; null for no card. Picking the same item again brings a new record.
+     */
+    private cardSeen;
+    /** Where focus was before the update being drawn: in the open sheet, elsewhere in the explorer, or outside it. */
+    private focusBefore;
+    /** Whether the host put something other than a status strip in the `status` slot, so no strip speaks. */
+    private get stripReplaced();
+    /** What the host put in the `status` slot changed, and with it whether a strip speaks. */
+    private onStatusSlot;
+    /** What the status region says: the card that opened last. */
+    private announced;
+    /**
+     * The level each layer is counted, coloured and labelled at, chosen on its card or in Colour by,
+     * keyed by layer name. A layer with no entry takes its default level. @internal
+     */
+    accessor levels: ReadonlyMap<string, number>;
     /** The cards kept open by Pin, oldest first. @internal */
     accessor pinned: Pinned[];
     /** Each callout's size as last measured, by its key. */
@@ -347,6 +381,23 @@ export declare class MosaicaExplorer extends MosaicaElement {
     protected resetServerData(): void;
     protected onStoreAdopted(store: Store | null): void;
     protected onStoreChange(): void;
+    static get observedAttributes(): string[];
+    /** An `aria-label` on the explorer is passed to its map. */
+    attributeChangedCallback(name: string, old: string | null, value: string | null): void;
+    /**
+     * As the selection's card comes, changes or goes. The wide layouts say which card opened in the
+     * status region. The narrow layout opens the Item sheet for it, and closes that sheet with it; a
+     * card that arrives while the viewer's focus is in another sheet leaves that sheet open. Sheets
+     * are the narrow layout's: growing wider closes the open one, and growing narrow with a card
+     * open opens the Item sheet.
+     */
+    protected willUpdate(changed: PropertyValues<this>): void;
+    /** Whether focus is in the explorer: in its own tree, or in an element the host put in a slot. */
+    private holdsFocus;
+    /** What the selection's card shows, or null where it has nothing to show or `panels` leaves the card out. */
+    private cardSubject;
+    /** Whether the selection has a card to show: a click that found nothing shows none, and a broken pick shows its fault. */
+    private hasDetail;
     connectedCallback(): void;
     /** Take the compact or the narrow form, or neither, for a container `width` pixels wide. */
     private fitWidth;
@@ -358,6 +409,11 @@ export declare class MosaicaExplorer extends MosaicaElement {
     private has;
     /** A press anywhere outside the Layers button, its popover and the Edit colours dialog it opens closes the popover. */
     private onOutside;
+    /**
+     * Focus going from the Layers button, its popover or their menus to somewhere else in the page
+     * closes the popover. The Edit colours dialog it opens is not somewhere else.
+     */
+    private onLayersFocusOut;
     private openLayers;
     private closeLayers;
     render(): TemplateResult | typeof nothing;
@@ -393,7 +449,8 @@ export declare class MosaicaExplorer extends MosaicaElement {
     /**
      * Place each callout beside its point under the camera as it stands, clear of the cards over the
      * map and of the callouts placed before it, and join it to its point. A callout whose point is off
-     * the map is hidden with its leader. Reads no layout: the sizes are those {@link measure} took.
+     * the map is hidden with its leader, and gives the focus it holds to the map. Reads no layout: the
+     * sizes are those {@link measure} took.
      */
     private placeCallouts;
     /**
@@ -415,11 +472,6 @@ export declare class MosaicaExplorer extends MosaicaElement {
     /** The enabled resolution stops the popover last drew, so a camera change that alters them redraws it. */
     private stopsSeen;
     private onCamera;
-    /**
-     * Tab from the map itself goes to the card beside the point, the selection's where it shows, so
-     * the card is the next stop after the map; from there Tab goes on in the page's order.
-     */
-    private onMapKey;
     /** Escape on a card: the card not pinned closes, dropping the selection; focus goes back to the map. */
     private onCalloutKey;
     /** The display settings as they stand. */
@@ -436,16 +488,22 @@ export declare class MosaicaExplorer extends MosaicaElement {
      */
     private mostPoints;
     /**
-     * Most clusters, while a `nested` or `dag` layer is drawn: a slider from `cluster-budget-min` to
-     * `cluster-budget-max` as Most points is. Letting go sets the most clusters such a layer is cut to.
+     * Cluster density, while a `nested` or `dag` layer is drawn, or a levelled layer following the zoom
+     * is drawn or coloured by: a slider over the cluster spacing on a log scale, from
+     * `cluster-spacing-max` at its Fewer end to `cluster-spacing-min` at its More end, with how many
+     * clusters the spacing gives the map at its size. Letting go sets the store's spacing.
+     */
+    private clusterDensity;
+    /**
+     * A slider standing `at` of the way along, with its readout, its ends' labels and its ticks. `of`
+     * gives the value at a share of the way along; dragging passes it to `drag`, and letting go to
+     * `set`.
      */
-    private mostClusters;
-    /** A log-scale slider over `range` on round numbers, with the number it stands at. */
     private mostSlider;
     /** Set the store's budget from Most points, and report it. */
     private setBudget;
-    /** Set the most clusters a treed layer is cut to from Most clusters, and report it. */
-    private setClusterBudget;
+    /** Set the store's cluster spacing from Cluster density, and report it. */
+    private setClusterSpacing;
     /**
      * The Colour section: Colour by, then the palette for a category, or the ramp, its scale and
      * Reverse for a number or a date, unless `hide-palettes` is set.
@@ -453,11 +511,17 @@ export declare class MosaicaExplorer extends MosaicaElement {
     private colourSection;
     /**
      * What Colour by offers: None, every layer that can colour (a levelled layer once per level, by
-     * its levels' titles), and the rendered category and number columns.
+     * its levels' titles, after Follow zoom where no level declares a zoom range), and the rendered
+     * category and number columns.
      */
     private colourOptions;
-    /** Colour by `value`: a column, `cluster:<layer>`, or `cluster:<layer>@<level>` for one level of a layer. */
+    /**
+     * Colour by `value`: a column, `cluster:<layer>`, `cluster:<layer>@<level>` for one level of a
+     * layer, or `cluster:<layer>@` for the level that follows the zoom.
+     */
     private chooseColour;
+    /** Count, colour and label `layer` at `level`, or at its default level where `level` is null; other layers keep theirs. */
+    private chooseLevel;
     /** Colour a layer's clusters from `palette`, and report it. */
     private chooseClusterPalette;
     /** Change the palette, the ramp, its scale or its direction, and report all four. */
@@ -497,7 +561,7 @@ export declare class MosaicaExplorer extends MosaicaElement {
     private closeMenu;
     /** The arrow keys on a menu's button open the menu, as a menu button's do. */
     private onMenuButtonKey;
-    /** Focus leaving the open menu, by Tab or otherwise, closes it; Tab goes on from where focus went. */
+    /** Focus leaving the open menu closes it. */
     private onMenuFocusOut;
     /** A press in the Layers popover outside the open menu's button closes the menu. */
     private onPopoverPress;
@@ -508,14 +572,29 @@ export declare class MosaicaExplorer extends MosaicaElement {
     private changeSize;
     /** Apply a change made in the Display section, and report every setting as it now stands. */
     private changeDisplay;
+    /** Close the list of density colours, with focus on its button. */
+    private closeDensityColours;
+    /** Escape in the list of density colours closes the list alone. */
+    private onDensityColoursKey;
+    /** Focus leaving the list of density colours and its button closes the list. */
+    private onDensityColoursFocusOut;
     /** Escape closes the Layers popover and returns focus to its button. */
     private onLayersKey;
-    /** The tab list's keys: the arrows move between tabs, wrapping, and Home and End go to the ends. */
+    /** The bar's keys: the arrows move between its buttons, wrapping, and Home and End go to the ends. */
     private onTabKey;
     /** Escape closes the sheet. */
     private onSheetKey;
-    /** Focus goes into a sheet as it opens, and back to its tab as it closes. */
+    /**
+     * Focus goes to the first control of the Layers popover as it opens. A sheet that opens takes
+     * the focus the explorer held, and none from the page around it. A sheet that closes gives the
+     * focus it held to its button, or to the map where the layout has grown wide and has no button.
+     */
     protected updated(changed: PropertyValues<this>): void;
+    /**
+     * While an open sheet reaches up over the map's tools, the map behind it is inert: nothing under
+     * the sheet takes focus or a press. A shorter sheet leaves the map above it in use.
+     */
+    private coverMap;
     /**
      * Hold the open Layers popover within the explorer's visible box: the part of it inside the
      * window. It opens down from its button, or up from it in the compact form, and is as tall as the