@elabs-ai/components-maps 4.2.0 → 5.1.0

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

@@ -0,0 +1,186 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  planBoundsOfGeometry,
+  planBoundsUnion,
+  planGroupId,
+  planGroupsFromRegions,
+  planRegionCentre,
+  planRegionsFromGeoJSON,
+  type MapPlanRegion,
+} from "./plan-regions";
+
+const rooms: GeoJSON.FeatureCollection<
+  GeoJSON.Geometry,
+  { id: string; name: string; status: string }
+> = {
+  type: "FeatureCollection",
+  features: [
+    {
+      type: "Feature",
+      properties: { id: "studio", name: "Studio", status: "free" },
+      geometry: {
+        type: "Polygon",
+        coordinates: [
+          [
+            [10, 20],
+            [210, 20],
+            [210, 120],
+            [10, 120],
+            [10, 20],
+          ],
+        ],
+      },
+    },
+    {
+      type: "Feature",
+      properties: { id: "aisle", name: "Aisle", status: "free" },
+      geometry: {
+        type: "LineString",
+        coordinates: [
+          [0, 400],
+          [1000, 420],
+        ],
+      },
+    },
+  ],
+};
+
+describe("planBoundsOfGeometry", () => {
+  it("boxes a polygon, a line and a nested multi-polygon alike", () => {
+    expect(planBoundsOfGeometry(rooms.features[0]!.geometry)).toEqual({
+      x: 10,
+      y: 20,
+      width: 200,
+      height: 100,
+    });
+    expect(planBoundsOfGeometry(rooms.features[1]!.geometry)).toEqual({
+      x: 0,
+      y: 400,
+      width: 1000,
+      height: 20,
+    });
+    expect(
+      planBoundsOfGeometry({
+        type: "MultiPolygon",
+        coordinates: [
+          [
+            [
+              [0, 0],
+              [10, 0],
+              [10, 10],
+              [0, 0],
+            ],
+          ],
+          [
+            [
+              [90, 90],
+              [100, 90],
+              [100, 100],
+              [90, 90],
+            ],
+          ],
+        ],
+      }),
+    ).toEqual({ x: 0, y: 0, width: 100, height: 100 });
+  });
+
+  it("boxes a geometry collection across its members", () => {
+    expect(
+      planBoundsOfGeometry({
+        type: "GeometryCollection",
+        geometries: [
+          { type: "Point", coordinates: [5, 5] },
+          { type: "Point", coordinates: [45, 25] },
+        ],
+      }),
+    ).toEqual({ x: 5, y: 5, width: 40, height: 20 });
+  });
+});
+
+describe("planRegionsFromGeoJSON", () => {
+  it("derives one region per feature, from property names", () => {
+    const regions = planRegionsFromGeoJSON(rooms, { id: "id", label: "name" });
+
+    expect(regions.map((region) => region.id)).toEqual(["studio", "aisle"]);
+    expect(regions[0]!.label).toBe("Studio");
+    expect(regions[0]!.bounds).toEqual({ x: 10, y: 20, width: 200, height: 100 });
+    expect(regions[0]!.description).toBeUndefined();
+  });
+
+  it("takes a function for anything computed", () => {
+    const regions = planRegionsFromGeoJSON(rooms, {
+      id: "id",
+      label: "name",
+      description: (properties) => `${properties.status} now`,
+      group: () => "level-3",
+    });
+
+    expect(regions[0]!.description).toBe("free now");
+    expect(regions[1]!.group).toBe("level-3");
+  });
+});
+
+describe("planRegionCentre", () => {
+  it("returns the middle of a box, in plan units", () => {
+    expect(planRegionCentre({ x: 10, y: 20, width: 200, height: 100 })).toEqual({
+      x: 110,
+      y: 70,
+    });
+  });
+});
+
+const SEATS: MapPlanRegion[] = [
+  {
+    id: "a-1",
+    label: "1",
+    group: "coach-a",
+    groupLabel: "Coach A",
+    bounds: { x: 0, y: 0, width: 50, height: 40 },
+  },
+  {
+    id: "a-2",
+    label: "2",
+    group: "coach-a",
+    groupLabel: "Coach A",
+    bounds: { x: 60, y: 10, width: 50, height: 40 },
+  },
+  { id: "toilet", label: "Toilet", bounds: { x: 200, y: 0, width: 30, height: 60 } },
+];
+
+describe("planBoundsUnion", () => {
+  it("is the smallest box holding all of them", () => {
+    expect(planBoundsUnion(SEATS.map((seat) => seat.bounds))).toEqual({
+      x: 0,
+      y: 0,
+      width: 230,
+      height: 60,
+    });
+  });
+
+  it("is null for nothing at all", () => {
+    expect(planBoundsUnion([])).toBeNull();
+  });
+});
+
+describe("planGroupsFromRegions", () => {
+  it("bundles regions by their group, in first-seen order", () => {
+    const groups = planGroupsFromRegions(SEATS);
+
+    expect(groups.map((group) => group.key)).toEqual(["coach-a", "toilet"]);
+    expect(groups[0]!.members.map((member) => member.id)).toEqual(["a-1", "a-2"]);
+    expect(groups[0]!.region.label).toBe("Coach A");
+    expect(groups[0]!.region.id).toBe(planGroupId("coach-a"));
+    // The group's own box spans its members, so its button covers all of them.
+    expect(groups[0]!.region.bounds).toEqual({ x: 0, y: 0, width: 110, height: 50 });
+  });
+
+  it("makes an ungrouped region a group of one, so nothing disappears", () => {
+    const groups = planGroupsFromRegions(SEATS);
+
+    const loner = groups.find((group) => group.key === "toilet")!;
+    expect(loner.members).toHaveLength(1);
+    expect(loner.region.label).toBe("toilet");
+    expect(loner.region.bounds).toEqual(SEATS[2]!.bounds);
+  });
+});

package/src/lib/plan-regions.ts

@@ -0,0 +1,209 @@
+import type { PlanPoint } from "./plan-crs";
+
+/** An axis-aligned rectangle in PLAN units. */
+export interface PlanRegionBounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * One interactive area of a plan — a room, a machine cell, a seat. The overlay
+ * needs a box and a name, not the geometry: a room's shape is drawn by WebGL,
+ * while the keyboard proxy, the label and the readout all work from its box.
+ */
+export interface MapPlanRegion {
+  /** Stable id. Must match the feature id the shape layer promotes. */
+  id: string;
+  /** The visible label, and the start of the button's accessible name. */
+  label: string;
+  /** Shown instead of `label` when the box is too small for the full one. */
+  shortLabel?: string;
+  /** Appended to the accessible name — a status word, a seat count, an owner. */
+  description?: string;
+  /** The region's box, in plan units. */
+  bounds: PlanRegionBounds;
+  /** Group id, for plans with more regions than a keyboard can walk (a carriage, a wing). */
+  group?: string;
+  /** The group's own label, used by group mode. */
+  groupLabel?: string;
+}
+
+/** The centre of a region's box, in plan units. */
+export function planRegionCentre(bounds: PlanRegionBounds): PlanPoint {
+  return { x: bounds.x + bounds.width / 2, y: bounds.y + bounds.height / 2 };
+}
+
+function walkCoordinates(input: unknown, visit: (x: number, y: number) => void): void {
+  if (!Array.isArray(input)) return;
+  if (typeof input[0] === "number" && typeof input[1] === "number") {
+    visit(input[0], input[1]);
+    return;
+  }
+  for (const entry of input) walkCoordinates(entry, visit);
+}
+
+/** The bounding box of any geometry, in the units its coordinates are written in. */
+export function planBoundsOfGeometry(geometry: GeoJSON.Geometry): PlanRegionBounds | null {
+  let minX = Number.POSITIVE_INFINITY;
+  let minY = Number.POSITIVE_INFINITY;
+  let maxX = Number.NEGATIVE_INFINITY;
+  let maxY = Number.NEGATIVE_INFINITY;
+
+  const visit = (x: number, y: number) => {
+    if (x < minX) minX = x;
+    if (y < minY) minY = y;
+    if (x > maxX) maxX = x;
+    if (y > maxY) maxY = y;
+  };
+
+  if (geometry.type === "GeometryCollection") {
+    for (const member of geometry.geometries) {
+      walkCoordinates((member as { coordinates?: unknown }).coordinates, visit);
+    }
+  } else {
+    walkCoordinates(geometry.coordinates, visit);
+  }
+
+  if (!Number.isFinite(minX) || !Number.isFinite(minY)) return null;
+  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+}
+
+/** A field read either from a feature property or computed from the properties. */
+export type PlanRegionField<P, T> = string | ((properties: P, index: number) => T);
+
+export interface PlanRegionFields<P extends GeoJSON.GeoJsonProperties> {
+  /** Property name, or a function, giving each region's id. */
+  id: PlanRegionField<P, string>;
+  /** Property name, or a function, giving each region's visible label. */
+  label: PlanRegionField<P, string>;
+  /** Optional short label for a small box. */
+  shortLabel?: PlanRegionField<P, string | undefined>;
+  /** Optional extra words for the accessible name. */
+  description?: PlanRegionField<P, string | undefined>;
+  /** Optional group id. */
+  group?: PlanRegionField<P, string | undefined>;
+  /** Optional group label. */
+  groupLabel?: PlanRegionField<P, string | undefined>;
+}
+
+function read<P extends GeoJSON.GeoJsonProperties, T>(
+  field: PlanRegionField<P, T> | undefined,
+  properties: P,
+  index: number,
+): T | undefined {
+  if (field === undefined) return undefined;
+  if (typeof field === "function") return field(properties, index);
+  return (properties as Record<string, unknown> | null)?.[field] as T | undefined;
+}
+
+/**
+ * Derive the overlay's regions from the same GeoJSON the shape layer draws, so
+ * the keyboard proxy can never drift out of step with the picture.
+ *
+ * ```ts
+ * const regions = planRegionsFromGeoJSON(rooms, { id: "id", label: "name" });
+ * ```
+ */
+export function planRegionsFromGeoJSON<P extends GeoJSON.GeoJsonProperties>(
+  data: GeoJSON.FeatureCollection<GeoJSON.Geometry, P>,
+  fields: PlanRegionFields<P>,
+): MapPlanRegion[] {
+  const regions: MapPlanRegion[] = [];
+
+  data.features.forEach((feature, index) => {
+    const bounds = planBoundsOfGeometry(feature.geometry);
+    if (!bounds) return;
+    const properties = feature.properties;
+    const id =
+      read(fields.id, properties, index) ?? (feature.id != null ? String(feature.id) : null);
+    if (id == null) return;
+
+    const shortLabel = read(fields.shortLabel, properties, index);
+    const description = read(fields.description, properties, index);
+    const group = read(fields.group, properties, index);
+    const groupLabel = read(fields.groupLabel, properties, index);
+
+    regions.push({
+      id: String(id),
+      label: String(read(fields.label, properties, index) ?? id),
+      ...(shortLabel !== undefined ? { shortLabel: String(shortLabel) } : {}),
+      ...(description !== undefined ? { description: String(description) } : {}),
+      ...(group !== undefined ? { group: String(group) } : {}),
+      ...(groupLabel !== undefined ? { groupLabel: String(groupLabel) } : {}),
+      bounds,
+    });
+  });
+
+  return regions;
+}
+
+/** The id the overlay gives a group's own button, namespaced away from region ids. */
+export function planGroupId(group: string): string {
+  return `group:${group}`;
+}
+
+/** One group of regions, with the synthetic region that stands for the whole of it. */
+export interface MapPlanGroup {
+  /** The group's key, as it appeared on its regions. */
+  key: string;
+  /** A region covering every member's box — what group mode puts a button on. */
+  region: MapPlanRegion;
+  /** The group's regions, in reading order. */
+  members: readonly MapPlanRegion[];
+}
+
+/** The smallest box containing all of them. `null` for an empty list. */
+export function planBoundsUnion(boxes: readonly PlanRegionBounds[]): PlanRegionBounds | null {
+  if (boxes.length === 0) return null;
+  let minX = Number.POSITIVE_INFINITY;
+  let minY = Number.POSITIVE_INFINITY;
+  let maxX = Number.NEGATIVE_INFINITY;
+  let maxY = Number.NEGATIVE_INFINITY;
+
+  for (const box of boxes) {
+    if (box.x < minX) minX = box.x;
+    if (box.y < minY) minY = box.y;
+    if (box.x + box.width > maxX) maxX = box.x + box.width;
+    if (box.y + box.height > maxY) maxY = box.y + box.height;
+  }
+
+  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+}
+
+/**
+ * Bundle regions by their `group`, in first-seen order.
+ *
+ * A region with no `group` becomes a group of one, keyed by its own id: group
+ * mode then still shows everything, instead of quietly dropping whatever was
+ * left ungrouped.
+ */
+export function planGroupsFromRegions(regions: readonly MapPlanRegion[]): MapPlanGroup[] {
+  const byKey = new Map<string, MapPlanRegion[]>();
+
+  for (const region of regions) {
+    const key = region.group ?? region.id;
+    const members = byKey.get(key);
+    if (members) members.push(region);
+    else byKey.set(key, [region]);
+  }
+
+  const groups: MapPlanGroup[] = [];
+  for (const [key, members] of byKey) {
+    const bounds = planBoundsUnion(members.map((member) => member.bounds));
+    if (!bounds) continue;
+    const first = members[0]!;
+    groups.push({
+      key,
+      region: {
+        id: planGroupId(key),
+        label: first.groupLabel ?? key,
+        bounds,
+      },
+      members,
+    });
+  }
+
+  return groups;
+}

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

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  PLAN_FILL_OPACITY,
+  PLAN_STATUSES,
+  PLAN_STATUS_ENCODING,
+  planStatusMatch,
+} from "./plan-status";
+
+describe("PLAN_STATUS_ENCODING", () => {
+  it("covers every status exactly once, in legend order", () => {
+    expect(PLAN_STATUSES).toEqual(["free", "occupied", "warning", "down"]);
+    expect(Object.keys(PLAN_STATUS_ENCODING).sort()).toEqual([...PLAN_STATUSES].sort());
+  });
+
+  it("gives every status its own texture and its own outline style", () => {
+    const patterns = PLAN_STATUSES.map((status) => PLAN_STATUS_ENCODING[status].pattern);
+    const dashes = PLAN_STATUSES.map((status) => PLAN_STATUS_ENCODING[status].dash);
+
+    // Four statuses, four textures, four outline styles: in greyscale they still
+    // read apart, which is the whole point of the table (WCAG 1.4.1).
+    expect(new Set(patterns).size).toBe(PLAN_STATUSES.length);
+    expect(new Set(dashes).size).toBe(PLAN_STATUSES.length);
+  });
+
+  it("carries a glyph only on the two states that must never be missed", () => {
+    expect(PLAN_STATUS_ENCODING.free.icon).toBeUndefined();
+    expect(PLAN_STATUS_ENCODING.occupied.icon).toBeUndefined();
+    expect(PLAN_STATUS_ENCODING.warning.icon).toBeDefined();
+    expect(PLAN_STATUS_ENCODING.down.icon).toBeDefined();
+    expect(PLAN_STATUS_ENCODING.warning.glyph).not.toBe(PLAN_STATUS_ENCODING.down.glyph);
+  });
+
+  it("leaves the free status solid, so a dash always means something", () => {
+    expect(PLAN_STATUS_ENCODING.free.dashArray).toBeUndefined();
+    for (const status of ["occupied", "warning", "down"] as const) {
+      expect(PLAN_STATUS_ENCODING[status].dashArray?.length).toBeGreaterThan(1);
+    }
+  });
+
+  it("keeps the ink rung off the mark rung", () => {
+    for (const status of PLAN_STATUSES) {
+      const encoding = PLAN_STATUS_ENCODING[status];
+      expect(encoding.markClass.startsWith("bg-")).toBe(true);
+      // `-text` is the ink rung; a bare `text-<tone>` would be the 3:1 fill rung.
+      expect(
+        encoding.textClass.endsWith("-text") || encoding.textClass === "text-muted-foreground",
+      ).toBe(true);
+    }
+  });
+
+  it("cannot be edited by a surface that reads it", () => {
+    expect(Object.isFrozen(PLAN_STATUS_ENCODING)).toBe(true);
+    expect(Object.isFrozen(PLAN_FILL_OPACITY)).toBe(true);
+  });
+
+  it("rises in opacity from rest through hover to selected", () => {
+    expect(PLAN_FILL_OPACITY.rest).toBeLessThan(PLAN_FILL_OPACITY.hover);
+    expect(PLAN_FILL_OPACITY.hover).toBeLessThan(PLAN_FILL_OPACITY.selected);
+  });
+});
+
+describe("planStatusMatch", () => {
+  it("builds one MapLibre match over the status property", () => {
+    const expression = planStatusMatch("state", (encoding) => encoding.dash, "solid");
+
+    expect(expression).toEqual([
+      "match",
+      ["get", "state"],
+      "free",
+      "solid",
+      "occupied",
+      "dotted",
+      "warning",
+      "dashed",
+      "down",
+      "dot-dash",
+      "solid",
+    ]);
+  });
+
+  it("falls back to the occupied value when no fallback is given", () => {
+    const expression = planStatusMatch("status", (encoding) => encoding.pattern);
+
+    expect(expression.at(-1)).toBe(PLAN_STATUS_ENCODING.occupied.pattern);
+  });
+});

package/src/lib/plan-status.ts

@@ -0,0 +1,147 @@
+/**
+ * Status on a plan — free desk, busy machine, line in alarm — without leaning on
+ * colour (WCAG 1.4.1).
+ *
+ * The MapLibre style spec decides how the channels split, and the split is not a
+ * matter of taste: `fill-pattern` and `line-dasharray` accept `zoom` and
+ * `feature` expressions but **not `feature-state`**, while `fill-color`,
+ * `fill-opacity`, `line-color` and `line-width` accept all three. So:
+ *
+ * - **status** rides feature PROPERTIES — pattern and dash, which cannot read
+ *   feature-state anyway;
+ * - **hover and selection** ride feature STATE — opacity, width and colour.
+ *
+ * The two can therefore never collide, and selection must never be expressed as
+ * a dash change: a selected free room would read as an occupied one.
+ *
+ * In greyscale each status still differs by four textures, four outline styles
+ * and, on the two states that must never be confused, a glyph — with the legend
+ * and the table repeating all of it as words.
+ */
+import { STATUS_TONE_ICONS } from "@elabs-ai/components-ui";
+import type { LucideIcon } from "lucide-react";
+
+/** What a region on a plan can be. */
+export type PlanStatus = "free" | "occupied" | "warning" | "down";
+
+/** Every {@link PlanStatus}, in legend order. */
+export const PLAN_STATUSES: readonly PlanStatus[] = ["free", "occupied", "warning", "down"];
+
+/** The generated hatch tile a status is textured with — see `lib/plan-patterns.ts`. */
+export type PlanPatternKind = "none" | "diagonal" | "cross" | "dense";
+
+/** The outline style a status is drawn with: the second non-colour channel. */
+export type PlanDash = "solid" | "dotted" | "dashed" | "dot-dash";
+
+/** MapLibre `line-dasharray` values, in line widths. `undefined` means solid. */
+const DASH_ARRAYS: Record<PlanDash, number[] | undefined> = {
+  solid: undefined,
+  dotted: [1, 1.5],
+  dashed: [3, 2],
+  "dot-dash": [4, 1.5, 1, 1.5],
+};
+
+export interface PlanStatusEncoding {
+  /** The status tone, for the token rungs below. */
+  tone: "success" | "neutral" | "warning" | "destructive";
+  /** The hatch tile registered with `map.addImage`. */
+  pattern: PlanPatternKind;
+  /** The outline style. */
+  dash: PlanDash;
+  /** `line-dasharray` for the outline; `undefined` keeps it solid. */
+  dashArray: number[] | undefined;
+  /**
+   * A glyph, on the two states that must never be confused with a working one.
+   * `undefined` elsewhere: a glyph on every neutral region is noise.
+   */
+  icon: LucideIcon | undefined;
+  /** Stable glyph name, so a test can assert the four states read apart. */
+  glyph: "none" | "clock" | "alert";
+  /** The token the shape's own ink resolves from (the ≥3:1 mark rung). */
+  colorToken: string;
+  /** Mark (fill-rung) utility, for a legend swatch. */
+  markClass: string;
+  /** Ink (`-text` rung) utility, for coloured text on an ordinary surface. */
+  textClass: string;
+}
+
+/**
+ * The one table every plan surface reads status from — map paint, legend, table
+ * and readout alike. Frozen, so a surface cannot quietly drift from the others.
+ */
+export const PLAN_STATUS_ENCODING: Readonly<Record<PlanStatus, PlanStatusEncoding>> = Object.freeze(
+  {
+    free: {
+      tone: "success",
+      pattern: "none",
+      dash: "solid",
+      dashArray: DASH_ARRAYS.solid,
+      icon: undefined,
+      glyph: "none",
+      colorToken: "--success",
+      markClass: "bg-success",
+      textClass: "text-success-text",
+    },
+    occupied: {
+      tone: "neutral",
+      pattern: "diagonal",
+      dash: "dotted",
+      dashArray: DASH_ARRAYS.dotted,
+      icon: undefined,
+      glyph: "none",
+      colorToken: "--muted-foreground",
+      markClass: "bg-muted-foreground",
+      textClass: "text-muted-foreground",
+    },
+    warning: {
+      tone: "warning",
+      pattern: "cross",
+      dash: "dashed",
+      dashArray: DASH_ARRAYS.dashed,
+      icon: STATUS_TONE_ICONS.warning,
+      glyph: "clock",
+      colorToken: "--warning",
+      markClass: "bg-warning",
+      textClass: "text-warning-text",
+    },
+    down: {
+      tone: "destructive",
+      pattern: "dense",
+      dash: "dot-dash",
+      dashArray: DASH_ARRAYS["dot-dash"],
+      icon: STATUS_TONE_ICONS.destructive,
+      glyph: "alert",
+      colorToken: "--destructive",
+      markClass: "bg-destructive",
+      textClass: "text-destructive-text",
+    },
+  },
+);
+
+/** Fill opacity per interaction state — the feature-state channel, in one place. */
+export const PLAN_FILL_OPACITY = Object.freeze({
+  rest: 0.16,
+  hover: 0.28,
+  selected: 0.36,
+});
+
+/**
+ * A MapLibre `match` expression over a status property, so one paint value can
+ * serve every status without a layer per status.
+ *
+ * ```ts
+ * "line-dasharray": planStatusMatch("status", (encoding) => encoding.dashArray ?? [1, 0])
+ * ```
+ */
+export function planStatusMatch<T>(
+  property: string,
+  value: (encoding: PlanStatusEncoding, status: PlanStatus) => T,
+  fallback?: T,
+): unknown[] {
+  const expression: unknown[] = ["match", ["get", property]];
+  for (const status of PLAN_STATUSES) {
+    expression.push(status, value(PLAN_STATUS_ENCODING[status], status));
+  }
+  expression.push(fallback ?? value(PLAN_STATUS_ENCODING.occupied, "occupied"));
+  return expression;
+}