@dclimate/zarr-map 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dClimate
+
+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

@@ -0,0 +1,374 @@
+# @dclimate/zarr-map
+
+`@dclimate/zarr-map` is a TypeScript library for rendering
+dClimate-compatible Zarr datasets on interactive maps. The package exists so a
+website can pass a dataset request, variable, map config, time range, spatial
+bounds, and visual options, then get a working MapLibre visualization without
+solving Zarr metadata, IPFS/gateway access, selector normalization, or renderer
+compatibility itself.
+
+The package should feel like a light map-rendering wrapper over
+`@dclimate/dclimate-client-js`, Jaxray-compatible dataset metadata/stores,
+MapLibre, and the selected Zarr renderer. It should not become a full data
+explorer application.
+
+## Product Direction
+
+The primary use case is no-hassle dClimate map rendering:
+
+```tsx
+<DClimateZarrMap
+  dataset={{
+    collection: "ecmwf_era5",
+    dataset: "temperature_2m",
+    variant: "finalized"
+  }}
+  gatewayUrl="https://ipfs-gateway.dclimate.net"
+  variable="2m_temperature"
+  map={mapConfig}
+  bounds={[-12, 35, 16, 60]}
+  timeRange={{
+    start: "2024-01-01T00:00:00Z",
+    end: "2024-01-07T23:00:00Z"
+  }}
+  colorScale={{
+    palette: "viridis",
+    domain: [260, 320],
+    unit: "K",
+    displayUnit: "C",
+    quantity: "temperature"
+  }}
+/>
+```
+
+The package should support two usage modes:
+
+1. **dClimate mode**
+   - Accept a dClimate dataset query/config.
+   - Use `@dclimate/dclimate-client-js` to resolve and load datasets, including
+     spatial bounds and time-window selection when provided.
+   - Render selected variables on a MapLibre map with light controls such as a
+     legend, time selector, loading/error status, and inspect callback.
+
+2. **Generic grid-source mode**
+   - Accept a normalized `GridDataSource` object.
+   - Support Jaxray-compatible datasets through an adapter.
+   - Keep the renderer reusable outside dClimate datasets.
+
+The preferred architecture is a generic core with first-class dClimate and
+Jaxray adapters, but package features should stay close to rendering and
+request-scoped data loading.
+
+## Product Boundaries
+
+Include functionality that removes friction from map rendering:
+
+- dClimate dataset resolution and bounded/time-window source loading.
+- Normalized metadata contracts for Zarr/Jaxray sources.
+- Selector normalization for time, band, and other non-spatial dimensions.
+- MapLibre layer creation and updates.
+- Renderer loading/error state.
+- Light visual customization: palette/gradient, color domain, opacity, display
+  unit, legend, time selector, and inspect callbacks.
+- Request preflight checks that estimate cells and bytes before oversized map
+  requests begin expensive bounded loading.
+
+Avoid functionality that turns this package into an application:
+
+- Marketplace purchase flow, wallet/order state, or decryption UX.
+- CSV/JSON export.
+- 2D chart rendering or chart aggregation.
+- Dashboard layouts, modal workflows, generic form builders, or rich explorer
+  pages.
+- Heavy map drawing/editing tools as core behavior.
+
+If a feature is mostly about discovering, resolving, slicing, or decrypting
+dClimate data rather than rendering it, prefer implementing it upstream in
+`dclimate-client-js` or another dClimate data package and consuming it here.
+
+## Initial Technical Direction
+
+- Base map: MapLibre GL JS by default.
+- Optional compatibility: allow users to provide existing MapLibre or Mapbox map instances where practical.
+- First renderer candidate: `@carbonplan/zarr-layer`.
+- Avoid a custom WebGL raster renderer unless the research spike proves existing renderers cannot support target datasets.
+- Keep `@dclimate/dclimate-client-js` optional for users who only need generic grid-source mode.
+- Keep React UI primitives small. Prefer prop-driven rendering over bundled
+  explorer workflows.
+
+## Target Package Shape
+
+```txt
+@dclimate/zarr-map
+@dclimate/zarr-map/core
+@dclimate/zarr-map/react
+@dclimate/zarr-map/dclimate
+```
+
+Planned responsibilities:
+
+- `src/core`: framework-agnostic contracts, selectors, validation, color scales, and query helpers.
+- `src/renderers`: renderer bridges, starting with MapLibre plus `@carbonplan/zarr-layer`.
+- `src/dclimate`: dClimate client adapter and dataset discovery/loading helpers.
+- `src/react`: React components such as `ZarrMap`, `DClimateZarrMap`, `TimeSlider`, and `Legend`.
+- `docs`: architecture notes and decision records.
+- `tests`: future unit and integration tests.
+- `fixtures`: small fixture datasets or mocks for tests.
+- `todo`: implementation tickets with acceptance criteria and dependencies.
+
+## MVP API Target
+
+```tsx
+import { DClimateZarrMap } from "@dclimate/zarr-map/react";
+
+export function App() {
+  return (
+    <DClimateZarrMap
+      dataset={{
+        collection: "ecmwf_era5",
+        dataset: "temperature_2m",
+        variant: "finalized"
+      }}
+      gatewayUrl="https://ipfs-gateway.dclimate.net"
+      variable="2m_temperature"
+      timeDimension="time"
+      initialSelector={{ time: "2024-01-01T00:00:00Z" }}
+      map={{
+        center: [-8.6, 39.5],
+        zoom: 5,
+        style: "https://demotiles.maplibre.org/style.json"
+      }}
+      bounds={[-12, 35, 16, 60]}
+      timeRange={{
+        start: "2024-01-01T00:00:00Z",
+        end: "2024-01-07T23:00:00Z"
+      }}
+      colorScale={{
+        palette: "viridis",
+        domain: [260, 320],
+        unit: "K"
+      }}
+      controls={{
+        timeSlider: true,
+        legend: true,
+        inspect: true
+      }}
+    />
+  );
+}
+```
+
+Generic mode should use the same renderer through a normalized source:
+
+```tsx
+import { createJaxraySource } from "@dclimate/zarr-map/core";
+import { ZarrMap } from "@dclimate/zarr-map/react";
+
+const source = createJaxraySource(dataset);
+
+<ZarrMap
+  source={source}
+  variable="precipitation"
+  selector={{ time: 0 }}
+  controls={{ timeSlider: true, legend: true }}
+/>;
+```
+
+## Install
+
+```bash
+npm install @dclimate/zarr-map maplibre-gl @carbonplan/zarr-layer
+```
+
+React users also install `react` and `react-dom`. dClimate mode additionally
+uses the optional peers `@dclimate/dclimate-client-js` and `@dclimate/jaxray`.
+
+## Demo
+
+- Demo URL after Vercel deployment: https://zarr-map-demo.vercel.app
+- Demo source: https://github.com/dClimate/zarr-map-demo
+
+The standalone Vite demo app consumes this package like an external user. For
+local development before the first NPM publish, the demo can depend on the
+package with a local `file:../zarr-map-visualizer` link.
+
+## Package Entrypoints
+
+```ts
+import { createJaxraySource, queryPoint } from "@dclimate/zarr-map/core";
+import { createMapLibreGridLayer } from "@dclimate/zarr-map/renderer";
+import { createDClimateSource } from "@dclimate/zarr-map/dclimate";
+import { DClimateZarrMap, ZarrMap } from "@dclimate/zarr-map/react";
+```
+
+## Generic Grid Mode
+
+```tsx
+import { createJaxraySource } from "@dclimate/zarr-map/core";
+import { ZarrMap } from "@dclimate/zarr-map/react";
+
+const source = createJaxraySource(dataset, {
+  bounds: [-10, 35, 5, 45],
+  spatialDimensions: { x: "lon", y: "lat" }
+});
+
+<ZarrMap
+  colorScale={{ palette: "viridis", domain: [0, 50], unit: "mm" }}
+  controls={{ legend: true, timeSlider: true, inspect: true }}
+  map={{
+    center: [-8.6, 39.5],
+    zoom: 5,
+    style: "https://demotiles.maplibre.org/style.json"
+  }}
+  source={source}
+  variable="precipitation"
+/>;
+```
+
+## dClimate Mode
+
+```tsx
+import { DClimateZarrMap } from "@dclimate/zarr-map/react";
+
+<DClimateZarrMap
+  colorScale={{
+    palette: "viridis",
+    domain: [260, 320],
+    unit: "K",
+    displayUnit: "C",
+    quantity: "temperature"
+  }}
+  dataset={{
+    collection: "ecmwf_era5",
+    dataset: "temperature_2m",
+    variant: "finalized"
+  }}
+  gatewayUrl="https://ipfs-gateway.dclimate.net"
+  initialSelector={{ time: "2024-01-01T00:00:00.000Z" }}
+  bounds={[-12, 35, 16, 60]}
+  timeRange={{
+    start: "2024-01-01T00:00:00Z",
+    end: "2024-01-07T23:00:00Z"
+  }}
+  map={{
+    bounds: [
+      [-12, 35],
+      [16, 60]
+    ],
+    style: "https://demotiles.maplibre.org/style.json"
+  }}
+  variable="2m_temperature"
+/>;
+```
+
+`bounds` and `timeRange` are convenience aliases for
+`sourceOptions.selection.bounds` and `sourceOptions.selection.timeRange`. If a
+caller needs lower-level dClimate selection options, it can pass
+`sourceOptions.selection` directly. The aliases normalize into that same
+selection object and do not create a separate selection model.
+
+`map.bounds` and `map.maxBounds` are forwarded to MapLibre for viewport fitting
+and pan limits.
+
+## Visual Customization
+
+`colorScale.palette` accepts a built-in palette name or a custom color-stop
+array such as `["#1d4ed8", "#f8fafc", "#b91c1c"]`. Renderer domains stay in
+the source unit. Built-in names include `viridis`, `inferno`, `magma`,
+`plasma`, `cividis`, `turbo`, `greys`, `temperature`, `precipitation`,
+`humidity`, `vegetation`, and `wind`. The `magma`, `precipitation`, and
+`vegetation` palettes start transparent at the lower bound for overlaying low,
+dry, or no-vegetation cells on top of the basemap. To show a converted display
+unit in legends and inspect results, include `unit`, `displayUnit`, and
+`quantity`:
+
+```tsx
+colorScale={{
+  palette: ["#1d4ed8", "#f8fafc", "#b91c1c"],
+  domain: [260, 320],
+  unit: "K",
+  displayUnit: "C",
+  quantity: "temperature"
+}}
+```
+
+Supported display conversions are temperature (`K`, `C`, `F`) and precipitation
+(`m`, `mm`, `in`).
+
+Inspect controls default to click-to-inspect with `controls={{ inspect: true }}`.
+Use hover mode for a pointer-following tooltip:
+
+```tsx
+<ZarrMap
+  ...
+  controls={{ inspect: { mode: "hover", debounceMs: 75 } }}
+/>
+```
+
+## Request Preflight
+
+dClimate mode can estimate request size before bounded raster chunks are
+materialized:
+
+```tsx
+<DClimateZarrMap
+  ...
+  preflight={{ limits: { maxCells: 100_000, maxBytes: 256 * 1024 * 1024 } }}
+  onPreflight={(result) => {
+    console.log(result.cells, result.bytes, result.warnings);
+  }}
+/>
+```
+
+The framework-independent helper is also exported from core as
+`preflightGridRequest`.
+
+The dClimate gateway is not generally down. On June 9, 2026,
+`../dclimate-client-js-autoresearch` still opened the current STAC ERA5 dataset
+through `@dclimate/dclimate-client-js` plus `@dclimate/jaxray`, and its smoke
+benchmark succeeded against `https://ipfs-gateway.dclimate.net`.
+
+Current validated fixture:
+
+- collection: `ecmwf_era5`
+- dataset: `temperature_2m`
+- variant: `finalized`
+- variable: `2m_temperature`
+- CID: `bafyr4ifr5jtjeommsulg7srirdkskybj5pay3n4qyehecyzsesas5k2kd4`
+
+The earlier blocked static CIDs should be treated as stale or unretrievable
+fixtures, not evidence that the gateway or Jaxray are broken. dClimate loading
+should call the real `DClimateClient.loadDataset({ request, options })` API and
+unwrap the returned `[Dataset, metadata]` tuple.
+
+## Query Helpers
+
+```ts
+import { queryGrid, queryPoint } from "@dclimate/zarr-map/core";
+
+const clicked = await queryPoint(source, "temperature", [-8.6, 39.5], {
+  time: "2024-01-01T00:00:00.000Z"
+});
+
+const bounded = await queryGrid({
+  source,
+  variable: "temperature",
+  geometry: { type: "BoundingBox", bounds: [-9, 38, -8, 40] },
+  maxCells: 5000
+});
+```
+
+## Development
+
+```bash
+npm run typecheck
+npm run format:check
+npm run lint
+npm run test
+npm run build
+```
+
+CI runs the same package checks on pushes and pull requests. The demo app has
+its own build and deployment workflow in the separate `zarr-map-demo`
+repository. Release expectations and known renderer limitations are documented
+in `docs/release-checklist.md`.