@elabs-ai/components-maps 4.2.0 → 5.1.0

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

@@ -0,0 +1,86 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import type { MapPlanRegion } from "../lib/plan-regions";
+import type { PlanStatus } from "../lib/plan-status";
+import { MapPlanTable } from "./map-plan-table";
+
+const REGIONS: MapPlanRegion[] = [
+  { id: "a1", label: "Cell A1", bounds: { x: 0, y: 0, width: 10, height: 10 } },
+  { id: "a2", label: "Cell A2", bounds: { x: 10, y: 0, width: 10, height: 10 } },
+];
+
+const STATUS: Record<string, PlanStatus> = { a1: "down", a2: "free" };
+
+afterEach(cleanup);
+
+describe("MapPlanTable", () => {
+  it("repeats the plan as words, one row per region", () => {
+    render(
+      <MapPlanTable
+        regions={REGIONS}
+        caption="Every cell on the line, with its state"
+        status={(region) => STATUS[region.id]}
+        statusLabels={{ down: "stopped", free: "free" }}
+        statusHeader="State"
+        columns={[{ key: "throughput", header: "Units/h", numeric: true, cell: () => 120 }]}
+      />,
+    );
+
+    const table = screen.getByRole("table", { name: "Every cell on the line, with its state" });
+    expect(table).toBeInTheDocument();
+    expect(screen.getAllByRole("row")).toHaveLength(REGIONS.length + 1);
+    // The status word is the point: a status that exists only as a colour on the
+    // canvas is invisible both to a screen reader and in greyscale.
+    expect(screen.getByText("stopped")).toBeInTheDocument();
+    expect(screen.getByText("free")).toBeInTheDocument();
+    expect(screen.getByRole("columnheader", { name: "State" })).toBeInTheDocument();
+  });
+
+  it("keeps a print-only table out of the screen layout but in the DOM", () => {
+    render(<MapPlanTable regions={REGIONS} caption="Cells" printOnly />);
+
+    const root = document.querySelector('[data-slot="map-plan-table"]')!;
+    expect(root.className).toContain("hidden");
+    expect(root.className).toContain("print:block");
+    expect(screen.getByRole("table")).toBeInTheDocument();
+  });
+
+  it("makes each row a second way to reach a region", async () => {
+    const user = userEvent.setup();
+    const onSelect = vi.fn();
+    render(<MapPlanTable regions={REGIONS} caption="Cells" onSelect={onSelect} />);
+
+    await user.click(screen.getByRole("button", { name: "Cell A2" }));
+
+    expect(onSelect).toHaveBeenCalledWith("a2", REGIONS[1]);
+  });
+
+  it("mirrors the selection, single id or many", () => {
+    const { rerender } = render(
+      <MapPlanTable regions={REGIONS} caption="Cells" onSelect={() => {}} selectedId="a1" />,
+    );
+    const rows = () => screen.getAllByRole("row").slice(1);
+    expect(rows().map((row) => row.getAttribute("aria-selected"))).toEqual(["true", "false"]);
+
+    rerender(
+      <MapPlanTable
+        regions={REGIONS}
+        caption="Cells"
+        onSelect={() => {}}
+        selectedId={["a1", "a2"]}
+      />,
+    );
+    expect(rows().map((row) => row.getAttribute("aria-selected"))).toEqual(["true", "true"]);
+  });
+
+  it("does not claim selectability when there is nothing to select", () => {
+    render(<MapPlanTable regions={REGIONS} caption="Cells" selectedId="a1" />);
+
+    for (const row of screen.getAllByRole("row").slice(1)) {
+      expect(row).not.toHaveAttribute("aria-selected");
+    }
+    expect(screen.queryByRole("button")).not.toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,153 @@
+"use client";
+
+import type { ReactNode } from "react";
+import {
+  Table,
+  TableBody,
+  TableCaption,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+import type { MapPlanRegion } from "../lib/plan-regions";
+import { PLAN_STATUS_ENCODING, type PlanStatus } from "../lib/plan-status";
+
+export interface MapPlanTableColumn {
+  /** Column key, used for the cell lookup and the React key. */
+  key: string;
+  /** Column header text. */
+  header: string;
+  /** Right-align the column — numbers belong on the end edge. */
+  numeric?: boolean;
+  /** The cell's content for one region. */
+  cell: (region: MapPlanRegion) => ReactNode;
+}
+
+export interface MapPlanTableProps {
+  /** The same regions the plan draws. */
+  regions: readonly MapPlanRegion[];
+  /** What the table is a table of ("Every room on level 3, with its state"). */
+  caption: string;
+  /** Extra columns after the name. The status column is built in when `status` is given. */
+  columns?: readonly MapPlanTableColumn[];
+  /** A region's status, if the plan has one. Adds a status column with the word. */
+  status?: (region: MapPlanRegion) => PlanStatus | undefined;
+  /** The word for each status — supplied by the consumer, so it can be localized. */
+  statusLabels?: Partial<Record<PlanStatus, string>>;
+  /** Header for the built-in status column. */
+  statusHeader?: string;
+  /** Header for the name column. */
+  nameHeader?: string;
+  /** The selected region id(s), mirrored as a row state. */
+  selectedId?: string | readonly string[] | null;
+  /** Called when a row is chosen — the table is a second way to reach a region. */
+  onSelect?: (id: string, region: MapPlanRegion) => void;
+  /**
+   * Hide the table on screen and keep it for print (default false). A WebGL
+   * canvas prints blank, so a plan that is meant to be printed needs this.
+   */
+  printOnly?: boolean;
+  className?: string;
+}
+
+/**
+ * The plan as words — the parallel channel for anyone who cannot see the canvas,
+ * for anyone who needs to sort or search it, and for the printer, which gets a
+ * blank rectangle where the WebGL canvas was.
+ *
+ * Visible by default rather than `sr-only`: the information is useful to
+ * everyone, and a hidden twin quietly rots.
+ */
+export function MapPlanTable({
+  regions,
+  caption,
+  columns,
+  status,
+  statusLabels,
+  statusHeader,
+  nameHeader = "Name",
+  selectedId,
+  onSelect,
+  printOnly = false,
+  className,
+}: MapPlanTableProps) {
+  const selected = selectedId == null ? [] : Array.isArray(selectedId) ? selectedId : [selectedId];
+
+  return (
+    <div data-slot="map-plan-table" className={cn(printOnly && "hidden print:block", className)}>
+      <Table>
+        <TableCaption>{caption}</TableCaption>
+        <TableHeader>
+          <TableRow>
+            <TableHead scope="col">{nameHeader}</TableHead>
+            {status && <TableHead scope="col">{statusHeader}</TableHead>}
+            {columns?.map((column) => (
+              <TableHead key={column.key} scope="col" className={column.numeric ? "text-end" : ""}>
+                {column.header}
+              </TableHead>
+            ))}
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {regions.map((region) => {
+            const regionStatus = status?.(region);
+            const encoding = regionStatus ? PLAN_STATUS_ENCODING[regionStatus] : undefined;
+            const isSelected = selected.includes(region.id);
+
+            return (
+              <TableRow
+                key={region.id}
+                data-slot="map-plan-table-row"
+                data-selected={isSelected || undefined}
+                data-status={regionStatus}
+                aria-selected={onSelect ? isSelected : undefined}
+              >
+                <TableCell>
+                  {onSelect ? (
+                    <button
+                      type="button"
+                      onClick={() => onSelect(region.id, region)}
+                      className="rounded-sm text-start focus-ring"
+                    >
+                      {region.label}
+                    </button>
+                  ) : (
+                    region.label
+                  )}
+                </TableCell>
+                {status && (
+                  <TableCell>
+                    {regionStatus && encoding ? (
+                      <span className="inline-flex items-center gap-1.5">
+                        {encoding.icon && (
+                          <encoding.icon
+                            className={cn("size-3.5", encoding.textClass)}
+                            aria-hidden="true"
+                          />
+                        )}
+                        <span className={encoding.textClass}>
+                          {statusLabels?.[regionStatus] ?? regionStatus}
+                        </span>
+                      </span>
+                    ) : null}
+                  </TableCell>
+                )}
+                {columns?.map((column) => (
+                  <TableCell
+                    key={column.key}
+                    className={column.numeric ? "text-end tabular-nums" : ""}
+                  >
+                    {column.cell(region)}
+                  </TableCell>
+                ))}
+              </TableRow>
+            );
+          })}
+        </TableBody>
+      </Table>
+    </div>
+  );
+}

package/src/map-plan/use-plan-selection.ts

@@ -0,0 +1,78 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+
+export interface UsePlanSelectionOptions {
+  /** Allow more than one region to be selected at a time (default false). */
+  multiple?: boolean;
+  /** The ids selected to begin with. */
+  initialSelectedIds?: readonly string[];
+  /** Called whenever the selection changes. */
+  onChange?: (selectedIds: string[]) => void;
+}
+
+export interface PlanSelection {
+  /** The single selected id, or the last of a multiple selection; `null` for none. */
+  selectedId: string | null;
+  /** Every selected id, in selection order. */
+  selectedIds: string[];
+  isSelected: (id: string) => boolean;
+  /** Toggle a region; `null` clears everything. */
+  select: (id: string | null) => void;
+  clear: () => void;
+}
+
+/**
+ * Selection state for a plan, keyed by region **id** rather than index — a
+ * status tick that re-orders the regions must not move the selection with it.
+ *
+ * Hand `selectedIds` to `<MapGeoJSON selectedId>` for the paint and to
+ * `<MapPlanOverlay selectedId>` for the pressed state, so both read one source.
+ */
+export function usePlanSelection({
+  multiple = false,
+  initialSelectedIds,
+  onChange,
+}: UsePlanSelectionOptions = {}): PlanSelection {
+  const [selectedIds, setSelectedIds] = useState<string[]>(() => [...(initialSelectedIds ?? [])]);
+
+  const commit = useCallback(
+    (next: string[]) => {
+      setSelectedIds(next);
+      onChange?.(next);
+    },
+    [onChange],
+  );
+
+  const select = useCallback(
+    (id: string | null) => {
+      if (id === null) {
+        commit([]);
+        return;
+      }
+      setSelectedIds((current) => {
+        const next = current.includes(id)
+          ? current.filter((entry) => entry !== id)
+          : multiple
+            ? [...current, id]
+            : [id];
+        onChange?.(next);
+        return next;
+      });
+    },
+    [commit, multiple, onChange],
+  );
+
+  const clear = useCallback(() => commit([]), [commit]);
+
+  return useMemo(
+    () => ({
+      selectedId: selectedIds.at(-1) ?? null,
+      selectedIds,
+      isSelected: (id: string) => selectedIds.includes(id),
+      select,
+      clear,
+    }),
+    [selectedIds, select, clear],
+  );
+}

package/src/map-plan-image/index.ts

@@ -0,0 +1 @@
+export { MapPlanImage, type MapPlanImageProps, type MapPlanImageSource } from "./map-plan-image";

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

@@ -0,0 +1,301 @@
+import { useEffect, useRef, 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 { MapPlanImage } from "./map-plan-image";
+
+/**
+ * A small plan, so the story is about the PICTURE rather than about a building:
+ * 1200 × 600 of whatever unit the caller works in.
+ */
+const PLAN = { width: 1200, height: 600, unit: "cm" } as const;
+
+/** Two rooms and a corridor, in plan units — the ink that sits on the picture. */
+const SHAPES: GeoJSON.FeatureCollection<GeoJSON.Polygon, { id: string; name: string }> = {
+  type: "FeatureCollection",
+  features: [
+    {
+      type: "Feature",
+      id: "west",
+      properties: { id: "west", name: "West wing" },
+      geometry: {
+        type: "Polygon",
+        coordinates: [
+          [
+            [60, 60],
+            [560, 60],
+            [560, 540],
+            [60, 540],
+            [60, 60],
+          ],
+        ],
+      },
+    },
+    {
+      type: "Feature",
+      id: "east",
+      properties: { id: "east", name: "East wing" },
+      geometry: {
+        type: "Polygon",
+        coordinates: [
+          [
+            [640, 60],
+            [1140, 60],
+            [1140, 540],
+            [640, 540],
+            [640, 60],
+          ],
+        ],
+      },
+    },
+  ],
+};
+
+/**
+ * Stands in for a scan or a CAD export: a grid drawn onto a canvas, which is one of
+ * the sources `MapPlanImage` takes as-is. `hue` shifts the drawing so a floor swap
+ * is visible without a second asset.
+ */
+function usePlanDrawing(ink: string, step = 100) {
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const [drawing, setDrawing] = useState<HTMLCanvasElement | null>(null);
+
+  useEffect(() => {
+    const canvas = canvasRef.current ?? document.createElement("canvas");
+    canvasRef.current = canvas;
+    canvas.width = PLAN.width;
+    canvas.height = PLAN.height;
+    const context = canvas.getContext("2d");
+    if (!context) return;
+    context.clearRect(0, 0, canvas.width, canvas.height);
+    context.strokeStyle = ink;
+    context.lineWidth = 2;
+    for (let x = 0; x <= canvas.width; x += step) {
+      context.beginPath();
+      context.moveTo(x, 0);
+      context.lineTo(x, canvas.height);
+      context.stroke();
+    }
+    for (let y = 0; y <= canvas.height; y += step) {
+      context.beginPath();
+      context.moveTo(0, y);
+      context.lineTo(canvas.width, y);
+      context.stroke();
+    }
+    setDrawing(canvas);
+  }, [ink, step]);
+
+  return drawing;
+}
+
+const meta = {
+  title: "Maps/MapPlanImage",
+  component: MapPlanImage,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "The custom background picture of a plan map: a floor plan, a scanned drawing, a CAD export or a canvas, laid out in the plan’s own units rather than on a world map. It takes a URL, a decoded image, a bitmap or a canvas, covers the whole plan by default, and accepts an `extent` in plan units for one wing of it. A swap goes through the existing source, so nothing refetches and nothing cross-fades.\n\nThe picture is context and the data on top is the ink — hold a drawing with baked-in colours back at low opacity, or leave it out and draw the plan as shapes, which themes correctly and never blurs.",
+      },
+    },
+  },
+} satisfies Meta<typeof MapPlanImage>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** The whole plan: the picture underneath, the shapes on top. */
+export const Default: Story = {
+  render: () => <PictureUnderShapes />,
+  play: async ({ canvas }) => {
+    // The picture's own parallel channel: `alt` is the one thing about a WebGL raster
+    // that assistive technology can read, so the story locks it.
+    await expect(await canvas.findByText("Survey grid, one square per metre")).toBeInTheDocument();
+  },
+};
+
+function PictureUnderShapes() {
+  return (
+    <div className="h-[420px] p-4">
+      <MapCanvas blank plan={PLAN} className="h-full">
+        <Layers />
+      </MapCanvas>
+    </div>
+  );
+}
+
+function Layers({ extent }: { extent?: { x: number; y: number; width: number; height: number } }) {
+  const ink = useTokenColor("--border-strong");
+  const outline = useTokenColor("--foreground");
+  const drawing = usePlanDrawing(ink);
+
+  return (
+    <>
+      {drawing && (
+        <MapPlanImage
+          id="drawing"
+          src={drawing}
+          extent={extent}
+          alt="Survey grid, one square per metre"
+          opacity={0.35}
+          resampling="nearest"
+        />
+      )}
+      <MapGeoJSON
+        id="wings"
+        data={SHAPES}
+        promoteId="id"
+        interactive={false}
+        fillPaint={false}
+        linePaint={{ "line-color": outline, "line-width": 2 }}
+      />
+    </>
+  );
+}
+
+/** One wing only: `extent` places the picture in plan units, not across the whole plan. */
+export const OverOneWing: Story = {
+  render: () => (
+    <div className="h-[420px] p-4">
+      <MapCanvas blank plan={PLAN} className="h-full">
+        <Layers extent={{ x: 640, y: 60, width: 500, height: 480 }} />
+      </MapCanvas>
+    </div>
+  ),
+};
+
+/** A floor swap: the same source, a new drawing — no refetch, no cross-fade. */
+export const FloorSwap: Story = {
+  render: () => {
+    function Demo() {
+      const [fine, setFine] = useState(false);
+      return (
+        <div className="flex h-[460px] flex-col gap-3 p-4">
+          <label className="flex items-center gap-2 text-caption">
+            <input
+              type="checkbox"
+              checked={fine}
+              onChange={(event) => setFine(event.target.checked)}
+            />
+            Half-metre grid
+          </label>
+          <div className="min-h-0 flex-1">
+            <MapCanvas blank plan={PLAN} className="h-full">
+              <SwappedDrawing step={fine ? 50 : 100} />
+            </MapCanvas>
+          </div>
+          <p className="text-meta text-muted-foreground">
+            The grid ink is a semantic token, resolved inside the canvas — WebGL cannot read a CSS
+            variable.
+          </p>
+        </div>
+      );
+    }
+    return <Demo />;
+  },
+};
+
+function SwappedDrawing({ step }: { step: number }) {
+  const ink = useTokenColor("--border-strong");
+  const drawing = usePlanDrawing(ink, step);
+  return drawing ? (
+    <MapPlanImage id="drawing" src={drawing} alt={`Survey grid, ${step} cm squares`} />
+  ) : null;
+}
+
+/** `visible={false}` toggles the layer’s visibility; the source stays, so nothing reloads. */
+export const Hidden: Story = {
+  render: () => {
+    function Demo() {
+      const [shown, setShown] = useState(false);
+      return (
+        <div className="flex h-[460px] flex-col gap-3 p-4">
+          <label className="flex items-center gap-2 text-caption">
+            <input
+              type="checkbox"
+              checked={shown}
+              onChange={(event) => setShown(event.target.checked)}
+            />
+            Show the drawing
+          </label>
+          <div className="min-h-0 flex-1">
+            <MapCanvas blank plan={PLAN} className="h-full">
+              <ToggledDrawing visible={shown} />
+            </MapCanvas>
+          </div>
+        </div>
+      );
+    }
+    return <Demo />;
+  },
+};
+
+function ToggledDrawing({ visible }: { visible: boolean }) {
+  const ink = useTokenColor("--border-strong");
+  const drawing = usePlanDrawing(ink);
+  return drawing ? (
+    <MapPlanImage id="drawing" src={drawing} visible={visible} alt="Survey grid" />
+  ) : null;
+}
+
+/** Nothing loaded yet: the canvas keeps the plan’s 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>
+  ),
+};
+
+/**
+ * The picture failed; the plan did not. `onError` reports it and the shapes stay, so
+ * the consumer decides what the gap should look like.
+ */
+export const MissingPicture: Story = {
+  render: () => {
+    function Demo() {
+      const [failed, setFailed] = useState(false);
+      return (
+        <div className="flex h-[460px] flex-col gap-2 p-4">
+          {failed && (
+            <StatePanel
+              kind="error"
+              title="Floor drawing unavailable"
+              description="The plan is still usable — every wing is drawn from its own coordinates."
+            />
+          )}
+          <div className="min-h-0 flex-1">
+            <MapCanvas blank plan={PLAN} className="h-full">
+              <MapPlanImage
+                id="drawing"
+                src="./missing-drawing.png"
+                onError={() => setFailed(true)}
+              />
+              <ShapesOnly />
+            </MapCanvas>
+          </div>
+        </div>
+      );
+    }
+    return <Demo />;
+  },
+};
+
+function ShapesOnly() {
+  const outline = useTokenColor("--foreground");
+  return (
+    <MapGeoJSON
+      id="wings"
+      data={SHAPES}
+      promoteId="id"
+      interactive={false}
+      fillPaint={false}
+      linePaint={{ "line-color": outline, "line-width": 2 }}
+    />
+  );
+}