@mosaicajs/components¶
The mosaica-* custom elements: the map, the panels that go around it, and <mosaica-explorer>,
which lays them all out together. Import the package root to define every element, or a subpath
such as @mosaicajs/components/count to define one. The map, the explorer, the field card, the
filter panel and the colour editor import @mosaicajs/deck, which depends on deck.gl; the other
elements do not.
Type Aliases¶
BasemapChoice¶
BasemapChoice =
BasemapValue|Readonly\<Record\<string,BasemapValue>> |Layer
The value of <mosaica-map>'s basemap: one BasemapValue for every view, an object
mapping view ids to one each, or a deck.gl layer you built, which is drawn as it is.
MosaicaEventDetails¶
MosaicaEventDetails =
object
Every event the elements fire, by name, with the type of its detail. Each event bubbles and is
composed, so you can listen on any ancestor, including one outside <mosaica-explorer>. A
mosaica_id is sent as a decimal string, since it is a 64-bit integer.
Properties¶
| Property | Type | Description |
|---|---|---|
mosaica-artifactfit |
object |
Fit was pressed for the artifact id. <mosaica-explorer> fits its map to it. |
mosaica-artifactfit.id |
string |
- |
mosaica-artifactopen |
object |
The artifact id was opened and its details arrived in detail, with maskedCount as a decimal string. |
mosaica-artifactopen.detail |
Omit\<ArtifactDetail, "maskedCount"> & object |
- |
mosaica-artifactopen.id |
string |
- |
mosaica-basemapchange |
object |
The map's message about its basemap changed. refusal says why the basemap value cannot be drawn under its view, and is shown over the map. note says why nothing is drawn under the current view, and is shown in a corner. Each is null if there is none. |
mosaica-basemapchange.note |
string | null |
- |
mosaica-basemapchange.refusal |
string | null |
- |
mosaica-budgetchange |
object |
The Most points slider was released. The store now aims to draw budget marks on screen. |
mosaica-budgetchange.budget |
number |
- |
mosaica-chipopen |
object |
A column's chip was pressed in a filter panel with chips-only, so you can show its card. verb is filter or highlight. |
mosaica-chipopen.column |
string |
- |
mosaica-chipopen.verb |
ClauseVerb |
- |
mosaica-clausechange |
object |
A member_of clause, which keeps the map to the members of the artifact id in layer layer, was added (on true) or removed. verb is filter or highlight, and outside is true if the clause keeps everything outside the artifact instead. |
mosaica-clausechange.id |
string |
- |
mosaica-clausechange.layer |
string |
- |
mosaica-clausechange.on |
boolean |
- |
mosaica-clausechange.outside |
boolean |
- |
mosaica-clausechange.verb |
ClauseVerb |
- |
mosaica-close |
object |
A card's close button was pressed. what says which card. |
mosaica-close.what |
"item" | "artifact" |
- |
mosaica-clusterbudgetchange |
object |
The Most clusters slider was released. A nested or dag layer is now cut to at most budget clusters. |
mosaica-clusterbudgetchange.budget |
number |
- |
mosaica-clustercolour |
object |
The viewer chose or reset colours for clusters of the layer layer. Each change names a cluster by its mosaica_id and its new colour as #rrggbb, or null if it was reset to its palette colour. The map already draws the new colours. To restore them in a later session, save them and set the map's or explorer's clusterColours. |
mosaica-clustercolour.changes |
object[] |
- |
mosaica-clustercolour.layer |
string |
- |
mosaica-clusterpalettechange |
object |
A palette was chosen for a layer's clusters in the explorer's Colour section and set on the store (Store.setPalette). |
mosaica-clusterpalettechange.palette |
PaletteName |
- |
mosaica-colourchange |
object |
The points are now coloured by colourBy: a column, cluster:<layer>, or null for a single colour. |
mosaica-colourchange.colourBy |
string | null |
- |
mosaica-displaychange |
object |
A display setting changed in the explorer's Layers popover. The detail holds every setting as it now stands. points is the opposite of the map's noPoints; the other fields match the map's properties of the same name. radius, pointOpacity and densityColours are null while the map chooses them itself. |
mosaica-displaychange.density |
DensityMode |
- |
mosaica-displaychange.densityColours |
DensityColours | null |
- |
mosaica-displaychange.densityResolution |
number |
- |
mosaica-displaychange.densityScale |
DensityScale |
- |
mosaica-displaychange.densityStrength |
number |
- |
mosaica-displaychange.pointOpacity |
number | null |
- |
mosaica-displaychange.points |
boolean |
- |
mosaica-displaychange.radius |
number | null |
- |
mosaica-expired |
object |
The session expired. refusal is the server's refusal that ended it, if there was one. |
mosaica-expired.refusal |
Refusal | null |
- |
mosaica-filterchange |
object |
A filter or highlight changed. column is the column whose control changed, or null for Clear all and for clearing the highlight. verb is filter or highlight (filter if absent). After an edit, expr is the combined expression of every control's clause for that verb, or null if there are none. When a chip is removed, or Clear all is pressed, expr is null. member_of clauses are reported by mosaica-clausechange. |
mosaica-filterchange.column |
string | null |
- |
mosaica-filterchange.expr? |
FilterExpr | null |
- |
mosaica-filterchange.verb? |
ClauseVerb |
- |
mosaica-fold |
object |
A field card's fold button folded it to one line (folded true) or opened it. |
mosaica-fold.field |
string |
- |
mosaica-fold.folded |
boolean |
- |
mosaica-hover |
object |
The pointer is over the point id, at x, y in canvas pixels. |
mosaica-hover.id |
string |
- |
mosaica-hover.x |
number |
- |
mosaica-hover.y |
number |
- |
mosaica-itemopen |
object |
The record of the selected item id arrived, whether it was selected by a click or by Store.pick. If the server refuses the record, this does not fire, and the refusal is in the store's selection.itemRefusal. |
mosaica-itemopen.id |
string |
- |
mosaica-itemopen.record |
ItemDetail |
- |
mosaica-layerchange |
object |
The chosen layers are now layers. The map also draws the layers each depends on, which the list leaves out. |
mosaica-layerchange.layers |
string[] |
- |
mosaica-levelchange |
object |
The level that clusters are coloured and labelled at is now level. Null is the default level. |
mosaica-levelchange.level |
number | null |
- |
mosaica-miss |
Record\<string, never> |
A click on the map found no point and no artifact. |
mosaica-open |
object |
Open was pressed on the item id, whose record's fields are fields. It fires both when Open calls the card's open and when it follows open-url. |
mosaica-open.fields |
Record\<string, unknown> |
- |
mosaica-open.id |
string |
- |
mosaica-palettechange |
object |
The palette, ramp, ramp scale or ramp direction was changed in the explorer's Colour section. The detail holds all four as they now stand. |
mosaica-palettechange.palette |
CategoryPaletteName |
- |
mosaica-palettechange.ramp |
RampName |
- |
mosaica-palettechange.reverse |
boolean |
- |
mosaica-palettechange.scale |
RampScale |
- |
mosaica-pick |
object |
A point was clicked. id is its mosaica_id. Its record follows in mosaica-itemopen. |
mosaica-pick.id |
string |
- |
mosaica-selectchange |
object |
The selected region changed. shape is the new shape in data coordinates, or null if the selection was cleared. It fires with status loading when a shape is selected or cleared when it is cleared, then again with shown or refused when the server answers. Then visible, matched and served carry the region's counts, and verdict says whether they are exact for the shape. |
mosaica-selectchange.matched? |
Masked |
- |
mosaica-selectchange.served? |
Count |
- |
mosaica-selectchange.shape |
SelectionShapeDetail | null |
- |
mosaica-selectchange.status? |
RegionProjection["status"] | "cleared" |
- |
mosaica-selectchange.verdict? |
RegionProjection["verdict"] |
- |
mosaica-selectchange.visible? |
Masked | null |
- |
mosaica-sizechange |
object |
A size setting changed in the explorer's Layers popover. The detail holds all four as they now stand: sizeBy is the number column that sizes the points, or null for a single size, min and max are the radii in pixels of its smallest and largest value, and scale is how values are placed between them. |
mosaica-sizechange.max |
number |
- |
mosaica-sizechange.min |
number |
- |
mosaica-sizechange.scale |
SizeScale |
- |
mosaica-sizechange.sizeBy |
string | null |
- |
mosaica-statechange |
object |
The panel state changed from from to to; from is null on the first render. If to is refused, unanswered, busy or expired, refusal says what went wrong; otherwise it is null. |
mosaica-statechange.from |
PanelState | null |
- |
mosaica-statechange.refusal |
Refusal | null |
- |
mosaica-statechange.to |
PanelState |
- |
mosaica-valuecolour |
object |
The viewer chose or reset colours for values of the category column column, in a colour picker or in Edit colours. Each change names a category key and its new colour as #rrggbb, or null if it was reset to its palette colour. The map already draws the new colours. To restore them in a later session, save them and set the map's or explorer's valueColours. |
mosaica-valuecolour.changes |
object[] |
- |
mosaica-valuecolour.column |
string |
- |
mosaica-viewchange |
object |
The camera moved. bbox is the area shown, [x0, y0, x1, y1] in the view's data coordinates. zoom is 0 when the 512-unit world is 512 pixels wide, and 1 more per doubling. width and height are the canvas size in CSS pixels. |
mosaica-viewchange.bbox |
[number, number, number, number] |
- |
mosaica-viewchange.height |
number |
- |
mosaica-viewchange.width |
number |
- |
mosaica-viewchange.zoom |
number |
- |
mosaica-viewfollow |
object |
A view chip on the item card asked to show the item in the view view, where it sits at x, y in that view's data coordinates. <mosaica-explorer> switches to the view and centres the map there. |
mosaica-viewfollow.view |
string |
- |
mosaica-viewfollow.x |
number |
- |
mosaica-viewfollow.y |
number |
- |
mosaica-viewswitch |
object |
The view changed from from to to. sameFrame is true if both views share one extent, in which case the camera stays where it is; otherwise the map refits. |
mosaica-viewswitch.from |
string |
- |
mosaica-viewswitch.sameFrame |
boolean |
- |
mosaica-viewswitch.to |
string |
- |
MosaicaEventMap¶
MosaicaEventMap =
{ [K in keyof MosaicaEventDetails]: CustomEvent<MosaicaEventDetails[K]> }
Every event the elements fire, as the CustomEvent a listener receives.
PanelState¶
PanelState =
"detached"|"loading"|"retrying"|"shown"|"empty"|"refused"|"unanswered"|"busy"|"expired"|"stale"
The state of a panel. Every element shows its state in its part="state" element, with
data-state set to one of these, so one CSS rule can style the same state across every panel.
| State | Meaning |
|---|---|
detached |
The element has no store. |
loading |
The store is connecting or fetching. |
retrying |
The server cannot be reached, or the store is asking again. What is drawn stays. |
shown |
The panel shows the server's answer. |
empty |
The server answered, with nothing to show. |
refused |
The server refused the request. |
unanswered |
The server failed with a 5xx that is not a Mosaica error, such as a gateway's 504. |
busy |
The server is too busy (429), even after the store's retries. |
expired |
The session expired: the token is past its expiry, or the server no longer accepts it. |
stale |
The panel shows an answer, but the data has changed since it was fetched. Refresh fetches it again. |
In the unanswered and busy states the store does not ask again until the viewer presses
Retry.
PartsOf¶
PartsOf = keyof typeof
PARTS
An element name PARTS lists: map, status, item-card, and so on.
SelectionShapeDetail¶
SelectionShapeDetail =
Exclude\<SelectionShape, {kind:"artifact"; }> | {id:string;kind:"artifact";outside?:boolean; }
A selection shape as an event carries it: an artifact's mosaica_id as a decimal string.
StoreSource¶
StoreSource =
"property"|"context"|"own"|"detached"
Where an element's store came from: property is its store property, context a
<mosaica-store> or <mosaica-explorer> above it, and own a store it built from viewer-url,
token or authorise. detached means it has none and shows its detached state.
Variables¶
PARTS¶
constPARTS:object
The parts each element may render, by element name without mosaica-. If you render an element
inside your own shadow root, forward PARTS[name] with exportparts so the page can style those
parts from outside.
Type Declaration¶
storeContext¶
conststoreContext:object
The Lit context through which elements find their store. <mosaica-store> and
<mosaica-explorer> provide it. To supply a store from your own element, provide it under this
context with a ContextProvider from @lit/context. The key is Symbol.for('mosaica.store'),
so two copies of the package on one page share it.
tokens¶
consttokens:CSSResult
The theme every element shares, as a Lit CSSResult. Add it to your own Lit element's styles
to use the same tokens. The elements take every colour and font, the corner radii, the shadow,
the map's height and the spacing of the map's corners from the --mosaica-* custom properties
that the components reference lists under Theme tokens; other spacing is fixed. Set a token on an element or any ancestor, including an
enclosing <mosaica-explorer>, to override its default. Each colour has a light and a dark
default, chosen by the page's color-scheme.
The colours the map uses for data are not tokens. Set them with the map's palette,
category-palette and ramp.
The default font is Instrument Sans if the page has loaded it. The elements fetch no fonts, so link it from your page if you want it.