@sjvair/map-sdk 0.0.0-stage → 0.1.0-beta.2

package/dist/view/MapView.svelte.d.ts

@@ -0,0 +1,43 @@
+import "@maptiler/sdk/dist/maptiler-sdk.css";
+import "../ui/controls.css";
+import type { Snippet } from "svelte";
+import type { MapContext } from "../core/create-map.svelte.js";
+import { type FeatureListOptions } from "./list-placement.js";
+interface Props {
+    /** The map to show. Fixed for the component's life. */
+    map: MapContext;
+    /** `false` releases the WebGL context; `true` rebuilds it with the same camera. */
+    active?: boolean;
+    class?: string;
+    /** The region's accessible name. Defaults to the `mapsdk_map_label` message. */
+    label?: string;
+    /** On-screen pieces drawn over the map; they get the map through `getMapContext()`. */
+    overlays?: Snippet;
+    /**
+     * The List button and its feature list panel: `false` leaves them out; `true` (default) or
+     * options place them. `position` picks the corner (default `"top-left"`); the button stacks
+     * below (or, in a bottom corner, above) the controls in that corner, and the open panel stops
+     * short of the controls and credits at the far end of its side. `reveal: "focus"` shows the
+     * button only while it or its open panel has keyboard focus (and the whole time the panel is
+     * open); otherwise it's visually hidden but stays in the Tab order, like a skip link.
+     */
+    featureList?: boolean | FeatureListOptions;
+    /** `false` leaves out the selection bar. */
+    selectionBar?: boolean;
+    /**
+     * The zoom controls: `"mapsdk"` (default) draws map-sdk's zoom buttons, `"engine"` the
+     * MapTiler SDK's default zoom/compass and locate-me controls, `"none"` none. The credits
+     * always show. Choose it up front: changing it after mount recreates the map (the engine
+     * controls are part of how the map is built), like `active`.
+     */
+    controls?: "mapsdk" | "engine" | "none";
+    /**
+     * `"pinned"` (default) anchors the tooltip to its feature. `"pointer"` shows it at the
+     * pointer, like sjvair.com's map, and hides it on zoom until the pointer moves again.
+     * Keyboard focus from the feature list always shows it pinned.
+     */
+    tooltip?: "pinned" | "pointer";
+}
+declare const MapView: import("svelte").Component<Props, {}, "">;
+type MapView = ReturnType<typeof MapView>;
+export default MapView;

package/dist/view/create-gl-map.d.ts

@@ -0,0 +1,34 @@
+import type { BasemapConfig } from "../core/basemap.svelte.js";
+import type { MapContext } from "../core/create-map.svelte.js";
+import type { GlMapLike } from "../core/gl.js";
+/**
+ * Calls `onChange` when the host's theme changes the tokens map colors are read from: on a
+ * `prefers-color-scheme` change, or a `data-theme`, `class`, or `style` change on `<html>`.
+ * Changes that leave the tokens on `container` as they were (e.g. a scroll lock's inline style)
+ * are ignored. Returns the stop function.
+ */
+export declare function watchTheme(container: Element, onChange: () => void): () => void;
+/** Today's live map: MapTiler Streets v4 and its variants, without the busy POI label layers. */
+export declare function defaultBasemaps(): BasemapConfig;
+/**
+ * A `transformRequest` that adds `key` to MapTiler API requests that have none. The SDK's own
+ * transform runs after it and only adds its global `config.apiKey` when `key` is missing, so
+ * each map's requests carry its own key, and two maps with different keys don't clash.
+ */
+export declare function maptilerKeyTransform(key: string): (url: string) => {
+    url: string;
+};
+/**
+ * Creates the MapTiler map for `ctx` in `container`, at `ctx`'s camera with its current basemap.
+ * Reads `ctx` untracked, so calling this in an effect doesn't make it depend on the camera or
+ * basemap. With `engineControls`, the MapTiler SDK adds its default zoom/compass and locate-me
+ * controls at the top right; they go with the map.
+ * Records the camera and bounds once the map loads and after every move.
+ */
+export declare function createGlMap(container: HTMLElement, ctx: MapContext, engineControls?: boolean): GlMapLike;
+/**
+ * Shows `credits` (plain text, one per dataset) in the map's attribution control, after the
+ * style's own credits. The control is replaced, not edited: MapLibre reads its custom
+ * attribution once. Does nothing for a map that isn't one of `createGlMap`'s or has no change.
+ */
+export declare function setDataCredits(gl: GlMapLike, credits: string[]): void;

package/dist/view/create-gl-map.js

@@ -0,0 +1,182 @@
+import { untrack } from "svelte";
+import { AttributionControl, AttributionControlMLGL, Map as MaptilerMap, MapStyle, config as maptilerConfig } from "@maptiler/sdk";
+import { themeSignature } from "../plugins/style.js";
+/**
+ * Calls `onChange` when the host's theme changes the tokens map colors are read from: on a
+ * `prefers-color-scheme` change, or a `data-theme`, `class`, or `style` change on `<html>`.
+ * Changes that leave the tokens on `container` as they were (e.g. a scroll lock's inline style)
+ * are ignored. Returns the stop function.
+ */
+export function watchTheme(container, onChange) {
+    let last = themeSignature(container);
+    const check = () => {
+        const next = themeSignature(container);
+        if (next === last)
+            return;
+        last = next;
+        onChange();
+    };
+    const media = matchMedia("(prefers-color-scheme: dark)");
+    media.addEventListener("change", check);
+    const observer = new MutationObserver(check);
+    observer.observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: ["data-theme", "class", "style"]
+    });
+    return () => {
+        media.removeEventListener("change", check);
+        observer.disconnect();
+    };
+}
+/** Today's live map: MapTiler Streets v4 and its variants, without the busy POI label layers. */
+export function defaultBasemaps() {
+    const streets = MapStyle.STREETS_V4;
+    return {
+        // Style URLs, not variant objects: the basemap fallback matches a failed style by its URL.
+        styles: streets.getVariants().map((v) => ({ id: v.getId(), style: v.getExpandedStyleURL() })),
+        defaultId: streets.getDefaultVariant().getId(),
+        excludedLayers: ["Sport", "Tourism", "Culture", "Shopping", "Food", "Transport"]
+    };
+}
+/**
+ * A `transformRequest` that adds `key` to MapTiler API requests that have none. The SDK's own
+ * transform runs after it and only adds its global `config.apiKey` when `key` is missing, so
+ * each map's requests carry its own key, and two maps with different keys don't clash.
+ */
+export function maptilerKeyTransform(key) {
+    return (url) => {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            return { url };
+        }
+        if (parsed.host !== maptilerConfig.apiHost || parsed.searchParams.has("key"))
+            return { url };
+        parsed.searchParams.append("key", key);
+        return { url: parsed.href };
+    };
+}
+/** MapLibre's own `setStyle`, which MapTiler's `Map` overrides. */
+const clearStyle = Object.getPrototypeOf(MaptilerMap.prototype)
+    .setStyle;
+/**
+ * MapLibre's `remove()` clears the style with `setStyle(null)`. MapTiler's `setStyle` turns
+ * `null` into its default Streets style when no style has loaded yet, so removing a map that is
+ * still loading (hiding it quickly) would request that style for nothing; and once one has
+ * loaded it keeps it, so the style's requests and worker sources outlive the map. `null` goes to
+ * MapLibre's `setStyle` instead (nothing else here passes `null`), and MapTiler's pending
+ * space and halo setup, which would read the cleared style, is marked done.
+ */
+class GlMap extends MaptilerMap {
+    /** Notes the SDK's own attribution control, which it adds while constructing the map. */
+    addControl(...args) {
+        const [control] = args;
+        if (control instanceof AttributionControlMLGL)
+            this.attribution = { control, credits: "[]" };
+        return super.addControl(...args);
+    }
+    setStyle(...args) {
+        if (args[0] !== null)
+            return super.setStyle(...args);
+        const pending = this
+            .spaceboxLoadingState;
+        if (pending)
+            pending.styleLoadedCallbackFired = true;
+        return clearStyle.apply(this, args);
+    }
+    /**
+     * MapTiler's telemetry timer calls this 2 s after the map is created, even when it has been
+     * removed since (a map hidden quickly), and a removed map has no style to ask.
+     */
+    isGlobeProjection() {
+        if (!this.style)
+            return false;
+        return super.isGlobeProjection();
+    }
+}
+/** The style of `ctx`'s current basemap. Throws when there is none, rather than letting MapTiler fall back to its own default style. */
+function styleOf(ctx) {
+    const id = ctx.basemap.current;
+    const entry = ctx.config.basemaps?.styles.find((s) => s.id === id);
+    if (!entry)
+        throw new Error(`map-sdk: no basemap style for "${id}"`);
+    return entry.style;
+}
+function recordView(gl, ctx) {
+    const center = gl.getCenter();
+    const bounds = gl.getBounds();
+    ctx.updateView({
+        center: [center.lng, center.lat],
+        zoom: gl.getZoom(),
+        bearing: gl.getBearing(),
+        pitch: gl.getPitch()
+    }, {
+        west: bounds.getWest(),
+        south: bounds.getSouth(),
+        east: bounds.getEast(),
+        north: bounds.getNorth()
+    });
+}
+/**
+ * Creates the MapTiler map for `ctx` in `container`, at `ctx`'s camera with its current basemap.
+ * Reads `ctx` untracked, so calling this in an effect doesn't make it depend on the camera or
+ * basemap. With `engineControls`, the MapTiler SDK adds its default zoom/compass and locate-me
+ * controls at the top right; they go with the map.
+ * Records the camera and bounds once the map loads and after every move.
+ */
+export function createGlMap(container, ctx, engineControls = false) {
+    const { camera, style } = untrack(() => ({ camera: ctx.camera, style: styleOf(ctx) }));
+    const gl = new GlMap({
+        container,
+        style,
+        center: camera.center,
+        zoom: camera.zoom,
+        bearing: camera.bearing,
+        pitch: camera.pitch,
+        // The key goes on each request, not on the SDK's global config (the `apiKey` option
+        // sets that global).
+        transformRequest: maptilerKeyTransform(ctx.config.maptilerKey),
+        cooperativeGestures: ctx.config.cooperativeGestures ?? false,
+        keyboard: true,
+        // The engine's attribution control (and MapTiler's logo, when the key's plan requires it),
+        // at its automatic size: full on wide maps, collapsed on narrow ones. The SDK's default is
+        // always full, so ask for its automatic mode.
+        attributionControl: { compact: "auto" },
+        // `controls: "engine"` gets the SDK's own zoom/compass and locate-me controls, with its
+        // defaults (as monitor-map has today); otherwise MapView draws the controls.
+        navigationControl: engineControls ? "top-right" : false,
+        geolocateControl: engineControls ? "top-right" : false,
+        logSDKVersion: false,
+        // Only when set, so a map without them gets today's constructor options.
+        ...(ctx.config.projection ? { projection: ctx.config.projection } : {}),
+        ...(ctx.config.space ? { space: ctx.config.space } : {})
+    });
+    gl.on("load", () => recordView(gl, ctx));
+    gl.on("moveend", () => recordView(gl, ctx));
+    return gl;
+}
+const escapeHtml = (text) => text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+/**
+ * Shows `credits` (plain text, one per dataset) in the map's attribution control, after the
+ * style's own credits. The control is replaced, not edited: MapLibre reads its custom
+ * attribution once. Does nothing for a map that isn't one of `createGlMap`'s or has no change.
+ */
+export function setDataCredits(gl, credits) {
+    const map = gl;
+    const current = map.attribution;
+    if (!current || !(map instanceof GlMap))
+        return;
+    const key = JSON.stringify(credits);
+    if (key === current.credits)
+        return;
+    map.removeControl(current.control);
+    map.attribution = null;
+    const next = new AttributionControl({
+        compact: undefined,
+        customAttribution: credits.map(escapeHtml)
+    });
+    map.addControl(next);
+    map.attribution = { control: next, credits: key };
+}

package/dist/view/list-placement.d.ts

@@ -0,0 +1,21 @@
+/** A corner of the map. */
+export type ListPosition = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+/** `MapView`'s `featureList` options. */
+export interface FeatureListOptions {
+    /** The corner the List button sits in; its panel opens from there. Default `"top-left"`. */
+    position?: ListPosition;
+    /**
+     * `"always"` (default) shows the button. `"focus"` shows it only while it, or its open panel,
+     * has keyboard focus, and the whole time the panel is open; otherwise it's visually hidden but
+     * stays in the Tab order and the accessibility tree, like a skip link.
+     */
+    reveal?: "always" | "focus";
+}
+/** The `featureList` prop with its defaults filled in, or `null` when the list is off. */
+export declare function resolveFeatureList(value: boolean | FeatureListOptions | undefined): Required<FeatureListOptions> | null;
+/** A corner's edges, and the other corner on the same side (where the panel must stop). */
+export declare function cornerSides(position: ListPosition): {
+    vertical: "top" | "bottom";
+    horizontal: "left" | "right";
+    far: ListPosition;
+};

package/dist/view/list-placement.js

@@ -0,0 +1,13 @@
+/** The `featureList` prop with its defaults filled in, or `null` when the list is off. */
+export function resolveFeatureList(value) {
+    if (value === false)
+        return null;
+    const options = value === true || value === undefined ? {} : value;
+    return { position: options.position ?? "top-left", reveal: options.reveal ?? "always" };
+}
+/** A corner's edges, and the other corner on the same side (where the panel must stop). */
+export function cornerSides(position) {
+    const [vertical, horizontal] = position.split("-");
+    const far = `${vertical === "top" ? "bottom" : "top"}-${horizontal}`;
+    return { vertical, horizontal, far };
+}

package/package.json

@@ -1,6 +1,104 @@
 {
-  "name": "@sjvair/map-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@sjvair/map-sdk",
+	"description": "Svelte 5 map components for SJVAir air-quality data",
+	"version": "0.1.0-beta.2",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/SJVAir/map-sdk"
+	},
+	"type": "module",
+	"engines": {
+		"node": ">=26"
+	},
+	"scripts": {
+		"dev": "vite dev",
+		"build": "svelte-package -i src/lib -o dist",
+		"prepack": "npm run build",
+		"check": "svelte-check --tsconfig ./tsconfig.json",
+		"lint": "prettier --check . && eslint .",
+		"format": "prettier --write .",
+		"test": "vitest run",
+		"test:unit": "vitest run --project unit",
+		"test:client": "vitest run --project client",
+		"test:browser": "vitest run --project browser",
+		"test:bundle": "npm run build && node scripts/check-bundle.mjs",
+		"test:licenses": "npm run build && node scripts/check-licenses.mjs",
+		"test:e2e": "playwright test"
+	},
+	"files": [
+		"dist"
+	],
+	"sideEffects": [
+		"**/*.css"
+	],
+	"svelte": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"svelte": "./dist/index.js",
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./stores": {
+			"svelte": "./dist/stores/index.js",
+			"types": "./dist/stores/index.d.ts",
+			"default": "./dist/stores/index.js"
+		},
+		"./data": {
+			"svelte": "./dist/data/index.js",
+			"types": "./dist/data/index.d.ts",
+			"default": "./dist/data/index.js"
+		},
+		"./messages/en.json": {
+			"default": "./dist/data/messages/en.json"
+		},
+		"./theme.css": {
+			"default": "./dist/theme.css"
+		}
+	},
+	"peerDependencies": {
+		"@sjvair/sdk": "npm:@jsr/sjvair__sdk@^5.0.0-beta.2",
+		"svelte": "^5.57.0"
+	},
+	"dependencies": {
+		"@maptiler/sdk": "~4.2.0",
+		"@turf/clusters-dbscan": "^7.4.0",
+		"@turf/helpers": "^7.4.0",
+		"@types/geojson": "^7946.0.16",
+		"color2k": "^2.0.4",
+		"esm-env": "^1.2.2"
+	},
+	"devDependencies": {
+		"@axe-core/playwright": "^4.14.0",
+		"@eslint/compat": "^2.1.1",
+		"@eslint/js": "^10.0.1",
+		"@maplibre/maplibre-gl-style-spec": "^24.10.0",
+		"@playwright/test": "^1.64.1",
+		"@sjvair/sdk": "npm:@jsr/sjvair__sdk@5.0.0-beta.3",
+		"@sveltejs/package": "^2.5.8",
+		"@sveltejs/vite-plugin-svelte": "^7.3.0",
+		"@tailwindcss/vite": "^4.3.3",
+		"@types/node": "^26.6.0",
+		"@vitest/browser-playwright": "^5.0.5",
+		"axe-core": "^4.14.0",
+		"eslint": "^10.10.0",
+		"eslint-config-prettier": "^10.1.8",
+		"eslint-plugin-svelte": "^3.23.0",
+		"globals": "^17.12.0",
+		"prettier": "^3.9.6",
+		"prettier-plugin-svelte": "^4.1.1",
+		"prettier-plugin-tailwindcss": "^0.8.1",
+		"svelte": "^5.57.0",
+		"svelte-check": "^4.7.6",
+		"tailwindcss": "^4.3.3",
+		"typescript": "^6.0.3",
+		"typescript-eslint": "^8.70.0",
+		"vite": "^8.3.0",
+		"vitest": "^5.0.3",
+		"vitest-browser-svelte": "^3.1.0"
+	},
+	"keywords": [
+		"svelte"
+	]
+}