mapped-image 0.1.0

package/MappedImage.tsx

@@ -0,0 +1,84 @@
+import { useState } from "react";
+import "leaflet/dist/leaflet.css";
+import "./MappedImage.css";
+import type { ICellClickProps, ImageSelectorProps, MappedImageProps } from "./types";
+import { DefaultImageSelector } from "./components/DefaultImageSelector";
+import { ImageLayer } from "./components/ImageLayer";
+
+export const MappedImage = (props: MappedImageProps) => {
+    if (props.images.length === 0) {
+        throw new Error("MappedImage requires at least one entry in `images`.");
+    }
+
+    const invalidImage = props.images.find((image) => image.rows <= 0 || image.columns <= 0);
+    if (invalidImage) {
+        throw new Error(
+            `MappedImage: image "${invalidImage.name}" must have rows > 0 and columns > 0.`,
+        );
+    }
+
+    const [internalSelectedCells, setInternalSelectedCells] = useState<Set<string>>(
+        props.selectedCells ?? new Set(),
+    );
+    const isSelectionControlled = props.selectedCells !== undefined;
+    const selectedCells = isSelectionControlled ? props.selectedCells! : internalSelectedCells;
+
+    const [selectedImageIndex, setSelectedImageIndex] = useState(
+        props.selectedImageIndex ?? 0,
+    );
+
+    const selectedImage = props.images[selectedImageIndex];
+    const colOffset = props.images
+        .slice(0, selectedImageIndex)
+        .reduce((sum, image) => sum + image.columns, 0);
+    const rowOffset = props.images
+        .slice(0, selectedImageIndex)
+        .reduce((sum, image) => sum + image.rows, 0);
+
+    const handleSelectImage = (index: number) => {
+        setSelectedImageIndex(index);
+        props.onSelectedImageIndexChange?.(index);
+    };
+
+    const handleCellClick = ({ row, col }: ICellClickProps) => {
+        const cellId = `${row},${col}`;
+        const next = new Set(selectedCells);
+        if (next.has(cellId)) {
+            next.delete(cellId);
+        } else {
+            next.add(cellId);
+        }
+
+        if (!isSelectionControlled) {
+            setInternalSelectedCells(next);
+        }
+        props.onSelectedCellsChange?.(next);
+        props.onCellClick?.({ row, col });
+    };
+
+    const renderSelector = props.renderImageSelector ?? (
+        (selectorProps: ImageSelectorProps) => <DefaultImageSelector {...selectorProps} />
+    );
+
+    return (
+        <div style={{ position: "relative", width: props.width, height: props.height }}>
+            <ImageLayer
+                key={selectedImage.src}
+                image={selectedImage}
+                colOffset={colOffset}
+                rowOffset={rowOffset}
+                width={props.width}
+                height={props.height}
+                alt={props.alt}
+                selectedCells={selectedCells}
+                maxBoundsPadding={props.maxBoundsPadding}
+                onCellClick={handleCellClick}
+            />
+            {renderSelector({
+                images: props.images,
+                selectedIndex: selectedImageIndex,
+                onSelect: handleSelectImage,
+            })}
+        </div>
+    );
+};

package/README.md

@@ -0,0 +1,75 @@
+# mapped-image
+
+A React component that overlays a clickable row/column grid on top of one or more images, built on [react-leaflet](https://react-leaflet.js.org/). Useful for marking specific regions of a part photographed from multiple angles, where rows and columns continue numbering across angles since they represent the same physical surface.
+
+## Install
+
+```bash
+npm install github:notetuwu/mapped-image
+```
+
+`leaflet` and `react-leaflet` are declared as dependencies and installed automatically. `react` and `react-dom` are peer dependencies, resolved from your app.
+
+> **Note:** this package currently ships untranspiled `.tsx` source (no build step) and is intended to be installed straight from this repository's source. Your app's own bundler is expected to compile it. If you instead need a pre-built `dist` (ESM/CJS + type declarations) for non-TS-aware consumers, that's not set up yet.
+
+## Usage
+
+```tsx
+import { MappedImage } from "mapped-image/MappedImage";
+
+<MappedImage
+  images={[
+    { name: "Front", src: "/front.png", columns: 5, rows: 5 },
+    { name: "Side", src: "/side.png", columns: 3, rows: 5 },
+  ]}
+  alt="Engine block"
+  width={800}
+  height={800}
+  onCellClick={({ row, col }) => console.log(row, col)}
+  onSelectedCellsChange={(cells) => console.log(cells)}
+/>
+```
+
+Clicking a cell toggles its selection (filled red) and reports the cell's row number / column letter. Both axes are numbered continuously across `images` — e.g. the "Side" image above picks up at column `F` (since "Front" used `A`-`E`) and would pick up at row `6` if "Front" had 5 rows. The same letter+number pair always identifies the same physical location, regardless of which image happens to be selected — useful since all images represent different angles of the same physical part.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `images` | `ImageConfig[]` | Required. The set of selectable angle images — see below. |
+| `alt` | `string` | Alt text for the currently displayed image. |
+| `width` / `height` | `number` | Pixel size of the rendered component. The image is scaled to fit without distortion (letterboxed if its aspect ratio doesn't match). |
+| `selectedCells` | `Set<string>` | Selection, as `"<row>,<colLetter>"` ids (e.g. `"3,F"`). If provided, the component is **fully controlled**: it's your responsibility to update it (typically in `onSelectedCellsChange`) for clicks to visibly toggle. Omit it to let the component manage selection internally instead. |
+| `selectedImageIndex` | `number` | Optional initial selected image index. Uncontrolled after mount. |
+| `onCellClick` | `({ row, col }) => void` | Fires on every cell click, `row` is a 1-based number from the top, `col` is the letter label. |
+| `onSelectedCellsChange` | `(cells: Set<string>) => void` | Fires whenever a cell is toggled, with the resulting selection. Required if `selectedCells` is controlled — also useful for persisting/exporting the selection (e.g. from an external editor). |
+| `onSelectedImageIndexChange` | `(index: number) => void` | Fires whenever the active image changes. |
+| `renderImageSelector` | `(props: ImageSelectorProps) => ReactNode` | Optional override for the image-switcher UI rendered over the map. Defaults to a row of buttons; pass your own to fully customize it, or build your own selector entirely outside this component using the controlled `selectedImageIndex`/`onSelectedImageIndexChange` props instead. |
+| `maxBoundsPadding` | `number` | Extra pannable margin, in pixels, beyond the image edges. Defaults to `50`. |
+
+### `ImageConfig`
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Label shown in the default image selector. |
+| `src` | `string` | Image URL. |
+| `columns` | `number` | Number of columns in this image's grid. |
+| `rows` | `number` | Number of rows in this image's grid. |
+| `columnWeights` | `Record<number, number>` | Optional relative width overrides, keyed by 0-based column index (default weight is `1`). Only needs entries for the columns that aren't uniform width — e.g. `{ 2: 3 }` makes column index 2 three times as wide as the others. |
+| `rowWeights` | `Record<number, number>` | Same as `columnWeights`, but for row heights. |
+
+> Both `rows`/`columns` must be greater than `0`.
+
+## Building an editor
+
+This package intentionally exposes `selectedImageIndex`/`onSelectedImageIndexChange` and a controllable `selectedCells`/`onSelectedCellsChange` so a separate editor app (outside this package) can drive the grid entirely from its own state — e.g. to add/remove rows and columns, adjust `columnWeights`/`rowWeights`, and persist the resulting `ImageConfig[]` plus selection as a JSON config to reload later. There's no editor UI in this package itself.
+
+## Development
+
+```bash
+npm install
+npm run dev    # demo app in src/App.tsx
+npm test       # unit tests
+npm run lint
+npm run build  # typecheck + build the demo app
+```

package/components/DefaultImageSelector.tsx

@@ -0,0 +1,33 @@
+import type { ImageSelectorProps } from "../types";
+
+export const DefaultImageSelector = ({ images, selectedIndex, onSelect }: ImageSelectorProps) => (
+    <div
+        style={{
+            position: "absolute",
+            top: 10,
+            right: 10,
+            zIndex: 1000,
+            display: "flex",
+            gap: 8,
+        }}
+    >
+        {images.map((image, index) => (
+            <button
+                key={image.name}
+                type="button"
+                onClick={() => onSelect(index)}
+                style={{
+                    padding: "12px 20px",
+                    fontSize: 16,
+                    fontWeight: index === selectedIndex ? "bold" : "normal",
+                    background: index === selectedIndex ? "#3388ff" : "white",
+                    color: index === selectedIndex ? "white" : "black",
+                    border: "1px solid #3388ff",
+                    borderRadius: 6,
+                }}
+            >
+                {image.name}
+            </button>
+        ))}
+    </div>
+);

package/components/Grid.tsx

@@ -0,0 +1,84 @@
+import { Rectangle, Marker } from "react-leaflet";
+import type { LatLngBoundsExpression } from "leaflet";
+import type { GridProps } from "../types";
+import { weightOffsets } from "../helpers/weights";
+import { headerIcon } from "../helpers/headerIcon";
+import { bindCellAccessibility } from "../helpers/cellAccessibility";
+
+export const Grid = ({
+    rows,
+    rowOffset,
+    rowWeights,
+    columnLabels,
+    columnWeights,
+    imgBounds,
+    selectedCells,
+    onCellClick,
+}: GridProps) => {
+    const [height, width] = imgBounds;
+
+    const colOffsets = weightOffsets(columnWeights);
+    const pxPerColWeightUnit = width / colOffsets[colOffsets.length - 1];
+    const colLeft = (colCount: number) => colOffsets[colCount] * pxPerColWeightUnit;
+    const colRight = (colCount: number) => colOffsets[colCount + 1] * pxPerColWeightUnit;
+
+    const rowOffsets = weightOffsets(rowWeights);
+    const pxPerRowWeightUnit = height / rowOffsets[rowOffsets.length - 1];
+    const rowBottom = (rowCount: number) => rowOffsets[rowCount] * pxPerRowWeightUnit;
+    const rowTop = (rowCount: number) => rowOffsets[rowCount + 1] * pxPerRowWeightUnit;
+
+    const cells = Array.from({ length: rows }).map((_, rowCount) =>
+        columnLabels.map((columnLabel, colCount) => {
+            const bounds: LatLngBoundsExpression = [
+                [rowTop(rowCount), colRight(colCount)],
+                [rowBottom(rowCount), colLeft(colCount)],
+            ];
+
+            const rowLabel = rowOffset + (rows - rowCount);
+            const cellId = `${rowLabel},${columnLabel}`;
+            const selected = selectedCells.has(cellId);
+            const activate = () => onCellClick?.({ col: columnLabel, row: rowLabel });
+
+            return (
+                <Rectangle
+                    key={cellId}
+                    ref={(instance) =>
+                        bindCellAccessibility(instance, `${columnLabel}${rowLabel}`, selected, activate)
+                    }
+                    bounds={bounds}
+                    pathOptions={{
+                        fillColor: selected ? "red" : "transparent",
+                        fillOpacity: selected ? 0.5 : 0,
+                        weight: 1.5,
+                    }}
+                    eventHandlers={{
+                        click: activate,
+                    }}
+                />
+            );
+        }),
+    );
+
+    const columnHeaders = columnLabels.map((columnLabel, colCount) => (
+        <Marker
+            key={`col-${columnLabel}`}
+            position={[height, (colLeft(colCount) + colRight(colCount)) / 2]}
+            icon={headerIcon(columnLabel, "grid-header-label--column")}
+            interactive={false}
+        />
+    ));
+
+    const rowHeaders = Array.from({ length: rows }).map((_, rowCount) => {
+        const rowLabel = rowOffset + (rows - rowCount);
+        return (
+            <Marker
+                key={`row-${rowLabel}`}
+                position={[(rowBottom(rowCount) + rowTop(rowCount)) / 2, -7]}
+                icon={headerIcon(String(rowLabel), "grid-header-label--row")}
+                interactive={false}
+            />
+        );
+    });
+
+    return [...cells, columnHeaders, rowHeaders];
+};

package/components/ImageLayer.tsx

@@ -0,0 +1,69 @@
+import { useEffect, useState } from "react";
+import { CRS, type LatLngBoundsExpression, type LatLngTuple } from "leaflet";
+import { MapContainer, ImageOverlay } from "react-leaflet";
+import type { ImageLayerProps } from "../types";
+import { Grid } from "./Grid";
+import { imageBounds } from "../helpers/imageBounds";
+import { colNames } from "../helpers/colNames";
+import { resolveWeights } from "../helpers/weights";
+
+export const ImageLayer = ({
+    image,
+    colOffset,
+    rowOffset,
+    width,
+    height,
+    alt,
+    selectedCells,
+    maxBoundsPadding = 100,
+    onCellClick,
+}: ImageLayerProps) => {
+    const [imgBounds, setImgBounds] = useState<LatLngTuple | null>(null);
+    const [loadError, setLoadError] = useState<Error | null>(null);
+
+    useEffect(() => {
+        imageBounds(image.src, width, height).then(setImgBounds).catch(setLoadError);
+    }, [image.src, width, height]);
+
+    if (loadError) {
+        throw loadError;
+    }
+
+    if (!imgBounds) {
+        return null;
+    }
+
+    const [imgHeight, imgWidth] = imgBounds;
+    const bounds: LatLngBoundsExpression = [[0, 0], imgBounds];
+    const maxBounds: LatLngBoundsExpression = [
+        [-maxBoundsPadding , -maxBoundsPadding],
+        [imgHeight + maxBoundsPadding, imgWidth + maxBoundsPadding],
+    ];
+    const columnLabels = colNames(colOffset, image.columns);
+    const columnWeights = resolveWeights(image.columns, image.columnWeights);
+    const rowWeights = resolveWeights(image.rows, image.rowWeights);
+
+    return (
+        <MapContainer
+            crs={CRS.Simple}
+            bounds={bounds}
+            boundsOptions={{ padding: [50, 50] }}
+            maxBounds={maxBounds}
+            maxBoundsViscosity={0.5}
+            style={{ width, height }}
+            maxZoom={2}
+        >
+            <Grid
+                rows={image.rows}
+                rowOffset={rowOffset}
+                rowWeights={rowWeights}
+                columnLabels={columnLabels}
+                columnWeights={columnWeights}
+                imgBounds={imgBounds}
+                selectedCells={selectedCells}
+                onCellClick={onCellClick}
+            />
+            <ImageOverlay url={image.src} bounds={bounds} alt={alt} />
+        </MapContainer>
+    );
+};

package/helpers/cellAccessibility.ts

@@ -0,0 +1,28 @@
+import type { Rectangle as LeafletRectangle } from "leaflet";
+
+// Path.getElement() returns the underlying SVG node but isn't declared in @types/leaflet, hence the cast.
+const getPathElement = (instance: LeafletRectangle) =>
+    (instance as unknown as { getElement(): SVGElement | undefined }).getElement();
+
+export const bindCellAccessibility = (
+    instance: LeafletRectangle | null,
+    label: string,
+    selected: boolean,
+    onActivate: () => void,
+) => {
+    const el = instance && getPathElement(instance);
+    if (!el) {
+        return;
+    }
+
+    el.setAttribute("role", "button");
+    el.setAttribute("tabindex", "0");
+    el.setAttribute("aria-label", label);
+    el.setAttribute("aria-pressed", String(selected));
+    el.onkeydown = (e) => {
+        if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            onActivate();
+        }
+    };
+};

package/helpers/colNames.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { colNames } from "./colNames";
+
+describe("colNames", () => {
+    it("generates the first 26 letters starting from offset 0", () => {
+        expect(colNames(0, 3)).toEqual(["A", "B", "C"]);
+    });
+
+    it("wraps into double letters after Z", () => {
+        expect(colNames(24, 4)).toEqual(["Y", "Z", "AA", "AB"]);
+    });
+
+    it("continues from a non-zero offset, as used for multi-image column continuity", () => {
+        expect(colNames(5, 3)).toEqual(["F", "G", "H"]);
+    });
+
+    it("returns an empty array for a zero count", () => {
+        expect(colNames(0, 0)).toEqual([]);
+    });
+});

package/helpers/colNames.ts

@@ -0,0 +1,15 @@
+const toColumnLetter = (n: number): string => {
+    let result = "";
+    let remaining = n;
+
+    while (remaining > 0) {
+        const remainder = (remaining - 1) % 26;
+        result = String.fromCharCode(65 + remainder) + result;
+        remaining = Math.floor((remaining - 1) / 26);
+    }
+
+    return result;
+};
+
+export const colNames = (startIndex: number, count: number): string[] =>
+    Array.from({ length: count }, (_, i) => toColumnLetter(startIndex + i + 1));

package/helpers/headerIcon.ts

@@ -0,0 +1,8 @@
+import { divIcon } from "leaflet";
+
+export const headerIcon = (label: string, className: string) =>
+    divIcon({
+        html: `<span class="grid-header-label ${className}">${label}</span>`,
+        className: "grid-header-label-icon",
+        iconSize: [0, 0],
+    });

package/helpers/imageBounds.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { imageBounds } from "./imageBounds";
+
+class FakeImage {
+    width: number;
+    height: number;
+    shouldError: boolean;
+    onload: (() => void) | null = null;
+    onerror: (() => void) | null = null;
+
+    constructor(width: number, height: number, shouldError: boolean) {
+        this.width = width;
+        this.height = height;
+        this.shouldError = shouldError;
+    }
+
+    set src(_value: string) {
+        queueMicrotask(() => {
+            if (this.shouldError) {
+                this.onerror?.();
+            } else {
+                this.onload?.();
+            }
+        });
+    }
+}
+
+const stubImage = (width: number, height: number, shouldError = false) => {
+    vi.stubGlobal(
+        "Image",
+        class {
+            constructor() {
+                return new FakeImage(width, height, shouldError);
+            }
+        },
+    );
+};
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+});
+
+describe("imageBounds", () => {
+    it("scales by the limiting dimension, preserving aspect ratio (width-constrained)", async () => {
+        stubImage(400, 200);
+        const bounds = await imageBounds("img.png", 100, 100);
+        expect(bounds).toEqual([50, 100]);
+    });
+
+    it("scales by the limiting dimension, preserving aspect ratio (height-constrained)", async () => {
+        stubImage(200, 400);
+        const bounds = await imageBounds("img.png", 100, 100);
+        expect(bounds).toEqual([100, 50]);
+    });
+
+    it("rejects when the image fails to load", async () => {
+        stubImage(0, 0, true);
+        await expect(imageBounds("missing.png", 100, 100)).rejects.toThrow(
+            "Failed to load image: missing.png",
+        );
+    });
+});

package/helpers/imageBounds.ts

@@ -0,0 +1,12 @@
+import type { LatLngTuple } from "leaflet";
+
+export const imageBounds = (src: string, containerWidth: number, containerHeight: number): Promise<LatLngTuple> =>
+    new Promise((resolve, reject) => {
+        const img = new Image();
+        img.src = src;
+        img.onload = () => {
+            const scale = Math.min(containerWidth / img.width, containerHeight / img.height);
+            resolve([img.height * scale, img.width * scale]);
+        };
+        img.onerror = () => reject(new Error(`Failed to load image: ${src}`));
+    });

package/helpers/weights.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { resolveWeights, weightOffsets } from "./weights";
+
+describe("resolveWeights", () => {
+    it("defaults every index to weight 1 with no overrides", () => {
+        expect(resolveWeights(4)).toEqual([1, 1, 1, 1]);
+    });
+
+    it("applies overrides only to the specified indices", () => {
+        expect(resolveWeights(4, { 2: 3 })).toEqual([1, 1, 3, 1]);
+    });
+});
+
+describe("weightOffsets", () => {
+    it("returns cumulative offsets starting at 0, ending at the total weight", () => {
+        expect(weightOffsets([1, 1, 3, 1])).toEqual([0, 1, 2, 5, 6]);
+    });
+
+    it("returns [0] for an empty weight list", () => {
+        expect(weightOffsets([])).toEqual([0]);
+    });
+});

package/helpers/weights.ts

@@ -0,0 +1,11 @@
+export const resolveWeights = (
+    count: number,
+    overrides: Record<number, number> = {},
+): number[] => Array.from({ length: count }, (_, i) => overrides[i] ?? 1);
+
+/** Cumulative leading edge (in weight units) of each index, plus the total at the end. */
+export const weightOffsets = (weights: number[]): number[] => {
+    const offsets = [0];
+    weights.forEach((weight) => offsets.push(offsets[offsets.length - 1] + weight));
+    return offsets;
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "mapped-image",
+  "version": "0.1.0",
+  "private": false,
+  "license": "MIT",
+  "description": "A React component that overlays a clickable, weighted row/column grid on top of one or more images, built on react-leaflet.",
+  "keywords": [
+    "react",
+    "leaflet",
+    "react-leaflet",
+    "image",
+    "grid",
+    "overlay"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/notetuwu/mapped-image.git"
+  },
+  "homepage": "https://github.com/notetuwu/mapped-image#readme",
+  "bugs": {
+    "url": "https://github.com/notetuwu/mapped-image/issues"
+  },
+  "type": "module",
+  "main": "MappedImage.tsx",
+  "types": "MappedImage.tsx",
+  "files": [
+    "**/*.ts",
+    "**/*.tsx"
+  ],
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "dependencies": {
+    "leaflet": "^1.9.4",
+    "react-leaflet": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/leaflet": "^1.9.21"
+  }
+}

package/types.ts

@@ -0,0 +1,62 @@
+import type { LatLngTuple } from "leaflet";
+import type { ReactNode } from "react";
+
+export type ImageConfig = {
+    name: string;
+    src: string;
+    columns: number;
+    rows: number;
+    /** colIndex -> relative width weight, default weight is 1. Only needs entries for non-uniform columns. */
+    columnWeights?: Record<number, number>;
+    /** rowIndex -> relative height weight, default weight is 1. Only needs entries for non-uniform rows. */
+    rowWeights?: Record<number, number>;
+};
+
+export type ImageSelectorProps = {
+    images: ImageConfig[];
+    selectedIndex: number;
+    onSelect: (index: number) => void;
+};
+
+export type MappedImageProps = {
+    images: ImageConfig[];
+    alt: string;
+    width: number;
+    height: number;
+    selectedCells?: Set<string>;
+    selectedImageIndex?: number;
+    onCellClick?: (props: ICellClickProps) => void;
+    onSelectedCellsChange?: (selectedCells: Set<string>) => void;
+    onSelectedImageIndexChange?: (index: number) => void;
+    renderImageSelector?: (props: ImageSelectorProps) => ReactNode;
+    /** Extra pannable margin (in pixels) beyond the image edges. Defaults to 50. */
+    maxBoundsPadding?: number;
+};
+
+export type ImageLayerProps = {
+    image: ImageConfig;
+    colOffset: number;
+    rowOffset: number;
+    width: number;
+    height: number;
+    alt: string;
+    selectedCells: Set<string>;
+    maxBoundsPadding?: number;
+    onCellClick: GridProps["onCellClick"];
+};
+
+export type GridProps = {
+    rows: number;
+    rowOffset: number;
+    rowWeights: number[];
+    columnLabels: string[];
+    columnWeights: number[];
+    imgBounds: LatLngTuple;
+    selectedCells: Set<string>;
+    onCellClick?: (props: ICellClickProps) => void;
+};
+
+export interface ICellClickProps {
+    col: string;
+    row: number;
+}