queria 0.0.0 → 0.1.0

package/src/boot.ts

@@ -0,0 +1,141 @@
+import type { AsyncDuckDB, DuckDBBundles } from "@duckdb/duckdb-wasm";
+import { stripLiterals } from "./sql.js";
+
+/**
+ * Source put before the DuckDB worker script. It adds a Bearer token to the worker's XHRs, and only to
+ * the origins it was given. DuckDB WASM sends no headers of its own (neither CREATE SECRET nor
+ * EXTRA_HTTP_HEADERS reach the request in the browser), and keeping the token in a JS variable of the
+ * worker keeps it out of reach of SQL. It takes only { queriaAuth: { token, origins } } messages and
+ * does not pass them on to DuckDB.
+ */
+export const authPatch = `(() => {
+  let token = null;
+  let origins = [];
+  self.addEventListener("message", (event) => {
+    const auth = event.data && typeof event.data === "object" ? event.data.queriaAuth : undefined;
+    if (auth === undefined) return;
+    event.stopImmediatePropagation();
+    token = auth && typeof auth.token === "string" ? auth.token : null;
+    origins = auth && Array.isArray(auth.origins) ? auth.origins.map((o) => String(o) + "/") : [];
+  });
+  const open = XMLHttpRequest.prototype.open;
+  XMLHttpRequest.prototype.open = function (method, url, ...rest) {
+    open.call(this, method, url, ...rest);
+    if (token !== null && origins.some((o) => String(url).startsWith(o))) {
+      this.setRequestHeader("Authorization", "Bearer " + token);
+    }
+  };
+})();
+`;
+
+export const bundlesAt = (base: string): DuckDBBundles => ({
+  mvp: { mainModule: `${base}/duckdb-mvp.wasm`, mainWorker: `${base}/duckdb-browser-mvp.worker.js` },
+  eh: { mainModule: `${base}/duckdb-eh.wasm`, mainWorker: `${base}/duckdb-browser-eh.worker.js` },
+});
+
+const workers = new WeakMap<AsyncDuckDB, Worker>();
+const authOrigins = new WeakMap<AsyncDuckDB, Set<string>>();
+
+/**
+ * Send the token to these origins from now on, as well as to the origins given before: queries run
+ * concurrently, and one that is still reading must keep its origins. A null token sends none.
+ */
+export const setAuth = (db: AsyncDuckDB, token: string | null, origins: readonly string[]): void => {
+  const all = token === null ? new Set<string>() : new Set([...(authOrigins.get(db) ?? []), ...origins]);
+  authOrigins.set(db, all);
+  workers.get(db)?.postMessage({ queriaAuth: { token, origins: [...all] } });
+};
+
+const instantiate = async (bundles: DuckDBBundles): Promise<AsyncDuckDB> => {
+  const duckdb = await import("@duckdb/duckdb-wasm");
+  const bundle = await duckdb.selectBundle(bundles);
+  if (!bundle.mainWorker) throw new Error("The DuckDB bundle has no worker script");
+  // The worker lives on another origin, and a page with a strict-dynamic CSP blocks importScripts,
+  // so fetch the script and start it from a blob URL.
+  const res = await fetch(bundle.mainWorker);
+  if (!res.ok) throw new Error(`${bundle.mainWorker}: ${res.status}`);
+  const url = URL.createObjectURL(new Blob([authPatch, await res.text()], { type: "text/javascript" }));
+  try {
+    // A CSP without blob: in worker-src throws here, so this is inside the try that revokes the URL.
+    const worker = new Worker(url);
+    const db = new duckdb.AsyncDuckDB(new duckdb.VoidLogger(), worker);
+    try {
+      // Pages without cross-origin isolation cannot start threads.
+      await (bundle.pthreadWorker
+        ? db.instantiate(bundle.mainModule, bundle.pthreadWorker).catch(() => db.instantiate(bundle.mainModule))
+        : db.instantiate(bundle.mainModule));
+    } catch (e) {
+      await db.terminate().catch(() => undefined);
+      throw e;
+    }
+    workers.set(db, worker);
+    return db;
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+};
+
+/** Start DuckDB from the given WASM URL, and from jsDelivr when that fails. */
+export const boot = async (wasm: string): Promise<AsyncDuckDB> => {
+  const db = await instantiate(bundlesAt(wasm)).catch(async (e: unknown) => {
+    const { getJsDelivrBundles } = await import("@duckdb/duckdb-wasm");
+    return instantiate(getJsDelivrBundles()).catch((e2: unknown) => {
+      throw new AggregateError([e, e2], "DuckDB WASM could not be started");
+    });
+  });
+  try {
+    // Read Parquet by range instead of downloading whole files. Arrow returns DECIMAL as an unscaled
+    // integer, so let DuckDB convert it to DOUBLE.
+    await db.open({ path: ":memory:", filesystem: { forceFullHTTPReads: false }, query: { castDecimalToDouble: true } });
+    const conn = await db.connect();
+    await conn.query("INSTALL ducklake; LOAD ducklake").finally(() => conn.close());
+  } catch (e) {
+    await db.terminate().catch(() => undefined);
+    throw e;
+  }
+  return db;
+};
+
+// The spatial extension is large, so it is loaded only for SQL that needs it, and on the error
+// DuckDB gives for a missing spatial function.
+
+/** Whether the SQL calls an ST_* function outside string literals and comments. */
+export const needsSpatial = (sql: string): boolean => /\bST_\w+\s*\(/i.test(stripLiterals(sql));
+
+/** Whether the error comes from the spatial extension not being loaded. */
+export const isSpatialMissing = (message: string): boolean =>
+  /exists in the spatial extension/i.test(message) || /\b(function|type) with name (st_\w+|geometry)\b.*does not exist/i.test(message);
+
+const spatial = new WeakMap<AsyncDuckDB, Promise<void>>();
+const spatialLoaded = new WeakSet<AsyncDuckDB>();
+
+export const loadSpatial = (db: AsyncDuckDB): Promise<void> => {
+  const found = spatial.get(db);
+  if (found) return found;
+  const p = db
+    .connect()
+    .then((conn) => conn.query("INSTALL spatial; LOAD spatial").finally(() => conn.close()))
+    .then(() => {
+      spatialLoaded.add(db);
+    })
+    .catch((e: unknown) => {
+      spatial.delete(db);
+      throw e;
+    });
+  spatial.set(db, p);
+  return p;
+};
+
+/** Run fn, loading spatial first when the SQL needs it, and once more after a missing-spatial error. */
+export const withSpatial = async <T>(db: AsyncDuckDB, sql: string, fn: () => Promise<T>): Promise<T> => {
+  if (needsSpatial(sql)) await loadSpatial(db);
+  // Once spatial is loaded, running the SQL again gives the same error.
+  const loaded = spatialLoaded.has(db);
+  try {
+    return await fn();
+  } catch (e) {
+    if (loaded || !isSpatialMissing(String(e))) throw e;
+    await loadSpatial(db);
+    return fn();
+  }
+};

package/src/client.test.ts

@@ -0,0 +1,77 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { aliases, connect, dataPath, lookup, parseDatasets } from "./client.js";
+
+describe("aliases", () => {
+  it("uses the last part of each name as the alias", () => {
+    expect([...aliases(["queria/e_stat", "queria/jma"])]).toEqual([
+      ["e_stat", "queria/e_stat"],
+      ["jma", "queria/jma"],
+    ]);
+  });
+  it("takes explicit aliases", () => {
+    expect([...aliases({ a: "alice/e_stat", b: "bob/e_stat" })]).toEqual([
+      ["a", "alice/e_stat"],
+      ["b", "bob/e_stat"],
+    ]);
+  });
+  it("rejects short names", () => expect(() => aliases(["e_stat"])).toThrow("fully qualified"));
+  it("rejects two datasets with one alias", () => expect(() => aliases(["alice/e_stat", "bob/e_stat"])).toThrow("share an alias"));
+});
+
+describe("parseDatasets", () => {
+  it("reads names and alias=name pairs", () => {
+    expect(parseDatasets(" queria/e_stat, a=alice/x ")).toEqual({ e_stat: "queria/e_stat", a: "alice/x" });
+  });
+  it("rejects two datasets with one alias", () =>
+    expect(() => parseDatasets("alice/e_stat bob/e_stat")).toThrow("share an alias"));
+});
+
+describe("dataPath", () => {
+  it("drops the version and points next to the catalog", () => {
+    expect(dataPath("https://data.queria.io/d/k/ducklake.duckdb?v=1")).toBe("https://data.queria.io/d/k/ducklake.duckdb.files/");
+  });
+});
+
+describe("lookup", () => {
+  afterEach(() => vi.unstubAllGlobals());
+  it("reads the row by qualified name and ignores unknown fields", async () => {
+    const fetch = vi.fn(async () => Response.json({ qualified_name: "queria/e_stat", catalog_url: "u", extra: 1 }));
+    vi.stubGlobal("fetch", fetch);
+    expect((await lookup("https://api", "queria/e_stat")).catalog_url).toBe("u");
+    expect(fetch).toHaveBeenCalledWith("https://api/v1/datasets/queria/e_stat", undefined);
+  });
+  it("sends the token as Bearer", async () => {
+    const fetch = vi.fn(async () => Response.json({ qualified_name: "x/y", catalog_url: "u" }));
+    vi.stubGlobal("fetch", fetch);
+    await lookup("https://api", "x/y", "qd_t");
+    expect(fetch).toHaveBeenCalledWith("https://api/v1/datasets/x/y", { headers: { Authorization: "Bearer qd_t" } });
+  });
+  it("rejects a response without a catalog URL", async () => {
+    vi.stubGlobal("fetch", async () => Response.json({ dataset: { qualified_name: "x/y" } }));
+    await expect(lookup("https://api", "x/y")).rejects.toThrow("no catalog_url");
+  });
+  it("reports a missing dataset", async () => {
+    vi.stubGlobal("fetch", async () => new Response(null, { status: 404 }));
+    await expect(lookup("https://api", "x/y")).rejects.toThrow("x/y was not found");
+  });
+});
+
+describe("sources", () => {
+  afterEach(() => vi.unstubAllGlobals());
+  it("asks a token function for each lookup", async () => {
+    const fetch = vi.fn(async (url: string) => Response.json({ qualified_name: url.split("/v1/datasets/")[1], catalog_url: "u" }));
+    vi.stubGlobal("fetch", fetch);
+    const token = vi.fn(async () => "qd_fresh");
+    await connect({ datasets: ["x/a", "x/b"], apiUrl: "https://api", token }).sources();
+    expect(token).toHaveBeenCalledTimes(2);
+    expect(fetch).toHaveBeenCalledWith("https://api/v1/datasets/x/a", { headers: { Authorization: "Bearer qd_fresh" } });
+  });
+  it("returns every declared dataset without SQL, and only the referenced ones with SQL", async () => {
+    vi.stubGlobal("fetch", async (url: string) =>
+      Response.json({ qualified_name: url.split("/v1/datasets/")[1], catalog_url: "u" }),
+    );
+    const conn = connect({ datasets: ["queria/e_stat", "queria/jma"], apiUrl: "https://api" });
+    expect((await conn.sources()).map((d) => d.qualified_name)).toEqual(["queria/e_stat", "queria/jma"]);
+    expect((await conn.sources("SELECT * FROM jma.main.t")).map((d) => d.qualified_name)).toEqual(["queria/jma"]);
+  });
+});

package/src/client.ts

@@ -0,0 +1,247 @@
+import type { AsyncDuckDB } from "@duckdb/duckdb-wasm";
+import { boot, setAuth, withSpatial } from "./boot.js";
+import { datasetsIn, lit } from "./sql.js";
+
+/** A license of a dataset, as returned by the Queria API. */
+export type License = { id?: string; title?: string; url?: string };
+
+/** The part of a dataset row from the Queria API that the package uses. */
+export type Dataset = {
+  qualified_name: string;
+  title?: string;
+  page_url?: string;
+  licenses?: License[];
+  catalog_url: string;
+  versioned_catalog_url?: string;
+};
+
+/** Datasets to read, by fully qualified name. An array uses each name's last part as the SQL alias. */
+export type Declared = readonly string[] | Readonly<Record<string, string>>;
+
+export type ConnectOptions = {
+  datasets: Declared;
+  /** Base URL of the Queria API. */
+  apiUrl?: string;
+  /** Base URL of the DuckDB WASM bundles. jsDelivr is used when they cannot be loaded. */
+  wasmUrl?: string;
+  /**
+   * A data token (qd_...) for datasets that are not public, or a function that returns one. A function is
+   * called before each request, so it can return a fresh token. The token is sent to the API and to the
+   * hosts of the declared datasets. DuckDB is shared by the page, so use one token per page.
+   */
+  token?: string | (() => string | Promise<string>);
+};
+
+export type Connection = {
+  /** Run SQL and return rows as plain objects. Datasets the SQL references are attached on first use. */
+  sql: <T = Record<string, unknown>>(sql: string) => Promise<T[]>;
+  /**
+   * The declared datasets the SQL references, for showing their sources and licenses.
+   * Without SQL (rows computed elsewhere), every declared dataset.
+   */
+  sources: (sql?: string) => Promise<Dataset[]>;
+};
+
+const API = "https://api.queria.io";
+// Must match the @duckdb/duckdb-wasm version in package.json "dependencies".
+const WASM = "https://assets.queria.io/duckdb-wasm/1.33.1-dev57.0";
+
+const ALIAS = /^[a-z_][a-z0-9_]*$/;
+const QUALIFIED = /^[a-z0-9_-]+\/[a-z_][a-z0-9_]*$/i;
+
+/** Map each SQL alias to a fully qualified name, rejecting names the package cannot use. */
+export const aliases = (declared: Declared): Map<string, string> => {
+  const pairs: [string, string][] = Array.isArray(declared)
+    ? declared.map((q: string) => [q.split("/")[1] ?? "", q])
+    : Object.entries(declared);
+  pairs.forEach(([alias, q]) => {
+    if (!QUALIFIED.test(q)) throw new Error(`"${q}" is not a fully qualified dataset name such as "queria/e_stat"`);
+    if (!ALIAS.test(alias)) throw new Error(`"${alias}" cannot be used as an SQL alias`);
+  });
+  const map = new Map(pairs);
+  if (map.size !== pairs.length) throw new Error("Two datasets share an alias. Declare them as { alias: name }");
+  return map;
+};
+
+/** Look up a dataset row. The API returns the catalog URL; the package never builds it. */
+export const lookup = async (api: string, qualified: string, token: string | null = null): Promise<Dataset> => {
+  const res = await fetch(`${api}/v1/datasets/${qualified}`, bearer(token));
+  if (res.status === 404) throw new Error(`Dataset ${qualified} was not found`);
+  if (!res.ok) throw new Error(`${api}/v1/datasets/${qualified}: ${res.status}`);
+  const d = (await res.json()) as Partial<Dataset> | null;
+  if (typeof d?.catalog_url !== "string" || typeof d.qualified_name !== "string")
+    throw new Error(`${api}/v1/datasets/${qualified}: the response has no catalog_url or qualified_name`);
+  return d as Dataset;
+};
+
+const bearer = (token: string | null): RequestInit | undefined =>
+  token === null ? undefined : { headers: { Authorization: `Bearer ${token}` } };
+
+/** Parquet files sit next to the catalog: .../ducklake.duckdb → .../ducklake.duckdb.files/ */
+export const dataPath = (catalogUrl: string): string => `${catalogUrl.split("?")[0]}.files/`;
+
+/**
+ * Attach one dataset. The catalog is fetched in a single GET: letting DuckDB read it by range
+ * costs hundreds of 16 KiB round trips for large catalogs. Data files are still read by range.
+ */
+const attach = async (db: AsyncDuckDB, alias: string, d: Dataset, token: string | null): Promise<void> => {
+  const url = d.versioned_catalog_url ?? d.catalog_url;
+  const res = await fetch(url, bearer(token));
+  if (!res.ok) throw new Error(`${url}: ${res.status}`);
+  // One file per alias: an alias is attached once per DuckDB, while one dataset can be attached
+  // under two aliases, and DuckDB refuses to attach one path twice.
+  const file = `${alias}.duckdb`;
+  await db.registerFileBuffer(file, new Uint8Array(await res.arrayBuffer()));
+  const conn = await db.connect();
+  try {
+    await conn.query(
+      `ATTACH ${lit(`ducklake:${file}`)} AS ${alias} (READ_ONLY, DATA_PATH ${lit(dataPath(d.catalog_url))}, OVERRIDE_DATA_PATH true)`,
+    );
+  } finally {
+    await conn.close();
+  }
+};
+
+/** Convert Arrow values to plain JS: lists to arrays, structs to objects, BIGINT and HUGEINT to number. */
+export const plain = (v: unknown): unknown => {
+  if (typeof v === "bigint") return Number(v);
+  if (v === null || typeof v !== "object") return v;
+  if (Array.isArray(v)) return v.map(plain);
+  // 128-bit integers come as Arrow big numbers (typed arrays); BLOBs stay Uint8Array.
+  if (ArrayBuffer.isView(v)) return Symbol.for("isArrowBigNum") in v ? Number(String(v)) : v;
+  if ("toJSON" in v && typeof v.toJSON === "function") return plain(v.toJSON());
+  return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, plain(x)]));
+};
+
+/** One DuckDB per WASM URL, shared by every connection on the page. Aliases are global within it. */
+type Engine = {
+  db: () => Promise<AsyncDuckDB>;
+  /** Terminate DuckDB if it was started. Never starts it. */
+  stop: () => Promise<void>;
+  attached: Map<string, { qualified: string; done: Promise<void> }>;
+};
+const engines = new Map<string, Engine>();
+
+const engine = (wasm: string): Engine => {
+  const found = engines.get(wasm);
+  if (found) return found;
+  let db: Promise<AsyncDuckDB> | null = null;
+  const e: Engine = {
+    db: async () => {
+      const p = (db ??= boot(wasm).catch((err: unknown) => {
+        if (db === p) {
+          db = null;
+          e.attached.clear();
+        }
+        throw err;
+      }));
+      const d = await p;
+      // stop() ran while DuckDB was starting; it terminates this one.
+      if (db !== p) throw new Error("DuckDB was stopped");
+      return d;
+    },
+    stop: async () => {
+      const started = db;
+      db = null;
+      e.attached.clear();
+      // A failed start was already reported to the query that started it.
+      await started?.then((d) => d.terminate(), () => undefined);
+    },
+    attached: new Map(),
+  };
+  engines.set(wasm, e);
+  return e;
+};
+
+/** Stop every DuckDB the package started. A later query starts it again. */
+export const closeAll = async (): Promise<void> => {
+  const all = [...engines.values()];
+  engines.clear();
+  await Promise.all(all.map((e) => e.stop()));
+};
+
+/**
+ * Connect to Queria datasets. Declare every dataset the SQL reads by its fully qualified name;
+ * the SQL refers to it by alias, such as e_stat.census.population. Short names are never resolved.
+ */
+export const connect = ({ datasets, apiUrl = API, wasmUrl = WASM, token }: ConnectOptions): Connection => {
+  const declared = aliases(datasets);
+  const auth = async (): Promise<string | null> => (token === undefined ? null : typeof token === "string" ? token : await token());
+  const rows = new Map<string, Promise<Dataset>>();
+  /** The dataset row, looked up once. Pass the token when the caller has already asked for it. */
+  const row = (qualified: string, token?: Promise<string | null>): Promise<Dataset> => {
+    const p =
+      rows.get(qualified) ??
+      (token ?? auth())
+        .then((t) => lookup(apiUrl, qualified, t))
+        .catch((e: unknown) => {
+          rows.delete(qualified);
+          throw e;
+        });
+    rows.set(qualified, p);
+    return p;
+  };
+
+  /** Declared aliases the SQL references. Other three-part names are left to DuckDB (alias.column.field). */
+  const used = (sql: string): string[] => datasetsIn(sql).filter((a) => declared.has(a));
+
+  const ensure = async (e: Engine, db: AsyncDuckDB, alias: string, t: string | null): Promise<void> => {
+    const qualified = declared.get(alias) ?? "";
+    const prev = e.attached.get(alias);
+    if (prev && prev.qualified !== qualified)
+      throw new Error(`Alias ${alias} is already used for ${prev.qualified} on this page. Declare ${qualified} with another alias`);
+    const done =
+      prev?.done ??
+      row(qualified, Promise.resolve(t))
+        .then((d) => attach(db, alias, d, t))
+        .catch((err: unknown) => {
+          e.attached.delete(alias);
+          throw err;
+        });
+    e.attached.set(alias, { qualified, done });
+    await done;
+  };
+
+  const sql = async <T,>(query: string): Promise<T[]> => {
+    const eng = engine(wasmUrl);
+    const aliasesUsed = used(query);
+    // Look up the datasets while DuckDB starts. The token function is called once per query.
+    const token = auth();
+    const [db, t, ds] = await Promise.all([eng.db(), token, Promise.all(aliasesUsed.map((a) => row(declared.get(a) ?? "", token)))]);
+    // Data files are read by the DuckDB worker, so hand it the token and the hosts it may go to.
+    if (t !== null) setAuth(db, t, [...new Set(ds.map((d) => new URL(d.catalog_url).origin))]);
+    await Promise.all(aliasesUsed.map((a) => ensure(eng, db, a, t)));
+    const run = async (): Promise<T[]> => {
+      const conn = await db.connect();
+      try {
+        return (await conn.query(query)).toArray().map((r) => plain(r) as T);
+      } finally {
+        await conn.close();
+      }
+    };
+    try {
+      return await withSpatial(db, query, run);
+    } catch (e) {
+      const undeclared = datasetsIn(query).filter((a) => !declared.has(a));
+      if (undeclared.length === 0) throw e;
+      throw new Error(`${String(e)}\nIf ${undeclared.join(", ")} is a dataset, declare it in connect({ datasets })`, { cause: e });
+    }
+  };
+
+  const sources = (query?: string): Promise<Dataset[]> =>
+    Promise.all((query === undefined ? [...declared.keys()] : used(query)).map((a) => row(declared.get(a) ?? "")));
+
+  return { sql, sources };
+};
+
+/** Read a list of datasets from an HTML attribute: "queria/e_stat queria/jma" or "a=alice/x b=bob/x". */
+export const parseDatasets = (attr: string): Declared => {
+  const pairs = attr
+    .split(/[\s,]+/)
+    .filter(Boolean)
+    .map((w) => (w.includes("=") ? w.split("=", 2) : [w.split("/")[1] ?? "", w]));
+  // Object.fromEntries would keep only the last of two datasets with one alias.
+  if (new Set(pairs.map(([alias]) => alias)).size !== pairs.length)
+    throw new Error("Two datasets share an alias. Declare them as alias=name");
+  return Object.fromEntries(pairs);
+};

package/src/elements/define.ts

@@ -0,0 +1,4 @@
+// Importing this module registers the custom elements.
+import { defineElements } from "./index.js";
+
+defineElements();

package/src/elements/index.ts

@@ -0,0 +1,151 @@
+import { connect, parseDatasets } from "../client.js";
+import { attributionHtml } from "../render/attribution.js";
+import { renderChart } from "../render/chart.js";
+import { renderMap } from "../render/data-map.js";
+import { esc } from "../render/escape.js";
+import { poweredByHtml } from "../render/poweredBy.js";
+
+/**
+ * <queria-chart datasets="queria/e_stat" sql="..." spec='{"mark": "line", ...}'>
+ * Runs the SQL and draws the rows with the Vega-Lite spec, followed by the sources of the datasets.
+ * Instead of sql, `rows` takes the rows as JSON, for pages that run the SQL at build time. Declare the datasets the
+ * rows came from in `datasets` so their sources are shown.
+ * `api-url` replaces the Queria API, for example with a staging host.
+ */
+export class QueriaChart extends HTMLElement {
+  static observedAttributes = ["datasets", "sql", "spec", "rows", "api-url"];
+  #run = 0;
+  #pending = false;
+  #finalize: (() => void) | null = null;
+
+  connectedCallback() {
+    this.#schedule();
+  }
+
+  attributeChangedCallback() {
+    if (this.isConnected) this.#schedule();
+  }
+
+  disconnectedCallback() {
+    this.#run++;
+    this.#clear();
+  }
+
+  /** Draw once per task: an upgrade calls attributeChangedCallback for every attribute, then connectedCallback. */
+  #schedule() {
+    if (this.#pending) return;
+    this.#pending = true;
+    queueMicrotask(() => {
+      this.#pending = false;
+      if (this.isConnected) this.#draw();
+    });
+  }
+
+  #clear() {
+    this.#finalize?.();
+    this.#finalize = null;
+  }
+
+  async #draw() {
+    const [datasets, sql, spec, rows] = ["datasets", "sql", "spec", "rows"].map((a) => this.getAttribute(a));
+    if (!spec || (!rows && !sql)) return;
+    const run = ++this.#run;
+    this.#clear();
+    this.innerHTML = '<p class="queria-note">Loading…</p>';
+    try {
+      const conn = connect({ datasets: parseDatasets(datasets ?? ""), apiUrl: this.getAttribute("api-url") ?? undefined });
+      // With rows, the page ran the SQL itself; show every declared dataset as a source.
+      const [data, sources] = await Promise.all([sql ? conn.sql(sql) : JSON.parse(rows ?? "[]"), conn.sources(sql ?? undefined)]);
+      if (run !== this.#run) return;
+      this.innerHTML = `<div></div>${attributionHtml(sources)}`;
+      const { finalize } = await renderChart(this.firstElementChild as HTMLElement, JSON.parse(spec), data);
+      if (run === this.#run) this.#finalize = finalize;
+      else finalize();
+    } catch (e) {
+      if (run === this.#run) this.innerHTML = `<p class="queria-note">${esc(String(e))}</p>`;
+    }
+  }
+}
+
+/**
+ * <queria-map datasets="queria/e_stat" sql="..." layer='{"area": "city", "code": "lg_code", "color": "population"}'>
+ * Runs the SQL and puts the rows on a map by area code or by lng/lat, followed by the sources of the datasets.
+ * `rows`, `api-url` work as on <queria-chart>. `theme` is light or dark; `map-style` takes another MapLibre style URL.
+ * Include maplibre-gl's CSS in the page. The map height is the CSS variable --queria-map-height (400px by default).
+ */
+export class QueriaMap extends HTMLElement {
+  static observedAttributes = ["datasets", "sql", "layer", "rows", "api-url", "theme", "map-style"];
+  #run = 0;
+  #pending = false;
+  #finalize: (() => void) | null = null;
+
+  connectedCallback() {
+    this.#schedule();
+  }
+
+  attributeChangedCallback() {
+    if (this.isConnected) this.#schedule();
+  }
+
+  disconnectedCallback() {
+    this.#run++;
+    this.#clear();
+  }
+
+  #schedule() {
+    if (this.#pending) return;
+    this.#pending = true;
+    queueMicrotask(() => {
+      this.#pending = false;
+      if (this.isConnected) this.#draw();
+    });
+  }
+
+  #clear() {
+    this.#finalize?.();
+    this.#finalize = null;
+  }
+
+  async #draw() {
+    const [datasets, sql, layer, rows, theme, style] = ["datasets", "sql", "layer", "rows", "theme", "map-style"].map((a) => this.getAttribute(a));
+    if (!layer || (!rows && !sql)) return;
+    const run = ++this.#run;
+    this.#clear();
+    this.innerHTML = '<p class="queria-note">Loading…</p>';
+    try {
+      const conn = connect({ datasets: parseDatasets(datasets ?? ""), apiUrl: this.getAttribute("api-url") ?? undefined });
+      const [data, sources] = await Promise.all([sql ? conn.sql(sql) : JSON.parse(rows ?? "[]"), conn.sources(sql ?? undefined)]);
+      if (run !== this.#run) return;
+      this.innerHTML = `<div style="height:var(--queria-map-height,400px)"></div>${attributionHtml(sources)}`;
+      const { finalize } = await renderMap(this.firstElementChild as HTMLElement, JSON.parse(layer), data, {
+        theme: theme === "dark" ? "dark" : "light",
+        ...(style ? { style } : {}),
+      });
+      if (run === this.#run) this.#finalize = finalize;
+      else finalize();
+    } catch (e) {
+      if (run === this.#run) this.innerHTML = `<p class="queria-note">${esc(String(e))}</p>`;
+    }
+  }
+}
+
+/** <queria-powered-by> */
+export class QueriaPoweredBy extends HTMLElement {
+  connectedCallback() {
+    this.innerHTML = poweredByHtml();
+  }
+}
+
+const elements = { "queria-chart": QueriaChart, "queria-map": QueriaMap, "queria-powered-by": QueriaPoweredBy };
+
+/** Register the custom elements. Safe to call more than once. */
+export const defineElements = (): void =>
+  Object.entries(elements).forEach(([name, cls]) => customElements.get(name) ?? customElements.define(name, cls));
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "queria-chart": QueriaChart;
+    "queria-map": QueriaMap;
+    "queria-powered-by": QueriaPoweredBy;
+  }
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export {
+  closeAll,
+  connect,
+  plain,
+  type Connection,
+  type ConnectOptions,
+  type Dataset,
+  type Declared,
+  type License,
+} from "./client.js";
+export { lit } from "./sql.js";
+export * from "./render/index.js";