feat(geolens): add a Sample server dropdown to the panel

Trying the plugin previously meant already knowing a GeoLens URL. The panel now
offers the two public deployments — datasets.geolibre.app and
demo.getgeolens.com — above the URL field. Picking one fills the field and
connects (that is the whole intent of the choice; leaving Connect to a second
click would only add a step), then resets to the placeholder, because the URL
field stays the source of truth and the user can edit it afterwards.

Also makes a blocked request legible. demo.getgeolens.com serves its catalog to
curl but sends no `Access-Control-Allow-Origin` at all, so no browser can reach
it — where datasets.geolibre.app allowlists the requesting origin and works.
`fetch` reports that as a bare TypeError ("Failed to fetch") with no detail by
design, which read as "GeoLibre is broken" rather than "this server does not
allow browser access". Every failure this module raises itself is a plain
Error, so the constructor cleanly separates the two, and a transport failure
now names the host and says the server refused a cross-origin request.

Verified in the browser, light and dark: the dropdown lists both entries, the
GeoLibre catalog loads (22 datasets), and the demo entry shows the CORS message
instead of a bare fetch error.

Author: giswqs

packages/plugins/src/index.ts

@@ -363,10 +363,12 @@ export {
   DEFAULT_GEOLENS_FEATURE_LIMIT,
   GEOLENS_FEATURES_SOURCE_KIND,
   GEOLENS_PLUGIN_ID,
+  GEOLENS_SAMPLE_SERVERS,
   maplibreGeoLensPlugin,
   normalizeGeoLensFeatureLimit,
   setGeoLensLabels,
   type GeoLensLabels,
+  type GeoLensSampleServer,
 } from "./plugins/maplibre-geolens";
 export {
   buildListObjectsUrl,

packages/plugins/src/plugins/maplibre-geolens.ts

@@ -59,6 +59,25 @@ export const GEOLENS_PLUGIN_ID = "maplibre-gl-geolens";
  */
 export const GEOLENS_FEATURES_SOURCE_KIND = "geolens-features";
 
+/** One entry in the sample-server dropdown. */
+export interface GeoLensSampleServer {
+  /** Shown in the dropdown; the URL is the title text. */
+  label: string;
+  baseUrl: string;
+}
+
+/**
+ * Public GeoLens deployments offered in the panel, so the plugin can be tried
+ * without hunting for a server URL. Both are open catalogs that need no key.
+ *
+ * The labels are the deployments' own names rather than translatable strings:
+ * they identify a specific server, the way a bookmark does.
+ */
+export const GEOLENS_SAMPLE_SERVERS: readonly GeoLensSampleServer[] = [
+  { label: "GeoLibre datasets", baseUrl: "https://datasets.geolibre.app" },
+  { label: "GeoLens demo", baseUrl: "https://demo.getgeolens.com" },
+];
+
 /** Number of datasets requested per catalog search. */
 const SEARCH_LIMIT = 50;
 /** Default maximum number of editable GeoJSON features loaded per dataset. */
@@ -80,6 +99,8 @@ const TOKEN_REFRESH_MAX_RETRY_SECONDS = 300;
 
 export interface GeoLensLabels {
   hint: string;
+  sampleServer: string;
+  sampleServerTitle: string;
   baseUrlPlaceholder: string;
   apiKeyPlaceholder: string;
   connect: string;
@@ -89,6 +110,7 @@ export interface GeoLensLabels {
   searching: string;
   noResults: string;
   loadError: (message: string) => string;
+  blockedError: (host: string) => string;
   showing: (count: number) => string;
   vectorBadge: string;
   rasterBadge: string;
@@ -125,6 +147,8 @@ export interface GeoLensLabels {
 
 export const DEFAULT_GEOLENS_LABELS: GeoLensLabels = {
   hint: "Connect to a GeoLens server to browse and add its catalog datasets.",
+  sampleServer: "Sample server…",
+  sampleServerTitle: "Connect to a public GeoLens deployment",
   baseUrlPlaceholder: "GeoLens URL, e.g. https://datasets.geolibre.app",
   apiKeyPlaceholder: "API key (optional, for private data)",
   connect: "Connect",
@@ -134,6 +158,9 @@ export const DEFAULT_GEOLENS_LABELS: GeoLensLabels = {
   searching: "Searching…",
   noResults: "No matching datasets.",
   loadError: (message) => `Could not reach GeoLens: ${message}`,
+  blockedError: (host) =>
+    `Could not reach ${host}. The server refused a cross-origin request from ` +
+    `GeoLibre — its administrator has to allow this origin (CORS).`,
   showing: (count) => `${count} dataset${count === 1 ? "" : "s"}.`,
   vectorBadge: "vector",
   rasterBadge: "raster",
@@ -299,6 +326,32 @@ function messageOf(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+/**
+ * Whether a failure was the request never reaching the server at all.
+ *
+ * `fetch` rejects with a bare `TypeError` ("Failed to fetch") when the browser
+ * blocks the request — a CORS policy, a DNS failure, being offline — and gives
+ * the page no detail beyond that, by design. Every failure this module raises
+ * itself is a plain `Error`, so the constructor is a reliable discriminator.
+ *
+ * It matters because CORS is the likeliest cause and the least guessable: a
+ * GeoLens deployment that serves its catalog happily to `curl` is unreachable
+ * from a browser unless it sends `Access-Control-Allow-Origin` for the app's
+ * origin, and `demo.getgeolens.com` currently sends none at all.
+ */
+function isTransportFailure(error: unknown): boolean {
+  return error instanceof TypeError;
+}
+
+/** The host of a base URL, for an error message; falls back to the whole URL. */
+function hostOf(baseUrl: string): string {
+  try {
+    return new URL(baseUrl).host;
+  } catch {
+    return baseUrl;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Layer creation + tile-token lifecycle.
 // ---------------------------------------------------------------------------
@@ -920,6 +973,22 @@ function buildPanel(
   featureLimitLabel.append(featureLimitInput);
   settingsPanel.append(featureLimitLabel, el("div", CSS.hint, labels.featureLimitHelp));
 
+  // A shortcut to the public deployments. It fills the URL field and connects,
+  // rather than only filling it: picking a sample server is the whole intent, so
+  // leaving the user to press Connect afterwards would just be a second click.
+  const sampleSelect = el("select", CSS.input) as HTMLSelectElement;
+  sampleSelect.title = labels.sampleServerTitle;
+  sampleSelect.setAttribute("aria-label", labels.sampleServerTitle);
+  const samplePlaceholder = el("option", "", labels.sampleServer);
+  samplePlaceholder.value = "";
+  sampleSelect.append(samplePlaceholder);
+  for (const server of GEOLENS_SAMPLE_SERVERS) {
+    const option = el("option", "", server.label);
+    option.value = server.baseUrl;
+    option.title = server.baseUrl;
+    sampleSelect.append(option);
+  }
+
   const baseUrlInput = el("input", CSS.input) as HTMLInputElement;
   baseUrlInput.placeholder = labels.baseUrlPlaceholder;
   baseUrlInput.autocomplete = "off";
@@ -953,6 +1022,7 @@ function buildPanel(
   panel.append(
     hintRow,
     settingsPanel,
+    sampleSelect,
     baseUrlInput,
     apiKeyInput,
     connectRow,
@@ -999,7 +1069,11 @@ function buildPanel(
     } catch (error) {
       if (isAbort(error) || generation !== state.generation) return false;
       status.textContent = "";
-      showError(labels.loadError(messageOf(error)));
+      showError(
+        isTransportFailure(error)
+          ? labels.blockedError(hostOf(state.client?.baseUrl ?? ""))
+          : labels.loadError(messageOf(error)),
+      );
       return false;
     }
   };
@@ -1284,6 +1358,15 @@ function buildPanel(
   };
 
   connectButton.addEventListener("click", () => void connect());
+  sampleSelect.addEventListener("change", () => {
+    const baseUrl = sampleSelect.value;
+    // Reset to the placeholder: the URL field is the source of truth (the user
+    // can edit it afterwards), so a stuck selection would soon be a lie.
+    sampleSelect.value = "";
+    if (!baseUrl) return;
+    baseUrlInput.value = baseUrl;
+    void connect();
+  });
   settingsButton.addEventListener("click", () => {
     const open = settingsPanel.style.display !== "flex";
     settingsPanel.style.display = open ? "flex" : "none";

tests/geolens-editing.test.ts

@@ -2,13 +2,15 @@ import assert from "node:assert/strict";
 import { beforeEach, describe, it } from "node:test";
 import { useAppStore } from "@geolibre/core";
 import type { FeatureCollection } from "geojson";
-import type {
-  GeoLensFetch,
-  GeoLensHttpResponse,
+import {
+  normalizeBaseUrl,
+  type GeoLensFetch,
+  type GeoLensHttpResponse,
 } from "../packages/plugins/src/plugins/geolens-api";
 import {
   clearEditSessions,
   GEOLENS_FEATURES_SOURCE_KIND,
+  GEOLENS_SAMPLE_SERVERS,
   pendingCountsFor,
   saveLayerEdits,
   type GeoLensEditableLayer,
@@ -228,3 +230,25 @@ describe("saveLayerEdits", () => {
     );
   });
 });
+
+describe("GEOLENS_SAMPLE_SERVERS", () => {
+  it("offers both public deployments as ready-to-use https URLs", () => {
+    assert.deepEqual(
+      GEOLENS_SAMPLE_SERVERS.map((s) => s.baseUrl),
+      ["https://datasets.geolibre.app", "https://demo.getgeolens.com"],
+    );
+  });
+
+  it("lists each server once, labelled, and already normalized", () => {
+    // normalizeBaseUrl runs on whatever reaches the URL field, so a sample that
+    // is not already in canonical form would connect to a different string than
+    // the one shown — and a trailing slash would double up in every path join.
+    const seen = new Set<string>();
+    for (const server of GEOLENS_SAMPLE_SERVERS) {
+      assert.ok(server.label.trim().length > 0, "sample server needs a label");
+      assert.equal(server.baseUrl, normalizeBaseUrl(server.baseUrl));
+      assert.equal(seen.has(server.baseUrl), false, `duplicate ${server.baseUrl}`);
+      seen.add(server.baseUrl);
+    }
+  });
+});