@elabs-ai/components-maps 4.1.0 → 5.0.0

package/src/map-north-arrow/map-north-arrow.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+import { forwardRef, useEffect, useRef, useState, type HTMLAttributes } from "react";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+import { useMap } from "../map-canvas/map-context";
+import { MAP_CORNER_CLASSES, type MapCorner } from "../map-legend/map-corner";
+
+/** Below this rotation (degrees) the map counts as north-up and the arrow stays away. */
+const NORTH_UP_TOLERANCE = 0.5;
+
+/** A bearing folded into (-180, 180]. */
+function normalizeBearing(bearing: number): number {
+  const b = ((bearing % 360) + 360) % 360;
+  return b > 180 ? b - 360 : b;
+}
+
+export interface MapNorthArrowProps extends HTMLAttributes<HTMLDivElement> {
+  /** Corner of the map (default `"top-left"`). */
+  position?: MapCorner;
+  /** The arrow's accessible name (default `"North"`). */
+  label?: string;
+}
+
+/**
+ * A north arrow that appears only while the map is rotated (bearing ≠ 0) and
+ * turns with it — a north-up map needs none. Static furniture, not a control:
+ * `<MapControls showCompass>` is the button that resets the bearing. Render
+ * inside `<MapCanvas>`.
+ */
+export const MapNorthArrow = forwardRef<HTMLDivElement, MapNorthArrowProps>(function MapNorthArrow(
+  { position = "top-left", label = "North", className, ...props },
+  ref,
+) {
+  const { map } = useMap();
+  const glyphRef = useRef<SVGSVGElement>(null);
+  const [rotated, setRotated] = useState(false);
+
+  useEffect(() => {
+    if (!map) return undefined;
+    const update = () => {
+      const bearing = normalizeBearing(map.getBearing());
+      setRotated(Math.abs(bearing) > NORTH_UP_TOLERANCE);
+      if (glyphRef.current) glyphRef.current.style.transform = `rotate(${-bearing}deg)`;
+    };
+    update();
+    map.on("rotate", update);
+    return () => {
+      map.off("rotate", update);
+    };
+  }, [map]);
+
+  return (
+    <div
+      ref={ref}
+      role="img"
+      aria-label={label}
+      data-slot="map-north-arrow"
+      hidden={!rotated}
+      className={cn(
+        "pointer-events-none absolute z-10 flex size-9 items-center justify-center rounded-full bg-background/80 text-foreground",
+        MAP_CORNER_CLASSES[position],
+        className,
+      )}
+      {...props}
+    >
+      <svg ref={glyphRef} viewBox="0 0 24 24" aria-hidden="true" className="size-7">
+        {/* The arrow: dark north half, hollow south half. */}
+        <path d="M12 3 L16 13 L12 11 Z" fill="currentColor" />
+        <path d="M12 3 L8 13 L12 11 Z" fill="currentColor" opacity={0.55} />
+        {/* The cartographic "N", drawn as strokes so it is not locale text. */}
+        <path
+          d="M9.5 21 V15.5 L14.5 21 V15.5"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth={1.5}
+          strokeLinejoin="round"
+        />
+      </svg>
+    </div>
+  );
+});

package/src/map-plan/index.ts

@@ -0,0 +1,13 @@
+export {
+  MapPlanOverlay,
+  type MapPlanOverlayMode,
+  type MapPlanOverlayProps,
+} from "./map-plan-overlay";
+export { MapPlanLegend, type MapPlanLegendProps, type PlanStatusLabels } from "./map-plan-legend";
+export { MapPlanTable, type MapPlanTableColumn, type MapPlanTableProps } from "./map-plan-table";
+export { MapPlanStatus, type MapPlanStatusProps } from "./map-plan-status";
+export {
+  usePlanSelection,
+  type PlanSelection,
+  type UsePlanSelectionOptions,
+} from "./use-plan-selection";

package/src/map-plan/map-plan-legend.test.tsx

@@ -0,0 +1,61 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { PLAN_STATUSES } from "../lib/plan-status";
+import { MapPlanLegend } from "./map-plan-legend";
+
+const LABELS = {
+  free: "free",
+  occupied: "in use",
+  warning: "attention",
+  down: "stopped",
+};
+
+afterEach(cleanup);
+
+describe("MapPlanLegend", () => {
+  it("names every status in words, which is the channel greyscale keeps", () => {
+    render(<MapPlanLegend labels={LABELS} label="Status key" />);
+
+    const list = screen.getByRole("list", { name: "Status key" });
+    expect(screen.getAllByRole("listitem")).toHaveLength(PLAN_STATUSES.length);
+    for (const word of Object.values(LABELS)) {
+      expect(list).toHaveTextContent(word);
+    }
+  });
+
+  it("gives each swatch its own border style, so the key matches the outlines on the map", () => {
+    render(<MapPlanLegend labels={LABELS} />);
+
+    const swatches = document.querySelectorAll('[data-slot="map-plan-legend-swatch"]');
+    expect(swatches).toHaveLength(PLAN_STATUSES.length);
+    const styles = new Set(
+      [...swatches].map((swatch) =>
+        [...swatch.classList].filter((name) => name.startsWith("border")).join(" "),
+      ),
+    );
+    expect(styles.size).toBe(PLAN_STATUSES.length);
+  });
+
+  it("leaves out a status with no word, and renders nothing when none has one", () => {
+    const { rerender } = render(<MapPlanLegend labels={{ free: "free", down: "stopped" }} />);
+    expect(screen.getAllByRole("listitem")).toHaveLength(2);
+
+    rerender(<MapPlanLegend labels={{}} />);
+    expect(screen.queryByRole("list")).not.toBeInTheDocument();
+  });
+
+  it("shows a count beside the word when one is given", () => {
+    render(<MapPlanLegend labels={LABELS} counts={{ free: 4, down: 0 }} />);
+
+    expect(screen.getByText("4")).toBeInTheDocument();
+    expect(screen.getByText("0")).toBeInTheDocument();
+  });
+
+  it("orders the statuses as asked", () => {
+    render(<MapPlanLegend labels={LABELS} statuses={["down", "free"]} />);
+
+    const items = screen.getAllByRole("listitem").map((item) => item.getAttribute("data-status"));
+    expect(items).toEqual(["down", "free"]);
+  });
+});

package/src/map-plan/map-plan-legend.tsx

@@ -0,0 +1,83 @@
+"use client";
+
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+import { PLAN_STATUSES, PLAN_STATUS_ENCODING, type PlanStatus } from "../lib/plan-status";
+
+/** Words for each status, supplied by the consumer so they can be localized. */
+export type PlanStatusLabels = Partial<Record<PlanStatus, string>>;
+
+export interface MapPlanLegendProps {
+  /** The word for each status. A status with no word is left out of the legend. */
+  labels: PlanStatusLabels;
+  /** Only show these statuses, in this order. Defaults to all four, in table order. */
+  statuses?: readonly PlanStatus[];
+  /** Optional count per status, e.g. how many rooms are free right now. */
+  counts?: Partial<Record<PlanStatus, number>>;
+  /** Accessible name for the legend as a whole. */
+  label?: string;
+  className?: string;
+}
+
+/**
+ * The key to the plan's status channels — and the place a sighted user learns
+ * that the dashes and textures mean something.
+ *
+ * Each entry repeats the status three ways: the tone as a swatch, the outline
+ * style as a rule under it, and the word. The two states that must never be
+ * confused with a working one also carry their glyph. In greyscale the outline
+ * styles and the words still tell them apart.
+ */
+export function MapPlanLegend({
+  labels,
+  statuses = PLAN_STATUSES,
+  counts,
+  label,
+  className,
+}: MapPlanLegendProps) {
+  const entries = statuses.filter((status) => labels[status]);
+  if (entries.length === 0) return null;
+
+  return (
+    <ul
+      data-slot="map-plan-legend"
+      aria-label={label}
+      className={cn("flex flex-wrap items-center gap-x-5 gap-y-2", className)}
+    >
+      {entries.map((status) => {
+        const encoding = PLAN_STATUS_ENCODING[status];
+        const Icon = encoding.icon;
+        const count = counts?.[status];
+
+        return (
+          <li
+            key={status}
+            data-slot="map-plan-legend-item"
+            data-status={status}
+            className="flex items-center gap-2 text-caption text-foreground"
+          >
+            <span
+              data-slot="map-plan-legend-swatch"
+              aria-hidden="true"
+              className={cn(
+                "inline-block size-3 rounded-xs",
+                encoding.markClass,
+                // The outline style, as the swatch's own border: the same
+                // second channel the shape on the map carries.
+                encoding.dash === "solid" && "border border-foreground/40",
+                encoding.dash === "dotted" && "border border-dotted border-foreground/70",
+                encoding.dash === "dashed" && "border border-dashed border-foreground/70",
+                encoding.dash === "dot-dash" && "border-2 border-dashed border-foreground/70",
+              )}
+            />
+            {Icon && <Icon className={cn("size-3.5", encoding.textClass)} aria-hidden="true" />}
+            <span>{labels[status]}</span>
+            {count !== undefined && (
+              <span className="tabular-nums text-muted-foreground">{count}</span>
+            )}
+          </li>
+        );
+      })}
+    </ul>
+  );
+}

package/src/map-plan/map-plan-overlay.stories.tsx

@@ -0,0 +1,260 @@
+import { useMemo, useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect } from "storybook/test";
+import { StatePanel } from "@elabs-ai/components-ui";
+
+import { MapCanvas } from "../map-canvas";
+import { MapGeoJSON } from "../map-geojson";
+import { useTokenColor } from "../lib/use-token-color";
+import { planRegionsFromGeoJSON, type MapPlanRegion } from "../lib/plan-regions";
+import { PLAN_FILL_OPACITY, planStatusMatch, type PlanStatus } from "../lib/plan-status";
+import { MapPlanLegend } from "./map-plan-legend";
+import { MapPlanOverlay } from "./map-plan-overlay";
+import { MapPlanStatus } from "./map-plan-status";
+import { MapPlanTable } from "./map-plan-table";
+import { usePlanSelection } from "./use-plan-selection";
+
+const PLAN = { width: 1200, height: 600, unit: "cm" } as const;
+
+interface BayProperties {
+  id: string;
+  name: string;
+  /** Which half of the hall the bay sits in — the group, in group mode. */
+  side: string;
+  sideLabel: string;
+  status: PlanStatus;
+  [key: string]: unknown;
+}
+
+const STATE_WORD: Partial<Record<PlanStatus, string>> = {
+  free: "Free",
+  occupied: "In use",
+  warning: "Needs attention",
+  down: "Out of service",
+};
+
+/** Four bays, two a side: small enough to read in a story, big enough for group mode. */
+const BAYS: GeoJSON.FeatureCollection<GeoJSON.Polygon, BayProperties> = {
+  type: "FeatureCollection",
+  features: (
+    [
+      ["west-1", "Bay 1", "west", "West side", "free", 60, 60],
+      ["west-2", "Bay 2", "west", "West side", "occupied", 60, 330],
+      ["east-1", "Bay 3", "east", "East side", "warning", 640, 60],
+      ["east-2", "Bay 4", "east", "East side", "down", 640, 330],
+    ] as [string, string, string, string, PlanStatus, number, number][]
+  ).map(([id, name, side, sideLabel, status, x, y]) => ({
+    type: "Feature",
+    id,
+    properties: { id, name, side, sideLabel, status },
+    geometry: {
+      type: "Polygon",
+      coordinates: [
+        [
+          [x, y],
+          [x + 500, y],
+          [x + 500, y + 210],
+          [x, y + 210],
+          [x, y],
+        ],
+      ],
+    },
+  })),
+};
+
+const meta = {
+  title: "Maps/MapPlanOverlay",
+  component: MapPlanOverlay,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          'A shape drawn in WebGL is not a DOM element, so it cannot be focused, named or pressed. `MapPlanOverlay` puts one real `<button aria-pressed>` over each region of a plan — roving tabindex, arrow keys that travel the way the plan looks, `Enter` to select, `Escape` to clear — and projects the boxes in a single coalesced pass per frame.\n\nPast what a keyboard can reasonably walk (a train with 192 seats), `mode="groups"` puts one button on each group instead and `Enter` descends into its members. The parts beside it carry the same facts in other channels: `MapPlanLegend` says what the appearances mean, `MapPlanTable` is the plan as words, and `MapPlanStatus` is one polite live region per plan.',
+      },
+    },
+  },
+} satisfies Meta<typeof MapPlanOverlay>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+function bayState(region: MapPlanRegion) {
+  return BAYS.features.find((feature) => feature.properties.id === region.id)?.properties.status;
+}
+
+function BayLayers({
+  selectedId,
+  hoveredId,
+}: {
+  selectedId: readonly string[];
+  hoveredId: string | null;
+}) {
+  const primary = useTokenColor("--primary");
+  const free = useTokenColor("--success");
+  const busy = useTokenColor("--muted-foreground");
+  const warning = useTokenColor("--warning");
+  const down = useTokenColor("--destructive");
+  const tone: Record<PlanStatus, string> = { free, occupied: busy, warning, down };
+
+  return (
+    <MapGeoJSON<BayProperties>
+      id="bays"
+      data={BAYS}
+      promoteId="id"
+      selectedId={selectedId}
+      hoveredId={hoveredId}
+      fillPaint={{
+        "fill-color": planStatusMatch("status", (_encoding, status) => tone[status]) as never,
+        "fill-opacity": PLAN_FILL_OPACITY.rest,
+      }}
+      fillHoverPaint={{ "fill-opacity": PLAN_FILL_OPACITY.hover }}
+      fillSelectedPaint={{ "fill-opacity": PLAN_FILL_OPACITY.selected }}
+      // The dash is the STATE channel and reads feature properties; selection rides
+      // feature-state instead, so the two can never overwrite each other.
+      linePaint={{
+        "line-color": planStatusMatch("status", (_encoding, status) => tone[status]) as never,
+        "line-width": 1.75,
+        "line-dasharray": planStatusMatch("status", (encoding) => [
+          "literal",
+          encoding.dashArray ?? [1, 0],
+        ]) as never,
+      }}
+      lineSelectedPaint={{ "line-color": primary, "line-width": 3.5 }}
+    />
+  );
+}
+
+/** One button per region: the default, for a plan a keyboard can walk. */
+export const Default: Story = {
+  render: () => <PlanDemo />,
+  play: async ({ canvas }) => {
+    // The exact accessible name: the visible label comes first (WCAG 2.5.3), and if the
+    // browser ever fails to hand MapLibre a WebGL context this fails instead of passing
+    // on an error panel.
+    await expect(await canvas.findByRole("button", { name: "Bay 1, Free" })).toBeInTheDocument();
+    await expect(canvas.getByRole("list", { name: "Bays in this hall" })).toBeInTheDocument();
+  },
+};
+
+function PlanDemo({ mode = "regions" as const }: { mode?: "regions" | "groups" }) {
+  const regions = useMemo(
+    () =>
+      planRegionsFromGeoJSON(BAYS, {
+        id: "id",
+        label: "name",
+        description: (properties) => STATE_WORD[properties.status] ?? "",
+        group: "side",
+        groupLabel: "sideLabel",
+      }),
+    [],
+  );
+  const selection = usePlanSelection();
+  const [activeId, setActiveId] = useState<string | null>(null);
+
+  const selected = BAYS.features.find(
+    (feature) => feature.properties.id === selection.selectedId,
+  )?.properties;
+
+  return (
+    <div className="flex h-[620px] flex-col gap-3 p-4">
+      <MapPlanLegend labels={STATE_WORD} label="What each bay’s appearance means" />
+
+      <div className="relative min-h-0 flex-1 overflow-hidden rounded-md">
+        <MapCanvas blank plan={PLAN} className="h-full">
+          <BayLayers selectedId={selection.selectedIds} hoveredId={activeId} />
+          <MapPlanOverlay
+            regions={regions}
+            label="Bays in this hall"
+            mode={mode}
+            describeGroup={(group) => `${group.members.length} bays`}
+            selectedId={selection.selectedIds}
+            onSelect={(id) => selection.select(id)}
+            onActiveChange={setActiveId}
+          />
+        </MapCanvas>
+      </div>
+
+      <MapPlanStatus
+        message={selected ? `${selected.name} selected.` : "Nothing selected in this hall."}
+      />
+
+      <MapPlanTable
+        regions={regions}
+        caption="Every bay in the hall, with its state"
+        nameHeader="Bay"
+        status={bayState}
+        statusLabels={STATE_WORD}
+        statusHeader="State"
+        selectedId={selection.selectedIds}
+        onSelect={(id) => selection.select(id)}
+      />
+    </div>
+  );
+}
+
+/**
+ * Group mode: one button per group, `Enter` to go in, `Escape` to come back out,
+ * `PageUp`/`PageDown` to change group at either level.
+ */
+export const Groups: Story = {
+  render: () => <PlanDemo mode="groups" />,
+  play: async ({ canvas, userEvent }) => {
+    const side = await canvas.findByRole("button", { name: "West side, 2 bays" });
+    // A group's button is a way in, not a toggle.
+    await expect(side).not.toHaveAttribute("aria-pressed");
+    side.focus();
+    await userEvent.keyboard("{Enter}");
+    await expect(await canvas.findByRole("button", { name: "Bay 1, Free" })).toBeInTheDocument();
+    await userEvent.keyboard("{Escape}");
+    await expect(await canvas.findByRole("button", { name: "East side, 2 bays" })).toBeVisible();
+  },
+};
+
+/** The plan as words only — what a printer gets, since a WebGL canvas prints blank. */
+export const AsWords: Story = {
+  render: () => {
+    const regions = planRegionsFromGeoJSON(BAYS, { id: "id", label: "name" });
+    return (
+      <div className="space-y-3 p-4">
+        <p className="text-caption text-muted-foreground">
+          The same facts as the plan, in the channel that survives a printer and a screen reader. In
+          a plan meant for paper this table carries <code>printOnly</code>.
+        </p>
+        <MapPlanTable
+          regions={regions}
+          caption="Every bay in the hall, with its state"
+          nameHeader="Bay"
+          status={bayState}
+          statusLabels={STATE_WORD}
+          statusHeader="State"
+        />
+      </div>
+    );
+  },
+};
+
+/** Nothing on the plan yet: the canvas keeps its shape and says so once. */
+export const Loading: Story = {
+  render: () => (
+    <div className="h-[420px] p-4">
+      <MapCanvas blank plan={PLAN} loading className="h-full" />
+    </div>
+  ),
+};
+
+/** A plan with no regions on it — a panel, not an empty grid. */
+export const NoRegions: Story = {
+  render: () => (
+    <div className="relative h-[420px] p-4">
+      <MapCanvas blank plan={PLAN} className="h-full" />
+      <div className="absolute inset-0 grid place-items-center p-8">
+        <StatePanel
+          kind="empty"
+          title="No bays in this hall"
+          description="Import the hall’s bays to see them laid out here."
+        />
+      </div>
+    </div>
+  ),
+};