@mosaicajs/components 0.1.0-rc.4 → 0.1.0

package/dist/explorer.d.ts

@@ -37,70 +37,31 @@ type Pinned = {
     };
 });
 /**
- * The map with its status strip, toolbar, field cards, display settings, layers, selection and item
- * card, laid out together. It builds its own store from `token` or an `authorise` property and
- * `viewer-url`, the page's own origin where unset, or from `viewer-url` alone for an open server,
- * or takes a `store` property, and provides it by
- * context to everything inside it, including elements a host puts in its slots.
+ * Use the explorer when you want a working map page without arranging the elements yourself. It
+ * gives the viewer a map with the filter panel, the status strip and a Layers popover, and it opens
+ * a card when they pick an item or a cluster or select a region.
  *
- * The heading names what is shown: `dataset-title` where the host sets one, with the view's name
- * under it, else the view's name alone. A view's name that is only its id is left out. With
- * several views the view's name is the view choice.
+ * Most of these parts have a slot, so you can put your own element in place of one of them. For a
+ * different arrangement, lay out the separate elements yourself.
  *
- * The left holds the heading and the filter panel (`<mosaica-filter-panel>`): what the cards count,
- * In view or Highlighted beside All matching, the clauses applied as chips with Clear all, one
- * `<mosaica-field-card>` per field, and Add field. `layout="docked"` puts them in a sidebar left of
- * the map; `layout="overlay"` puts them in a card over the map's top-left, which scrolls inside
- * itself when tall. The map's tools sit at the top-left of the map, right of the card in the
- * overlay layout, with a Layers button beneath them. The status strip sits in the map's
- * bottom-right.
+ * The explorer builds its store from `viewer-url` and `token` or `authorise`, unless you give it
+ * one in its `store` property. Every element inside it uses that store, including the ones you put
+ * in its slots.
  *
- * Picking a point opens its item card beside the point, joined to it by a short leader: on the side
- * with most room, clear of the cards over the map, the map's tools and the Layers button, following
- * the point as the map pans and zooms, hidden while the point is off the map, and clear of the
- * other cards beside points. Where no side beside the point is clear, the card goes to the clear
- * place nearest it. The card shows the headline, the `subtitle-field` field, the `card-fields`
- * fields (else the first three), "Show all N fields", and Open where `open-url` or `open` says what
- * it does. Show all grows the card as far as the map's height and the same things allow; past that
- * the card scrolls. Picking another point replaces it unless Pin was pressed, which keeps it open;
- * Close or Escape closes it and drops the selection, and a click on the map that finds nothing does
- * the same for the card that is not pinned. Tab from the map goes to the card, which is named by
- * its item's title and gives focus back to the map as it closes. A picked cluster's card behaves
- * the same way. While a region is selected its card stands in the map's top-right corner, and where
- * the map holds no position for the selection, as after following an item into another view, the
- * item's card goes there too.
+ * `layout="docked"` puts the heading and the filter panel in a sidebar beside the map, and
+ * `layout="overlay"` puts them in a card over it. When the bundle offers more than one view or
+ * group of views, the heading holds the view picker so that viewers can switch between them.
  *
- * The Layers button opens a popover in four sections. Points: whether the points are drawn; Most
- * points, a slider from `budget-min` to `budget-max` on a log scale that sets the store's budget
- * when it is let go (`Store.setBudget`); while a `nested` or `dag` layer is drawn, Most clusters,
- * a slider from `cluster-budget-min` to `cluster-budget-max` on a log scale that sets the most
- * clusters such a layer is cut to when it is let go (`Store.setClusterBudget`); what sizes the
- * points; and their opacity. Size by lists
- * None and the number columns the points arrive with. Under None one Size slider sets every
- * point's radius, which `hide-size` leaves out; under a column two sliders set the radii of its
- * smallest and largest value, and a Linear, Log or Rank choice places values between them. Colour:
- * Colour by, which lists None, every layer that can colour (a levelled layer once per level) and
- * the rendered category and number columns; then for a layer or a category the palette, and for a
- * number the ramp, Linear or Log and Reverse, unless `hide-palettes` is set. A layer's palette is
- * the store's (`Store.setPalette`), whose size the clusters' slots are served for. While the
- * points are coloured by a category or a layer, Edit colours opens `<mosaica-colour-editor>` over
- * the page, listing the values or the clusters drawn (at the level coloured, on a levelled layer)
- * with their colours to choose and reset, in an order that holds through a pan or a filter. A field card's paint button chooses Colour by too. Density: how density is drawn, at what resolution, in which
- * colours and how strongly. Layers: the layer picker. The display settings are the explorer's properties of
- * the same names, passed to its map. `pinned-filters` names the columns whose cards are listed
- * before they hold a clause.
+ * A picked item's card opens beside its point and follows the point as the map moves. Picking
+ * another point replaces the card unless the viewer has pinned it.
  *
- * In a container narrower than 1000 px, either layout takes the overlay's form with a narrower card
- * of 264 px, every field card folded to one line until one is opened, and opening one folds the
- * one open before; the tools move to the bottom-left and the strip shortens its figures. In a
- * container 720 px wide or narrower, the heading sits in a bar above the map, the status strip
- * runs full width above a tab bar (Fields, Layers, Item), and each tab opens its panel as a sheet:
- * the filter panel, folded as in the compact form; the Layers popover's sections; and the item
- * card. The cards over the map are not drawn there.
+ * Each setting in the Layers popover is also an attribute of the explorer, so you can set it from
+ * HTML.
  *
- * Every event its elements fire bubbles out of it, since each is composed.
+ * 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.
  *
- * @summary The map and every panel, in a default layout.
+ * @summary A complete map application in a single element.
  * @tagname mosaica-explorer
  * @category Elements
  * @slot toolbar - Replaces the view picker and the key picker.
@@ -115,9 +76,9 @@ type Pinned = {
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-pick']>} mosaica-pick - A point was clicked.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-itemopen']>} mosaica-itemopen - The selected item's record arrived.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-basemapchange']>} mosaica-basemapchange - The map's basemap refusal or note changed.
- * @fires {CustomEvent<MosaicaEventDetails['mosaica-miss']>} mosaica-miss - A click on the map found nothing; the explorer closes the card that is not pinned and drops the selection.
+ * @fires {CustomEvent<MosaicaEventDetails['mosaica-miss']>} mosaica-miss - A click on the map found nothing. The explorer closes the unpinned card.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-hover']>} mosaica-hover - The pointer moved over a point.
- * @fires {CustomEvent<MosaicaEventDetails['mosaica-artifactopen']>} mosaica-artifactopen - An artifact was opened and its drill-down arrived.
+ * @fires {CustomEvent<MosaicaEventDetails['mosaica-artifactopen']>} mosaica-artifactopen - An artifact was opened and its details arrived.
  * @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.
@@ -137,7 +98,7 @@ type Pinned = {
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-clausechange']>} mosaica-clausechange - A `member_of` clause was put on or taken off.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-artifactfit']>} mosaica-artifactfit - Fit was pressed on the artifact card; the explorer fits its map to the artifact.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-open']>} mosaica-open - Open was pressed on the item card.
- * @fires {CustomEvent<MosaicaEventDetails['mosaica-close']>} mosaica-close - A card's close button was pressed; the explorer closes the card and drops the selection it shows.
+ * @fires {CustomEvent<MosaicaEventDetails['mosaica-close']>} mosaica-close - A card's close button was pressed. The explorer closes the card and clears its selection.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-viewswitch']>} mosaica-viewswitch - The view changed through the view or key picker.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-viewfollow']>} mosaica-viewfollow - A view chip on the item card was pressed; the explorer switches to that view and centres on the item.
  * @csspart frame - The explorer's grid.
@@ -182,8 +143,7 @@ type Pinned = {
  * @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`.
  * @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: a row per palette, each a strip of its
- *   colours, its name and a line saying how many it has.
+ * @csspart palette-menu - The Palette menu, while it is open.
  * @csspart palette-option - A palette in that menu, with `data-value` and `aria-checked`.
  * @csspart edit-colours - The Edit colours button, enabled while the points are coloured by a
  *   category or a layer.
@@ -195,16 +155,16 @@ type Pinned = {
  * @csspart ramp-reverse - The Reverse button, with `aria-pressed`.
  * @csspart density-mode - The Density choice: None, Smooth, Hex, Grid and Lines, each with
  *   `data-mode` and `aria-checked`.
- * @csspart density-resolution - The Resolution slider, while density is drawn: the cell size on
- *   screen, coarse to fine. Its stops past the finest the server will count for the view are shown
- *   struck through, and the slider stops at the last one it can count.
+ * @csspart density-resolution - The Resolution slider for density's cell size, while density is
+ *   drawn. Sizes finer than the server allows for the view are struck through.
  * @csspart density-scale - The Linear and Log choice of density's colour scale, while density is
  *   drawn, each with `data-scale` and `aria-checked`.
  * @csspart density-colours - The button that opens the list of density colours, while density is
  *   drawn in colours.
  * @csspart density-strength - The Strength slider, while density is drawn.
- * @csspart detail - The item or artifact card in the map's top-right corner, where the map holds no
- *   position for the selection.
+ * @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 strip-row - The full-width status strip, in the narrow layout.
  * @csspart tabs - The tab bar, in the narrow layout.
@@ -229,110 +189,107 @@ export declare class MosaicaExplorer extends MosaicaElement {
     static styles: import("lit").CSSResult[];
     protected canBuildOwn: boolean;
     /**
-     * `docked`, the map beside a sidebar, or `overlay`, the map full-bleed under a card holding the
-     * same panels.
+     * `docked` puts the panels in a sidebar beside the map. `overlay` makes the map fill the element
+     * and puts the panels in a card over it.
      */
     accessor layout: 'docked' | 'overlay';
     /**
-     * Which regions appear, space- or comma-separated, from `toolbar` (the heading), `legend` (the
-     * Layers button and its popover), `filters` (the filter panel), `selection` and `detail` (the
-     * item and artifact cards). Defaults to all five. Any other name, such as `hierarchy`, shows
-     * nothing.
+     * The regions to show, separated by spaces or commas: `toolbar` (the heading), `legend` (the
+     * Layers button and popover), `filters` (the filter panel), `selection` (the selected region's
+     * card) and `detail` (the item and artifact cards). Defaults to all five. Other names are ignored.
      */
     accessor panels: string;
-    /** Passed to the map's `colour-by`. */
+    /** What colours the points, as for `<mosaica-map>`'s `colour-by`. */
     accessor colourBy: string;
-    /** Passed to the map's `layers`. */
+    /** The annotation layers to draw, as for `<mosaica-map>`'s `layers`. */
     accessor layers: string;
-    /** Passed to the map's `tooltip-fields`. */
+    /** The columns the hover tooltip shows, as for `<mosaica-map>`'s `tooltip-fields`. */
     accessor tooltipFields: string;
-    /** The field that titles a point, in the map's tooltip and the item card's headline. Unset, the title is the `mosaica_id`. */
+    /** The field that titles a point in the hover tooltip and the item card. Unset, the title is the `mosaica_id`. */
     accessor titleField: string;
-    /** The field the item card shows under its headline. Unset, it shows none. */
+    /** The field the item card shows under its title. Unset, there is no subtitle. */
     accessor subtitleField: string;
-    /** Passed to the item card's `card-fields`: the fields it shows before "Show all", in this order. Unset, the first three. */
+    /** The fields the item card shows before "Show all", in order, as for `<mosaica-item-card>`. Unset, the first three. */
     accessor cardFields: string;
-    /** Passed to the item card's `open-url`: the address Open goes to, filled from the item's fields. Unset, and without `open`, there is no Open. */
+    /** The link template for the item card's Open button, as for `<mosaica-item-card>`. Without it or `open`, there is no Open button. */
     accessor openUrl: string;
-    /** Passed to the item card's `open`: called when Open is pressed. Set, it wins over `open-url`. */
+    /** A function the item card calls when Open is pressed, as for `<mosaica-item-card>`. Takes precedence over `open-url`. */
     accessor open: MosaicaItemCard['open'];
     /**
-     * How many marks to aim for on screen, passed to the map's `budget`. `0`, the default, leaves the
-     * store's own, which starts at 250000. Most points in the Layers popover sets the store's budget
-     * itself.
+     * How many marks to aim for on screen. `0` keeps the store's budget, which starts at 250000. Most
+     * points in the Layers popover changes the store's budget directly.
      */
     accessor budget: number;
-    /** The fewest marks Most points offers, passed to the map's `budget-min`. */
+    /** The lowest value of the Most points slider. */
     accessor budgetMin: number;
-    /** The most marks Most points offers, passed to the map's `budget-max`. */
+    /** The highest value of the Most points slider. */
     accessor budgetMax: number;
     /**
-     * The most clusters a `nested` or `dag` layer is cut to, passed to the map's `cluster-budget`;
-     * `0` is the finest cut. Most clusters in the Layers popover sets the store's itself.
+     * The most clusters a `nested` or `dag` layer is cut to; `0` removes the limit. Most clusters in
+     * the Layers popover changes it.
      */
     accessor clusterBudget: number;
-    /** The fewest clusters Most clusters offers. */
+    /** The lowest value of the Most clusters slider. */
     accessor clusterBudgetMin: number;
-    /** The most clusters Most clusters offers. */
+    /** The highest value of the Most clusters slider. */
     accessor clusterBudgetMax: number;
     /**
-     * Passed to the map's `basemap`: `world`, `none`, `{tiles, attribution}`, `{image, bounds}`, a
-     * mapping from view id (as `meta.views` lists it, and not `tiles` or `image`) to one of those, or
-     * a deck.gl layer. The attribute takes `world` and `none`. Unset, the world outline under a view
-     * with a map projection and nothing under one without.
+     * 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
+     * nothing.
      */
     accessor basemap: BasemapChoice | null;
-    /** Passed to the map's `no-points`; the Points switch in the Layers popover changes it. */
+    /** Hides the points. The Points switch in the Layers popover changes it. */
     accessor noPoints: boolean;
-    /** Passed to the map's `radius`; the Size slider in the Layers popover changes it. */
+    /** A fixed point radius in pixels, as for `<mosaica-map>`. The Size slider in the Layers popover changes it. */
     accessor radius: number | null;
-    /** Passed to the map's `size-by`; the Size by choice in the Layers popover changes it. */
+    /** The number column that sizes the points, as for `<mosaica-map>`. Size by in the Layers popover changes it. */
     accessor sizeBy: string;
-    /** Passed to the map's `size-min`; the smallest-size slider in the Layers popover changes it. */
+    /** The radius of the smallest value under `size-by`. A slider in the Layers popover changes it. */
     accessor sizeMin: number | null;
-    /** Passed to the map's `size-max`; the largest-size slider in the Layers popover changes it. */
+    /** The radius of the largest value under `size-by`. A slider in the Layers popover changes it. */
     accessor sizeMax: number | null;
-    /** Passed to the map's `size-scale`; the Scale choice in the Layers popover changes it. */
+    /** How values are placed between the two sizes, as for `<mosaica-map>`. The Scale choice in the Layers popover changes it. */
     accessor sizeScale: SizeScale | '';
-    /** Leaves the Size slider out of the Layers popover, for a host that sets `radius` itself. */
+    /** Leaves the Size slider out of the Layers popover, for when you set `radius` yourself. */
     accessor hideSize: boolean;
-    /** Passed to the map's `point-opacity`; the Opacity slider in the Layers popover changes it. */
+    /** A fixed point opacity from 0.1 to 1. The Opacity slider in the Layers popover changes it. */
     accessor pointOpacity: number | null;
-    /** Passed to the map's `density`; the Density choice in the Layers popover changes it. */
+    /** How density is drawn, as for `<mosaica-map>`. The Density choice in the Layers popover changes it. */
     accessor density: DensityMode;
-    /** Passed to the map's `density-colours`; the Colours choice in the Layers popover changes it. */
+    /** The colours density is drawn in, as for `<mosaica-map>`. The Colours choice in the Layers popover changes it. */
     accessor densityColours: DensityColours | '';
-    /** Passed to the map's `density-strength`; the Strength slider in the Layers popover changes it. */
+    /** How strongly density is drawn, from 0.1 to 1. The Strength slider in the Layers popover changes it. */
     accessor densityStrength: number;
     /**
-     * Passed to the map's `density-resolution`, the cell size on screen in CSS pixels; the Resolution
+     * The size of density's cells on screen, in CSS pixels, as for `<mosaica-map>`. The Resolution
      * slider in the Layers popover changes it.
      */
     accessor densityResolution: number;
-    /** Passed to the map's `density-scale`; the Scale choice under Resolution in the Layers popover changes it. */
+    /** `linear` or `log` colouring of density counts. The Scale choice under Resolution in the Layers popover changes it. */
     accessor densityScale: DensityScale;
     /**
-     * Passed to the map's `palette`, the palette a layer's clusters are coloured from; the Palette
-     * choice in the Colour section changes it while the points are coloured by a layer.
+     * The palette clusters are coloured from, as for `<mosaica-map>`. The Palette choice in the Colour
+     * section changes it while the points are coloured by a layer.
      */
     accessor palette: PaletteName | '';
-    /** Passed to the map's `category-palette`. */
+    /** The palette for colouring by a category column, as for `<mosaica-map>`. */
     accessor categoryPalette: CategoryPaletteName | '';
-    /** Passed to the map's `ramp`. */
+    /** The colour ramp for colouring by a number column, as for `<mosaica-map>`. */
     accessor ramp: RampName | '';
-    /** Passed to the map's `ramp-scale`. */
+    /** How numbers are placed on the ramp, `linear` or `log`. */
     accessor rampScale: RampScale | '';
-    /** Passed to the map's `ramp-reverse`. */
+    /** Runs the ramp from its high end to its low end. */
     accessor rampReverse: boolean;
-    /** Passed to the map's `valueColours`. */
+    /** Colours for individual category values, as for `<mosaica-map>`'s `valueColours`. */
     accessor valueColours: Colouring['values'] | null;
-    /** Passed to the map's `clusterColours`. */
+    /** Colours for individual clusters, as for `<mosaica-map>`'s `clusterColours`. */
     accessor clusterColours: Record<string, Record<string, string>> | null;
-    /** The dataset's title, which heads the explorer above the view's name. Unset, the view's name is the heading. */
+    /** The dataset's title, shown as the heading above the view's name. Unset, the view's name is the heading. */
     accessor datasetTitle: string;
-    /** Passed to the filter panel's `pinned`: the columns whose cards are listed before they hold a clause. */
+    /** Columns whose field cards always show, even when they hold no filter, as for `<mosaica-filter-panel>`'s `pinned`. */
     accessor pinnedFilters: string;
-    /** Leaves the palette and ramp choices out of the Colour section, for a host that sets them. */
+    /** Leaves the palette and ramp choices out of the Colour section, for when you set them yourself. */
     accessor hidePalettes: boolean;
     /** The menu open beside the Layers popover. @internal */
     accessor menu: Menu | null;
@@ -394,7 +351,7 @@ export declare class MosaicaExplorer extends MosaicaElement {
     disconnectedCallback(): void;
     /** Dispose of the store the explorer built and of its map's GPU resources. */
     dispose(): void;
-    /** The `<mosaica-map>` the explorer renders, for a host that calls `fit`, `fitTo` or `select`. */
+    /** The explorer's `<mosaica-map>`, for calling its methods such as `fit`, `fitTo` or `select`. */
     get map(): MosaicaMap | null;
     private has;
     /** A press anywhere outside the Layers button, its popover and the Edit colours dialog it opens closes the popover. */