@loidolt/theme-maps 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Loidolt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# @loidolt/theme-maps
+
+Accessible, themed [MapLibre](https://maplibre.org) maps for Svelte 5, painted from the Loidolt
+tokens.
+
+- **A basemap in the loidolt palette.** Land, water, parks, buildings, roads and names drawn from
+  any OpenMapTiles-schema vector tiles — [OpenFreeMap](https://openfreemap.org)'s free, keyless
+  tiles by default — in the `--loidolt-map-*` colours. A theme switch repaints it in place, and
+  data layers follow with it. `basemap="blank"` draws land only, with no network at all.
+- **Keyboard and screen reader first.** The canvas is named and described (including how to move
+  it); arrow keys pan and + and − zoom; where a keyboard move lands is announced. Markers are real
+  buttons with names; popups take focus and give it back; `MapFeatureList` lists every place as a
+  list you can tab through.
+- **Server-rendered safely.** MapLibre loads in the browser only. Without WebGL the map says so
+  instead of leaving a blank box.
+- **Only what changed.** Layers diff their paint, layout and filters and send MapLibre only the
+  difference; GeoJSON updates replace data in place.
+
+## Install
+
+```sh
+npm install @loidolt/theme-maps maplibre-gl
+```
+
+`maplibre-gl` (5 or 6) is a peer dependency. Import the map stylesheet once, next to the theme's:
+
+```css
+@import '@loidolt/theme-svelte/styles.css';
+@import '@loidolt/theme-maps/styles.css';
+```
+
+**MapLibre 6 and bundlers.** MapLibre 6 ships its web worker as a separate file and finds it at
+runtime in a way bundlers cannot follow. Without it, raster layers draw but GeoJSON and vector
+tiles never do. With Vite, have it bundle the worker and say where it went, once at start-up:
+
+```ts
+import { setMapLibreWorkerUrl } from '@loidolt/theme-maps';
+import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
+
+setMapLibreWorkerUrl(workerUrl);
+```
+
+and set `worker: { format: 'es' }` in `vite.config`. MapLibre 5 inlines its worker and needs
+neither.
+
+The stylesheet layers MapLibre's own CSS under the loidolt components (see _Cascade layers_ in the main
+README), so the loidolt control, popup and attribution styles win without `!important`.
+
+```svelte
+<script lang="ts">
+  import { CircleLayer, MapMarker, MapSource, MapView } from '@loidolt/theme-maps';
+</script>
+
+<MapView label="Delivery stops" center={[-122.68, 45.52]} zoom={12}>
+  <MapSource id="stops" data={stopsGeoJSON}>
+    <CircleLayer id="stop-points" />
+  </MapSource>
+  <MapMarker lngLat={[-122.66, 45.51]} label="Workshop">
+    {#snippet popup()}<strong>Workshop</strong>
+      <p>Open 8 to 5</p>{/snippet}
+  </MapMarker>
+</MapView>
+```
+
+## Components
+
+| Component            | What it is                                                                |
+| -------------------- | ------------------------------------------------------------------------- |
+| `MapView`            | The map: basemap, view state (bindable), controls, keyboard announcements |
+| `MapSource`          | GeoJSON or any MapLibre source, with optional clustering                  |
+| `FillLayer`          | Filled polygons                                                           |
+| `LineLayer`          | Lines                                                                     |
+| `CircleLayer`        | Points as circles                                                         |
+| `SymbolLayer`        | Text and icons                                                            |
+| `FillExtrusionLayer` | Polygons in 3D                                                            |
+| `HeatmapLayer`       | Point density on the sequential ramp                                      |
+| `RasterLayer`        | Raster tiles or a georeferenced image                                     |
+| `MapMarker`          | The loidolt pin as a named button, with an optional popup                 |
+| `MapPopup`           | A non-modal panel pointing at a spot                                      |
+| `MapControl`         | Any content as a map control                                              |
+| `MapLegend`          | Category or gradient key, on the map or beside it                         |
+| `MapLegendGroup`     | Several collapsible legends in one control                                |
+| `CoordinateDisplay`  | Coordinate under the pointer (or at the centre) and zoom                  |
+| `BasemapSwitcher`    | Switch between the loidolt basemap, the plain one, and your own styles    |
+| `MapFeatureList`     | Every place as a list that flies the map there — the non-visual route     |
+| `LayerManager`       | Show, fade and reorder layers; keyboard reordering, announced             |
+| `DeckOverlay`        | deck.gl layers on the map (optional peer)                                 |
+
+Layers take `id`, `source` (or the enclosing `MapSource`), `sourceLayer`, `beforeId`, `filter`,
+`minZoom`/`maxZoom`, `visible`, `layout`, `label`, `onClick`, `onHover` and `paint`. `paint` is
+merged over themed defaults; pass a function of the colours to follow light and dark:
+
+```svelte
+<FillLayer id="zones" paint={(colors) => ({ 'fill-color': colors.categorical[2] })} />
+```
+
+## Tiles and attribution
+
+The default basemap uses OpenFreeMap. It needs no key and no account, but it is a free service
+with no service-level agreement, and its attribution must stay visible (the attribution control
+shows it). Labels use the fonts its glyph server has — Noto Sans — not the page's.
+
+To use other tiles, pass any OpenMapTiles-schema source as a TileJSON URL or `{z}/{x}/{y}`
+template, with its attribution:
+
+```svelte
+<MapView label="…" tiles="https://tiles.example.com/planet.json" attribution="© Example" />
+```
+
+`mapStyle` takes a complete style URL or document instead; it is used as is and not recoloured.
+
+## Styles and helpers without a component
+
+`@loidolt/theme-maps/core` is plain TypeScript with no Svelte and no MapLibre import:
+
+- `createBasemapStyle`, `createBlankStyle`, `basemapPaint` — the styles `MapView` uses, for a
+  map you create yourself.
+- `boundsOf`, `boundsCenter`, `padBounds`, `boundsContain`, `boundsIntersect`.
+- `validateGeoJSON` (catches `[lat, lng]` order), `loadGeoJSON`, `pointsToFeatureCollection`,
+  `featureAnchor`.
+- `formatCoordinate` (latitude first, with hemispheres; decimal or DMS), `formatDistance`,
+  `formatArea`.
+- `clusterColor`, `clusterRadius`, `expandCluster`.
+- `formatMoveAnnouncement`, `describeZoom`, `MAP_KEYS`.
+
+## Routes and directions
+
+Straight-line routing with no service and no key: `haversine` and `pathLength` (metres),
+`distanceMatrix`, and `optimizeRoute(origin, stops)` — nearest neighbour, then 2-opt — which
+returns the visiting order, each leg and the total. Hand the order to a phone's maps app with
+`googleDirectionsUrl` or `appleDirectionsUrl`; `googleDirectionsLegUrls` splits a long route into
+links that each fit Google's waypoint limit, every leg starting where the last one ended.
+
+## Large datasets
+
+- `createSpatialIndex()` — an R-tree over features: `search(bounds)` for what is in view,
+  `nearest(point, count)`.
+- `simplifyLine`, `simplifyFeatures`, `convexHull`, and `createLevelOfDetail(collection)`, which
+  simplifies to what a pixel can show at each zoom and caches per level; `outlineOf(features)`
+  collapses a group into one shape for far zooms.
+- `createSpatialWorker()` runs the index and simplification in a web worker, falling back to the
+  main thread (same answers) where no worker can start. It finds its worker next to itself; if a
+  bundler's dependency pre-bundling loses it, import it through the bundler and pass it in:
+
+  ```ts
+  import SpatialWorker from '@loidolt/theme-maps/spatial.worker?worker';
+  const spatial = createSpatialWorker({ workerFactory: () => new SpatialWorker() });
+  ```
+
+## deck.gl
+
+`DeckOverlay` draws deck.gl layers on the map, on a canvas of their own that follows the camera.
+`interleaved` draws them in among MapLibre's layers instead, sharing its depth — but it reaches
+into MapLibre's renderer, so it needs a deck.gl release that supports your MapLibre major
+(deck.gl 9.4 does not yet support MapLibre 6's). deck.gl is an optional peer; register it once
+and build your layers as usual:
+
+```ts
+import { setDeckLoader } from '@loidolt/theme-maps';
+setDeckLoader(() => import('@deck.gl/mapbox'));
+```
+
+```svelte
+<DeckOverlay layers={[new ScatterplotLayer({ id: 'jobs', data, getPosition, getRadius })]} />
+```
+
+## Loading MapLibre yourself
+
+Maps import `maplibre-gl` on first use. To use a global build, or a stand-in under test:
+
+```ts
+import { setMapLibreLoader } from '@loidolt/theme-maps';
+setMapLibreLoader(() => window.maplibregl);
+```
+
+## License
+
+MIT

package/dist/components/BasemapSwitcher.svelte

@@ -0,0 +1,53 @@
+<script lang="ts">
+  import { ToggleGroup, cx } from '@loidolt/theme-svelte';
+  import type { StyleSpecification } from '../core/types.js';
+  import { requireMapContext } from '../internal/context.js';
+  import MapControl from './MapControl.svelte';
+
+  type Corner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+  interface Basemap {
+    id: string;
+    label: string;
+    /** A style of your own. Leave it out for the built-in `default` and `blank`. */
+    style?: string | StyleSpecification;
+  }
+
+  interface Props {
+    /** The choices, in order. Defaults to the loidolt basemap and the plain one. */
+    basemaps?: Basemap[];
+    /** Names the group of choices. */
+    label?: string;
+    position?: Corner;
+    onChange?: (id: string) => void;
+    class?: string;
+  }
+
+  let {
+    basemaps = [
+      { id: 'default', label: 'Map' },
+      { id: 'blank', label: 'Plain' },
+    ],
+    label = 'Basemap',
+    position = 'top-left',
+    onChange,
+    class: className,
+  }: Props = $props();
+
+  const context = requireMapContext('BasemapSwitcher');
+</script>
+
+<MapControl {position} class={cx('ldt-basemap-switcher', className)}>
+  <ToggleGroup
+    {label}
+    size="sm"
+    value={context.basemap}
+    options={basemaps.map((basemap) => ({ value: basemap.id, label: basemap.label }))}
+    onValueChange={(next) => {
+      const choice = basemaps.find((basemap) => basemap.id === next);
+      if (!choice) return;
+      context.setBasemap(choice.id, choice.style);
+      onChange?.(choice.id);
+    }}
+  />
+</MapControl>

package/dist/components/BasemapSwitcher.svelte.d.ts

@@ -0,0 +1,20 @@
+import type { StyleSpecification } from '../core/types.js';
+type Corner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+interface Basemap {
+    id: string;
+    label: string;
+    /** A style of your own. Leave it out for the built-in `default` and `blank`. */
+    style?: string | StyleSpecification;
+}
+interface Props {
+    /** The choices, in order. Defaults to the loidolt basemap and the plain one. */
+    basemaps?: Basemap[];
+    /** Names the group of choices. */
+    label?: string;
+    position?: Corner;
+    onChange?: (id: string) => void;
+    class?: string;
+}
+declare const BasemapSwitcher: import("svelte").Component<Props, {}, "">;
+type BasemapSwitcher = ReturnType<typeof BasemapSwitcher>;
+export default BasemapSwitcher;

package/dist/components/CircleLayer.svelte

@@ -0,0 +1,22 @@
+<script lang="ts">
+  import type { MapColors } from '@loidolt/theme-tokens';
+  import { useLayer, type LayerProps } from '../internal/use-layer.svelte.js';
+
+  /* Points as circles. Defaults to accent dots with a surface-coloured ring. */
+  type Props = LayerProps;
+
+  let props: Props = $props();
+
+  useLayer(
+    'circle',
+    () => props,
+    (colors: MapColors) => ({
+      paint: {
+        'circle-color': colors.accent,
+        'circle-radius': 6,
+        'circle-stroke-color': colors.surface,
+        'circle-stroke-width': 1.5,
+      },
+    })
+  );
+</script>

package/dist/components/CircleLayer.svelte.d.ts

@@ -0,0 +1,4 @@
+import { type LayerProps } from '../internal/use-layer.svelte.js';
+declare const CircleLayer: import("svelte").Component<LayerProps, {}, "">;
+type CircleLayer = ReturnType<typeof CircleLayer>;
+export default CircleLayer;

package/dist/components/CoordinateDisplay.svelte

@@ -0,0 +1,68 @@
+<script lang="ts">
+  import { cx } from '@loidolt/theme-svelte';
+  import { formatCoordinate } from '../core/format.js';
+  import type { LngLat } from '../core/types.js';
+  import { requireMapContext } from '../internal/context.js';
+  import MapControl from './MapControl.svelte';
+
+  type Corner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+  interface Props {
+    position?: Corner;
+    /** `decimal` degrees, or degrees, minutes and seconds. */
+    format?: 'decimal' | 'dms';
+    precision?: number;
+    showZoom?: boolean;
+    zoomLabel?: string;
+    class?: string;
+  }
+
+  let {
+    position = 'bottom-left',
+    format = 'decimal',
+    precision,
+    showZoom = true,
+    zoomLabel = 'Zoom',
+    class: className,
+  }: Props = $props();
+
+  const context = requireMapContext('CoordinateDisplay');
+  let coordinate = $state<LngLat | null>(null);
+  let zoom = $state(0);
+
+  // Under the pointer while it is over the map; the centre otherwise, so keyboard users see it too.
+  $effect(() => {
+    const target = context.map;
+    if (!target) return;
+    let pointer = false;
+    const centre = () => {
+      const { lng, lat } = target.getCenter();
+      zoom = target.getZoom();
+      if (!pointer) coordinate = [lng, lat];
+    };
+    const move = (event: { lngLat: { lng: number; lat: number } }) => {
+      pointer = true;
+      coordinate = [event.lngLat.lng, event.lngLat.lat];
+    };
+    const leave = () => {
+      pointer = false;
+      centre();
+    };
+    centre();
+    target.on('move', centre);
+    target.on('mousemove', move);
+    target.on('mouseout', leave);
+    return () => {
+      target.off('move', centre);
+      target.off('mousemove', move);
+      target.off('mouseout', leave);
+    };
+  });
+</script>
+
+<MapControl {position}>
+  <p class={cx('ldt-map-coordinates', className)}>
+    {#if coordinate}<span>{formatCoordinate(coordinate, { format, precision })}</span>{/if}
+    {#if showZoom}<span>{zoomLabel} {zoom.toFixed(1)}</span>{/if}
+  </p>
+</MapControl>

package/dist/components/CoordinateDisplay.svelte.d.ts

@@ -0,0 +1,13 @@
+type Corner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+interface Props {
+    position?: Corner;
+    /** `decimal` degrees, or degrees, minutes and seconds. */
+    format?: 'decimal' | 'dms';
+    precision?: number;
+    showZoom?: boolean;
+    zoomLabel?: string;
+    class?: string;
+}
+declare const CoordinateDisplay: import("svelte").Component<Props, {}, "">;
+type CoordinateDisplay = ReturnType<typeof CoordinateDisplay>;
+export default CoordinateDisplay;

package/dist/components/DeckOverlay.svelte

@@ -0,0 +1,58 @@
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import type { IControl } from 'maplibre-gl';
+  import { loadDeck, type DeckOverlayInstance } from '../deck.js';
+  import { requireMapContext } from '../internal/context.js';
+  import { safely } from '../internal/safely.js';
+
+  interface Props {
+    /** deck.gl layers, built by you (`new ScatterplotLayer({…})`). Replace the array to update. */
+    layers: unknown[];
+    /**
+     * Draw deck.gl layers in among the map's own, sharing its depth, rather than on a canvas
+     * above it. Off by default: interleaving reaches into MapLibre's renderer, so it needs a
+     * deck.gl release that supports your MapLibre major (deck.gl 9.4 does not yet support
+     * MapLibre 6's).
+     */
+    interleaved?: boolean;
+    /** Anything else `MapboxOverlay` takes — `getTooltip`, `pickingRadius`, `effects`… */
+    overlayProps?: Record<string, unknown>;
+    /** deck.gl could not be loaded: nothing is drawn. Register it with `setDeckLoader`. */
+    onUnavailable?: () => void;
+  }
+
+  let { layers, interleaved = false, overlayProps = {}, onUnavailable }: Props = $props();
+
+  const context = requireMapContext('DeckOverlay');
+  let overlay = $state.raw<DeckOverlayInstance | null>(null);
+
+  $effect(() => {
+    const map = context.map;
+    if (!map) return;
+    let disposed = false;
+    let created: DeckOverlayInstance | null = null;
+    void loadDeck().then((deck) => {
+      if (disposed) return;
+      if (!deck) {
+        untrack(() => onUnavailable?.());
+        return;
+      }
+      created = new deck.MapboxOverlay(untrack(() => ({ ...overlayProps, interleaved, layers })));
+      map.addControl(created as unknown as IControl);
+      overlay = created;
+    });
+    return () => {
+      disposed = true;
+      overlay = null;
+      if (created) {
+        const done = created;
+        safely(() => map.removeControl(done as unknown as IControl));
+        done.finalize?.();
+      }
+    };
+  });
+
+  $effect(() => {
+    overlay?.setProps({ ...overlayProps, layers });
+  });
+</script>

package/dist/components/DeckOverlay.svelte.d.ts

@@ -0,0 +1,18 @@
+interface Props {
+    /** deck.gl layers, built by you (`new ScatterplotLayer({…})`). Replace the array to update. */
+    layers: unknown[];
+    /**
+     * Draw deck.gl layers in among the map's own, sharing its depth, rather than on a canvas
+     * above it. Off by default: interleaving reaches into MapLibre's renderer, so it needs a
+     * deck.gl release that supports your MapLibre major (deck.gl 9.4 does not yet support
+     * MapLibre 6's).
+     */
+    interleaved?: boolean;
+    /** Anything else `MapboxOverlay` takes — `getTooltip`, `pickingRadius`, `effects`… */
+    overlayProps?: Record<string, unknown>;
+    /** deck.gl could not be loaded: nothing is drawn. Register it with `setDeckLoader`. */
+    onUnavailable?: () => void;
+}
+declare const DeckOverlay: import("svelte").Component<Props, {}, "">;
+type DeckOverlay = ReturnType<typeof DeckOverlay>;
+export default DeckOverlay;

package/dist/components/FillExtrusionLayer.svelte

@@ -0,0 +1,17 @@
+<script lang="ts">
+  import type { MapColors } from '@loidolt/theme-tokens';
+  import { useLayer, type LayerProps } from '../internal/use-layer.svelte.js';
+
+  /* Polygons raised into 3D by a height property. */
+  type Props = LayerProps;
+
+  let props: Props = $props();
+
+  useLayer(
+    'fill-extrusion',
+    () => props,
+    (colors: MapColors) => ({
+      paint: { 'fill-extrusion-color': colors.categorical[1], 'fill-extrusion-opacity': 0.8 },
+    })
+  );
+</script>

package/dist/components/FillExtrusionLayer.svelte.d.ts

@@ -0,0 +1,4 @@
+import { type LayerProps } from '../internal/use-layer.svelte.js';
+declare const FillExtrusionLayer: import("svelte").Component<LayerProps, {}, "">;
+type FillExtrusionLayer = ReturnType<typeof FillExtrusionLayer>;
+export default FillExtrusionLayer;

package/dist/components/FillLayer.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+  import type { MapColors } from '@loidolt/theme-tokens';
+  import { useLayer, type LayerProps } from '../internal/use-layer.svelte.js';
+
+  /* Shapes filled from polygon data. Defaults to the first series colour, lightly filled. */
+  type Props = LayerProps;
+
+  let props: Props = $props();
+
+  useLayer(
+    'fill',
+    () => props,
+    (colors: MapColors) => ({
+      paint: {
+        'fill-color': colors.categorical[0],
+        'fill-opacity': 0.28,
+        'fill-outline-color': colors.categorical[0],
+      },
+    })
+  );
+</script>

package/dist/components/FillLayer.svelte.d.ts

@@ -0,0 +1,4 @@
+import { type LayerProps } from '../internal/use-layer.svelte.js';
+declare const FillLayer: import("svelte").Component<LayerProps, {}, "">;
+type FillLayer = ReturnType<typeof FillLayer>;
+export default FillLayer;

package/dist/components/HeatmapLayer.svelte

@@ -0,0 +1,36 @@
+<script lang="ts">
+  import type { MapColors } from '@loidolt/theme-tokens';
+  import { useLayer, type LayerProps } from '../internal/use-layer.svelte.js';
+
+  /* Point density as a heatmap, coloured on the sequential ramp. */
+  type Props = LayerProps;
+
+  let props: Props = $props();
+
+  useLayer(
+    'heatmap',
+    () => props,
+    (colors: MapColors) => ({
+      paint: {
+        'heatmap-color': [
+          'interpolate',
+          ['linear'],
+          ['heatmap-density'],
+          0,
+          `${colors.sequential[0].slice(0, 7)}00`,
+          0.2,
+          colors.sequential[0],
+          0.4,
+          colors.sequential[1],
+          0.6,
+          colors.sequential[2],
+          0.8,
+          colors.sequential[3],
+          1,
+          colors.sequential[4],
+        ],
+        'heatmap-opacity': 0.85,
+      },
+    })
+  );
+</script>

package/dist/components/HeatmapLayer.svelte.d.ts

@@ -0,0 +1,4 @@
+import { type LayerProps } from '../internal/use-layer.svelte.js';
+declare const HeatmapLayer: import("svelte").Component<LayerProps, {}, "">;
+type HeatmapLayer = ReturnType<typeof HeatmapLayer>;
+export default HeatmapLayer;