@sakuzu/maplibre-gl-draw-ui 1.0.0 → 1.2.0

package/README.md

@@ -23,8 +23,14 @@ npm install @sakuzu/maplibre-gl-draw @sakuzu/maplibre-gl-draw-ui maplibre-gl
 
 `@sakuzu/maplibre-gl-draw` (2.x) and `maplibre-gl` are peer
 dependencies: the application installs them, and the interface uses the
-same copies as the application. Svelte is a dependency, and kata is
-compiled into the package.
+same copies as the application.
+
+The package is used from any framework or none: React, Vue, Svelte,
+another framework, or a plain page. It ships compiled JavaScript, and
+the page needs no Svelte of its own. The interface is written in
+Svelte, but Svelte is inside the package: its components are compiled
+before they are published, the Svelte runtime they use comes as a
+dependency of the package, and kata is compiled into it.
 
 The package loads in two ways.
 
@@ -33,33 +39,156 @@ The package loads in two ways.
   `@sakuzu/maplibre-gl-draw-ui/style.css` is the style sheet.
 - Without a bundler: `dist/maplibre-gl-draw-ui.js` is one module with
   Svelte and kata in it. It loads with `<script type="module">` and an
-  import map that names `@sakuzu/maplibre-gl-draw` and `maplibre-gl`,
-  together with `dist/style.css`.
+  import map that names `@sakuzu/maplibre-gl-draw`,
+  `@sakuzu/maplibre-gl-draw/geometry` and `maplibre-gl`, together with
+  `dist/style.css`.
 
-```html
-<link rel="stylesheet" href="/vendor/maplibre-gl.css" />
-<link rel="stylesheet" href="/vendor/maplibre-gl-draw-ui/style.css" />
-<script type="importmap">
-  {
-    "imports": {
-      "maplibre-gl": "/vendor/maplibre-gl.mjs",
-      "@sakuzu/maplibre-gl-draw": "/vendor/maplibre-gl-draw.js"
-    }
-  }
-</script>
-<script type="module">
-  import { Map } from 'maplibre-gl';
-  import { createDraw } from '@sakuzu/maplibre-gl-draw';
-  import { createDrawUI } from '/vendor/maplibre-gl-draw-ui/maplibre-gl-draw-ui.js';
+In every case the interface is created after the draw instance and
+destroyed before it: `createDrawUI(draw)` after `createDraw(map)`, and
+`ui.destroy()`, then `draw.destroy()`, then `map.remove()`.
+
+### From React
 
-  const map = new Map({ container: 'map', style: '/style.json' });
-  createDrawUI(createDraw(map));
+```tsx
+import { useEffect, useRef } from 'react';
+import * as maplibregl from 'maplibre-gl';
+import 'maplibre-gl/dist/maplibre-gl.css';
+import { createDraw } from '@sakuzu/maplibre-gl-draw';
+import { createDrawUI } from '@sakuzu/maplibre-gl-draw-ui';
+import '@sakuzu/maplibre-gl-draw-ui/style.css';
+
+const style = 'https://tiles.openfreemap.org/styles/liberty';
+
+export function DrawMap() {
+  const container = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!container.current) return;
+    const map = new maplibregl.Map({ container: container.current, style });
+    const draw = createDraw(map);
+    const ui = createDrawUI(draw);
+    return () => {
+      ui.destroy();
+      draw.destroy();
+      map.remove();
+    };
+  }, []);
+
+  return <div ref={container} style={{ height: 400 }} />;
+}
+```
+
+The interface lies over the map's container, so the component renders
+the container alone. In development, Strict Mode runs the effect twice;
+the cleanup destroys the first set, so this is safe.
+
+### From Vue
+
+```vue
+<script setup lang="ts">
+import { onBeforeUnmount, onMounted, ref } from 'vue';
+import * as maplibregl from 'maplibre-gl';
+import 'maplibre-gl/dist/maplibre-gl.css';
+import { createDraw, type Draw } from '@sakuzu/maplibre-gl-draw';
+import { createDrawUI, type DrawUI } from '@sakuzu/maplibre-gl-draw-ui';
+import '@sakuzu/maplibre-gl-draw-ui/style.css';
+
+const style = 'https://tiles.openfreemap.org/styles/liberty';
+const container = ref<HTMLDivElement>();
+let map: maplibregl.Map | undefined;
+let draw: Draw | undefined;
+let ui: DrawUI | undefined;
+
+onMounted(() => {
+  map = new maplibregl.Map({ container: container.value!, style });
+  draw = createDraw(map);
+  ui = createDrawUI(draw);
+});
+
+onBeforeUnmount(() => {
+  ui?.destroy();
+  draw?.destroy();
+  map?.remove();
+});
 </script>
+
+<template>
+  <div ref="container" style="height: 400px"></div>
+</template>
+```
+
+`map`, `draw` and `ui` are plain variables, not `ref`s, which would wrap
+them in proxies. The guide to
+[using core with a framework](https://sakuzu.github.io/maplibre-gl-draw/guides/frameworks.html)
+shows the same patterns for Svelte, and how to keep the map out of
+server-side rendering. Under some bundlers, maplibre-gl 6 needs its
+worker URL set once per page, as the
+[README of core](https://github.com/sakuzu/maplibre-gl-draw#usage) shows
+for Vite.
+
+### Without a bundler
+
+A plain HTML page loads every module from a CDN through an import map.
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <title>Draw</title>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/maplibre-gl@6.11.1/dist/maplibre-gl.css">
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@sakuzu/maplibre-gl-draw-ui@1/dist/style.css">
+    <script type="importmap">
+      {
+        "imports": {
+          "maplibre-gl": "https://cdn.jsdelivr.net/npm/maplibre-gl@6.11.1/dist/maplibre-gl.mjs",
+          "@sakuzu/maplibre-gl-draw": "https://esm.sh/@sakuzu/maplibre-gl-draw@2?external=maplibre-gl",
+          "@sakuzu/maplibre-gl-draw/geometry": "https://esm.sh/@sakuzu/maplibre-gl-draw@2/geometry",
+          "@sakuzu/maplibre-gl-draw-ui": "https://cdn.jsdelivr.net/npm/@sakuzu/maplibre-gl-draw-ui@1/dist/maplibre-gl-draw-ui.js"
+        }
+      }
+    </script>
+    <style>
+      html, body, #map { height: 100%; margin: 0; }
+    </style>
+  </head>
+  <body>
+    <div id="map"></div>
+    <script type="module">
+      import * as maplibregl from 'maplibre-gl';
+      import { createDraw } from '@sakuzu/maplibre-gl-draw';
+      import { createDrawUI } from '@sakuzu/maplibre-gl-draw-ui';
+
+      const map = new maplibregl.Map({
+        container: 'map',
+        style: 'https://tiles.openfreemap.org/styles/liberty',
+        center: [139.767, 35.681],
+        zoom: 14,
+      });
+      createDrawUI(createDraw(map));
+    </script>
+  </body>
+</html>
 ```
 
-The paths stand for where the page serves the files: maplibre-gl's
-`dist/maplibre-gl.mjs`, the `dist/` of this package, and a module of core
-with its own dependencies in it that imports `maplibre-gl` by that name.
+The import map names four modules.
+
+- `maplibre-gl` is maplibre-gl's own ES module build, at a version that
+  the peer of core accepts (`~6.11.1`). It starts its worker from the
+  same address by itself.
+- `@sakuzu/maplibre-gl-draw` comes from esm.sh, which puts core's own
+  dependencies in it. `?external=maplibre-gl` leaves maplibre-gl to the
+  import map, so the page and the library share one copy.
+- `@sakuzu/maplibre-gl-draw/geometry` is imported by the interface for
+  its measurements.
+- `@sakuzu/maplibre-gl-draw-ui` is the single-file build of this
+  package, with Svelte and kata in it.
+
+The same page works with files served by the application: put the
+addresses of its own copies (maplibre-gl's `dist/maplibre-gl.mjs`, this
+package's `dist/`, and a build of core with its dependencies in it that
+imports `maplibre-gl` by that name) in the import map and the two
+`<link>` elements. Pin exact versions in production.
 
 ## Use
 
@@ -85,8 +214,8 @@ The options of `createDrawUI`, all optional:
 | --- | --- | --- |
 | `container` | The positioned element it lies over | the map's container |
 | `toolbar` | `false`, or the `tools`, `delete` and `snapping` | `true` |
-| `inspector` | `false`, or the `tabs` and `operations` | `true` |
-| `layers` | `false`, or the `features`, `add` and `reorder` | `true` |
+| `inspector` | `false`, or `tabs` (the first opens) and `operations` | `true` |
+| `layers` | `false`, or `features`, `datasets`, `add`, `reorder` | `true` |
 | `legend` | The legend beside the layer panel | `true` |
 | `locale` | `en`, `ja`, or words laid over English | `en` |
 | `theme` | `light`, `dark` or `auto` (follows the system) | `auto` |
@@ -96,6 +225,12 @@ The options of `createDrawUI`, all optional:
 | `side` | The side panels `floating` over the map or `beside` it | `floating` |
 | `themeToggle` | The button that switches the look | `true` |
 | `mapControls` | maplibre-gl's globe, compass, zoom and scale | `true` |
+| `basemaps` | The basemaps the basemap row opens | none |
+| `basemap` | The ID of the basemap current at the start | the map's |
+| `onbasemap` | Called with the basemap after it changed | none |
+| `actions` | The actions of the application, in a card at the left | none |
+| `actionsTitle` | The title of the card of the actions | `Actions` |
+| `actionsOpen` | Whether the card of the actions starts unfolded | `true` |
 
 Each part also goes alone into an element of the page, with its own
 options and `target`, `locale` and `theme`: `createToolbar`,
@@ -103,26 +238,58 @@ options and `target`, `locale` and `theme`: `createToolbar`,
 
 The interface is laid over the map's container. The toolbar alone goes
 into any positioned element with `createToolbar(draw, { target })`.
+The magnet at the end of the toolbar is pressed while snapping is on,
+and opens the snapping settings above the toolbar: snapping itself and,
+under it, the kinds of target (vertices, edges, intersections and
+guides), then snapping to datasets, tracing edges and moving shared
+vertices together, with the key that pauses snapping while it is held.
+Each switch writes `draw.options.update`, and the settings follow
+`options.changed`, so a change made by code shows too.
 The side panels float over the map, gap-md from its edges and as tall
 as their content; `side: 'beside'` docks them beside the map on a wide
-one instead. The map's padding follows the interface, the width of a
-panel that stands beside the map and the toolbar's height at the bottom,
-so that `fitBounds` and `easeTo` keep clear of them; `padding: false`
-leaves the map's padding alone.
+one instead. The map's padding follows the interface: at the left, the
+room the left panel takes (beside the map, or floating over it with its
+gap), and at the bottom, the height of the sheets of a narrow map, as
+kata's Shell reports them (`onlayout`'s inset), so that `fitBounds` and
+`easeTo` keep clear of them. The right panel opens and closes with the
+selection and leaves the padding alone, so that the view does not jump;
+the controls of the bottom right move out of its way instead (see
+[Map controls](#map-controls)). `padding: false` leaves the map's
+padding alone.
 
 On the left, the layer panel and the legend share a panel, in two tabs.
-The layer panel is the tree of the layers, their groups and their
-features, from the front, with the eye, the lock, renaming in place (F2
-or a double click), reordering by dragging and an add menu (a new layer,
+The layer panel has two sections, Stack and Basemap. Stack is the tree
+of the layers, their groups and their features, from the front, with
+the eye, the lock, reordering by dragging and an add menu (a new layer,
 a new group from the selected features). A feature is named by its
-`properties.name`, or by its type when it has none. The legend shows
-the rows of the style rule (`styleRule`) of each layer that has one.
+`properties.name`, or by its type when it has none; names are changed
+in the head of the inspector, not in the tree. Each row costs its
+drawing, so a layer lists up to 1,000 features, those of its groups
+included: a layer that holds more lists none of them and shows their
+number instead, with a hint to select them on the map, and its own row
+works as before (the eye, the lock, the active layer). `features` sets
+the limit as a number, and `false` lists no features, only the groups.
+The datasets (`draw.datasets`) are rows of the stack too, in their place
+among the layers: those of `above-store` in front of every layer, those
+of `layer-order` where `layers.getOrder()` places them, and those of
+`below-store` behind every layer. A dataset row shows its ID (core gives
+a dataset no name), with the eye (`setVisible`) and no lock; a press on
+it leaves the selection as it is. Every dataset is dragged among the
+layers: one of `above-store` or `below-store` dropped there is moved to
+`layer-order` (`draw.datasets.move`) and placed where it was dropped
+(`draw.layers.reorder`), and goes back to its own order when the reorder
+is refused. Basemap, under it, is the back of the stack (see
+[Basemaps](#basemaps)). The legend shows the rows of the style rule
+(`styleRule`) of each layer and of each dataset that has one, in the
+order of the stack.
 Shift+L opens and closes the panel, and while it is closed a button at
 the top left of the map opens it again.
 
 ```ts
 const ui = createDrawUI(draw, {
-  layers: { features: true, add: true, reorder: true }, // or false for none
+  // or false for none; features: true lists up to 1,000 in a layer, a number
+  // sets that limit, and false lists none
+  layers: { features: true, datasets: true, add: true, reorder: true },
   legend: true,
 });
 ```
@@ -146,15 +313,18 @@ ui.tools.add({
 
 The inspector is the panel on the right of `createDrawUI`. It opens
 while something is selected and closes, clearing the selection, with its
-close button. For one feature it shows its name (`properties.name`,
-changed where it stands); under it, its measurements and its description
-(`properties.description`, changed where it stands); then a Style tab
-with the fields its type reads and an Attributes tab with its other
-attributes. Several features
+close button. On a narrow map it is a sheet from the bottom, as wide as
+the map. For one feature it shows its name (`properties.name`, changed
+where it stands); under it, its measurements, and the tabs, which stay
+while the content scrolls: a Style tab with the fields its type reads
+and an Attributes tab with its other attributes. The content of each tab
+starts with its description (`properties.description`, changed where it
+stands). Several features
 show the fields they share, a field whose values differ being mixed, and
 the operations that apply to them (union, intersection, difference,
 split and buffer). A layer and a group show their name, whether they are
-visible and whether they are locked.
+visible and whether they are locked. Delete is at the start of the foot
+of every inspector, for one feature and for several things selected.
 
 ```ts
 const ui = createDrawUI(draw, {
@@ -163,6 +333,9 @@ const ui = createDrawUI(draw, {
 });
 ```
 
+The tabs open on the first of `tabs`: `['attributes', 'style']` opens
+on Attributes. A tab chosen stays open from one feature to the next.
+
 A value typed into an attribute is kept as the string typed. The
 inspector alone goes into any element with
 `createInspector(draw, { target })`, and an application adds a section
@@ -191,15 +364,27 @@ ui.inspector?.sections.add({
 ## Customize
 
 Everything the interface draws is inside its root element, which has the
-class `mgd-ui`, and its style sheet reaches nothing outside it. kata's
-tokens (the CSS custom properties `--kata-*`) are set on that element;
-set them on `.mgd-ui` to change the look. The `theme` option of
+class `mgd-ui`, and its style sheet reaches nothing outside it but
+maplibre-gl's controls of the map (see [Map controls](#map-controls)).
+kata's tokens (the CSS custom properties `--kata-*`) are set on that
+element; set them on `.mgd-ui` to change the look. The `theme` option of
 `createDrawUI` and of each part put alone is `light`, `dark` or `auto`
 (the default, which follows the system's `prefers-color-scheme` as it
 changes), and `ui.setTheme` changes it. kata's theme is dark;
 `data-color-mode="light"` on the root element, which `light` sets, or on
 any element around it, turns it light.
 
+maplibre-gl's controls in the map's container, those of the application
+too, follow the theme of `createDrawUI`: while it is on the map,
+maplibre-gl's control container (`.maplibregl-control-container`) has
+`data-mgd-ui-controls`, which takes kata's tokens, and the
+`data-color-mode` of the root. The groups of buttons, the lines between
+them, the attribution and the scale are painted with the tokens, and
+maplibre-gl's icons, which are dark images, are inverted in the dark
+look (`filter: invert(1)`). Set the tokens on
+`[data-mgd-ui-controls]` to change their look. `destroy()` removes both
+attributes.
+
 A button at the top right of the map switches the look: a sun while it
 is dark, a moon while it is light. It sets the theme to the look that is
 not shown, so from `auto` it keeps the one the system does not prefer;
@@ -209,8 +394,106 @@ open over the map or beside it, the button stands to the left of it.
 
 Beyond the look, the options above choose the parts and what each shows,
 `ui.tools.add` adds a tool for a mode of the application (see
-[Use](#use)), and `ui.inspector.sections.add` adds a section to the
-inspector (see [Inspector](#inspector)).
+[Use](#use)), `ui.inspector.sections.add` adds a section to the
+inspector (see [Inspector](#inspector)), and `ui.actions.add` adds an
+action of the application (see [Actions](#actions)).
+
+### Actions
+
+An action of the application, such as saving the drawing or turning a
+setting on and off, is a row of a card at the bottom left of the map,
+above maplibre-gl's scale and, where its box reaches the card across, the
+attribution: a switch (`kind: 'toggle'`) or a button
+(`kind: 'action'`), with its key at the end. A press on the row and its
+key both call `run`; a switch shows what `checked` returns, read again
+after each run and on `ui.actions.refresh()`, so the state stays with
+the application. `disabled` dims the row and turns its key off, and
+`hint` is a caption under it. The keys are listed with `?` under the
+title of the card, and do nothing while a field has the focus. A key the
+interface uses (the keys of the tools, Delete, Backspace, Escape, `?`
+and Shift+L) or another action uses is refused with an error. The card
+shows while there is an action, its head folds it into one button, and
+on a map narrower than 48rem it starts folded; where it would reach the
+toolbar across, it stands above the toolbar, and the layer panel
+floating at the left ends above it. The card is no taller than the map
+above its place, less gap-md at the top and the button that opens the
+layer panel again while it shows; the whole card scrolls when its rows
+do not fit. Its title is `actionsTitle`, or the
+word for actions of the locale.
+
+```ts
+const ui = createDrawUI(draw, {
+  actions: [
+    {
+      id: 'read-only',
+      label: 'Read-only',
+      kind: 'toggle',
+      shortcut: 'R',
+      run: () => draw.setReadOnly(!draw.isReadOnly()),
+      checked: () => draw.isReadOnly(),
+    },
+  ],
+});
+
+const remove = ui.actions.add({
+  id: 'save',
+  label: 'Save',
+  kind: 'action',
+  shortcut: 'S',
+  run: () => localStorage.setItem('drawing', JSON.stringify(draw.document.toJSON())),
+});
+```
+
+## Basemaps
+
+The last section of the layer panel, Basemap, is the back of the stack:
+one row under the tree of the layers, apart from it as the basemap is no
+layer, so it is not dragged, hidden, locked or selected. The row shows
+the name of the basemap the map shows: the label of the current one of
+`basemaps`, else the `name` of the map's style, read again on each
+`style.load`, else the word for a basemap.
+
+With two or more `basemaps`, pressing the row opens them on the right,
+in the place of the inspector: a list of their labels, each with its
+`preview` (a value of CSS `background`, such as a gradient in the colors
+of the style; a neutral square without one), and a check on the current
+one. Opening it clears the selection, and selecting a feature on the map
+or in the tree closes it, as do its close button and Escape. Choosing a
+basemap replaces the map's style with its `style` (a URL or a style
+object) and calls `onbasemap`, and the list stays open.
+`ui.setBasemap(id)` does the same, and `ui.getBasemap()` returns the
+current one. The current one at the start is `basemap`, or else the
+first whose `style` is the URL the map's style was loaded from. With
+fewer, the row only shows the name.
+
+```ts
+const styles = 'https://tiles.openfreemap.org/styles';
+const ui = createDrawUI(draw, {
+  basemaps: [
+    {
+      id: 'bright',
+      label: 'Bright',
+      style: `${styles}/bright`,
+      preview: 'linear-gradient(135deg, #f4f1ea, #dfe7d5)',
+    },
+    { id: 'dark', label: 'Dark', style: `${styles}/dark` },
+  ],
+  onbasemap: (basemap) => console.log(basemap.id),
+});
+```
+
+The layer panel put alone takes the same options
+(`LayerPanelOptions`):
+`createLayerPanel(draw, { target, basemaps, basemap, onbasemap })`.
+There, the row opens the list in the place of the panel's sections,
+until its close button or Escape closes it.
+
+The drawing stays: choosing a basemap calls
+`map.setStyle(style, { diff: false })`, which replaces the style whole,
+and the draw instance adds its layers again on top of the new style once
+it has loaded. Sources, layers and the terrain that the application
+added to the map itself go with the old style, so it adds them again on
+the map's `style.load` event.
 
 ## Map controls
 
@@ -228,12 +511,21 @@ const ui = createDrawUI(draw, {
 });
 ```
 
-A page that adds controls of its own passes `mapControls: false`. Where
-the toolbar reaches a bottom corner of the map across, as on a narrow
-map, that corner (its controls and the attribution) is lifted above the
-toolbar. This is the one rule of the style sheet outside the root
-element: it applies to the map's container while the interface is on
-it.
+A page that adds controls of its own passes `mapControls: false`. The
+bottom corners of the map are kept clear of the interface:
+
+- where the toolbar reaches a bottom corner across, as on a narrow map,
+  that corner (its controls and the attribution) is lifted above the
+  toolbar
+- while the right panel covers the bottom right of the map, the controls
+  there (not the attribution) move to the left of it, gap-md apart
+- where the attribution's box reaches the scale across, as the two-line
+  attribution of a narrow map does, the bottom left corner is lifted
+  above it. The attribution is only read; its compact form is
+  maplibre-gl's own
+
+These are the rules of the style sheet outside the root element: they
+apply to the map's container while the interface is on it.
 
 ## Development
 

package/dist/actions.d.ts

@@ -0,0 +1,46 @@
+import type { Shortcut } from '@sakuzu/kata/svelte';
+import type { Messages } from './messages.js';
+import { Box } from './store.js';
+import type { ActionSpec, ActionsHandle, ToolEntry } from './types.js';
+/**
+ * A key written one way: the modifiers in a fixed order, then the key, all in lowercase, so that
+ * `Shift+R`, `shift+r` and `r+shift` compare equal
+ */
+export declare function normalizeKey(shortcut: string): string;
+/**
+ * Checks an action of the application
+ *
+ * @throws Error when a field is missing or has the wrong type
+ */
+export declare function checkAction(spec: ActionSpec): void;
+/**
+ * Checks that the key of an action is free
+ *
+ * @throws Error when it is a key of the interface, of a tool or of another action
+ */
+export declare function checkActionKey(spec: ActionSpec, tools: readonly ToolEntry[], messages: Messages, actions: readonly ActionSpec[]): void;
+/** The actions of the card, and the count of their changes that the rows follow */
+export interface ActionsState {
+    /** The actions in the order of the card */
+    readonly list: Box<ActionSpec[]>;
+    /** Changed after each run and on `refresh()`, so that the rows read `checked` and `disabled` */
+    readonly version: Box<number>;
+}
+/**
+ * The actions of the options, checked
+ *
+ * @throws Error when an action is not valid, two share an ID, or a key is taken
+ */
+export declare function actionsState(actions: readonly ActionSpec[] | undefined, tools: readonly ToolEntry[], messages: Messages): ActionsState;
+/** Runs an action, unless it is disabled, and has the rows read their state again */
+export declare function runAction(state: ActionsState, spec: ActionSpec): void;
+/** The actions of the card, to add to and to remove from */
+export declare function actionsHandle(state: ActionsState, tools: Box<ToolEntry[]>, messages: Box<Messages>): ActionsHandle;
+/** The keys of the actions, as shortcuts of kata's Shell under the title of the card */
+export declare function actionShortcuts(state: ActionsState, group: string): Shortcut[];
+/**
+ * Checks that the key of a tool is not the key of an action
+ *
+ * @throws Error when an action has the key
+ */
+export declare function checkToolKey(id: string, shortcut: string | undefined, actions: readonly ActionSpec[]): void;

package/dist/basemaps.d.ts

@@ -0,0 +1,58 @@
+import { Box } from './store.js';
+import type { Basemap } from './types.js';
+/** The members of the map the basemaps use */
+export interface BasemapMap {
+    setStyle(style: Basemap['style'], options?: {
+        diff?: boolean;
+    }): unknown;
+    /** The URL the style was loaded from (maplibre-gl 6), to find the current basemap */
+    getStyleUrl?(): string | null;
+    /** The style as it is now, whose name names a basemap that is none of the list */
+    getStyle?(): {
+        name?: string;
+    } | undefined;
+    /** Follows the load of each new style, to read its name again */
+    on?(type: 'style.load', listener: () => void): unknown;
+    off?(type: 'style.load', listener: () => void): unknown;
+}
+/** The basemaps of the options, checked, and the ID of the current one */
+export interface BasemapSettings {
+    list: readonly Basemap[];
+    current: string | null;
+}
+/**
+ * Checks the basemaps of the options and finds the current one: `initial` when given, else the
+ * first whose style is the URL of the map's style, else none.
+ *
+ * @throws Error when a basemap has no ID, no label or no style, has a preview that is not a
+ *   string, two share an ID, or `initial` is the ID of none of them
+ */
+export declare function basemapSettings(basemaps: readonly Basemap[] | undefined, initial: string | undefined, styleUrl: string | null): BasemapSettings;
+/** The basemaps on a map: the list, the current one, its name, and the change */
+export interface BasemapControl {
+    /** The basemaps, in the order they are offered */
+    readonly list: readonly Basemap[];
+    /** The ID of the current basemap, which the row and the basemaps to choose from follow */
+    readonly current: Box<string | null>;
+    /**
+     * The name of the basemap the map shows: the label of the current basemap, else the `name` of
+     * the map's style, else null. Read inside a component, it is followed
+     */
+    name(): string | null;
+    /**
+     * Replaces the map's style with the style of a basemap and calls `onchange` with it; nothing
+     * happens when it is current already
+     *
+     * @throws Error when no basemap has this ID
+     */
+    set(id: string): void;
+    /** The current basemap, or null */
+    get(): Basemap | null;
+    /** Stops following the map's style */
+    destroy(): void;
+}
+/**
+ * Keeps the current basemap of a map and changes its style. The name of the map's style is read
+ * now and again on each `style.load`
+ */
+export declare function basemapControl(map: BasemapMap, settings: BasemapSettings, onchange?: (basemap: Basemap) => void): BasemapControl;

package/dist/controls.d.ts

@@ -1,4 +1,5 @@
 import { type ControlPosition, type IControl } from 'maplibre-gl';
+import type { ShellInset } from './padding.js';
 import type { MapControlsOptions } from './types.js';
 /** The members of the map the controls use */
 export interface ControlsMap {
@@ -20,17 +21,32 @@ export interface MapControls {
 export declare function mapControls(map: ControlsMap, option: boolean | MapControlsOptions | undefined): MapControls;
 /** The attribute on the map's container while the interface lifts its bottom corners */
 export declare const LIFT_ATTRIBUTE = "data-mgd-ui-lift";
-/** The bottom corners of the map, lifted above the toolbar while it reaches them */
+/** The bottom corners of the map, kept clear of the interface and of the attribution */
 export interface CornerLift {
-    /** Measures again after the toolbar came, went or changed */
-    update(): void;
+    /**
+     * Measures again after the toolbar came, went or changed, or the regions of the shell moved;
+     * with the inset the shell reported, which is kept until the next one
+     */
+    update(inset?: ShellInset): void;
     /** Stops following and puts the corners back */
     destroy(): void;
 }
 /**
- * Lifts the bottom corners of maplibre-gl's controls in `container` (the map's container) above
- * the toolbar of the interface in `root`, each while the toolbar reaches it across: by the
- * distance from the top of the toolbar to the bottom of the map. root.css moves the corners by
- * the custom properties this sets on the container (--mgd-ui-lift-left and --mgd-ui-lift-right).
+ * Keeps the bottom corners of maplibre-gl's controls in `container` (the map's container) clear
+ * of the interface in `root` and of the attribution. root.css moves them by the custom properties
+ * this sets on the container:
+ *
+ * - --mgd-ui-lift-left and --mgd-ui-lift-right lift a corner above the toolbar while the toolbar
+ *   reaches it across, by the distance from the top of the toolbar to the bottom of the map; the
+ *   controls of the bottom right moved to the left (below) count as reaching it where they are
+ *   moved to
+ * - --mgd-ui-shift-right moves the controls of the bottom right, not the attribution, to the left
+ *   while the right region covers the stage (the inset's right) and they are under it up and
+ *   down: by the inset and gap-md
+ * - --mgd-ui-lift-left also lifts the bottom left corner above the attribution's box while that
+ *   box reaches the corner across
+ *
+ * The boxes are measured where maplibre-gl places them, without what this moved. The attribution
+ * and the right region are followed with a ResizeObserver, as the toolbar and the corners are.
  */
 export declare function cornerLift(container: HTMLElement, root: HTMLElement): CornerLift;