@georeferencing/react 0.2.0 → 0.3.0

package/README.md

@@ -30,9 +30,10 @@ Importing the package is SSR-safe. Create maps and start browser processing only
 on the client.
 
 **Install the same version of `@georeferencing/react`, `@georeferencing/core` and
-`@georeferencing/plugins`**, and upgrade them together. React depends on core and
-re-exports its controller; a mismatched version can install a second copy of core
-with a separate projection registry. See
+`@georeferencing/plugins`**, and upgrade them together. React declares core as a peer
+dependency and re-exports its controller; a mismatched version is reported as a
+peer-dependency conflict rather than installing a second core with a separate
+projection registry. See
 [keep package versions aligned](https://georeferencing-api-docs.gh.tobilg.com/Getting_started/#keep-package-versions-aligned).
 
 ## Integrate with a host-owned map
@@ -176,7 +177,10 @@ sticky bar:
 Completed steps in the step bar are clickable. Desktop keeps both views side by
 side; below 720 px, Image/Map buttons switch panes and follow pending points.
 In both views, dragging pans and scrolling zooms; a click without dragging places
-a point.
+a point. Zooming the image beyond the reduced preview's resolution loads the
+full-resolution image (`controller.requestDetailImage()`), and source pixels are shown
+crisply once each covers several screen pixels, so points can be placed at the
+original resolution.
 
 OpenLayers' `Map` creates its default interactions with `onFocusOnly: true`. If
 the map target has a `tabindex` (for keyboard navigation), mouse panning and wheel

package/dist/Georeferencer.js

@@ -15,6 +15,15 @@ import { PreviewControls } from "./panels/PreviewControls.js";
 import { ReferencePanel } from "./panels/ReferencePanel.js";
 const DEFAULT_BINDING = {};
 const NO_CONTROLS = {};
+/** Activate a tool from an effect, reporting instead of throwing into React. */
+function selectTool(controller, tool) {
+    try {
+        controller.setTool(tool);
+    }
+    catch (error) {
+        controller.reportError(error);
+    }
+}
 /**
  * Ready-made React editor for an existing OpenLayers map. Composes image, GCP, alignment, reference, output and optional drawing controls.
  *
@@ -49,7 +58,7 @@ export function Georeferencer({ controller, referenceMap, bindingOptions = DEFAU
         setMobileView("image");
         // A metadata-only restored document still needs its matching local bytes.
         if (imageId && imageReady && controller.getSnapshot().mode === "align")
-            controller.setTool("gcp");
+            selectTool(controller, "gcp");
     }, [controller, guided, imageId, imageReady]);
     useEffect(() => {
         if (guided)
@@ -58,7 +67,7 @@ export function Georeferencer({ controller, referenceMap, bindingOptions = DEFAU
     // Matching always uses the point tool; dragging pans, so no separate pan mode is needed.
     useEffect(() => {
         if (guided && step === 1 && s.tool !== "gcp" && s.mode === "align")
-            controller.setTool("gcp");
+            selectTool(controller, "gcp");
     }, [controller, guided, step, s.tool, s.mode]);
     useEffect(() => {
         if (guided && mobileView === "map")
@@ -66,7 +75,15 @@ export function Georeferencer({ controller, referenceMap, bindingOptions = DEFAU
     }, [guided, mobileView, referenceMap]);
     useEffect(() => {
         controller.start();
-        binding.current = attachReferenceMap(referenceMap, controller, bindingOptions);
+        try {
+            binding.current = attachReferenceMap(referenceMap, controller, bindingOptions);
+        }
+        catch (error) {
+            // Invalid projection or datum-grid configuration: keep the editor mounted and
+            // show the error instead of unmounting the host tree.
+            binding.current = null;
+            controller.reportError(error);
+        }
         return () => {
             binding.current?.detach();
             binding.current = null;

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 /**
  * Ready-made editor, composable panels and subscription hook with optional exports.
  * Import from `@georeferencing/react`.
- * @module react
+ * @module @georeferencing/react
+ * @group @georeferencing/react
  */
 export type { ControllerOptions, Document, Features, Gcp, ImageMetadata, SaveEnvelope, } from "@georeferencing/core";
 export { createDocument, GeoreferencerController } from "@georeferencing/core";

package/dist/index.js

@@ -1,7 +1,8 @@
 /**
  * Ready-made editor, composable panels and subscription hook with optional exports.
  * Import from `@georeferencing/react`.
- * @module react
+ * @module @georeferencing/react
+ * @group @georeferencing/react
  */
 export { createDocument, GeoreferencerController } from "@georeferencing/core";
 export { ALL_CONTROLS, MINIMAL_CONTROLS } from "./controls.js";

package/dist/panels/FeaturePanel.js

@@ -1,5 +1,4 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { validateFeatures } from "@georeferencing/core";
 import { useGeoreferencer } from "../hooks/useGeoreferencer.js";
 import { identity } from "../localization.js";
 /** Plain-language names for drawing tools and the geometry types they create. */
@@ -28,7 +27,7 @@ t = identity, }) {
     const s = useGeoreferencer(controller), d = s.document;
     if (!controller.options.digitizing)
         return null;
-    return (_jsxs("section", { children: [_jsxs("h2", { children: [t("Drawings"), " ", _jsx("small", { children: d.features.features.length })] }), validateFeatures(d.features).map((error) => (_jsx("p", { className: "rg-error", children: t(error) }, error))), _jsx("div", { className: "rg-toolbar", children: ["Point", "LineString", "Polygon", "modify", "navigate"].map((tool) => (_jsx("button", { type: "button", disabled: s.mode !== "draw", "aria-pressed": s.tool === tool, onClick: () => controller.setTool(tool), children: t(TOOL_LABELS[tool]) }, tool))) }), _jsx("p", { className: "rg-hint", children: t("Double-click to finish lines and areas. Escape cancels. Use Edit shapes to move vertices; Alt-click a vertex to remove it.") }), d.features.features.map((f, i) => (_jsxs("div", { className: "rg-feature", children: [_jsxs("span", { children: [i + 1, " \u00B7 ", t(TOOL_LABELS[f.geometry.type])] }), _jsx("button", { type: "button", disabled: s.mode !== "draw", "aria-label": `${t("Delete feature")} ${i + 1}`, onClick: () => controller.deleteFeature(String(f.id)), children: "\u00D7" }), propertyEditor?.(f, (p) => controller.updateProperties(String(f.id), p))] }, f.id))), d.features.features.length > 0 &&
+    return (_jsxs("section", { children: [_jsxs("h2", { children: [t("Drawings"), " ", _jsx("small", { children: d.features.features.length })] }), controller.getFeatureErrors().map((error) => (_jsx("p", { className: "rg-error", children: t(error) }, error))), _jsx("div", { className: "rg-toolbar", children: ["Point", "LineString", "Polygon", "modify", "navigate"].map((tool) => (_jsx("button", { type: "button", disabled: s.mode !== "draw", "aria-pressed": s.tool === tool, onClick: () => controller.setTool(tool), children: t(TOOL_LABELS[tool]) }, tool))) }), _jsx("p", { className: "rg-hint", children: t("Double-click to finish lines and areas. Escape cancels. Use Edit shapes to move vertices; Alt-click a vertex to remove it.") }), d.features.features.map((f, i) => (_jsxs("div", { className: "rg-feature", children: [_jsxs("span", { children: [i + 1, " \u00B7 ", t(TOOL_LABELS[f.geometry.type])] }), _jsx("button", { type: "button", disabled: s.mode !== "draw", "aria-label": `${t("Delete feature")} ${i + 1}`, onClick: () => controller.deleteFeature(String(f.id)), children: "\u00D7" }), propertyEditor?.(f, (p) => controller.updateProperties(String(f.id), p))] }, f.id))), d.features.features.length > 0 &&
                 d.featuresReviewedAgainstAlignmentRevision !== d.alignmentRevision && (_jsx("button", { type: "button", disabled: d.confirmedAlignmentRevision !== d.alignmentRevision, onClick: () => controller.reviewFeatures(), children: t("I reviewed drawings against this alignment") })), _jsx("button", { type: "button", className: "rg-primary", disabled: !controller.options.onSave ||
                     !controller.canSaveFeatures() ||
                     s.saving === "running", onClick: () => void controller.save().catch((e) => controller.reportError(e)), children: t(s.saving === "running" ? "Saving…" : "Save features") }), _jsx("p", { "aria-live": "polite", children: s.saving === "succeeded"

package/dist/panels/ImagePanel.js

@@ -18,7 +18,7 @@ navigation = true,
 displayAdjustment = true, 
 /** Extra actions inside the empty drop zone, such as a sample image button. */
 emptyActions, }) {
-    const s = useGeoreferencer(controller), image = s.document.sourceImage, svg = useRef(null);
+    const s = useGeoreferencer(controller), image = s.document.sourceImage, imageWidth = image?.width, svg = useRef(null);
     const view = s.imageView ?? [
         0, 0, 100, 100,
     ];
@@ -30,6 +30,10 @@ emptyActions, }) {
     ]);
     const filterId = `rg-stretch-${useId().replace(/:/g, "")}`;
     const displayPixels = useRef(null);
+    // Preview pixels per canonical image pixel, known once the preview has loaded.
+    const [previewScale, setPreviewScale] = useState(0);
+    // On-screen pixels per canonical image pixel for the current view.
+    const [screenScale, setScreenScale] = useState(0);
     const stretchHistogram = (local) => {
         const pixels = displayPixels.current;
         if (!pixels || !image)
@@ -97,6 +101,8 @@ emptyActions, }) {
             const ctx = canvas.getContext("2d");
             ctx.drawImage(img, 0, 0);
             displayPixels.current = ctx.getImageData(0, 0, canvas.width, canvas.height);
+            if (imageWidth)
+                setPreviewScale(img.width / imageWidth);
             const data = displayPixels.current.data, bins = Array(32).fill(0);
             for (let i = 0; i < data.length; i += 4)
                 if (data[i + 3])
@@ -108,10 +114,31 @@ emptyActions, }) {
         return () => {
             disposed = true;
             displayPixels.current = null;
+            setPreviewScale(0);
             img.onload = null;
             img.src = "";
         };
-    }, [s.imageUrl]);
+    }, [s.imageUrl, imageWidth]);
+    // Track the on-screen scale; the viewBox keeps its aspect ratio ("meet").
+    const viewWidth = view[2], viewHeight = view[3];
+    useEffect(() => {
+        const element = svg.current;
+        if (!element)
+            return;
+        const measure = () => setScreenScale(Math.min(element.clientWidth / viewWidth, element.clientHeight / viewHeight));
+        measure();
+        if (typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(measure);
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [viewWidth, viewHeight]);
+    // Zoomed beyond the preview resolution: show full-resolution detail for precise picking.
+    const needsDetail = previewScale > 0 && screenScale > previewScale * 1.25;
+    useEffect(() => {
+        if (needsDetail)
+            void controller.requestDetailImage();
+    }, [needsDetail, controller]);
     const point = (e) => {
         const matrix = svg.current?.getScreenCTM();
         if (!matrix)
@@ -240,6 +267,10 @@ emptyActions, }) {
                             setDragPoint(null);
                         }, children: [_jsx("defs", { children: _jsx("filter", { id: filterId, colorInterpolationFilters: "sRGB", children: _jsxs("feComponentTransfer", { children: [_jsx("feFuncR", { type: "linear", slope: 255 / (stretch[0][1] - stretch[0][0]), intercept: -stretch[0][0] / (stretch[0][1] - stretch[0][0]) }), _jsx("feFuncG", { type: "linear", slope: 255 / (stretch[1][1] - stretch[1][0]), intercept: -stretch[1][0] / (stretch[1][1] - stretch[1][0]) }), _jsx("feFuncB", { type: "linear", slope: 255 / (stretch[2][1] - stretch[2][0]), intercept: -stretch[2][0] / (stretch[2][1] - stretch[2][0]) })] }) }) }), s.imageUrl && (_jsx("image", { href: s.imageUrl, width: image.width, height: image.height, style: {
                                     filter: `url(#${filterId}) brightness(${brightness}) contrast(${contrast})`,
+                                } })), s.detailImageUrl && needsDetail && (_jsx("image", { href: s.detailImageUrl, width: image.width, height: image.height, "data-detail": "", style: {
+                                    filter: `url(#${filterId}) brightness(${brightness}) contrast(${contrast})`,
+                                    // Show individual source pixels once each covers several screen pixels.
+                                    imageRendering: screenScale >= 4 ? "pixelated" : "auto",
                                 } })), s.document.gcps.map((gcp) => {
                                 const p = dragPoint?.id === gcp.id ? dragPoint.point : gcp.image;
                                 return (_jsxs("g", { transform: `translate(${p[0]} ${p[1]})`, onPointerDown: (e) => {

package/dist/utils/downloadBlob.d.ts

@@ -1,5 +1,6 @@
 /**
- * Start a browser download and revoke its temporary object URL after one second. Invoke
- * from a client-side user action; this utility performs no upload.
+ * Start a browser download and revoke its temporary object URL after one minute, which
+ * leaves large files (such as full-resolution GeoTIFFs) time to start saving in every
+ * browser. Invoke from a client-side user action; this utility performs no upload.
  */
 export declare function downloadBlob(blob: Blob, name: string): void;

package/dist/utils/downloadBlob.js

@@ -1,11 +1,20 @@
 /**
- * Start a browser download and revoke its temporary object URL after one second. Invoke
- * from a client-side user action; this utility performs no upload.
+ * Start a browser download and revoke its temporary object URL after one minute, which
+ * leaves large files (such as full-resolution GeoTIFFs) time to start saving in every
+ * browser. Invoke from a client-side user action; this utility performs no upload.
  */
 export function downloadBlob(blob, name) {
     const url = URL.createObjectURL(blob), a = document.createElement("a");
     a.href = url;
     a.download = name;
-    a.click();
-    setTimeout(() => URL.revokeObjectURL(url), 1000);
+    a.style.display = "none";
+    // Some browsers ignore clicks on anchors outside the document.
+    document.body.append(a);
+    try {
+        a.click();
+    }
+    finally {
+        a.remove();
+    }
+    setTimeout(() => URL.revokeObjectURL(url), 60_000);
 }

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -31,15 +31,14 @@
     },
     "./styles.css": "./dist/styles.css"
   },
-  "dependencies": {
-    "@georeferencing/core": "^0.2.0"
-  },
   "peerDependencies": {
+    "@georeferencing/core": "^0.3.0",
     "react": ">=19.3.0 <20",
     "react-dom": ">=19.3.0 <20",
     "ol": ">=10.10.0 <11"
   },
   "devDependencies": {
+    "@georeferencing/core": "0.3.0",
     "typescript": "5.9.3",
     "react": "19.3.0",
     "react-dom": "19.3.0",