react-threat-map 0.2.0 → 0.2.2

package/DECISIONS.md

@@ -247,7 +247,8 @@ Every runtime dependency, and why it earns its place:
 Both are declared `external`, so consumers dedupe them against their own copies of d3
 rather than shipping a second one.
 
-`react` is a **peer** dependency (>=18), never bundled.
+`react` is a **peer** dependency, never bundled. The supported range and the reasoning
+behind its floor are in [§7](#7-react-version-support-1614-and-up).
 
 Deliberately **not** dependencies: no state manager, no styling library, no CSS-in-JS, no
 animation library, no `d3-selection`/`d3-zoom`/`d3-scale`. The library ships zero CSS —
@@ -329,3 +330,128 @@ lines — silently erase every self-directed threat on the map.
 Consumers upgrading from 0.1.x see new animated loops wherever their feed contains
 same-region attacks that previously rendered as static dots. This is why the change went
 out as a minor bump rather than a patch.
+
+---
+
+## 7. React version support: 16.14 and up
+
+**Chosen:** `peerDependencies: { react: ">=16.14.0" }`, covering React 16.14, 17, 18, and 19.
+
+### Why the floor is 16.14.0 and not 16.8.0
+
+16.8.0 is the obvious guess, since that is where hooks landed and hooks are all this library
+uses. It is wrong. The compiled output uses the **automatic JSX runtime**, so it imports
+`react/jsx-runtime`, and that entry point first ships in **16.14.0**.
+
+The failure mode is what makes this worth recording: on 16.8–16.13 the package *installs
+cleanly* and then fails at the consumer's bundler on an unresolved module. A range of
+`>=16.8.0` would be a promise that npm accepts and webpack rejects, which is the worst
+place for the error to surface. If the JSX transform is ever changed back to `classic`, the
+floor can drop to 16.8.0 — those two facts move together.
+
+### Why not the original `>=18.0.0`
+
+There was no recorded reason for it, and it was wrong in both directions: it excluded React
+16.14/17 consumers the library works fine on, and it *included* React 19, which was broken
+(below). Nothing here needs more than the floor — the library uses only `useState`,
+`useEffect`, `useRef`, `useMemo`, and `useCallback`.
+
+Widened in 0.2.1, as a patch: broadening a peer range cannot break an existing consumer.
+
+### Why the public types import from `react` by name
+
+Supporting a wide range is why `CSSProperties`, `MouseEvent`, `ReactElement`, and
+`RefObject` are imported **by name** rather than reached through the `React` UMD global or
+the global `JSX` namespace.
+
+A bare `JSX.Element` in an emitted `.d.ts` resolves against whatever `@types/react` the
+consumer happens to have, which is not a thing this library controls. `@types/react@19`
+removed the global `JSX` namespace, so the 0.2.0 type surface failed for React 19 consumers
+compiling with `skipLibCheck: false`:
+
+```
+dist/index.d.ts(40,76): error TS2503: Cannot find namespace 'JSX'.
+```
+
+Those four names are exported identically by `@types/react` 16 through 19. The rule is
+enforced by `tests/react-compat.test.ts`, which rejects `React.*` and `JSX.*` in `src/`.
+
+### Tradeoff accepted
+
+**The test suite does not run against the floor.** `@testing-library/react@16` requires
+React 18+, so every test here executes on 18. Covering 16.14 properly means a second
+devDependency tree and a CI matrix, which was judged not worth it for a library using five
+hooks. A green suite is therefore *not* evidence that the floor works.
+
+What closes most of the gap is static: `tests/react-compat.test.ts` asserts that every name
+imported from `react` appears on an allowlist checked against 16.14 by hand, so reaching
+for `useSyncExternalStore`, `useId`, `useTransition`, `useDeferredValue`, or `use` fails the
+build rather than shipping. It cannot catch behavioural differences — only API existence.
+
+The one behavioural difference worth knowing: React 16/17 do not batch `setState` outside
+event handlers, so the `ResizeObserver`, `matchMedia`, and geo-load callbacks each trigger
+their own render there. Every one of those call sites issues a single `setState`, so the
+practical cost is nil — but a future hook that sets two pieces of state in one async
+callback would render twice on the floor and once on 18+.
+
+---
+
+## 8. Package entry points: per-condition types, plus a `typesVersions` fallback
+
+**Chosen:** `exports` declares types *inside* each of the `import` and `require`
+conditions, and `typesVersions` maps the `geo` subpath for resolvers that ignore `exports`
+entirely.
+
+This is not decoration. 0.2.1 shipped with two independent faults here, both invisible to
+every other check in the repo: the suite imports from `src/`, and the smoke test exercises
+one resolution mode. A package can be entirely correct at runtime and still fail to
+typecheck for a large share of its consumers.
+
+### `moduleResolution: "node"` ignores `exports`, so the subpath had no types
+
+Under node10 resolution — still the default for any project that has not opted in, which
+is disproportionately the React 16/17 projects the floor in §7 deliberately invites —
+`react-threat-map/geo` resolved to nothing:
+
+```
+error TS2307: Cannot find module 'react-threat-map/geo' or its corresponding type
+declarations. There are types at '.../dist/geo.d.ts', but this result could not be
+resolved under your current 'moduleResolution' setting.
+```
+
+`typesVersions` is the only mechanism node10 honours for subpath types, so it is the fix.
+
+The workaround a consumer reaches for first is a trap worth naming, because it *looks*
+like it works: `react-threat-map/dist/geo` typechecks fine, then fails at runtime with
+`ERR_PACKAGE_PATH_NOT_EXPORTED`, since the deep path is not in `exports`. Webpack 5
+enforces the same restriction. Neither specifier satisfied both the compiler and the
+bundler — which is why this needed fixing in the library rather than working around
+downstream.
+
+### One `types` per subpath made the package masquerade as ESM
+
+The map previously declared a single `"types": "./dist/index.d.ts"` covering both
+conditions. Because this package is `"type": "module"`, that `.d.ts` is read as an ES
+module — so a **CommonJS** consumer on `node16`/`nodenext` was told the types were ESM
+while the runtime correctly handed it `dist/index.cjs`:
+
+```
+error TS1479: The current file is a CommonJS module whose imports will produce 'require'
+calls; however, the referenced file is an ECMAScript module...
+```
+
+tsup was *already emitting* `dist/index.d.cts` and `dist/geo.d.cts`. The exports map simply
+never pointed at them, so they shipped in every tarball as dead weight. Declaring types
+per-condition is what makes the dual build actually dual.
+
+### Tradeoff accepted
+
+`typesVersions` is a legacy mechanism superseded by `exports`, and it duplicates the `geo`
+mapping in a second place. Adding a subpath therefore means editing both, and forgetting
+one breaks only node10 consumers — the group least likely to be on the maintainer's
+machine. It is kept because node10 offers no alternative, and dropping it would mean
+telling React 16/17 consumers to change their `tsconfig` to install a library that
+otherwise supports them.
+
+`npm run check:exports` (arethetypeswrong) runs in CI and covers every entry point against
+every resolution mode. It is what would have caught both faults before 0.2.1 went out.

package/README.md

@@ -49,12 +49,17 @@ import { ThreatMap } from 'react-threat-map';
 npm install react-threat-map
 ```
 
-React 18+ is a peer dependency:
+React is a peer dependency:
 
 ```json
-{ "peerDependencies": { "react": ">=18.0.0" } }
+{ "peerDependencies": { "react": ">=16.14.0" } }
 ```
 
+16.14.0 is the floor because that is the first release to ship `react/jsx-runtime`,
+which the compiled output imports. The library uses only `useState`, `useEffect`,
+`useRef`, `useMemo`, and `useCallback`, so nothing above that floor is required —
+React 16.14, 17, 18, and 19 are all supported.
+
 ---
 
 ## Quick start

package/dist/geo.d.cts

@@ -1,5 +1,6 @@
-import { G as GeoData } from './regions-neHSPgtu.cjs';
-export { R as RegionEntry, a as RegionIndex, U as UNKNOWN_REGION, g as getRegionById, l as listRegions, b as lookupRegionCode } from './regions-neHSPgtu.cjs';
+import { G as GeoData } from './regions-Bsys6EFr.cjs';
+export { R as RegionEntry, a as RegionIndex, U as UNKNOWN_REGION, g as getRegionById, l as listRegions, b as lookupRegionCode } from './regions-Bsys6EFr.cjs';
+import 'react';
 
 /**
  * Boundary geometry loading — the `react-threat-map/geo` entry point.

package/dist/geo.d.ts

@@ -1,5 +1,6 @@
-import { G as GeoData } from './regions-neHSPgtu.js';
-export { R as RegionEntry, a as RegionIndex, U as UNKNOWN_REGION, g as getRegionById, l as listRegions, b as lookupRegionCode } from './regions-neHSPgtu.js';
+import { G as GeoData } from './regions-Bsys6EFr.js';
+export { R as RegionEntry, a as RegionIndex, U as UNKNOWN_REGION, g as getRegionById, l as listRegions, b as lookupRegionCode } from './regions-Bsys6EFr.js';
+import 'react';
 
 /**
  * Boundary geometry loading — the `react-threat-map/geo` entry point.

package/dist/index.d.cts

@@ -1,5 +1,6 @@
-import { T as ThreatMapProps, A as AnimationConfig, L as LineStyleConfig, c as RegionsConfig, d as ThreatMapTheme, e as AggregationConfig, a as RegionIndex, f as Attack, h as Threat, I as IntensityScale, S as Severity, i as ResolvedRegion, j as AggregationGranularity, k as LatLng, m as AttackLocation } from './regions-neHSPgtu.cjs';
-export { n as AggregationGroupBy, o as AggregationKeyFn, p as AggregationSeverityFn, C as Color, E as EasingName, G as GeoData, q as GeoFeature, r as GeoFeatureCollection, s as GeoGeometry, t as GeoProjectionLike, P as ProjectionName, u as ProjectionSpec, v as RegionCode, R as RegionEntry, w as RegionKind, x as RegionRenderContext, y as RegionRenderer, z as ThreatMapError, B as ThreatRenderContext, D as ThreatRenderer, U as UNKNOWN_REGION, g as getRegionById, l as listRegions, b as lookupRegionCode } from './regions-neHSPgtu.cjs';
+import { ReactElement } from 'react';
+import { T as ThreatMapProps, A as AnimationConfig, L as LineStyleConfig, c as RegionsConfig, d as ThreatMapTheme, e as AggregationConfig, a as RegionIndex, f as Attack, h as Threat, I as IntensityScale, S as Severity, i as ResolvedRegion, j as AggregationGranularity, k as LatLng, m as AttackLocation } from './regions-Bsys6EFr.cjs';
+export { n as AggregationGroupBy, o as AggregationKeyFn, p as AggregationSeverityFn, C as Color, E as EasingName, G as GeoData, q as GeoFeature, r as GeoFeatureCollection, s as GeoGeometry, t as GeoProjectionLike, P as ProjectionName, u as ProjectionSpec, v as RegionCode, R as RegionEntry, w as RegionKind, x as RegionRenderContext, y as RegionRenderer, z as ThreatMapError, B as ThreatRenderContext, D as ThreatRenderer, U as UNKNOWN_REGION, g as getRegionById, l as listRegions, b as lookupRegionCode } from './regions-Bsys6EFr.cjs';
 
 /**
  * The `<ThreatMap>` component.
@@ -37,7 +38,7 @@ export { n as AggregationGroupBy, o as AggregationKeyFn, p as AggregationSeverit
  * />
  * ```
  */
-declare function ThreatMap<TMeta = unknown>(props: ThreatMapProps<TMeta>): JSX.Element;
+declare function ThreatMap<TMeta = unknown>(props: ThreatMapProps<TMeta>): ReactElement;
 
 /**
  * Default theme and configuration objects.

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { T as ThreatMapProps, A as AnimationConfig, L as LineStyleConfig, c as RegionsConfig, d as ThreatMapTheme, e as AggregationConfig, a as RegionIndex, f as Attack, h as Threat, I as IntensityScale, S as Severity, i as ResolvedRegion, j as AggregationGranularity, k as LatLng, m as AttackLocation } from './regions-neHSPgtu.js';
-export { n as AggregationGroupBy, o as AggregationKeyFn, p as AggregationSeverityFn, C as Color, E as EasingName, G as GeoData, q as GeoFeature, r as GeoFeatureCollection, s as GeoGeometry, t as GeoProjectionLike, P as ProjectionName, u as ProjectionSpec, v as RegionCode, R as RegionEntry, w as RegionKind, x as RegionRenderContext, y as RegionRenderer, z as ThreatMapError, B as ThreatRenderContext, D as ThreatRenderer, U as UNKNOWN_REGION, g as getRegionById, l as listRegions, b as lookupRegionCode } from './regions-neHSPgtu.js';
+import { ReactElement } from 'react';
+import { T as ThreatMapProps, A as AnimationConfig, L as LineStyleConfig, c as RegionsConfig, d as ThreatMapTheme, e as AggregationConfig, a as RegionIndex, f as Attack, h as Threat, I as IntensityScale, S as Severity, i as ResolvedRegion, j as AggregationGranularity, k as LatLng, m as AttackLocation } from './regions-Bsys6EFr.js';
+export { n as AggregationGroupBy, o as AggregationKeyFn, p as AggregationSeverityFn, C as Color, E as EasingName, G as GeoData, q as GeoFeature, r as GeoFeatureCollection, s as GeoGeometry, t as GeoProjectionLike, P as ProjectionName, u as ProjectionSpec, v as RegionCode, R as RegionEntry, w as RegionKind, x as RegionRenderContext, y as RegionRenderer, z as ThreatMapError, B as ThreatRenderContext, D as ThreatRenderer, U as UNKNOWN_REGION, g as getRegionById, l as listRegions, b as lookupRegionCode } from './regions-Bsys6EFr.js';
 
 /**
  * The `<ThreatMap>` component.
@@ -37,7 +38,7 @@ export { n as AggregationGroupBy, o as AggregationKeyFn, p as AggregationSeverit
  * />
  * ```
  */
-declare function ThreatMap<TMeta = unknown>(props: ThreatMapProps<TMeta>): JSX.Element;
+declare function ThreatMap<TMeta = unknown>(props: ThreatMapProps<TMeta>): ReactElement;
 
 /**
  * Default theme and configuration objects.

package/dist/{regions-neHSPgtu.d.cts → regions-Bsys6EFr.d.cts}

@@ -1,3 +1,5 @@
+import { CSSProperties } from 'react';
+
 /**
  * Public data types for `react-threat-map`.
  *
@@ -6,6 +8,7 @@
  *
  * @packageDocumentation
  */
+
 /**
  * A raw geographic coordinate in degrees (WGS84).
  *
@@ -651,7 +654,7 @@ interface ThreatMapProps<TMeta = unknown> {
     /** Applied to the wrapper element. */
     readonly className?: string;
     /** Applied to the wrapper element. The canvases fill it. */
-    readonly style?: React.CSSProperties;
+    readonly style?: CSSProperties;
     /** Accessible label for the map. Default `"Cyberattack threat map"`. */
     readonly ariaLabel?: string;
 }

package/dist/{regions-neHSPgtu.d.ts → regions-Bsys6EFr.d.ts}

@@ -1,3 +1,5 @@
+import { CSSProperties } from 'react';
+
 /**
  * Public data types for `react-threat-map`.
  *
@@ -6,6 +8,7 @@
  *
  * @packageDocumentation
  */
+
 /**
  * A raw geographic coordinate in degrees (WGS84).
  *
@@ -651,7 +654,7 @@ interface ThreatMapProps<TMeta = unknown> {
     /** Applied to the wrapper element. */
     readonly className?: string;
     /** Applied to the wrapper element. The canvases fill it. */
-    readonly style?: React.CSSProperties;
+    readonly style?: CSSProperties;
     /** Accessible label for the map. Default `"Cyberattack threat map"`. */
     readonly ariaLabel?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-threat-map",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "A React component that renders animated cyberattack threats on a static world map, with intelligent per-region aggregation and first-class US state support.",
   "keywords": [
     "react",
@@ -29,16 +29,33 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "geo": [
+        "./dist/geo.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     },
     "./geo": {
-      "types": "./dist/geo.d.ts",
-      "import": "./dist/geo.js",
-      "require": "./dist/geo.cjs"
+      "import": {
+        "types": "./dist/geo.d.ts",
+        "default": "./dist/geo.js"
+      },
+      "require": {
+        "types": "./dist/geo.d.cts",
+        "default": "./dist/geo.cjs"
+      }
     },
     "./package.json": "./package.json"
   },
@@ -56,6 +73,7 @@
     "build": "npm run geo && tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
+    "check:exports": "attw --pack .",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -64,13 +82,14 @@
     "example": "npm --prefix examples/demo run dev"
   },
   "peerDependencies": {
-    "react": ">=18.0.0"
+    "react": ">=16.14.0"
   },
   "dependencies": {
     "d3-geo": "^3.1.1",
     "topojson-client": "^3.1.0"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.1.0",
     "@types/d3-geo": "^3.1.0",