<mosaica-explorer>

A complete map application in a single element.

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.

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 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.

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.

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.

Each setting in the Layers popover is also an attribute of the explorer, so you can set it from 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.

import '@mosaicajs/components/explorer';

Attributes

Attribute	Property	Type	Default	Description
layout	layout	'docked' | 'overlay'	'docked'	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.
panels	panels	string		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.
colour-by	colourBy	string	''	What colours the points, as for <mosaica-map>'s colour-by.
layers	layers	string	''	The annotation layers to draw, as for <mosaica-map>'s layers.
tooltip-fields	tooltipFields	string	''	The columns the hover tooltip shows, as for <mosaica-map>'s tooltip-fields.
title-field	titleField	string	''	The field that titles a point in the hover tooltip and the item card. Unset, the title is the mosaica_id.
subtitle-field	subtitleField	string	''	The field the item card shows under its title. Unset, there is no subtitle.
card-fields	cardFields	string	''	The fields the item card shows before "Show all", in order, as for <mosaica-item-card>. Unset, the first three.
image-fields	imageFields	string	''	The fields the item card draws as images, as for <mosaica-item-card>'s image-fields.
open-url	openUrl	string	''	The link template for the item card's Open button, as for <mosaica-item-card>. Without it or open, there is no Open button.
budget	budget	number	0	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.
budget-min	budgetMin	number	1_000	The lowest value of the Most points slider.
budget-max	budgetMax	number	2_000_000	The highest value of the Most points slider.
cluster-budget	clusterBudget	number	1_000	The most clusters a nested or dag layer is cut to; 0 removes the limit. Most clusters in the Layers popover changes it.
cluster-budget-min	clusterBudgetMin	number	10	The lowest value of the Most clusters slider.
cluster-budget-max	clusterBudgetMax	number	10_000	The highest value of the Most clusters slider.
basemap	basemap	BasemapChoice | null	null	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.
no-points	noPoints	boolean	false	Hides the points. The Points switch in the Layers popover changes it.
radius	radius	number | null	null	A fixed point radius in pixels, as for <mosaica-map>. The Size slider in the Layers popover changes it.
size-by	sizeBy	string	''	The number column that sizes the points, as for <mosaica-map>. Size by in the Layers popover changes it.
size-min	sizeMin	number | null	null	The radius of the smallest value under size-by. A slider in the Layers popover changes it.
size-max	sizeMax	number | null	null	The radius of the largest value under size-by. A slider in the Layers popover changes it.
size-scale	sizeScale	SizeScale | ''	''	How values are placed between the two sizes, as for <mosaica-map>. The Scale choice in the Layers popover changes it.
hide-size	hideSize	boolean	false	Leaves the Size slider out of the Layers popover, for when you set radius yourself.
point-opacity	pointOpacity	number | null	null	A fixed point opacity from 0.1 to 1. The Opacity slider in the Layers popover changes it.
density	density	DensityMode	'none'	How density is drawn, as for <mosaica-map>. The Density choice in the Layers popover changes it.
density-colours	densityColours	DensityColours | ''	''	The colours density is drawn in, as for <mosaica-map>. The Colours choice in the Layers popover changes it.
density-strength	densityStrength	number	1	How strongly density is drawn, from 0.1 to 1. The Strength slider in the Layers popover changes it.
density-resolution	densityResolution		DEFAULT_DENSITY_CELL_PX	The size of density's cells on screen, in CSS pixels, as for <mosaica-map>. The Resolution slider in the Layers popover changes it.
density-scale	densityScale	DensityScale	DEFAULT_DENSITY_SCALE	linear or log colouring of density counts. The Scale choice under Resolution in the Layers popover changes it.
palette	palette	PaletteName | ''	''	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.
category-palette	categoryPalette	CategoryPaletteName | ''	''	The palette for colouring by a category column, as for <mosaica-map>.
ramp	ramp	RampName | ''	''	The colour ramp for colouring by a number column, as for <mosaica-map>.
ramp-scale	rampScale	RampScale | ''	''	How numbers are placed on the ramp, linear or log.
ramp-reverse	rampReverse	boolean	false	Runs the ramp from its high end to its low end.
dataset-title	datasetTitle	string	''	The dataset's title, shown as the heading above the view's name. Unset, the view's name is the heading.
pinned-filters	pinnedFilters	string	''	Columns whose field cards always show, even when they hold no filter, as for <mosaica-filter-panel>'s pinned.
hide-palettes	hidePalettes	boolean	false	Leaves the palette and ramp choices out of the Colour section, for when you set them yourself.
viewer-url	viewerUrl	string	''	The base URL of the Mosaica viewer server, for the store the element builds: a full URL such as https://maps.example.org, or a path such as /mosaica. Unset, the page's own origin. Read only by the map, the explorer and <mosaica-store>. Changing it builds a new store.
token	token	string	''	A viewer token for the store the element builds. Without token or authorise, only an open server (serve.open) answers. Read only by the map, the explorer and <mosaica-store>. Changing it builds a new store.
artifacts-per-tile	artifactsPerTile	number | null	null	The most artifacts one level of a layer shows per map tile, for the store the element builds. Unset, 50, or the server's selection.max_artifacts_per_tile if lower. A value above that maximum is refused. Read only by the map, the explorer and <mosaica-store>. Changing it builds a new store.

Properties

Set as JavaScript properties; they have no attribute.

Property	Type	Default	Description
open	MosaicaItemCard['open']	null	A function the item card calls when Open is pressed, as for <mosaica-item-card>. Takes precedence over open-url.
valueColours	Colouring['values'] | null	null	Colours for individual category values, as for <mosaica-map>'s valueColours.
clusterColours	Record<string, Record<string, string>> | null	null	Colours for individual clusters, as for <mosaica-map>'s clusterColours.
map	MosaicaMap | null	read-only	The explorer's <mosaica-map>, for calling its methods such as fit, fitTo or select.
store	Store | null	null	The store to use, ahead of one from context or one the element would build. The element never disposes it.
authorise	TokenSupplier | null	null	A function that returns a viewer token, used instead of token and called again before the token expires. A different function builds a new store, so keep it stable across renders. Set it together with viewer-url: a store built from viewer-url alone first sends a request with no token, and is replaced when authorise arrives.
activeStore	Store | null	read-only	The store this element is using, or null if it has none.
source	StoreSource	read-only	Where activeStore came from.

Methods

Method	Returns	Description
dispose()	void	Dispose of the store the explorer built and of its map's GPU resources.

Events

Each bubbles and is composed. Events gives each detail.

Event	Fired when
mosaica-viewchange	The map's camera moved.
mosaica-pick	A point was clicked.
mosaica-itemopen	The selected item's record arrived.
mosaica-basemapchange	The map's basemap refusal or note changed.
mosaica-miss	A click on the map found nothing. The explorer closes the unpinned card.
mosaica-hover	The pointer moved over a point.
mosaica-artifactopen	An artifact was opened and its details arrived.
mosaica-selectchange	A selection was drawn, changed or cleared, or its counts arrived.
mosaica-layerchange	The layers chosen changed.
mosaica-colourchange	Colour by changed, in the Layers popover or by a card's paint button.
mosaica-levelchange	The level a layer is coloured and labelled at changed.
mosaica-displaychange	A setting in the Points or Density section changed.
mosaica-sizechange	Size by, the size range or the scale changed in the Points section.
mosaica-budgetchange	Most points was let go at a new number.
mosaica-clusterbudgetchange	Most clusters was let go at a new number.
mosaica-fold	A field card was folded to one line or opened.
mosaica-valuecolour	Colours were chosen or reset for values of a category, on a field card or in Edit colours.
mosaica-clustercolour	Colours were chosen or reset for clusters of a layer, on a field card or in Edit colours.
mosaica-palettechange	The palette, the ramp, its scale or its direction was chosen in the Colour section.
mosaica-clusterpalettechange	A palette was chosen for a layer's clusters in the Colour section.
mosaica-statechange	The status strip's panel state changed.
mosaica-expired	The session expired.
mosaica-filterchange	A field card or chip changed a clause.
mosaica-clausechange	A member_of clause was put on or taken off.
mosaica-artifactfit	Fit was pressed on the artifact card; the explorer fits its map to the artifact.
mosaica-open	Open was pressed on the item card.
mosaica-close	A card's close button was pressed. The explorer closes the card and clears its selection.
mosaica-viewswitch	The view changed through the view or key picker.
mosaica-viewfollow	A view chip on the item card was pressed; the explorer switches to that view and centres on the item.

Slots

Slot	Description
toolbar	Replaces the view picker and the key picker.
layers	Replaces the layer picker, in the Layers popover.
filters	Replaces the filter panel.
selection	Replaces the selection panel, shown while a region is selected.
detail	Replaces the item and artifact cards, in the card beside the point.
status	Replaces the status strip drawn on the map.
tooltip	Replaces the map's hover tooltip.
top-right	Content in the map's top-right corner, above the selection's card.

Parts

Styled from outside the element with ::part().

Part	Description
frame	The explorer's grid.
sidebar	The sidebar, in the docked layout.
panel	The card over the map's top-left, in the overlay layout and in a container narrower than 1000 px.
title-bar	The heading, above the map in the narrow layout.
dataset-title	The heading's dataset title, where dataset-title is set.
view-name	The view's name in the heading, where there is one view to show and its name is not its id.
selection-card	The card in the map's top-right corner holding the selection, while a region is selected.
callout	A card beside a point on the map, with data-side (right, left, below or above) and data-pinned while pinned.
pin	A callout's Pin button, with aria-pressed.
leaders	The lines joining each callout to its point.
layers-toggle	The Layers button under the map's tools, with data-on while any layer is drawn.
layers-popover	The popover holding the display sections and the layer picker, while it is open.
display	The Points, Colour and Density sections, at the top of the Layers popover.
points-toggle	The Points switch, with aria-checked.
most-points	The Most points slider.
most-points-value	The number of points it stands at, such as "250K".
most-clusters	The Most clusters slider, while a nested or dag layer is drawn.
most-clusters-value	The number of clusters it stands at, such as "1K".
size-by	The Size by button, naming the column the points are sized by or None, with aria-expanded while its menu is open.
size-menu	The Size by menu, while it is open.
size-option	An entry in the Size by menu, with data-value (empty for None) and aria-checked.
point-size	The Size slider: every point's radius in pixels, under Size by None unless hide-size is set.
size-min	The slider for the radius of the smallest value, under Size by a column.
size-max	The slider for the radius of the largest value, under Size by a column.
size-range	The two radii as text, such as "2 – 9 px".
size-scale	The Linear, Log and Rank choice, each with data-scale and aria-checked.
point-opacity	The Opacity slider.
colour-by	The Colour by button, naming what the points are coloured by, with aria-expanded while its menu is open.
colour-menu	The Colour by menu, while it is open.
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.
palette	The Palette button, while the points are coloured by a layer or a category.
palette-menu	The Palette menu, while it is open.
palette-option	A palette in that menu, with data-value and aria-checked.
edit-colours	The Edit colours button, enabled while the points are coloured by a category or a layer.
ramp	The Ramp button, while the points are coloured by a number or a date.
ramp-menu	The Ramp menu, while it is open.
ramp-option	A ramp in that menu, with data-value and aria-checked.
ramp-scale	The Linear and Log choice of the ramp's scale, each with data-scale and aria-checked.
ramp-reverse	The Reverse button, with aria-pressed.
density-mode	The Density choice: None, Smooth, Hex, Grid and Lines, each with data-mode and aria-checked.
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.
density-scale	The Linear and Log choice of density's colour scale, while density is drawn, each with data-scale and aria-checked.
density-colours	The button that opens the list of density colours, while density is drawn in colours.
density-strength	The Strength slider, while density is drawn.
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.
sheet	The open sheet, in the narrow layout.
strip-row	The full-width status strip, in the narrow layout.
tabs	The tab bar, in the narrow layout.
map-<part>	A part of the inner <mosaica-map>, such as map-controls.
status-<part>	A part of an inner <mosaica-status>.
view-picker-<part>	A part of the inner <mosaica-view-picker>.
key-picker-<part>	A part of the inner <mosaica-key-picker>.
layer-picker-<part>	A part of the inner <mosaica-layer-picker>.
filter-panel-<part>	A part of the inner <mosaica-filter-panel>.
field-card-<part>	A part of a <mosaica-field-card> in the filter panel.
filter-<part>	A part of a <mosaica-filter> search box on a card.
cluster-filter-<part>	A part of a <mosaica-cluster-filter> search box on a card.
selection-<part>	A part of the inner <mosaica-selection>.
item-card-<part>	A part of the inner <mosaica-item-card>, such as item-card-title.
artifact-card-<part>	A part of the inner <mosaica-artifact-card>.
colour-editor-<part>	A part of the inner <mosaica-colour-editor>, such as colour-editor-dialog.

CSS custom properties

Property	Default	Description
--mosaica-explorer-height	100%	The explorer's height.
--mosaica-sidebar-width	340px	The width of the docked sidebar and of the card over the map.

The theme tokens apply to this element.