@elabs-ai/components-maps 4.1.0 → 5.0.0

package/src/lib/plan-crs.ts

@@ -0,0 +1,252 @@
+/**
+ * A coordinate system for a CUSTOM, non-geographic plan — a floor plan, a
+ * factory layout, a train carriage, a rack elevation. Kept engine-free so it can
+ * be unit-tested (same convention as `arc-math.ts`).
+ *
+ * MapLibre GL JS renders Web Mercator and nothing else: it has no custom CRS and
+ * none is planned, so a plan coordinate system has to be SYNTHESIZED on top of
+ * Mercator. The same convention as Leaflet's `CRS.Simple` (origin top-left, one
+ * map unit = one pixel) and Qlik Sense's image background layer (corner
+ * coordinates in the image's own pixels, projection "undefined").
+ *
+ * The plan is mapped LINEARLY INTO NORMALIZED MERCATOR, not linearly into
+ * degrees. Normalized Mercator is what the screen shows, so one scale factor for
+ * both axes keeps the plan's aspect ratio exact at every zoom and every plan
+ * size. Mapping linearly into degrees — the naive reading of "undefined degrees"
+ * — stretches the plan vertically by Mercator's cos(lat) factor: a 1600 x 900
+ * plan comes out at aspect 1.996 instead of 1.778, 12% too wide.
+ *
+ * What this is NOT: a georeference. Mercator's y is non-linear in latitude, so
+ * lengths measured on the Earth are meaningless here. Distances belong to the
+ * plan (`distance()` returns plan units); never put a scale bar on a plan map,
+ * and never combine a plan with the globe projection.
+ */
+
+/**
+ * How much of normalized Mercator the plan's LONG side spans. Normalizing on the
+ * long side caps the footprint whatever the aspect ratio: the tallest possible
+ * plan reaches +-66.5 deg latitude, comfortably inside Mercator's +-85.05 limit.
+ */
+export const PLAN_MERCATOR_SPAN = 0.5;
+
+/** MapLibre's world is this many CSS pixels across at zoom 0. */
+const MERCATOR_TILE_SIZE = 512;
+
+/** A point in plan units. */
+export interface PlanPoint {
+  x: number;
+  y: number;
+}
+
+/** The plan's own extent and units — everything the coordinate system needs. */
+export interface PlanExtent {
+  /** Plan width in plan units (image pixels, millimetres, metres — your choice). */
+  width: number;
+  /** Plan height in plan units. */
+  height: number;
+  /**
+   * Where plan (0, 0) sits. `"top-left"` (the default) matches an image and
+   * Leaflet's `CRS.Simple`; `"bottom-left"` matches y-up CAD/DXF exports.
+   */
+  origin?: "top-left" | "bottom-left";
+  /** Unit name, for labels and readouts only — the maths never reads it. */
+  unit?: string;
+}
+
+/** The four image-source corners MapLibre wants: top-left, top-right, bottom-right, bottom-left. */
+export type PlanImageCoordinates = [
+  [number, number],
+  [number, number],
+  [number, number],
+  [number, number],
+];
+
+/** A two-way transform between plan units and lng/lat, plus everything derived from it. */
+export interface PlanCrs {
+  /** The extent this was built from, with defaults applied. */
+  readonly extent: Required<PlanExtent>;
+  /** Normalized Mercator units per plan unit. */
+  readonly scale: number;
+  /** Plan point -> `[lng, lat]`. */
+  toLngLat(point: PlanPoint | [number, number]): [number, number];
+  /** `[lng, lat]` -> plan point. */
+  toPlan(lngLat: [number, number] | { lng: number; lat: number }): PlanPoint;
+  /** Deep-convert GeoJSON authored in plan units into lng/lat GeoJSON. */
+  toGeoJSON<T>(data: T): T;
+  /** The plan's bounds as `[[west, south], [east, north]]`. */
+  readonly bounds: [[number, number], [number, number]];
+  /** Bounds grown by `padFraction` of the long side — a pan limit that still shows the edges. */
+  maxBounds(padFraction?: number): [[number, number], [number, number]];
+  /** The plan's four corners, ready for a MapLibre `image` or `canvas` source. */
+  readonly imageCoordinates: PlanImageCoordinates;
+  /** The zoom at which the plan's long side covers `px` CSS pixels. */
+  zoomForLongSidePixels(px: number): number;
+  /** Zoom at which the plan's long side is 128 px — small but still findable. */
+  readonly minZoom: number;
+  /** Zoom at which the plan's long side is 32768 px — a desk, a machine, a seat. */
+  readonly maxZoom: number;
+  /** Straight-line distance between two plan points, in plan units. */
+  distance(a: PlanPoint, b: PlanPoint): number;
+}
+
+const RAD_PER_DEG = Math.PI / 180;
+const DEG_PER_RAD = 180 / Math.PI;
+
+/**
+ * `[lng, lat]` -> normalized Mercator `[x, y]`, both in `[0, 1]`, with `y = 0` at
+ * the NORTH-WEST corner. The Web Mercator spec formulas, implemented here so the
+ * module stays engine-free; a parity test pins them to MapLibre's own
+ * `MercatorCoordinate`.
+ */
+export function mercatorFromLngLat(lng: number, lat: number): [number, number] {
+  const x = (180 + lng) / 360;
+  const y = (180 - DEG_PER_RAD * Math.log(Math.tan(Math.PI / 4 + (lat * RAD_PER_DEG) / 2))) / 360;
+  return [x, y];
+}
+
+/** Normalized Mercator `[x, y]` -> `[lng, lat]`. The inverse of `mercatorFromLngLat`. */
+export function lngLatFromMercator(x: number, y: number): [number, number] {
+  const lng = x * 360 - 180;
+  const y2 = 180 - y * 360;
+  const lat = (360 / Math.PI) * (Math.atan(Math.exp(y2 * RAD_PER_DEG)) - Math.PI / 4);
+  return [lng, lat];
+}
+
+function asPlanPoint(point: PlanPoint | [number, number]): PlanPoint {
+  return Array.isArray(point) ? { x: point[0], y: point[1] } : point;
+}
+
+/**
+ * Build a plan coordinate system from the plan's extent.
+ *
+ * ```tsx
+ * const plan = createPlanCrs({ width: 2400, height: 1600, unit: "cm" });
+ * <MapCanvas blank plan={plan}>
+ *   <MapPlanImage src={floorPlanPng} />
+ *   <MapGeoJSON data={roomsInPlanUnits} promoteId="id" />
+ * </MapCanvas>
+ * ```
+ *
+ * Throws when the extent is not a pair of finite, positive numbers — a NaN
+ * coordinate system is unfixable three layers downstream.
+ */
+export function createPlanCrs(extent: PlanExtent): PlanCrs {
+  const { width, height, origin = "top-left", unit = "px" } = extent;
+
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+    throw new Error(
+      `createPlanCrs: width and height must be finite positive numbers (received ${String(width)} x ${String(height)})`,
+    );
+  }
+
+  const resolved: Required<PlanExtent> = { width, height, origin, unit };
+  const scale = PLAN_MERCATOR_SPAN / Math.max(width, height);
+  // Centre the plan on normalized Mercator (0.5, 0.5), i.e. on lng/lat [0, 0].
+  const x0 = 0.5 - (width * scale) / 2;
+  const y0 = 0.5 - (height * scale) / 2;
+
+  // Mercator y already increases southward, so a top-left plan origin needs no
+  // flip. Only a y-up plan does.
+  const planYToMercatorY = (y: number) => y0 + (origin === "top-left" ? y : height - y) * scale;
+  const mercatorYToPlanY = (my: number) => {
+    const y = (my - y0) / scale;
+    return origin === "top-left" ? y : height - y;
+  };
+
+  const toLngLat = (point: PlanPoint | [number, number]): [number, number] => {
+    const { x, y } = asPlanPoint(point);
+    return lngLatFromMercator(x0 + x * scale, planYToMercatorY(y));
+  };
+
+  const toPlan = (lngLat: [number, number] | { lng: number; lat: number }): PlanPoint => {
+    const [lng, lat] = Array.isArray(lngLat) ? lngLat : [lngLat.lng, lngLat.lat];
+    const [mx, my] = mercatorFromLngLat(lng, lat);
+    return { x: (mx - x0) / scale, y: mercatorYToPlanY(my) };
+  };
+
+  const topLeft = toLngLat({ x: 0, y: 0 });
+  const bottomRight = toLngLat({ x: width, y: height });
+  // Plan y grows downward, so the plan's y=0 edge is the NORTHERN one.
+  const west = topLeft[0];
+  const east = bottomRight[0];
+  const north = Math.max(topLeft[1], bottomRight[1]);
+  const south = Math.min(topLeft[1], bottomRight[1]);
+
+  const bounds: [[number, number], [number, number]] = [
+    [west, south],
+    [east, north],
+  ];
+
+  const imageCoordinates: PlanImageCoordinates = [
+    toLngLat({ x: 0, y: 0 }),
+    toLngLat({ x: width, y: 0 }),
+    toLngLat({ x: width, y: height }),
+    toLngLat({ x: 0, y: height }),
+  ];
+
+  const zoomForLongSidePixels = (px: number) =>
+    Math.log2(px / (PLAN_MERCATOR_SPAN * MERCATOR_TILE_SIZE));
+
+  return Object.freeze({
+    extent: resolved,
+    scale,
+    toLngLat,
+    toPlan,
+    toGeoJSON: <T>(data: T): T => convertGeoJSON(data, toLngLat),
+    bounds,
+    maxBounds(padFraction = 0.1): [[number, number], [number, number]] {
+      const pad = Math.max(width, height) * padFraction;
+      const outerTopLeft = toLngLat({ x: -pad, y: -pad });
+      const outerBottomRight = toLngLat({ x: width + pad, y: height + pad });
+      return [
+        [outerTopLeft[0], Math.min(outerTopLeft[1], outerBottomRight[1])],
+        [outerBottomRight[0], Math.max(outerTopLeft[1], outerBottomRight[1])],
+      ];
+    },
+    imageCoordinates,
+    zoomForLongSidePixels,
+    minZoom: zoomForLongSidePixels(128),
+    maxZoom: zoomForLongSidePixels(32768),
+    distance: (a: PlanPoint, b: PlanPoint) => Math.hypot(b.x - a.x, b.y - a.y),
+  });
+}
+
+type Convert = (point: PlanPoint | [number, number]) => [number, number];
+
+function convertPositions(coordinates: unknown, convert: Convert): unknown {
+  if (!Array.isArray(coordinates)) return coordinates;
+  // A position is a flat [x, y(, z)] — convert it and drop any third element,
+  // which would be a plan-unit altitude MapLibre cannot interpret.
+  if (typeof coordinates[0] === "number" && typeof coordinates[1] === "number") {
+    return convert([coordinates[0], coordinates[1]]);
+  }
+  return coordinates.map((entry) => convertPositions(entry, convert));
+}
+
+/**
+ * Deep-convert every position in a GeoJSON value from plan units to lng/lat.
+ * `bbox` is STRIPPED rather than converted: MapLibre trusts a declared bbox, and
+ * a plan-unit one would put the geometry in the wrong place.
+ */
+function convertGeoJSON<T>(data: T, convert: Convert): T {
+  if (!data || typeof data !== "object") return data;
+
+  const input = data as Record<string, unknown>;
+  const { bbox: _bbox, ...rest } = input;
+  const output: Record<string, unknown> = { ...rest };
+
+  if (Array.isArray(input.features)) {
+    output.features = input.features.map((feature) => convertGeoJSON(feature, convert));
+  }
+  if (Array.isArray(input.geometries)) {
+    output.geometries = input.geometries.map((geometry) => convertGeoJSON(geometry, convert));
+  }
+  if (input.geometry && typeof input.geometry === "object") {
+    output.geometry = convertGeoJSON(input.geometry, convert);
+  }
+  if (input.coordinates !== undefined) {
+    output.coordinates = convertPositions(input.coordinates, convert);
+  }
+
+  return output as T;
+}

package/src/lib/plan-patterns.test.ts

@@ -0,0 +1,255 @@
+/**
+ * jsdom ships no 2D canvas context, which is exactly the environment
+ * `createPlanPatternTile` must survive — so the no-context path is asserted for
+ * real, and the drawing itself is asserted against a recording stub.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { renderHook } from "@testing-library/react";
+import type MapLibreGL from "maplibre-gl";
+
+import { MockMap } from "../test-utils/maplibre-mock";
+import { createPlanPatternTile, planPatternImageId, usePlanPatterns } from "./plan-patterns";
+import { PLAN_STATUSES, PLAN_STATUS_ENCODING, type PlanPatternKind } from "./plan-status";
+
+interface DrawnLine {
+  from: [number, number];
+  to: [number, number];
+  width: number;
+}
+
+interface RecordingContext {
+  lines: DrawnLine[];
+  strokeStyle: string;
+  globalAlpha: number;
+  lineWidth: number;
+}
+
+/** A 2D context that records what was stroked instead of rasterizing it. */
+function stubCanvasContext() {
+  const recorded: RecordingContext[] = [];
+
+  const spy = vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockImplementation(function (
+    this: HTMLCanvasElement,
+    kind: string,
+  ) {
+    if (kind !== "2d") return null;
+
+    const state: RecordingContext = {
+      lines: [],
+      strokeStyle: "",
+      globalAlpha: 1,
+      lineWidth: 1,
+    };
+    recorded.push(state);
+
+    let pen: [number, number] = [0, 0];
+    const context = {
+      set strokeStyle(value: string) {
+        state.strokeStyle = value;
+      },
+      get strokeStyle() {
+        return state.strokeStyle;
+      },
+      set globalAlpha(value: number) {
+        state.globalAlpha = value;
+      },
+      get globalAlpha() {
+        return state.globalAlpha;
+      },
+      set lineWidth(value: number) {
+        state.lineWidth = value;
+      },
+      get lineWidth() {
+        return state.lineWidth;
+      },
+      lineCap: "butt",
+      clearRect: () => {},
+      beginPath: () => {},
+      moveTo: (x: number, y: number) => {
+        pen = [x, y];
+      },
+      lineTo: (x: number, y: number) => {
+        state.lines.push({ from: pen, to: [x, y], width: state.lineWidth });
+      },
+      stroke: () => {},
+      getImageData: (_x: number, _y: number, width: number, height: number) => ({
+        data: new Uint8ClampedArray(width * height * 4),
+      }),
+    };
+
+    return context as unknown as CanvasRenderingContext2D;
+  });
+
+  return { recorded, spy };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  MockMap.instances = [];
+});
+
+describe("planPatternImageId", () => {
+  it("namespaces the id, so two plans on one map cannot collide", () => {
+    expect(planPatternImageId("diagonal")).toBe("plan-pattern-diagonal");
+    const kinds: PlanPatternKind[] = ["diagonal", "cross", "dense"];
+    expect(new Set(kinds.map(planPatternImageId)).size).toBe(kinds.length);
+  });
+});
+
+describe("createPlanPatternTile", () => {
+  it("returns null for the untextured status and for a context-less environment", () => {
+    // No stub: jsdom has no 2D context, and the dash channel carries the meaning.
+    expect(createPlanPatternTile("none", "#000")).toBeNull();
+    expect(createPlanPatternTile("diagonal", "#000")).toBeNull();
+  });
+
+  it("draws a 16px tile in the ink it was handed, below full alpha", () => {
+    const { recorded } = stubCanvasContext();
+
+    const tile = createPlanPatternTile("diagonal", "rgb(1, 2, 3)");
+
+    expect(tile).not.toBeNull();
+    expect(tile!.width).toBe(16);
+    expect(tile!.height).toBe(16);
+    expect(recorded[0]!.strokeStyle).toBe("rgb(1, 2, 3)");
+    expect(recorded[0]!.globalAlpha).toBeLessThan(1);
+  });
+
+  it("gives each kind its own line geometry, and joins across tile edges", () => {
+    const { recorded } = stubCanvasContext();
+
+    createPlanPatternTile("diagonal", "#000");
+    createPlanPatternTile("cross", "#000");
+    createPlanPatternTile("dense", "#000");
+
+    const [diagonal, cross, dense] = recorded as [
+      RecordingContext,
+      RecordingContext,
+      RecordingContext,
+    ];
+
+    // `cross` hatches both ways; the other two run one way only.
+    const slopeSign = (line: DrawnLine) =>
+      Math.sign((line.to[1] - line.from[1]) / (line.to[0] - line.from[0]));
+    const slopes = (state: RecordingContext) => new Set(state.lines.map(slopeSign));
+    expect(slopes(diagonal).size).toBe(1);
+    expect(slopes(cross).size).toBe(2);
+    // `dense` is the same direction as `diagonal` at half the spacing, so it
+    // must draw more lines or the two would read alike.
+    expect(dense.lines.length).toBeGreaterThan(diagonal.lines.length);
+    expect(slopes(dense).size).toBe(1);
+
+    // Every line starts or ends outside the 16px tile: that overshoot is what
+    // makes the pattern seamless across tile edges.
+    for (const state of recorded) {
+      for (const line of state.lines) {
+        const coordinates = [...line.from, ...line.to];
+        expect(coordinates.some((value) => value < 0 || value > 16)).toBe(true);
+      }
+    }
+
+    // …and every line actually crosses the tile's middle third. A hatch line
+    // that only clips a corner passes every assertion above while painting
+    // nothing: the status then has no texture at all, which is how a
+    // corner-only `cross` shipped looking exactly like `dense`.
+    const crossesTheMiddle = (line: DrawnLine) => {
+      const [x1, y1] = line.from;
+      const [x2, y2] = line.to;
+      for (let step = 0; step <= 100; step += 1) {
+        const t = step / 100;
+        const x = x1 + (x2 - x1) * t;
+        const y = y1 + (y2 - y1) * t;
+        if (x > 16 / 3 && x < (16 * 2) / 3 && y > 16 / 3 && y < (16 * 2) / 3) return true;
+      }
+      return false;
+    };
+    for (const state of recorded) {
+      expect(state.lines.filter(crossesTheMiddle).length).toBeGreaterThan(0);
+    }
+    // `cross` crosses the middle in BOTH directions — the crosshatch is the
+    // whole point of it being a separate texture.
+    expect(new Set(cross.lines.filter(crossesTheMiddle).map(slopeSign)).size).toBe(2);
+  });
+});
+
+describe("usePlanPatterns", () => {
+  const renderWith = (map: MockMap | null, isLoaded = true, ink = "#111") =>
+    renderHook(
+      ({ ink: currentInk }: { ink: string }) =>
+        usePlanPatterns(map as unknown as MapLibreGL.Map | null, isLoaded, currentInk),
+      { initialProps: { ink } },
+    );
+
+  it("registers one image per textured status, at pixelRatio 2", () => {
+    stubCanvasContext();
+    const map = new MockMap({ container: document.createElement("div") });
+
+    renderWith(map);
+
+    const textured = new Set(
+      PLAN_STATUSES.map((status) => PLAN_STATUS_ENCODING[status].pattern).filter(
+        (pattern) => pattern !== "none",
+      ),
+    );
+    expect(map.addImageCalls).toHaveLength(textured.size);
+    for (const [id, , options] of map.addImageCalls) {
+      expect(id.startsWith("plan-pattern-")).toBe(true);
+      expect(options).toEqual({ pixelRatio: 2 });
+    }
+    expect(map.hasImage(planPatternImageId("diagonal"))).toBe(true);
+  });
+
+  it("re-registers on styledata, because setStyle drops every style image", () => {
+    stubCanvasContext();
+    const map = new MockMap({ container: document.createElement("div") });
+
+    renderWith(map);
+    const added = map.addImageCalls.length;
+    map.updateImageCalls = [];
+
+    // A theme swap calls setStyle, which fires styledata with the images gone.
+    map.emit("styledata");
+
+    // Second pass updates in place rather than adding twice.
+    expect(map.addImageCalls).toHaveLength(added);
+    expect(map.updateImageCalls.length).toBeGreaterThan(0);
+  });
+
+  it("stops listening when it unmounts", () => {
+    stubCanvasContext();
+    const map = new MockMap({ container: document.createElement("div") });
+
+    const view = renderWith(map);
+    view.unmount();
+    map.updateImageCalls = [];
+    map.emit("styledata");
+
+    expect(map.updateImageCalls).toHaveLength(0);
+  });
+
+  it("redraws when the ink changes, so a theme swap re-inks the hatch", () => {
+    const { recorded } = stubCanvasContext();
+    const map = new MockMap({ container: document.createElement("div") });
+
+    const view = renderWith(map);
+    // Only the drawing passes count: the registration reads the tile back
+    // through a second `getContext("2d")` that strokes nothing.
+    const inks = () =>
+      new Set(recorded.filter((state) => state.lines.length > 0).map((state) => state.strokeStyle));
+    expect(inks()).toEqual(new Set(["#111"]));
+
+    view.rerender({ ink: "#eee" });
+
+    expect(inks()).toEqual(new Set(["#111", "#eee"]));
+  });
+
+  it("does nothing without a map or before the style loads", () => {
+    stubCanvasContext();
+    const map = new MockMap({ container: document.createElement("div") });
+
+    renderWith(null);
+    renderWith(map, false);
+
+    expect(map.addImageCalls).toHaveLength(0);
+  });
+});

package/src/lib/plan-patterns.ts

@@ -0,0 +1,160 @@
+"use client";
+
+import { useEffect } from "react";
+import type MapLibreGL from "maplibre-gl";
+
+import { PLAN_STATUSES, PLAN_STATUS_ENCODING, type PlanPatternKind } from "./plan-status";
+
+/**
+ * Seamless hatch tiles for the status channel, generated on a canvas and handed
+ * to `map.addImage`. Generated rather than fetched: a blank plan style has no
+ * sprite and no glyph endpoint, and a texture that needs the network is a
+ * texture that sometimes is not there.
+ *
+ * The tile geometry mirrors `SeriesPatternKind` in
+ * `packages/charts/src/charts/series-pattern.tsx`, so a factory plan and a
+ * chart of the same data are textured alike. It is deliberately a copy: the
+ * one-way dependency graph forbids maps importing charts.
+ */
+
+/** Tile edge, in px. Small enough to read at fit zoom, large enough not to moiré. */
+const TILE = 16;
+/** Ink alpha. The pattern is a texture over a tone wash, not a second fill. */
+const INK_ALPHA = 0.55;
+
+/** Image ids are stable and namespaced, so two plans on one map cannot collide. */
+export function planPatternImageId(kind: PlanPatternKind): string {
+  return `plan-pattern-${kind}`;
+}
+
+/**
+ * A hatch at `spacing` px, as segments that overshoot the tile on both ends.
+ *
+ * The lines are laid out so the set repeats under a TILE-sized shift in either
+ * axis — that, not the overshoot alone, is what makes the tile seamless. Each
+ * line is written as the two points where it meets the tile's own axes, so one
+ * of them always crosses the tile's middle rather than clipping a corner: a
+ * corner-only line paints nothing and leaves the status untextured.
+ *
+ * `RISING` runs bottom-left to top-right (canvas y grows downward, so these are
+ * the `x + y = c` lines); `FALLING` is its mirror, and the two together are the
+ * crosshatch.
+ */
+const OVERSHOOT = TILE / 2;
+
+function RISING(spacing: number): [number, number, number, number][] {
+  const lines: [number, number, number, number][] = [];
+  for (let c = 0; c <= TILE * 2; c += spacing) {
+    lines.push([-OVERSHOOT, c + OVERSHOOT, TILE + OVERSHOOT, c - TILE - OVERSHOOT]);
+  }
+  return lines;
+}
+
+function FALLING(spacing: number): [number, number, number, number][] {
+  return RISING(spacing).map(
+    ([x1, y1, x2, y2]) => [x1, TILE - y1, x2, TILE - y2] as [number, number, number, number],
+  );
+}
+
+function strokeLines(
+  context: CanvasRenderingContext2D,
+  lines: [number, number, number, number][],
+  width: number,
+) {
+  context.lineWidth = width;
+  context.lineCap = "square";
+  for (const [x1, y1, x2, y2] of lines) {
+    context.beginPath();
+    context.moveTo(x1, y1);
+    context.lineTo(x2, y2);
+    context.stroke();
+  }
+}
+
+/**
+ * Draw one seamless tile. Returns `null` for `"none"`, and for any environment
+ * with no 2D context (jsdom) — the dash channel then carries the meaning alone,
+ * which is why status has two non-colour channels rather than one.
+ */
+export function createPlanPatternTile(
+  kind: PlanPatternKind,
+  ink: string,
+): HTMLCanvasElement | null {
+  if (kind === "none") return null;
+  if (typeof document === "undefined") return null;
+
+  const canvas = document.createElement("canvas");
+  canvas.width = TILE;
+  canvas.height = TILE;
+  const context = canvas.getContext("2d");
+  if (!context) return null;
+
+  context.clearRect(0, 0, TILE, TILE);
+  context.globalAlpha = INK_ALPHA;
+  context.strokeStyle = ink;
+
+  if (kind === "diagonal") {
+    strokeLines(context, RISING(TILE), 1.5);
+  } else if (kind === "cross") {
+    strokeLines(context, [...RISING(TILE), ...FALLING(TILE)], 1.25);
+  } else {
+    // dense: half the spacing of `diagonal`, so the two never read alike.
+    strokeLines(context, RISING(TILE / 2), 1.25);
+  }
+
+  return canvas;
+}
+
+/** Every pattern kind the status table uses, deduplicated. */
+function usedPatternKinds(): PlanPatternKind[] {
+  const kinds = new Set<PlanPatternKind>();
+  for (const status of PLAN_STATUSES) kinds.add(PLAN_STATUS_ENCODING[status].pattern);
+  kinds.delete("none");
+  return [...kinds];
+}
+
+/**
+ * Register (and re-register) the status textures on a map.
+ *
+ * Re-registration is not optional: `map.setStyle` — which a theme swap performs —
+ * drops every image the style holds, and a `fill-pattern` naming a missing image
+ * renders nothing at all. So the images are (re)added on `styledata` as well as
+ * whenever the ink changes.
+ *
+ * @param ink The colour to draw the hatch in, already resolved from a token.
+ */
+export function usePlanPatterns(map: MapLibreGL.Map | null, isLoaded: boolean, ink: string) {
+  useEffect(() => {
+    if (!map || !isLoaded) return;
+
+    const register = () => {
+      for (const kind of usedPatternKinds()) {
+        const tile = createPlanPatternTile(kind, ink);
+        if (!tile) continue;
+        const id = planPatternImageId(kind);
+        const image = {
+          width: tile.width,
+          height: tile.height,
+          data: tile.getContext("2d")?.getImageData(0, 0, tile.width, tile.height).data,
+        };
+        if (!image.data) continue;
+        try {
+          if (map.hasImage(id)) {
+            map.updateImage(id, image as unknown as ImageData);
+          } else {
+            map.addImage(id, image as unknown as ImageData, { pixelRatio: 2 });
+          }
+        } catch {
+          // style mid-reload; the `styledata` handler below re-runs this
+        }
+      }
+    };
+
+    register();
+    map.on("styledata", register);
+
+    return () => {
+      map.off("styledata", register);
+    };
+  }, [map, isLoaded, ink]);
+}