@georeferencing/react 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TobiLG <github@tobilg.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,401 @@
-# Temporary Holding Version
+# @georeferencing/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React 19 components and hooks for georeferencing local images on an existing
+OpenLayers map. This package provides the ready-made editor, composable panels,
+subscription hook, unsaved-work dialog and scoped styles.
+
+The authoritative session and processing engine live in
+[`@georeferencing/core`](https://github.com/tobilg/georeferencing/tree/main/packages/core).
+Optional exports come from
+[`@georeferencing/plugins`](https://github.com/tobilg/georeferencing/tree/main/packages/plugins).
+React has no runtime dependency on plugins or pdf-lib: it displays formats
+configured on the controller.
+
+## Installation and compatibility
+
+```sh
+pnpm add @georeferencing/core @georeferencing/react react@19 react-dom@19 ol@10
+# Optional output formats:
+pnpm add @georeferencing/plugins
+# TypeScript React applications also need the React declarations:
+pnpm add -D @types/react@19 @types/react-dom@19
+```
+
+Verified peer ranges are React/React DOM `>=19.3.0 <20` and OpenLayers
+`>=10.10.0 <11`. The host owns these libraries and its map. Packages ship ESM and
+TypeDoc-bearing TypeScript declarations. Node.js 22.12+ is the declared tooling
+requirement; the repository uses pnpm 12.x.
+
+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
+[keep package versions aligned](https://georeferencing-api-docs.gh.tobilg.com/Getting_started/#keep-package-versions-aligned).
+
+## Integrate with a host-owned map
+
+The map must already have a visible target, dimensions and initialized view. Make
+one stable controller/engine per session, and inject your real save service.
+This example needs no export plugin and sends geographic features to the host.
+
+```tsx
+import type { ControllerOptions } from "@georeferencing/core";
+import { GeoreferencerController } from "@georeferencing/core";
+import { createWorkerEngine } from "@georeferencing/core/engine";
+import { Georeferencer } from "@georeferencing/react";
+import type OLMap from "ol/Map.js";
+import "ol/ol.css";
+import "@georeferencing/react/styles.css";
+
+export function createEditorSession(
+  workingCrs: string,
+  persistFeatures: NonNullable<ControllerOptions["onSave"]>,
+  persistDraft?: ControllerOptions["onSaveDraft"],
+) {
+  const engine = createWorkerEngine();
+  const controller = new GeoreferencerController({
+    workingCrs,
+    engine,
+    digitizing: true,
+    onSave: persistFeatures,
+    onSaveDraft: persistDraft,
+  });
+  return {
+    controller,
+    dispose() {
+      controller.dispose();
+      engine.dispose();
+    },
+  };
+}
+
+export function ImageEditor({
+  map,
+  session,
+}: {
+  map: OLMap;
+  session: ReturnType<typeof createEditorSession>;
+}) {
+  return <Georeferencer controller={session.controller} referenceMap={map} />;
+}
+```
+
+The host calls `createEditorSession` once, for example when opening an editor,
+and retains it across renders. Render `ImageEditor` only after the host map exists.
+On permanent close, resolve unsaved work, unmount the editor, then dispose the
+session. A temporary detach/remount must retain the same controller.
+
+With Vite, use ES module workers:
+
+```ts
+export default { worker: { format: "es" } };
+```
+
+The stylesheet is optional. It uses `rg-` classes; the host controls map layout
+and dimensions. Core's engine and each optional codec support explicit worker
+URLs/factories for deployments that do not preserve default bundled asset paths.
+
+## Ready-made editor props
+
+| Prop | Contract |
+| --- | --- |
+| `controller` | Required stable authoritative session controller |
+| `referenceMap` | Required initialized, host-owned OpenLayers map |
+| `bindingOptions` | Stable reference providers, projections, snapping and optional initial map framing |
+| `t` | Translate default English text, including configured format labels |
+| `formatError` | Format structured errors by code/message/operation ID |
+| `className` | Additional editor root class |
+| `propertyEditor` | Host feature-property form; update replacement JSON properties |
+| `onExport` | Receive any configured format's artifacts instead of automatic downloads |
+
+Memoize `bindingOptions` or construct it outside rendering. Changing its identity
+reattaches the binding. The ready-made component owns its attachment; do not also
+call `attachReferenceMap` for the same controller and map.
+
+## Select exports on demand
+
+No format is enabled implicitly. Configure the controller at creation or replace
+its registry at runtime:
+
+```ts
+import type { GeoreferencerController } from "@georeferencing/core";
+import { geoTiff } from "@georeferencing/plugins/geotiff";
+import { jpeg } from "@georeferencing/plugins/jpeg";
+import { pdf, type ReportMap } from "@georeferencing/plugins/pdf";
+
+export function enableExports(
+  controller: GeoreferencerController,
+  currentMap: () => ReportMap | undefined,
+) {
+  controller.setExportFormats([
+    geoTiff(),
+    jpeg({ quality: 0.92 }),
+    pdf({ map: currentMap }),
+  ]);
+}
+```
+
+The UI shows only these actions. `setExportFormats` replaces the registry and
+cancels active export work. Import a subset to exclude unused implementations
+from the browser bundle; heavy format code loads on request.
+
+The default UI downloads every artifact. `onExport(result)` can handle them in
+host code; inspect `result.format`, `result.document` and each `{ name, blob }`
+in `result.files`. JPEG and world-file exports include required CRS/placement
+sidecars. Export completion never acknowledges host persistence. See the
+[plugins README](https://github.com/tobilg/georeferencing/blob/main/packages/plugins/README.md)
+for format settings, cancellation and limits.
+
+## Guided four-step layout
+
+Supply `referenceView` to `Georeferencer` to use the guided layout. It is a React
+node containing the host's map target and optional map controls; the host still
+owns the map and must attach its target before editor effects run (a React
+callback ref is suitable). Without this prop, the classic workbench with every
+control remains. See the
+[complete demo host](https://github.com/tobilg/georeferencing/blob/main/packages/demo/main.tsx)
+for a typed integration with target attachment and cleanup.
+
+The guided layout leads users through four steps, each with one main action in a
+sticky bar:
+
+1. **Load image**: drop zone with **Choose image** and any `emptyImageActions`
+   (for example a sample-image button).
+2. **Match points**: click a spot in the image, then the same spot on the map.
+   Progress shows how many points the model needs; **Run alignment** fits them.
+3. **Check alignment**: the overlay on the map, a plain-language accuracy summary
+   (average residual in image pixels, or a hint to add a point when the fit is
+   exact) and the point list. **Adjust points** goes back; **Looks good, continue**
+   confirms the alignment.
+4. **Export or draw**: download buttons for the configured formats and, with
+   `digitizing`, drawing tools and **Save features**. **Back to check** returns.
+
+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.
+
+OpenLayers' `Map` creates its default interactions with `onFocusOnly: true`. If
+the map target has a `tabindex` (for keyboard navigation), mouse panning and wheel
+zoom then only work after the map has focus. Create the host map with
+`interactions: defaults({ onFocusOnly: false })` from `ol/interaction/defaults.js`,
+as the demo does, so both work immediately.
+
+### Choose the controls
+
+The guided layout starts minimal. Add expert controls individually with
+`controls`; omitted flags fall back to `MINIMAL_CONTROLS`:
+
+```tsx
+import { ALL_CONTROLS, Georeferencer } from "@georeferencing/react";
+
+<Georeferencer
+  controller={controller}
+  referenceMap={map}
+  referenceView={mapView}
+  controls={{ transformation: true, outputSettings: true }}
+/>;
+// Every control: controls={ALL_CONTROLS}
+```
+
+| Flag | Default | Adds |
+| --- | --- | --- |
+| `history` | on | Undo and redo |
+| `previewMode` | off | Manual/automatic preview selector (otherwise the controller's `previewMode` applies) |
+| `transformation` | off | Transformation model selector while matching |
+| `pointTable` | off | Full point table with editable coordinates, CRS and residuals (otherwise a compact list) |
+| `manualEntry` | off | Add a point pair by typing coordinates, the keyboard alternative to clicking |
+| `navigation` | off | Previous/next image and map views, linked navigation |
+| `displayAdjustment` | off | Brightness, contrast and histogram stretch |
+| `referenceStatus` | off | Load status of reference providers |
+| `outputSettings` | off | Raster output CRS, resampling, compression, no-data, pixel size and bounds |
+| `sessionFiles` | off | Restore session, import `.points`, save draft and early session downloads |
+| `unsavedIndicator` | off | Unsaved-changes indicator |
+
+Enable `manualEntry` when keyboard-only point entry is required.
+
+### Preview policy and panels
+
+`previewMode: "manual"` on the controller waits for **Run alignment**;
+`"automatic"` updates eligible previews after committed edits without advancing
+the user's step. Worker validation reports singular or unusable arrangements when
+a run is requested.
+
+The composable panels keep every control by default and accept the same opt-outs:
+`GcpPanel` takes `variant` (`"table"` or `"compact"`), `manualEntry` and `tools`;
+`ImagePanel` takes `navigation`, `displayAdjustment` and `emptyActions`;
+`PreviewControls` takes `modeSelector` and calls `onReview` only for a successful
+preview matching the requested revision. `AlignmentPanel` accepts
+`controls={false}` when transformation and preview controls are rendered
+elsewhere. These panels never take map or engine ownership.
+
+## References, projections and snapping
+
+Pass core's `BindingOptions` as `bindingOptions`. Providers include bounded
+viewport WFS, static GeoJSON, custom abortable loaders and borrowed vector layers.
+A borrowed layer retains its host loading and ownership. Reference errors and
+partial results appear in the UI without disabling manual target entry.
+
+Configure real endpoint/type names, request/response CRSs and axis conventions.
+Preserve AbortSignal when injecting authentication. Query bounds limit reference
+loading; `initialView` only frames the map. Neither georeferences the image.
+Drawing bounds and raster bounds are independent.
+
+Register the same custom projection definitions and NTv2 grids with the engine
+and binding. Image GCPs use original-resolution, orientation-normalized pixels;
+feature drafts/save payloads use longitude/latitude regardless of the map view.
+Supplying provider `snapping` opts into GCP snapping. Drawing snapping is separately
+controlled by `digitizingSnapping.references` and `.drafts`. The
+[reference guide](https://github.com/tobilg/georeferencing/blob/main/packages/documentation/guides/reference-data.md)
+contains typed provider examples.
+
+## Image lifecycle, confirmation and saving
+
+The image picker and drop zone use controller lifecycle methods. Selection supports
+files up to 25 MiB, subject to decoded-pixel and memory budgets. Replacing/removing
+an image invokes the ready-made Save/Discard/Cancel dialog when needed, cancels
+old processing and preserves the host map view. Original bytes stay outside the
+serializable document. Restoring a JSON session requires the matching source file.
+
+Digitizing is opt-in through `digitizing: true`. A valid current alignment must be
+explicitly confirmed before drawing multiple points, lines or polygons. Features
+can be modified, deleted and undone/redone. Returning to alignment leaves them
+geographically anchored; subsequent alignment changes require confirmation and
+explicit feature review before saving accepted features again.
+
+`onChange` mirrors draft state. `onSave` receives an immutable accepted-feature
+envelope with stable IDs, source fingerprint, alignment and provenance.
+`onSaveDraft` can persist unfinished sessions separately. A save callback resolves
+after actual storage success and rejects on failure; a failed draft remains
+retryable. Older save completion does not acknowledge newer edits. Feature saving
+never requires raster export. Hosts must separately persist source bytes and
+protect route/window closure; the image-transition dialog is not a general router
+or browser-close guard.
+
+## React Strict Mode and ownership
+
+The editor resumes the controller during setup and suspends it during cleanup.
+It adds/removes only package-owned map layers/interactions. It does not dispose
+the host map, borrowed layers, controller or engine on unmount. This permits
+React 19 Strict Mode setup/cleanup cycles and later remounts.
+
+Use permanent `dispose()` only after the host has finished with the session;
+do not put it in an effect cleanup that Strict Mode uses for temporary teardown.
+Host interactions remain host-owned. Use `onActiveToolChange` in controller options
+to coordinate conflicting host drawing tools explicitly. Pending host saves are
+revision-safe but are not cancelled by UI suspension.
+
+## Compose a custom UI
+
+| Export | Purpose |
+| --- | --- |
+| `Georeferencer` | Complete editor, map attachment, guard dialog and output controls |
+| `useGeoreferencer(controller)` | Subscribe to the authoritative snapshot |
+| `ImagePanel` | Image selection, image view and image-side GCP interaction |
+| `GcpPanel` | Paired-point table, numeric editing and diagnostics |
+| `PreviewControls` | Manual/automatic preview policy, readiness and explicit run/review |
+| `AlignmentPanel` | Transformation selection, confirmation and alignment controls |
+| `ReferencePanel` | Reference loading/error/incomplete-result feedback |
+| `FeaturePanel` | Drawing tools, features/properties, review and save controls |
+
+Composable panels do not install a map binding or unsaved-work dialog. Supply a
+controller with a host `guard`, attach the map once and manage suspension yourself:
+
+```tsx
+import type { GeoreferencerController } from "@georeferencing/core";
+import { attachReferenceMap, type BindingOptions } from "@georeferencing/core/openlayers";
+import {
+  AlignmentPanel, FeaturePanel, GcpPanel, ImagePanel,
+  ReferencePanel, useGeoreferencer,
+} from "@georeferencing/react";
+import type OLMap from "ol/Map.js";
+import { useEffect } from "react";
+
+export function CustomEditor({ map, controller, options }: {
+  map: OLMap;
+  controller: GeoreferencerController;
+  options: BindingOptions;
+}) {
+  const state = useGeoreferencer(controller);
+  useEffect(() => {
+    controller.start();
+    const binding = attachReferenceMap(map, controller, options);
+    return () => {
+      binding.detach();
+      controller.suspend();
+    };
+  }, [map, controller, options]);
+
+  return (
+    <div className="rg-editor">
+      <ImagePanel controller={controller} />
+      <GcpPanel controller={controller} />
+      <AlignmentPanel controller={controller} />
+      <ReferencePanel controller={controller} />
+      <FeaturePanel controller={controller} />
+      <p role="status">{state.error ?? `Document revision ${state.document.documentRevision}`}</p>
+    </div>
+  );
+}
+```
+
+Custom layouts provide their own export/session actions through controller APIs.
+Keep the `options` object stable. Omitting a headless guard safely cancels dirty
+image transitions instead of silently discarding them.
+
+## Localization and property forms
+
+Use `t` for UI messages and `formatError` for structured dynamic errors. Business
+properties remain host-defined JSON. Never mutate the frozen feature passed to
+a property renderer; call its update callback with replacement properties.
+
+```tsx
+import type { GeoreferencerProps } from "@georeferencing/react";
+
+export const propertyEditor: GeoreferencerProps["propertyEditor"] = (feature, update) => (
+  <label>
+    Name
+    <input
+      value={String(feature.properties.name ?? "")}
+      onChange={(event) => update({ ...feature.properties, name: event.target.value })}
+    />
+  </label>
+);
+
+export const translate: NonNullable<GeoreferencerProps["t"]> = (message) => {
+  const messages: Record<string, string> = { "Choose image": "Bild auswählen" };
+  return messages[message] ?? message;
+};
+```
+
+Pass these functions as props to `Georeferencer`, or to the relevant composable
+panels. The package includes focusable map/image controls, labeled inputs and
+status feedback; hosts remain responsible for accessible custom property editors,
+layout, translations and their application's overall keyboard behavior.
+
+## Source organization
+
+`src/index.ts` defines the public exports. The editor lives in `Georeferencer.tsx`,
+composable panels in `panels/`, the subscription hook in `hooks/`, shared fields
+in `components/`, and download handling in `utils/`. Translation types/defaults
+live in `localization.ts`. These internal modules preserve the public API; consumers
+continue importing from `@georeferencing/react` and its `styles.css` entry.
+
+## Troubleshooting and license
+
+`@georeferencing/react` exposes `.` and `/styles.css`. Declarations carry TypeDoc
+comments for editor help; the same comments are published as the
+[API documentation](https://georeferencing-api-docs.gh.tobilg.com). Source, issues and contribution notes are in the
+[GitHub repository](https://github.com/tobilg/georeferencing). MIT licensed.
+
+| Symptom | Check |
+| --- | --- |
+| Blank map or missing overlay | Host map target/size, valid current fit and overlay visibility |
+| Repeated reference loads / lost map interaction state | Stable controller, map and memoized binding options |
+| Duplicate editor layers/interactions | Only one attachment per controller/map; avoid manual binding alongside `Georeferencer` |
+| Drawing/save controls unavailable | Opt-in digitizing, valid confirmation, feature review and configured save handler |
+| Export controls absent | Register the desired optional plugins |
+| Worker or map-capture error | Worker URLs/CSP, supported browser APIs and CORS-safe map layers |

package/dist/Georeferencer.d.ts

@@ -0,0 +1,71 @@
+import type { ExportResult, GeoreferencerController } from "@georeferencing/core";
+import type { BindingOptions } from "@georeferencing/core/openlayers";
+import type OLMap from "ol/Map.js";
+import type { ReactNode } from "react";
+import type { GeoreferencerControls } from "./controls.js";
+import type { Translate } from "./localization.js";
+import { FeaturePanel } from "./panels/FeaturePanel.js";
+/**
+ * Integration props for the ready-made editor. Keep controller, map and binding
+ * configuration stable across React renders.
+ */
+export interface GeoreferencerProps {
+    /**
+     * Opt into the guided four-step layout (load, match, check, export/draw) by supplying
+     * the host map's rendered target and controls. The host still creates, targets and
+     * disposes the map. This slot stays mounted across all steps and responsive
+     * image/map tabs.
+     */
+    referenceView?: ReactNode;
+    /**
+     * Optional controls of the guided layout. Omitted flags use {@link MINIMAL_CONTROLS};
+     * pass {@link ALL_CONTROLS} for every expert control. The classic layout always shows
+     * all controls.
+     */
+    controls?: Partial<GeoreferencerControls>;
+    /**
+     * Extra actions shown in the empty image drop zone next to "Choose image", for example
+     * a button that loads a sample image.
+     */
+    emptyImageActions?: ReactNode;
+    /**
+     * Host-owned authoritative controller; the component resumes/suspends it but does not
+     * permanently dispose it.
+     */
+    controller: GeoreferencerController;
+    /**
+     * Existing host-owned OpenLayers map. The component attaches owned layers/interactions
+     * and leaves the map alive on unmount.
+     */
+    referenceMap: OLMap;
+    /**
+     * Reference providers, projections, snapping and optional initial map framing. Memoize
+     * this object to avoid reattachment.
+     */
+    bindingOptions?: BindingOptions;
+    /** Translation function for default English messages; identity when omitted. */
+    t?: Translate;
+    /**
+     * Additional class on the editor root; built-in styles are scoped beneath rg-prefixed
+     * classes.
+     */
+    className?: string;
+    /**
+     * Optional structured-error formatter, allowing localization by error code instead of
+     * parsing English strings.
+     */
+    formatError?: (error: NonNullable<ReturnType<GeoreferencerController["getSnapshot"]>["errorDetail"]>) => string;
+    /**
+     * Render a host-specific property form. Call the provided update callback with a
+     * replacement JSON properties object; do not mutate the frozen feature.
+     */
+    propertyEditor?: Parameters<typeof FeaturePanel>[0]["propertyEditor"];
+    /** Receive any configured format's revisioned artifacts instead of default downloads. */
+    onExport?: (result: ExportResult) => void | Promise<void>;
+}
+/**
+ * Ready-made React editor for an existing OpenLayers map. Composes image, GCP, alignment, reference, output and optional drawing controls.
+ *
+ * Supplying `referenceView` selects the guided four-step layout, whose optional controls are chosen with `controls`; otherwise the classic workbench shows every control. Its effects attach/detach owned map resources and resume/suspend the controller for React Strict Mode. It installs a Save/Discard/Cancel guard and cancels pending dialogs on cleanup. The host retains final ownership of map, controller and engine. Import the optional scoped stylesheet from `@georeferencing/react/styles.css`.
+ */
+export declare function Georeferencer({ controller, referenceMap, bindingOptions, t, className, propertyEditor, onExport, formatError, referenceView, controls: controlOverrides, emptyImageActions, }: GeoreferencerProps): import("react/jsx-runtime").JSX.Element;