@tellegen/svelte 0.2.0 → 0.4.0

package/dist/TellegenMap.svelte.d.ts

@@ -1,4 +1,9 @@
 import 'maplibre-gl/dist/maplibre-gl.css';
+import type { Layer } from '@deck.gl/core';
+import type { MapLibreOverlay } from '@deck.gl/maplibre';
+import type { Map as MapLibreMap } from 'maplibre-gl';
+import { type BasemapFallbackReason, type BasemapStyle, type MapProjection, type MapTheme } from './basemap.js';
+import { type CameraSnapshot } from './state.svelte.js';
 type $$ComponentProps = {
     onbusclick: (caseId: string, busId: number) => void;
     onlocalbusclick: (caseId: string, busId: number) => void;
@@ -8,6 +13,46 @@ type $$ComponentProps = {
     onmultiedgeclick?: (caseId: string, edgeId: string) => void;
     onplacecase: (lon: number, lat: number) => void;
     onmapclick: () => void;
+    /** Primary basemap: a style URL or inline style. Default: the CARTO style
+     * for `theme` when `cartoApiKey` is set, else the OpenFreeMap style.
+     * Changing it (or `fallbackMapStyle`, `theme`, `hideBasemapLabels`,
+     * `cartoApiKey`, `attribution`) rebuilds the map in place and keeps the
+     * camera. */
+    mapStyle?: BasemapStyle;
+    /** Basemap used when the primary cannot be shown; `null` disables the
+     * switch. Default: whichever of the CARTO and OpenFreeMap styles is not
+     * the default primary. */
+    fallbackMapStyle?: BasemapStyle | null;
+    /** Picks the default basemaps and the overlay palette (bus outlines,
+     * hover highlight, unsolved grey). */
+    theme?: MapTheme;
+    /** Re-applied after every `style.load`, so a basemap switch keeps it. */
+    projection?: MapProjection;
+    /** Camera for the first paint; read once per mount. */
+    initialCamera?: CameraSnapshot;
+    /** Hide the basemap's `symbol` layers after every `style.load`. */
+    hideBasemapLabels?: boolean;
+    /** CARTO basemap key (free for non-commercial use from
+     * carto.com/basemaps/apikey; restrict it to your hosts). With one, the
+     * CARTO style leads and OpenFreeMap is the fallback; without one, the
+     * order flips. Trimmed; a blank key counts as none. */
+    cartoApiKey?: string;
+    /** deck.gl layers drawn after tellegen's own, in the same overlay. */
+    extraLayers?: Layer[];
+    /** Attribution control mode. There is no off switch: tile licences
+     * require the credit on screen. */
+    attribution?: 'compact' | 'full';
+    /** Called once the map and overlay exist, with an optional cleanup. It
+     * fires again after a context-loss or basemap remount, after the previous
+     * cleanup ran. */
+    onMapReady?: (map: MapLibreMap, overlay: MapLibreOverlay) => void | (() => void);
+    /** The primary basemap failed and the fallback was requested. The
+     * reason's `from` and `to` name the providers (`'carto'`,
+     * `'openfreemap'` or `'custom'`). */
+    onBasemapFallback?: (reason: BasemapFallbackReason) => void;
+    /** No basemap can be shown; the network layers still draw. The reason's
+     * `from` names the provider that failed last, and `to` is `null`. */
+    onBasemapError?: (reason: BasemapFallbackReason) => void;
 };
 declare const TellegenMap: import("svelte").Component<$$ComponentProps, {}, "">;
 type TellegenMap = ReturnType<typeof TellegenMap>;

package/dist/TellegenProvider.svelte

@@ -9,13 +9,24 @@
 	} from './context.svelte.js';
 	import { createController } from './controller.svelte.js';
 	import { createAppState } from './state.svelte.js';
+	import { PanelLayout, setPanelLayout } from './panels.svelte.js';
+	import { NoticeCenter, setNoticeCenter } from './notices.svelte.js';
 
 	interface Props extends TellegenUiOptions {
 		children?: Snippet;
 	}
 
-	let { apiBase, loadDefaultCases, docsHref, orgHref, orgLabel, showFooter, children }: Props =
-		$props();
+	let {
+		apiBase,
+		loadDefaultCases,
+		docsHref,
+		orgHref,
+		orgLabel,
+		showFooter,
+		theme,
+		cartoApiKey,
+		children
+	}: Props = $props();
 
 	const config = untrack(() =>
 		resolveTellegenUiConfig({
@@ -24,15 +35,40 @@
 			docsHref,
 			orgHref,
 			orgLabel,
-			showFooter
+			showFooter,
+			theme,
+			cartoApiKey
 		})
 	);
 	const app = createAppState();
-	const ctrl = createController(app, { apiBase: config.apiBase });
+	const ctrl = createController(app, {
+		apiBase: config.apiBase,
+		loadDefaultCases: config.loadDefaultCases
+	});
+	// A host that opens its own cases never calls load(), so the shell must not
+	// sit in its loading state waiting for a fetch that will not come.
+	if (!config.loadDefaultCases) ctrl.casesLoaded = true;
 
+	setPanelLayout(new PanelLayout());
+	setNoticeCenter(new NoticeCenter());
 	setUiConfig(config);
 	setAppState(app);
 	setController(ctrl);
+
+	// The dark tokens in styles.css hang off `:root[data-theme='dark']`. Set it
+	// only for dark, and only while mounted, so a light host is untouched. A
+	// server-rendered host that wants no light flash can also put the
+	// attribute in its app template.
+	$effect(() => {
+		if (config.theme !== 'dark') return;
+		const root = document.documentElement;
+		const previous = root.dataset.theme;
+		root.dataset.theme = 'dark';
+		return () => {
+			if (previous === undefined) delete root.dataset.theme;
+			else root.dataset.theme = previous;
+		};
+	});
 </script>
 
 {@render children?.()}

package/dist/TellegenShell.svelte

@@ -1,26 +1,32 @@
 <script lang="ts">
 	import { onMount } from 'svelte';
 	import AppFooter from './components/AppFooter.svelte';
+	import NotificationCenter from './components/NotificationCenter.svelte';
 	import AppHeader from './components/AppHeader.svelte';
-	import BusPicker from './components/BusPicker.svelte';
 	import ControlPanel from './components/ControlPanel.svelte';
 	import DropZone from './components/DropZone.svelte';
 	import PlacementCue from './components/PlacementCue.svelte';
 	import RestoreDefaultsButton from './components/RestoreDefaultsButton.svelte';
 	import SolveCard from './components/SolveCard.svelte';
+	import PanelHost from './components/PanelHost.svelte';
+	import ShellEnvironment from './components/ShellEnvironment.svelte';
 	import { getAppState, getController, getUiConfig } from './context.svelte.js';
 	import TellegenMap from './TellegenMap.svelte';
 
-	const FILE_DROP_QUERY = '(hover: hover) and (pointer: fine) and (min-width: 761px)';
-	const COMPACT_QUERY = '(max-width: 760px)';
-
 	const app = getAppState();
 	const ctrl = getController();
 	const config = getUiConfig();
 
 	let dragDepth = 0;
 
+	// ShellEnvironment drops the affordance when no fine pointer is attached;
+	// forget any drag that was in flight so the next one counts from zero.
 	$effect(() => {
+		if (!ctrl.showFileDropUi) dragDepth = 0;
+	});
+
+	$effect(() => {
+		if (app.studyView) return;
 		let hasDisplayMode = false;
 		for (const option of ctrl.displayOptions) {
 			if (option.mode === app.displayMode) {
@@ -29,50 +35,18 @@
 			}
 		}
 		if (ctrl.displayOptions.length > 0 && !hasDisplayMode) {
-			app.displayMode = 'lmp';
+			app.displayMode = 'price';
 		}
 	});
 
 	onMount(() => {
+		// The provider already marked the shell loaded when default cases are
+		// off, and load() itself is gated; this only frames whatever is there.
 		if (config.loadDefaultCases) {
 			if (!ctrl.casesLoaded) void ctrl.load();
 		} else {
-			ctrl.casesLoaded = true;
-			app.requestFrame('all');
+			void app.requestFrame('all');
 		}
-
-		const query = window.matchMedia(FILE_DROP_QUERY);
-		const syncFileDropUi = () => {
-			ctrl.showFileDropUi = query.matches;
-			if (!ctrl.showFileDropUi) {
-				dragDepth = 0;
-				app.dragOver = false;
-			}
-		};
-		syncFileDropUi();
-		query.addEventListener('change', syncFileDropUi);
-
-		const compact = window.matchMedia(COMPACT_QUERY);
-		const syncCompact = () => {
-			app.compactLayout = compact.matches;
-			if (!compact.matches) app.sheetInset = 0;
-		};
-		syncCompact();
-		compact.addEventListener('change', syncCompact);
-
-		// The sheet sizes its snaps against the viewport and the map caps how far
-		// it lifts the basemap chrome, so both read one measurement taken here.
-		const syncViewport = () => (app.viewportHeight = window.innerHeight);
-		syncViewport();
-		window.addEventListener('resize', syncViewport);
-		window.addEventListener('orientationchange', syncViewport);
-
-		return () => {
-			query.removeEventListener('change', syncFileDropUi);
-			compact.removeEventListener('change', syncCompact);
-			window.removeEventListener('resize', syncViewport);
-			window.removeEventListener('orientationchange', syncViewport);
-		};
 	});
 
 	function dragHasFiles(e: DragEvent): boolean {
@@ -116,6 +90,8 @@
 	ondrop={onDrop}
 />
 
+<ShellEnvironment />
+
 <main>
 	<TellegenMap
 		onbusclick={ctrl.selectBus}
@@ -126,18 +102,20 @@
 		onmultiedgeclick={ctrl.selectMultiEdge}
 		onplacecase={ctrl.placeCase}
 		onmapclick={ctrl.clearSelection}
+		theme={config.theme}
+		cartoApiKey={config.cartoApiKey || undefined}
 	/>
 
 	<AppHeader />
+	<PanelHost />
+	<NotificationCenter />
 	<ControlPanel />
 	<SolveCard />
-	<!-- ControlPanel mounts the lookup and the footer inline when compact. -->
-	{#if !app.compactLayout}
-		<BusPicker />
+	{#if !app.studyView}
+		<DropZone />
+		<PlacementCue />
+		<RestoreDefaultsButton />
 	{/if}
-	<DropZone />
-	<PlacementCue />
-	<RestoreDefaultsButton />
 	{#if config.showFooter && !app.compactLayout}
 		<AppFooter />
 	{/if}

package/dist/TellegenViewer.svelte

@@ -3,8 +3,16 @@
 	import TellegenShell from './TellegenShell.svelte';
 	import type { TellegenUiOptions } from './context.svelte.js';
 
-	let { apiBase, loadDefaultCases, docsHref, orgHref, orgLabel, showFooter }: TellegenUiOptions =
-		$props();
+	let {
+		apiBase,
+		loadDefaultCases,
+		docsHref,
+		orgHref,
+		orgLabel,
+		showFooter,
+		theme,
+		cartoApiKey
+	}: TellegenUiOptions = $props();
 </script>
 
 <TellegenProvider
@@ -14,6 +22,8 @@
 	{orgHref}
 	{orgLabel}
 	{showFooter}
+	{theme}
+	{cartoApiKey}
 >
 	<TellegenShell />
 </TellegenProvider>

package/dist/api.d.ts

@@ -2,15 +2,24 @@ import type { CaseSummary, DemandDeltas, Network, SensitivityColumn, Solution, S
 export type { BranchRatingDeltas, CaseSummary, DemandDeltas, Network, NetworkBranch, NetworkBus, SensitivityColumn, Solution, SolveIteration } from '@tellegen/engine';
 type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
 export interface TellegenApiClientOptions {
-    apiBase?: string;
+    /** Backend base path, default `/api`. `null` means no backend: the
+     * factory returns `null` instead of a client. */
+    apiBase?: string | null;
     fetch?: FetchLike;
     EventSource?: typeof EventSource;
 }
 export interface TellegenApiClient {
     getCases(): Promise<CaseSummary[]>;
     getNetwork(caseId: string): Promise<Network>;
-    getCaseNetworkJson(caseId: string, signal?: AbortSignal): Promise<string>;
+    getCaseModuleJson(caseId: string, signal?: AbortSignal): Promise<string>;
     getSolution(caseId: string): Promise<Solution>;
+    getSavedCase?(caseId: string): Promise<{
+        base_input: string;
+        input: string;
+        solution: string;
+        view: import('@tellegen/engine').StudyView;
+        display_solution: Solution;
+    }>;
     getSensitivity(caseId: string, bus: number, deltas?: DemandDeltas, signal?: AbortSignal): Promise<SensitivityColumn>;
     getBranchSensitivity(caseId: string, branch: number, deltas?: DemandDeltas, signal?: AbortSignal): Promise<SensitivityColumn>;
     /** Whether the server's compute endpoints (solve stream, sensitivities) are
@@ -40,4 +49,10 @@ export interface SolveStreamHandlers {
     onfail?: (message: string) => void;
     ondone?: () => void;
 }
-export declare function createApiClient(options?: TellegenApiClientOptions): TellegenApiClient;
+export declare function createApiClient(options: TellegenApiClientOptions & {
+    apiBase: null;
+}): null;
+export declare function createApiClient(options?: TellegenApiClientOptions & {
+    apiBase?: string;
+}): TellegenApiClient;
+export declare function createApiClient(options?: TellegenApiClientOptions): TellegenApiClient | null;

package/dist/api.js

@@ -72,16 +72,19 @@ async function getJson(fetchImpl, url, signal) {
     return res.json();
 }
 export function createApiClient(options = {}) {
+    if (options.apiBase === null)
+        return null;
     const apiBase = options.apiBase ?? '/api';
     const fetchImpl = options.fetch ?? defaultFetch();
     return {
         getCases: () => getJson(fetchImpl, apiPath(apiBase, '/cases')),
         getNetwork: (caseId) => getJson(fetchImpl, apiPath(apiBase, `/cases/${caseId}/network`)),
-        async getCaseNetworkJson(caseId, signal) {
+        async getCaseModuleJson(caseId, signal) {
             const url = apiPath(apiBase, `/cases/${caseId}/case`);
             const res = await checkedFetch(fetchImpl, url, signal);
             return res.text();
         },
+        getSavedCase: (caseId) => getJson(fetchImpl, apiPath(apiBase, `/cases/${caseId}/snapshot`)),
         getSolution: (caseId) => getJson(fetchImpl, apiPath(apiBase, `/cases/${caseId}/solution`)),
         getSensitivity(caseId, bus, deltas = {}, signal) {
             const d = encodeDeltas(deltas);
@@ -111,7 +114,10 @@ export function createApiClient(options = {}) {
                 finished = true;
                 es.close();
             };
-            es.addEventListener('solution', (e) => handlers.onsolution?.(JSON.parse(e.data)));
+            es.addEventListener('solution', (e) => {
+                const solution = JSON.parse(e.data);
+                handlers.onsolution?.(solution);
+            });
             es.addEventListener('sensitivity', (e) => handlers.onsensitivity?.(JSON.parse(e.data)));
             es.addEventListener('fail', (e) => {
                 finish();

package/dist/basemap.d.ts

@@ -0,0 +1,192 @@
+import type { StyleSpecification } from 'maplibre-gl';
+/** Basemap selection, fallback and tuning for `TellegenMap`.
+ *
+ * CARTO's vector styles sit quietly under a network overlay, and CARTO's
+ * basemap terms ask for an API key (free for non-commercial use, from
+ * carto.com/basemaps/apikey). With a key, the CARTO style leads and
+ * OpenFreeMap (no key, CORS open) is the fallback. Without one, OpenFreeMap
+ * leads and the keyless CARTO style is the fallback. Whenever an OpenFreeMap
+ * style renders, `openFreeMapEdits` tunes it towards CARTO's look. A host can
+ * replace either style with its own URL or inline `StyleSpecification`, or
+ * disable the fallback with `null`. */
+export type BasemapTheme = 'light' | 'dark';
+export type BasemapStyle = string | StyleSpecification;
+/** `TellegenMap`'s `theme` prop: the basemap theme, which also picks the
+ * overlay palette. */
+export type MapTheme = BasemapTheme;
+/** `TellegenMap`'s `projection` prop. MapLibre's globe falls back to
+ * Mercator at high zoom on its own. */
+export type MapProjection = 'mercator' | 'globe';
+/** Who serves a basemap style: one of the two default providers, or
+ * `'custom'` for a style the host supplied. */
+export type BasemapProvider = 'carto' | 'openfreemap' | 'custom';
+export interface BasemapSpec {
+    primary: BasemapStyle;
+    fallback: BasemapStyle | null;
+    /** Hide the style's `symbol` layers after every `style.load`. */
+    hideLabels: boolean;
+    /** Who serves `primary`. Absent counts as `'custom'`. */
+    primaryProvider?: BasemapProvider;
+    /** Who serves `fallback`, `null` with no fallback. Absent counts as
+     * `'custom'`. */
+    fallbackProvider?: BasemapProvider | null;
+}
+/** A `BasemapSpec` that names both providers, as `defaultBasemap` and
+ * `resolveBasemap` return it. A host words its credits and fallback notice
+ * from these instead of reading style URLs. */
+export interface ResolvedBasemap extends BasemapSpec {
+    primaryProvider: BasemapProvider;
+    fallbackProvider: BasemapProvider | null;
+}
+/** What `defaultBasemap` returns: one CARTO and one OpenFreeMap style URL,
+ * in the order the key decides. Never `'custom'`, and never without a
+ * fallback. */
+export interface DefaultBasemap extends ResolvedBasemap {
+    primary: string;
+    fallback: string;
+    primaryProvider: 'carto' | 'openfreemap';
+    fallbackProvider: 'carto' | 'openfreemap';
+}
+export declare const OPENFREEMAP_STYLES: {
+    readonly light: "https://tiles.openfreemap.org/styles/positron";
+    readonly dark: "https://tiles.openfreemap.org/styles/dark";
+};
+export declare const CARTO_STYLES: {
+    readonly light: "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json";
+    readonly 'light-nolabels': "https://basemaps.cartocdn.com/gl/positron-nolabels-gl-style/style.json";
+    readonly dark: "https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json";
+    readonly 'dark-nolabels': "https://basemaps.cartocdn.com/gl/dark-matter-nolabels-gl-style/style.json";
+};
+/** A CARTO key with surrounding whitespace removed, or `undefined` when
+ * nothing is left. A variable saved with a stray newline or space must not
+ * count as a key. */
+export declare function normalizeCartoApiKey(apiKey: string | undefined): string | undefined;
+/** A CARTO style URL with the optional API key appended as `key=`. A blank
+ * key appends nothing. */
+export declare function cartoStyleUrl(style: string, apiKey?: string): string;
+export interface DefaultBasemapOptions {
+    /** CARTO basemap key, sent as `key=`. With one, CARTO leads and
+     * OpenFreeMap is the fallback; without one, the order flips. The key is
+     * trimmed, and a blank one counts as none. Restrict the key to the hosts
+     * that serve your app. */
+    cartoApiKey?: string;
+    /** Default `true`: the CARTO style uses its `-nolabels` variant, and label
+     * layers are hidden on load whichever style renders. */
+    hideLabels?: boolean;
+}
+/** The default primary and fallback for a theme, ordered by whether a CARTO
+ * key is at hand. */
+export declare function defaultBasemap(theme: BasemapTheme, options?: DefaultBasemapOptions): DefaultBasemap;
+export interface ResolveBasemapInput {
+    /** Overrides the default primary. */
+    mapStyle?: BasemapStyle;
+    /** Overrides the default fallback; `null` disables the fallback. */
+    fallbackMapStyle?: BasemapStyle | null;
+    theme: BasemapTheme;
+    hideBasemapLabels: boolean;
+    cartoApiKey?: string;
+}
+/** The spec `TellegenMap` renders from its props: explicit styles win, the
+ * theme fills in whatever is left, and `null` turns the fallback off. An
+ * explicit style is `'custom'`, whichever host serves it. */
+export declare function resolveBasemap(input: ResolveBasemapInput): ResolvedBasemap;
+/** Whether a style draws on OpenFreeMap's tiles, whichever URL loaded it. */
+export declare function isOpenFreeMapStyle(style: StyleSpecification): boolean;
+/** One change to a loaded style, applied through the map's own API. */
+export type StyleEdit = {
+    kind: 'zoom-range';
+    layer: string;
+    minzoom: number;
+    maxzoom: number;
+} | {
+    kind: 'paint';
+    layer: string;
+    property: 'fill-color' | 'line-color';
+    value: string;
+};
+/** Edits that let an OpenFreeMap style sit under a network overlay the way
+ * CARTO's styles do.
+ *
+ * - Road lines (`transportation`) start at z8.
+ * - In the dark theme, water and waterways take Dark Matter's colours, and
+ *   plain land fills (`landuse`, `landcover`, `park`) take the style's
+ *   background colour, so the water stands out against one tone of land.
+ *
+ * Layers are matched by `source-layer`, not by id, so the edits still apply
+ * when OpenFreeMap renames its layers. */
+export declare function openFreeMapEdits(style: StyleSpecification, theme: BasemapTheme): StyleEdit[];
+/** The providers a fallback event concerns. */
+export interface BasemapSwitch {
+    /** The provider whose style failed. */
+    from: BasemapProvider;
+    /** The provider switched to; `null` when no basemap is left to show. */
+    to: BasemapProvider | null;
+}
+type BasemapFailure = {
+    kind: 'style-load';
+    message: string;
+    status?: number;
+} | {
+    kind: 'source-forbidden';
+    message: string;
+    status: number;
+    sourceId: string;
+} | {
+    kind: 'tiles-unavailable';
+    message: string;
+    sourceId: string;
+} | {
+    kind: 'webgl';
+    message: string;
+};
+export type BasemapFallbackReason = BasemapFailure & BasemapSwitch;
+/** The fields of a MapLibre `error` or `sourcedata` event the fallback reads. */
+export interface BasemapMapEvent {
+    error?: unknown;
+    sourceId?: string;
+    tile?: unknown;
+    dataType?: string;
+    isSourceLoaded?: boolean;
+}
+/** The slice of `maplibregl.Map` the fallback needs; a test drives a fake. */
+export interface BasemapMapLike {
+    on(type: string, listener: (event: BasemapMapEvent) => void): unknown;
+    off(type: string, listener: (event: BasemapMapEvent) => void): unknown;
+    setStyle(style: BasemapStyle, options?: {
+        diff?: boolean;
+    }): unknown;
+    /** MapLibre types this `boolean | void`; only `true` counts as loaded. */
+    isStyleLoaded(): boolean | void;
+}
+export interface BasemapFallbackHandlers {
+    /** The primary failed and the fallback style was requested. `from` is the
+     * spec's primary provider and `to` its fallback provider. */
+    onFallback?(reason: BasemapFallbackReason): void;
+    /** No basemap can be shown: the fallback failed too, none was configured,
+     * or WebGL is unavailable. `from` is the provider on screen, `to` is
+     * `null`. */
+    onFailure?(reason: BasemapFallbackReason): void;
+}
+export interface BasemapFallbackOptions {
+    /** Clock for the tile failure window; tests inject one. */
+    now?: () => number;
+}
+/** Watch a map's `error` stream and switch to `spec.fallback` when the
+ * primary basemap cannot be shown. Rules, in order:
+ *
+ * 1. an error with no `sourceId` before the first `style.load` is a style
+ *    fetch failure: switch to the fallback once;
+ * 2. a source or tile error with status 401, 403 or 429, or a message naming
+ *    an API key, forbidden or unauthorized access: switch;
+ * 3. more than six tile fetch failures within ten seconds while no tile of
+ *    any source has arrived: switch. A failure is a network error with no
+ *    status, or an HTTP 5xx answer;
+ * 4. a WebGL error: report failure, no style can help;
+ * 5. everything else is logged the way MapLibre logs an unhandled error,
+ *    because registering this listener silences that default.
+ *
+ * After the switch the same rules report `onFailure` instead of switching
+ * again, as they do when `spec.fallback` is `null`. Returns a detach
+ * function. */
+export declare function attachBasemapFallback(map: BasemapMapLike, spec: BasemapSpec, handlers?: BasemapFallbackHandlers, options?: BasemapFallbackOptions): () => void;
+export {};