queria 0.0.0 → 0.1.0

package/src/react/Chart.tsx

@@ -0,0 +1,49 @@
+import { useEffect, useRef, useState } from "react";
+import type { Dataset } from "../client.js";
+import { attributionHtml } from "../render/attribution.js";
+import { type ChartSpec, renderChart } from "../render/chart.js";
+import { useQueria } from "./query.js";
+
+type Props = { spec: ChartSpec; className?: string } & ({ sql: string } | { rows: readonly Record<string, unknown>[] });
+
+/** A Vega-Lite chart of the SQL result (or of `rows`), followed by the sources of the datasets. */
+export const Chart = ({ spec, className = "queria-chart", ...data }: Props) => {
+  const conn = useQueria();
+  const el = useRef<HTMLDivElement>(null);
+  const [state, setState] = useState<{ sources: Dataset[]; error?: unknown }>({ sources: [] });
+  const sql = "sql" in data ? data.sql : null;
+  const rows = "rows" in data ? data.rows : null;
+  // Compare the spec by content: a spec written inline is a new object on every render of the parent.
+  const specKey = JSON.stringify(spec);
+
+  useEffect(() => {
+    let alive = true;
+    let finalize: (() => void) | undefined;
+    const load = sql === null ? Promise.all([rows ?? [], conn.sources()]) : Promise.all([conn.sql(sql), conn.sources(sql)]);
+    load
+      .then(async ([values, sources]) => {
+        if (!alive || !el.current) return;
+        setState({ sources });
+        ({ finalize } = await renderChart(el.current, spec, values));
+        if (!alive) finalize();
+      })
+      .catch((error: unknown) => {
+        if (!alive) return;
+        // finalize stops the previous chart but leaves its drawing in the element.
+        el.current?.replaceChildren();
+        setState({ sources: [], error });
+      });
+    return () => {
+      alive = false;
+      finalize?.();
+    };
+  }, [conn, sql, rows, specKey]);
+
+  return (
+    <div className={className}>
+      {state.error ? <p className="queria-note">{String(state.error)}</p> : null}
+      <div ref={el} />
+      <div dangerouslySetInnerHTML={{ __html: attributionHtml(state.sources) }} />
+    </div>
+  );
+};

package/src/react/DataMap.tsx

@@ -0,0 +1,52 @@
+import { useEffect, useRef, useState } from "react";
+import type { Dataset } from "../client.js";
+import { attributionHtml } from "../render/attribution.js";
+import { type MapLayer, type MapRenderOptions, renderMap } from "../render/data-map.js";
+import { useQueria } from "./query.js";
+
+type Props = { layer: MapLayer; className?: string } & MapRenderOptions &
+  ({ sql: string } | { rows: readonly Record<string, unknown>[] });
+
+/** The SQL result (or `rows`) on a map by area code or by lng/lat, followed by the sources. Its height is the CSS variable --queria-map-height (400px by default). */
+export const DataMap = ({ layer, className = "queria-map", style, theme, ...data }: Props) => {
+  const conn = useQueria();
+  const el = useRef<HTMLDivElement>(null);
+  const [state, setState] = useState<{ sources: Dataset[]; error?: unknown }>({ sources: [] });
+  const sql = "sql" in data ? data.sql : null;
+  const rows = "rows" in data ? data.rows : null;
+  // Inline objects are new on every render of the parent, so compare them by content.
+  const key = JSON.stringify([layer, style, theme]);
+
+  useEffect(() => {
+    let alive = true;
+    let finalize: (() => void) | undefined;
+    // Each map gets its own element: a map removed after the next one started takes its class off its element.
+    const box = document.createElement("div");
+    box.style.height = "100%";
+    el.current?.append(box);
+    const load = sql === null ? Promise.all([rows ?? [], conn.sources()]) : Promise.all([conn.sql(sql), conn.sources(sql)]);
+    load
+      .then(async ([values, sources]) => {
+        if (!alive) return;
+        setState({ sources });
+        ({ finalize } = await renderMap(box, layer, values, { style, theme }));
+        if (!alive) finalize();
+      })
+      .catch((error: unknown) => {
+        if (alive) setState({ sources: [], error });
+      });
+    return () => {
+      alive = false;
+      finalize?.();
+      box.remove();
+    };
+  }, [conn, sql, rows, key]);
+
+  return (
+    <div className={className}>
+      {state.error ? <p className="queria-note">{String(state.error)}</p> : null}
+      <div ref={el} style={{ height: "var(--queria-map-height, 400px)" }} />
+      <div dangerouslySetInnerHTML={{ __html: attributionHtml(state.sources) }} />
+    </div>
+  );
+};

package/src/react/MapView.tsx

@@ -0,0 +1,45 @@
+import type { Map, MapOptions, StyleSpecification } from "maplibre-gl";
+import { type ReactNode, useEffect, useRef } from "react";
+import { type MapHandle, mountMap } from "../render/map.js";
+
+type Props = {
+  style: StyleSpecification | string;
+  /** Called once when the map is created. Attach handlers here and return a cleanup. */
+  onReady?: (map: Map) => void | (() => void);
+  options?: Omit<MapOptions, "container" | "style">;
+  className?: string;
+  children?: ReactNode;
+};
+
+/** A MapLibre map. Passing a new style applies only the diff. */
+export const MapView = ({ style, onReady, options, className = "queria-map", children }: Props) => {
+  const container = useRef<HTMLDivElement>(null);
+  const handle = useRef<MapHandle | null>(null);
+
+  useEffect(() => {
+    if (!container.current) return;
+    const h = mountMap(container.current, style, options);
+    handle.current = h;
+    const cleanup = h.map.then((m) => onReady?.(m));
+    return () => {
+      cleanup.then((f) => f?.(), console.error);
+      h.destroy();
+      handle.current = null;
+    };
+    // Create the map once; style changes are applied below.
+  }, []);
+
+  // The map is created with the first style; apply only later changes.
+  const applied = useRef(style);
+  useEffect(() => {
+    if (applied.current === style) return;
+    applied.current = style;
+    handle.current?.map.then((m) => m.setStyle(style), console.error);
+  }, [style]);
+
+  return (
+    <div className={className} ref={container}>
+      {children}
+    </div>
+  );
+};

package/src/react/PoweredBy.tsx

@@ -0,0 +1,4 @@
+import { poweredByHtml } from "../render/poweredBy.js";
+
+/** A link that shows the app is built on Queria. */
+export const PoweredBy = () => <span dangerouslySetInnerHTML={{ __html: poweredByHtml() }} />;

package/src/react/index.ts

@@ -0,0 +1,5 @@
+export { QueriaProvider, useQueria, useQuery, type QueryState } from "./query.js";
+export { Chart } from "./Chart.js";
+export { DataMap } from "./DataMap.js";
+export { MapView } from "./MapView.js";
+export { PoweredBy } from "./PoweredBy.js";

package/src/react/query.tsx

@@ -0,0 +1,64 @@
+import { createContext, type ReactNode, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { type Connection, type ConnectOptions, connect } from "../client.js";
+
+const Context = createContext<Connection | null>(null);
+
+/** Declare the datasets for the components below: <QueriaProvider datasets={["queria/e_stat"]}>. */
+export const QueriaProvider = ({ children, ...options }: ConnectOptions & { children: ReactNode }) => {
+  // JSON drops functions, so a token function is keyed by its presence and called through a ref:
+  // a new function on each render keeps the connection, and the latest one is called.
+  const { token } = options;
+  const latest = useRef(token);
+  latest.current = token;
+  const key = JSON.stringify({ ...options, token: typeof token === "function" ? "function" : token });
+  const conn = useMemo(
+    () =>
+      connect({
+        ...options,
+        token:
+          typeof token === "function"
+            ? async () => {
+                const t = latest.current;
+                if (t === undefined) throw new Error("The token was removed");
+                return typeof t === "function" ? t() : t;
+              }
+            : token,
+      }),
+    [key],
+  );
+  return <Context.Provider value={conn}>{children}</Context.Provider>;
+};
+
+export const useQueria = (): Connection => {
+  const conn = useContext(Context);
+  if (!conn) throw new Error("Wrap the component in <QueriaProvider datasets={[...]}>");
+  return conn;
+};
+
+export type QueryState<T> =
+  | { status: "idle" }
+  | { status: "loading" }
+  | { status: "done"; rows: T[] }
+  | { status: "error"; error: unknown };
+
+/** Run SQL and re-run it when the SQL changes. Pass null to skip; the state is then idle. */
+export const useQuery = <T = Record<string, unknown>,>(sql: string | null): QueryState<T> => {
+  const conn = useQueria();
+  const [state, setState] = useState<QueryState<T>>(sql === null ? { status: "idle" } : { status: "loading" });
+  useEffect(() => {
+    if (sql === null) {
+      setState({ status: "idle" });
+      return;
+    }
+    let alive = true;
+    setState({ status: "loading" });
+    conn.sql<T>(sql).then(
+      (rows) => alive && setState({ status: "done", rows }),
+      (error: unknown) => alive && setState({ status: "error", error }),
+    );
+    return () => {
+      alive = false;
+    };
+  }, [conn, sql]);
+  return state;
+};

package/src/render/attribution.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { attributionHtml } from "./attribution.js";
+
+describe("attributionHtml", () => {
+  it("lists each dataset with its licenses", () => {
+    const html = attributionHtml([
+      {
+        qualified_name: "queria/e_stat",
+        title: "e-Stat",
+        page_url: "https://queria.io/datasets/queria/e_stat",
+        licenses: [{ id: "CC-BY-4.0", title: "CC BY 4.0", url: "https://creativecommons.org/licenses/by/4.0/" }],
+        catalog_url: "u",
+      },
+    ]);
+    expect(html).toContain('href="https://queria.io/datasets/queria/e_stat"');
+    expect(html).toContain(">CC BY 4.0</a>");
+  });
+  it("does not link non-http URLs", () => {
+    expect(attributionHtml([{ qualified_name: "a/b", page_url: "javascript:x", catalog_url: "u" }])).not.toContain("href");
+  });
+  it("is empty without datasets", () => expect(attributionHtml([])).toBe(""));
+});

package/src/render/attribution.ts

@@ -0,0 +1,21 @@
+import type { Dataset } from "../client.js";
+import { esc } from "./escape.js";
+
+const link = (url: string | undefined, text: string): string =>
+  url && /^https?:\/\//.test(url) ? `<a href="${esc(url)}" target="_blank" rel="noopener">${esc(text)}</a>` : esc(text);
+
+/**
+ * Markup of the sources and licenses of the datasets, for display under a chart or map.
+ * Licenses such as CC BY require it wherever the data is shown.
+ */
+export const attributionHtml = (datasets: readonly Dataset[]): string =>
+  datasets.length === 0
+    ? ""
+    : '<p class="queria-attribution">Source: ' +
+      datasets
+        .map((d) => {
+          const licenses = (d.licenses ?? []).map((l) => link(l.url, l.title ?? l.id ?? "")).filter(Boolean);
+          return link(d.page_url, d.title ?? d.qualified_name) + (licenses.length ? ` (${licenses.join(", ")})` : "");
+        })
+        .join("; ") +
+      "</p>";

package/src/render/chart.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { withData } from "./chart.js";
+
+describe("withData", () => {
+  it("puts rows into a spec without data", () => {
+    expect(withData({ mark: "line" }, [{ x: 1 }])).toEqual({ width: "container", mark: "line", data: { values: [{ x: 1 }] } });
+  });
+  it("passes named rows as datasets for data: { name }", () => {
+    const spec = { layer: [{ mark: "line", data: { name: "a" } }, { mark: "point", data: { name: "b" } }] };
+    expect(withData(spec, { a: [{ x: 1 }], b: [{ x: 2 }] })).toMatchObject({ datasets: { a: [{ x: 1 }], b: [{ x: 2 }] } });
+  });
+  it("keeps the spec's own datasets", () => {
+    expect(withData({ datasets: { c: [{ x: 3 }] }, mark: "line" }, { a: [{ x: 1 }] })).toMatchObject({
+      datasets: { c: [{ x: 3 }], a: [{ x: 1 }] },
+    });
+  });
+  it("copies rows and leaves width alone for composite views", () => {
+    const rows = [Object.freeze({ x: 1 })];
+    const out = withData({ hconcat: [] }, rows);
+    expect(out).not.toHaveProperty("width");
+    expect(Object.isFrozen((out.data as { values: object[] }).values[0])).toBe(false);
+  });
+});

package/src/render/chart.ts

@@ -0,0 +1,80 @@
+import type { EmbedOptions, Result, VisualizationSpec } from "vega-embed";
+
+/** A Vega-Lite spec. Its data is put in by the package. */
+export type ChartSpec = VisualizationSpec | Record<string, unknown>;
+
+export type Rows = readonly Record<string, unknown>[];
+
+// Vega writes an id into every row it reads, so hand it copies: the caller's rows may be frozen or shared.
+const copy = (rows: Rows): Record<string, unknown>[] => rows.map((r) => ({ ...r }));
+
+const isRows = (d: Rows | Readonly<Record<string, Rows>>): d is Rows => Array.isArray(d);
+
+const ownDatasets = (spec: ChartSpec): object => {
+  const d: unknown = "datasets" in spec ? spec.datasets : undefined;
+  return typeof d === "object" && d !== null ? d : {};
+};
+
+/**
+ * Put the data into the spec. With rows, they become the data of a spec that has none.
+ * With named rows, the spec (or its layers) picks them with data: { name }; rows named "" are the default data.
+ */
+export const withData = (spec: ChartSpec, data: Rows | Readonly<Record<string, Rows>>): Record<string, unknown> => {
+  const named = isRows(data) ? { "": data } : data;
+  const { "": main, ...rest } = named;
+  // Vega-Lite takes width "container" only for single and layered views, and warns on the others.
+  const composite = ["facet", "repeat", "concat", "hconcat", "vconcat"].some((k) => k in spec);
+  return {
+    ...(composite ? {} : { width: "container" }),
+    ...spec,
+    ...(main && !("data" in spec) ? { data: { values: copy(main) } } : {}),
+    // The spec's own datasets stay; named rows are laid over them.
+    ...(Object.keys(rest).length
+      ? { datasets: { ...ownDatasets(spec), ...Object.fromEntries(Object.entries(rest).map(([k, v]) => [k, copy(v)])) } }
+      : {}),
+  };
+};
+
+export type ChartOptions = {
+  /** Vega-Lite config, such as a theme. The spec's own config is merged over it. */
+  config?: Record<string, unknown>;
+  /** Export and source menu. Hidden by default. */
+  actions?: EmbedOptions["actions"];
+  /** Labels of the menu. */
+  i18n?: EmbedOptions["i18n"];
+  tooltipTheme?: "light" | "dark";
+  /** By default svg, and canvas when there are more than 5,000 rows in all. */
+  renderer?: "svg" | "canvas";
+};
+
+const CANVAS_ABOVE = 5000;
+
+const rowCount = (data: Rows | Readonly<Record<string, Rows>>): number =>
+  isRows(data) ? data.length : Object.values(data).reduce((n, rows) => n + rows.length, 0);
+
+/**
+ * Draw a Vega-Lite chart. vega-embed and vega-interpreter are loaded on first use. Expressions are run by the
+ * interpreter, so charts draw on pages whose Content Security Policy has no unsafe-eval.
+ * Returns the Vega view and a function that removes the chart.
+ * Sources and licenses are not drawn here; the elements and React components add them under the chart.
+ */
+export const renderChart = async (
+  el: HTMLElement,
+  spec: ChartSpec,
+  data: Rows | Readonly<Record<string, Rows>>,
+  { config, actions = false, i18n, tooltipTheme, renderer }: ChartOptions = {},
+): Promise<Pick<Result, "view" | "finalize">> => {
+  const [{ default: embed }, { expressionInterpreter }] = await Promise.all([import("vega-embed"), import("vega-interpreter")]);
+  const { view, finalize } = await embed(el, withData(spec, data) as VisualizationSpec, {
+    // Read the spec as Vega-Lite even when its $schema says Vega
+    mode: "vega-lite",
+    ast: true,
+    expr: expressionInterpreter,
+    renderer: renderer ?? (rowCount(data) > CANVAS_ABOVE ? "canvas" : "svg"),
+    actions,
+    ...(i18n ? { i18n } : {}),
+    ...(config ? { config } : {}),
+    ...(tooltipTheme ? { tooltip: { theme: tooltipTheme } } : {}),
+  });
+  return { view, finalize };
+};

package/src/render/data-map.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { areaCode, areaRows, colorsOf, pointFeatures } from "./data-map.js";
+
+describe("areaCode", () => {
+  it("restores leading zeros and drops the check digit", () => {
+    expect(areaCode("prefecture", 1)).toBe("01");
+    expect(areaCode("city", 13101)).toBe("13101");
+    expect(areaCode("city", "131016")).toBe("13101");
+    expect(areaCode("city", 1101)).toBe("01101");
+    expect(areaCode("small_area", 1101000101)).toBe("01101000101");
+    expect(areaCode("city", null)).toBeNull();
+  });
+});
+
+describe("colorsOf", () => {
+  it("runs numbers from light to dark", () => {
+    expect(colorsOf([{ v: 0 }, { v: 10 }], "v")).toEqual(["#dbeafe", "#1d4ed8"]);
+  });
+  it("gives each category its own color", () => {
+    const [a, b, c] = colorsOf([{ v: "x" }, { v: "y" }, { v: "x" }], "v");
+    expect(a).toBe(c);
+    expect(a).not.toBe(b);
+  });
+  it("uses one color without a column", () => expect(new Set(colorsOf([{}, {}], undefined)).size).toBe(1));
+});
+
+describe("pointFeatures", () => {
+  it("leaves out rows without a position", () => {
+    const data = pointFeatures([{ x: 139.7, y: 35.6, n: "a" }, { x: null, y: 35 }, { x: "", y: 35 }], { lng: "x", lat: "y", label: "n" });
+    expect(data).toMatchObject({ features: [{ geometry: { coordinates: [139.7, 35.6] }, properties: { hover: "a" } }] });
+  });
+});
+
+describe("areaRows", () => {
+  it("keys rows by the tile code, first row wins", () => {
+    const areas = areaRows([{ c: 13101, p: 1 }, { c: "131016", p: 2 }], { area: "city", code: "c", color: "p" });
+    expect([...areas.keys()]).toEqual(["13101"]);
+    expect(areas.get("13101")?.hover).toBe("p: 1");
+  });
+});

package/src/render/data-map.ts

@@ -0,0 +1,230 @@
+import type { GeoJSONSourceSpecification, Map as MapLibreMap, StyleSpecification } from "maplibre-gl";
+import type { Rows } from "./chart.js";
+
+export type AreaLevel = "prefecture" | "city" | "small_area";
+
+/**
+ * How rows are put on the map: by area code (the shapes come from Queria's boundary tiles) or by longitude and latitude.
+ * The values are column names. `color` colors by a column, `label` names a row on hover.
+ */
+export type MapLayer = ({ area: AreaLevel; code: string } | { lng: string; lat: string }) & {
+  color?: string;
+  label?: string;
+  opacity?: number;
+};
+
+/** Queria's map styles. They keep their URL when the tiles are rebuilt, and hold the boundary sources. */
+export const MAP_STYLES = {
+  light: "https://assets.queria.io/maps/v1/light.json",
+  dark: "https://assets.queria.io/maps/v1/dark.json",
+} as const;
+
+/** The style's source for each area level. */
+export const boundarySource = (area: AreaLevel): string => `queria-${area}`;
+
+/**
+ * Put a code into the form of the boundary tiles: restore leading zeros lost in numeric columns, and drop
+ * the check digit of a 6-digit local government code.
+ */
+export const areaCode = (area: AreaLevel, value: unknown): string | null => {
+  if (typeof value !== "string" && typeof value !== "number" && typeof value !== "bigint") return null;
+  const text = String(value).trim();
+  if (text === "") return null;
+  if (area === "small_area") return text.length === 8 || text.length === 10 ? `0${text}` : text;
+  const digits = area === "prefecture" ? 2 : 5;
+  return text.length >= digits ? text.slice(0, digits) : text.padStart(digits, "0");
+};
+
+const BASE = "#2563eb";
+const LOW = [219, 234, 254];
+const HIGH = [29, 78, 216];
+const CATEGORIES = ["#2563eb", "#ea580c", "#16a34a", "#dc2626", "#9333ea", "#0891b2", "#ca8a04", "#db2777", "#4b5563", "#65a30d"];
+
+const hex = (rgb: number[]): string => `#${rgb.map((c) => Math.round(c).toString(16).padStart(2, "0")).join("")}`;
+
+/**
+ * A color for each row. Numbers run from light to dark between the smallest and largest value;
+ * other values get one color each, in order of first appearance.
+ */
+export const colorsOf = (rows: Rows, column: string | undefined): string[] => {
+  if (column === undefined) return rows.map(() => BASE);
+  const values = rows.map((r) => r[column]);
+  const nums = values.filter((v): v is number => typeof v === "number" && Number.isFinite(v));
+  if (nums.length > 0 && nums.length === values.filter((v) => v !== null && v !== undefined).length) {
+    // Spreading a large array into Math.min overflows the stack.
+    const min = nums.reduce((a, b) => Math.min(a, b));
+    const max = nums.reduce((a, b) => Math.max(a, b));
+    return values.map((v) => {
+      if (typeof v !== "number" || !Number.isFinite(v)) return "#d4d4d4";
+      const t = max === min ? 1 : (v - min) / (max - min);
+      return hex(LOW.map((l, i) => l + (HIGH[i] - l) * t));
+    });
+  }
+  const order = [...new Set(values.map(String))];
+  return values.map((v) => CATEGORIES[order.indexOf(String(v)) % CATEGORIES.length]);
+};
+
+/** Lines shown on hover: the label, then the colored value. */
+const hoverLines = (row: Record<string, unknown>, layer: MapLayer): string[] =>
+  [
+    layer.label === undefined ? null : String(row[layer.label] ?? ""),
+    layer.color === undefined ? null : `${layer.color}: ${typeof row[layer.color] === "number" ? (row[layer.color] as number).toLocaleString() : String(row[layer.color])}`,
+  ].filter((l): l is string => !!l);
+
+const coordinate = (v: unknown): number =>
+  typeof v === "number" ? v : typeof v === "string" && v.trim() !== "" ? Number(v) : Number.NaN;
+
+/** The row's [lng, lat], or null when either is missing or not a number. */
+const positionOf = (row: Record<string, unknown>, layer: { lng: string; lat: string }): [number, number] | null => {
+  const [lng, lat] = [coordinate(row[layer.lng]), coordinate(row[layer.lat])];
+  return Number.isFinite(lng) && Number.isFinite(lat) ? [lng, lat] : null;
+};
+
+/** Points as GeoJSON. Rows without a valid position are left out. */
+export const pointFeatures = (rows: Rows, layer: MapLayer & { lng: string; lat: string }): GeoJSONSourceSpecification["data"] => {
+  const colors = colorsOf(rows, layer.color);
+  return {
+    type: "FeatureCollection",
+    features: rows.flatMap((r, i) => {
+      const position = positionOf(r, layer);
+      if (position === null) return [];
+      return [{ type: "Feature" as const, geometry: { type: "Point" as const, coordinates: position }, properties: { color: colors[i], hover: hoverLines(r, layer).join("\n") } }];
+    }),
+  };
+};
+
+/** Color and hover lines by area code. The first row of a code wins. */
+export const areaRows = (rows: Rows, layer: MapLayer & { area: AreaLevel; code: string }): Map<string, { color: string; hover: string }> => {
+  const colors = colorsOf(rows, layer.color);
+  const out = new Map<string, { color: string; hover: string }>();
+  rows.forEach((r, i) => {
+    const code = areaCode(layer.area, r[layer.code]);
+    if (code !== null && !out.has(code)) out.set(code, { color: colors[i], hover: hoverLines(r, layer).join("\n") });
+  });
+  return out;
+};
+
+type Bbox = [number, number, number, number];
+
+const union = (boxes: Bbox[]): Bbox | null =>
+  boxes.length === 0
+    ? null
+    : boxes.reduce((a, b) => [Math.min(a[0], b[0]), Math.min(a[1], b[1]), Math.max(a[2], b[2]), Math.max(a[3], b[3])]);
+
+const bboxIndexes = new Map<string, Promise<Record<string, Bbox>>>();
+
+/** The bbox index at the URL, fetched once per page. */
+const bboxIndex = (url: string): Promise<Record<string, Bbox>> => {
+  const found = bboxIndexes.get(url);
+  if (found) return found;
+  const p = fetch(url)
+    .then((res) => {
+      if (!res.ok) throw new Error(`${url}: ${res.status}`);
+      return res.json() as Promise<Record<string, Bbox>>;
+    })
+    .catch((e: unknown) => {
+      bboxIndexes.delete(url);
+      throw e;
+    });
+  bboxIndexes.set(url, p);
+  return p;
+};
+
+/** The bounds of the points, or of the areas from the style's bbox index (small areas use their city). */
+const boundsOf = async (map: MapLibreMap, layer: MapLayer, rows: Rows, codes: string[]): Promise<Bbox | null> => {
+  if ("lng" in layer) {
+    return union(rows.flatMap((r): Bbox[] => {
+      const p = positionOf(r, layer);
+      return p ? [[p[0], p[1], p[0], p[1]]] : [];
+    }));
+  }
+  const url = (map.getStyle().metadata as Record<string, unknown> | undefined)?.["queria:bbox"];
+  if (typeof url !== "string") return null;
+  const index = await bboxIndex(url);
+  return union(codes.flatMap((c): Bbox[] => {
+      const box = index[layer.area === "small_area" ? c.slice(0, 5) : c];
+      return box ? [box] : [];
+    }));
+};
+
+export type MapRenderOptions = {
+  /** A MapLibre style or its URL. By default Queria's style, which has the boundary tiles. */
+  style?: StyleSpecification | string;
+  theme?: keyof typeof MAP_STYLES;
+};
+
+/**
+ * Draw rows on a MapLibre map. maplibre-gl is loaded on first use; include its CSS in your page.
+ * The map is fitted to the rows. Sources and licenses are not drawn here; the elements and React components add them.
+ */
+export const renderMap = async (
+  el: HTMLElement,
+  layer: MapLayer,
+  rows: Rows,
+  { style, theme = "light" }: MapRenderOptions = {},
+): Promise<{ map: MapLibreMap; finalize: () => void }> => {
+  const { default: maplibregl } = await import("maplibre-gl");
+  const map = new maplibregl.Map({ container: el, style: style ?? MAP_STYLES[theme], center: [137, 37], zoom: 4 });
+  try {
+    // An error before the style loads stops the map. Later errors, such as a tile or a sprite that fails to
+    // load, leave it drawing, and MapLibre logs them once no listener is left.
+    await new Promise<void>((resolve, reject) => {
+      const fail = (e: { error: Error }) => reject(e.error);
+      map.on("error", fail);
+      map.once("style.load", () => map.off("error", fail));
+      map.once("load", () => resolve());
+    });
+    // Areas go under the first label of the base map, so place names stay readable; points go on top.
+    const below = map.getStyle().layers.find((l) => l.type === "symbol")?.id;
+    const opacity = layer.opacity ?? ("lng" in layer ? 0.9 : 0.6);
+    let codes: string[] = [];
+    let hover: (f: { properties: Record<string, unknown> }) => string | undefined;
+    if ("lng" in layer) {
+      map.addSource("queria-rows", { type: "geojson", data: pointFeatures(rows, layer) });
+      map.addLayer({
+        id: "queria-rows",
+        type: "circle",
+        source: "queria-rows",
+        paint: { "circle-radius": 4, "circle-color": ["get", "color"], "circle-opacity": opacity, "circle-stroke-width": 1, "circle-stroke-color": "#ffffff" },
+      });
+      hover = (f) => f.properties.hover as string | undefined;
+    } else {
+      const source = boundarySource(layer.area);
+      if (!map.getSource(source)) throw new Error(`The map style has no source "${source}". Use Queria's style to draw areas`);
+      const areas = areaRows(rows, layer);
+      codes = [...areas.keys()];
+      if (codes.length > 0)
+        map.addLayer({
+          id: "queria-rows",
+          type: "fill",
+          source,
+          "source-layer": layer.area,
+          // A match on a literal list is a lookup table; "in" would scan the list for every feature.
+          filter: ["match", ["get", "code"], codes, true, false],
+          paint: {
+            "fill-color": ["match", ["get", "code"], ...[...areas].flatMap(([c, a]) => [c, a.color]), "rgba(0,0,0,0)"] as unknown as string,
+            "fill-opacity": opacity,
+            "fill-outline-color": "#ffffff",
+          },
+        }, below);
+      hover = (f) => areas.get(String(f.properties.code))?.hover;
+    }
+    const popup = new maplibregl.Popup({ closeButton: false, closeOnClick: false });
+    map.on("mousemove", "queria-rows", (e) => {
+      const text = e.features?.[0] ? hover(e.features[0]) : undefined;
+      if (!text) return popup.remove();
+      // The text comes from the data, so it is set as text, never as HTML.
+      const body = document.createElement("div");
+      body.style.whiteSpace = "pre-line";
+      body.textContent = text;
+      popup.setLngLat(e.lngLat).setDOMContent(body).addTo(map);
+    });
+    map.on("mouseleave", "queria-rows", () => popup.remove());
+    const bounds = await boundsOf(map, layer, rows, codes).catch(() => null);
+    if (bounds) map.fitBounds(bounds, { padding: 24, maxZoom: 14, duration: 0 });
+  } catch (e) {
+    map.remove();
+    throw e;
+  }
+  return { map, finalize: () => map.remove() };
+};

package/src/render/escape.ts

@@ -0,0 +1,4 @@
+const entities: Record<string, string> = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+
+/** Escape text for use in HTML or SVG markup. */
+export const esc = (s: string): string => s.replace(/[&<>"']/g, (c) => entities[c] ?? c);

package/src/render/index.ts

@@ -0,0 +1,12 @@
+export { attributionHtml } from "./attribution.js";
+export { renderChart, withData, type ChartOptions, type ChartSpec, type Rows } from "./chart.js";
+export { mountMap, type MapHandle } from "./map.js";
+export { poweredByHtml } from "./poweredBy.js";
+export {
+  areaCode,
+  MAP_STYLES,
+  renderMap,
+  type AreaLevel,
+  type MapLayer,
+  type MapRenderOptions,
+} from "./data-map.js";