@mmerlone/react-tz-globepicker 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcio Merlone
+
+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,416 @@
+# react-tz-globepicker
+
+Interactive 3D globe component for timezone selection with React.
+
+https://miro.medium.com/v2/resize:fit:4800/format:webp/0*AuW8APtlc27iI-5D
+
+## Features
+
+- Interactive 3D globe visualization with drag-to-rotate and zoom
+- Clickable timezone markers with hover tooltips
+- Animated fly-to transitions when selecting timezones
+- Multiple visualization modes (nautic bands, etc-gmt boundaries, iana country-level)
+- Bundled timezone data for easy setup
+
+## Installation
+
+```bash
+pnpm add react-tz-globepicker
+# or
+npm install react-tz-globepicker
+# or
+yarn add react-tz-globepicker
+```
+
+## Peer Dependencies
+
+This package requires the following peer dependencies:
+
+- `react` ^18.0.0
+- `react-dom` ^18.0.0
+
+## Complete Example
+
+Here's a complete example showing how to use the utilities together, similar to how they're used in production applications:
+
+```tsx
+import React, { useState, useEffect } from "react";
+import {
+  TzGlobePicker,
+  buildMarkerList,
+} from "react-tz-globepicker";
+
+interface TimezoneOption {
+  value: string;
+  label: string;
+}
+
+// You would typically get this from your own API or timezone utilities
+const mockTimezones: TimezoneOption[] = [
+  { value: "America/New_York", label: "America/New York (UTC-5)" },
+  { value: "Europe/London", label: "Europe/London (UTC+0)" },
+  { value: "Asia/Tokyo", label: "Asia/Tokyo (UTC+9)" },
+  { value: "Australia/Sydney", label: "Australia/Sydney (UTC+10)" },
+];
+
+function TimezoneSelector() {
+  const [selectedTimezone, setSelectedTimezone] = useState<string | null>(
+    "America/New_York",
+  );
+  const [timezones, setTimezones] = useState<TimezoneOption[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    // Load available timezones (you'd typically get this from your own API)
+    setTimeout(() => {
+      setTimezones(mockTimezones);
+      setIsLoading(false);
+    }, 500);
+  }, []);
+
+  // Generate markers for the globe from available timezones
+  const markers = buildMarkerList(timezones.map((tz) => tz.value));
+
+  return (
+    <div style={{ display: "flex", gap: "2rem", padding: "2rem" }}>
+      {/* Globe Component */}
+      <div>
+        <h3>Select Timezone on Globe</h3>
+        <TzGlobePicker
+          timezone={selectedTimezone}
+          size={350}
+          onSelect={(tz) => setSelectedTimezone(tz)}
+          markers={markers}
+          showTooltips={true}
+          zoomMarkers={true}
+          showCountryBorders={true}
+          showTZBoundaries="etc-gmt"
+        />
+      </div>
+
+      {/* Dropdown Selector */}
+      <div style={{ minWidth: "300px" }}>
+        <h3>Or Select from List</h3>
+        <label htmlFor="timezone-select">Timezone</label>
+        <select
+          id="timezone-select"
+          style={{ display: "block", marginTop: "0.5rem", minWidth: "100%" }}
+          value={selectedTimezone ?? ""}
+          onChange={(event) => {
+            setSelectedTimezone(event.target.value || null);
+          }}
+          disabled={isLoading}
+        >
+          <option value="">Select your timezone...</option>
+          {timezones.map((tz) => (
+            <option key={tz.value} value={tz.value}>
+              {tz.label}
+            </option>
+          ))}
+        </select>
+
+        {selectedTimezone && (
+          <div
+            style={{
+              marginTop: "1rem",
+              padding: "1rem",
+              backgroundColor: "#f5f5f5",
+              borderRadius: "4px",
+            }}
+          >
+            <strong>Selected:</strong> {selectedTimezone}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function App() {
+  return <TimezoneSelector />;
+}
+```
+
+## Basic Usage
+
+```tsx
+import { TzGlobePicker } from "react-tz-globepicker";
+
+function App() {
+  const [timezone, setTimezone] = React.useState<string | null>(
+    "America/New_York",
+  );
+
+  return (
+    <TzGlobePicker
+      timezone={timezone}
+      size={400}
+      onSelect={(tz) => setTimezone(tz)}
+      showMarkers={true}
+      showTooltips={true}
+    />
+  );
+}
+```
+
+## Space Background
+
+The package includes a small `SpaceBackground` React component you can pass as the `background` prop to get a starfield-style backdrop.
+
+```tsx
+import { TzGlobePicker, SpaceBackground } from "react-tz-globepicker";
+
+function App() {
+  return (
+    <TzGlobePicker
+      timezone="America/New_York"
+      size={400}
+      onSelect={(tz) => console.log(tz)}
+      showMarkers={true}
+      background={<SpaceBackground />}
+    />
+  );
+}
+```
+
+
+### Boundary Mode Constants
+
+Use `TZ_BOUNDARY_MODES` to avoid string literals when setting `showTZBoundaries`:
+
+```tsx
+import {
+  TzGlobePicker,
+  TZ_BOUNDARY_MODES,
+  type TzBoundaryMode,
+} from "react-tz-globepicker";
+
+function App() {
+  const [mode, setMode] = React.useState<TzBoundaryMode>(
+    TZ_BOUNDARY_MODES.ETCGMT,
+  );
+
+  return (
+    <TzGlobePicker
+      timezone="Europe/London"
+      showTZBoundaries={mode}
+      onSelect={(tz) => setMode(TZ_BOUNDARY_MODES.IANA)}
+    />
+  );
+}
+```
+
+## Data Loading
+
+The component uses bundled timezone data and requires no additional configuration for data loading.
+
+### Updating Globe Data
+
+To update the bundled globe data artifacts, run:
+
+```bash
+pnpm gen:globe
+```
+
+This will fetch the latest data from Natural Earth and regenerate the files in `src/data/`, including the split IANA and ETC/GMT geometry artifacts.
+
+## API Reference
+
+### TzGlobePicker Props
+
+| Prop                 | Type                                                | Default     | Description                                        |
+| -------------------- | --------------------------------------------------- | ----------- | -------------------------------------------------- |
+| `timezone`           | `string \| null`                                    | `null`      | IANA timezone identifier (e.g. "America/New_York") |
+| `size`               | `number`                                            | `250`       | Globe diameter in pixels                           |
+| `onSelect`           | `(timezone: string) => void`                        | -           | Called when a timezone marker is clicked           |
+| `showMarkers`        | `boolean`                                           | `false`     | Whether to render timezone markers                 |
+| `showTooltips`       | `boolean`                                           | `false`     | Whether to show hover tooltips on markers          |
+| `zoomMarkers`        | `boolean`                                           | `false`     | When true, markers scale with zoom level           |
+| `showTZBoundaries`   | `'nautic' \| 'etc-gmt' \| 'iana' \| 'none'`          | `'none'`    | Timezone boundary visualization mode               |
+| `showCountryBorders` | `boolean`                                           | `false`     | Whether to render country borders                  |
+| `markers`            | `MarkerEntry[]`                                     | -           | Optional explicit marker list                      |
+| `background`         | `string \| React.ReactElement \| null \| undefined` | `undefined` | Background styling (color, JSX, or transparent)    |
+| `colors`             | `Partial<GlobePalette>`                             | -           | Custom color palette override                      |
+| `minZoom`            | `number`                                            | `MIN_ZOOM`  | Minimum zoom level                                 |
+| `maxZoom`            | `number`                                            | `MAX_ZOOM`  | Maximum zoom level                                 |
+| `initialZoom`        | `number`                                            | `1`         | Initial zoom level                                 |
+| `style`              | `React.CSSProperties`                               | -           | Optional inline styles for the outer container     |
+| `className`          | `string`                                            | -           | Optional CSS class name for the outer container    |
+
+## Exported Components
+
+```typescript
+import { TzGlobePicker, SpaceBackground } from "react-tz-globepicker";
+```
+
+- `TzGlobePicker`: Main interactive globe component
+- `SpaceBackground`: Optional starfield-style background component
+
+## Exported Types
+
+```typescript
+import type {
+  TzGlobePickerProps,
+  TzBoundaryMode,
+  GlobeState,
+  MarkerEntry,
+  Coordinate,
+  LatLng,
+  Rotation,
+  GeoData,
+  RenderFn,
+} from "react-tz-globepicker";
+```
+
+## Exported Constants
+
+```typescript
+import {
+  TZ_BOUNDARY_MODES,
+  COLORS,
+  TILT,
+  GRATICULE_STEP,
+  MAX_BOUNDARY_AREA,
+  HIT_RADIUS,
+  CLICK_THRESHOLD,
+  FLY_DURATION,
+  DRAG_SENSITIVITY,
+  INERTIA_FRICTION,
+  INERTIA_MIN_VELOCITY,
+  MIN_ZOOM,
+  MAX_ZOOM,
+  ZOOM_SENSITIVITY,
+  MAX_LATITUDE,
+} from "react-tz-globepicker";
+```
+
+## Exported Utils
+
+```typescript
+import {
+  formatUtcOffset,
+  getSubsolarPoint,
+  getTimezoneCenter,
+  getUtcOffsetMinutes,
+  getUtcOffsetHour,
+  buildMarkerList,
+  CANONICAL_MARKERS,
+  TIMEZONE_COORDINATES,
+  mapToCanonicalTz,
+  utcOffsetToLongitude,
+  useGlobeState,
+} from "react-tz-globepicker";
+```
+
+### Utility Functions
+
+#### `buildMarkerList(allowed?)`
+
+Builds a list of timezone markers from coordinate data. Used to generate markers for the globe.
+
+```tsx
+import { buildMarkerList } from "react-tz-globepicker";
+
+// Get markers for all timezones
+const allMarkers = buildMarkerList();
+
+// Get markers for specific timezones only
+const timezones = ["America/New_York", "Europe/London", "Asia/Tokyo"];
+const filteredMarkers = buildMarkerList(timezones);
+
+// Example: Generate markers from timezone objects with value property
+const timezoneObjects = [
+  { value: "America/New_York", label: "New York" },
+  { value: "Europe/London", label: "London" },
+];
+const markers = buildMarkerList(timezoneObjects.map((tz) => tz.value));
+```
+
+#### `CANONICAL_MARKERS`
+
+Pre-built subset of markers filtered to canonical timezone regions (~64 entries).
+
+```tsx
+import { CANONICAL_MARKERS } from "react-tz-globepicker";
+
+// Use canonical markers for better performance
+<TzGlobePicker markers={CANONICAL_MARKERS} />;
+```
+
+#### `TIMEZONE_COORDINATES`
+
+Lookup map from IANA timezone ID to approximate [lat, lng] centroid coordinates.
+
+```tsx
+import { TIMEZONE_COORDINATES } from "react-tz-globepicker";
+
+const [lat, lng] = TIMEZONE_COORDINATES["America/New_York"] ?? [0, 0];
+console.log(`New York is at ${lat}°, ${lng}°`);
+```
+
+#### `getUtcOffsetMinutes(timezone)` & `getUtcOffsetHour(timezone)`
+
+Get current UTC offset for a timezone.
+
+```tsx
+import { getUtcOffsetMinutes, getUtcOffsetHour } from "react-tz-globepicker";
+
+const offsetMinutes = getUtcOffsetMinutes("America/New_York"); // -300 or -240 (DST)
+const offsetHours = getUtcOffsetHour("Asia/Kolkata"); // 5.5
+```
+
+#### `mapToCanonicalTz(timezone)`
+
+Map any IANA timezone to its canonical timezone-boundary-builder region.
+
+```tsx
+import { mapToCanonicalTz } from "react-tz-globepicker";
+
+const canonical = mapToCanonicalTz("America/Indiana/Indianapolis");
+// Returns: 'America/New_York'
+```
+
+#### `utcOffsetToLongitude(offset)`
+
+Convert UTC offset to longitude center.
+
+```tsx
+import { utcOffsetToLongitude } from "react-tz-globepicker";
+
+const longitude = utcOffsetToLongitude(-5); // -75 (Eastern US)
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run linting
+pnpm lint
+
+# Run type checking
+pnpm type-check
+
+# Format code
+pnpm format
+
+# Format check
+pnpm format:check
+
+# Update globe data
+pnpm gen:globe
+```
+
+## License
+
+MIT
+
+## Data Sources
+
+This package uses high-quality, open geodata from:
+
+- [Natural Earth 10m Time Zones](https://github.com/nvkelso/natural-earth-vector): authoritative, closed-polygon timezone boundaries. See [ne_10m_time_zones.geojson](https://github.com/nvkelso/natural-earth-vector/blob/master/geojson/ne_10m_time_zones.geojson).
+- [visionscarto-world-atlas](https://github.com/visionscarto/world-atlas): simplified world country boundaries (110m resolution).
+
+Data is downloaded and processed automatically by the `pnpm gen:globe` script. See `scripts/update-globe-data.ts` for details.

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@mmerlone/react-tz-globepicker",
+  "version": "0.1.0",
+  "type": "module",
+  "workspaces": [
+    "demo"
+  ],
+  "description": "Interactive 3D globe component for timezone selection with React",
+  "homepage": "https://ywybase.vercel.app/",
+  "author": "Marcio Merlone <mmerlone@gmail.com> (https://mmerlone.dev.br)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mmerlone/react-tz-globepicker.git"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "scripts"
+  ],
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "dependencies": {
+    "d3-drag": "^3.0.0",
+    "d3-geo": "^3.1.1",
+    "d3-selection": "^3.0.0",
+    "hex-rgb": "^5.0.0",
+    "topojson-client": "^3.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/d3-drag": "^3.0.7",
+    "@types/d3-geo": "^3.1.0",
+    "@types/d3-selection": "^3.0.11",
+    "@types/geojson": "^7946.0.13",
+    "@types/node": "^22",
+    "@types/react": "^18",
+    "@types/react-dom": "^18",
+    "@types/topojson-client": "^3.1.5",
+    "@types/topojson-server": "^3.0.4",
+    "@types/topojson-simplify": "^3.0.3",
+    "@types/topojson-specification": "^1.0.5",
+    "@types/yauzl": "^2.10.3",
+    "@typescript-eslint/eslint-plugin": "^8.48.0",
+    "@typescript-eslint/parser": "^8.48.0",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "globals": "^17.3.0",
+    "husky": "^8.0.0",
+    "prettier": "^3.3.3",
+    "topojson-server": "^3.0.1",
+    "topojson-simplify": "^3.0.3",
+    "tsx": "^4.7.1",
+    "typescript": "^5.3.0",
+    "visionscarto-world-atlas": "^1.0.0",
+    "yauzl": "^3.2.1"
+  },
+  "keywords": [
+    "react",
+    "timezone",
+    "globe",
+    "3d",
+    "interactive",
+    "d3",
+    "geojson"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "type-check": "tsc --noEmit",
+    "build": "tsc --project tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "prebuild": "pnpm clean",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "gen:globe": "tsx scripts/update-globe-data.ts",
+    "test:unit": "tsx scripts/test-iana-to-etc.ts",
+    "demo": "pnpm --filter ./demo dev"
+  }
+}

package/scripts/test-iana-to-etc.ts

@@ -0,0 +1,52 @@
+import { ianaToEtc, offsetKeyFromEtc } from "../src/utils/timezoneMapping";
+
+const cases: Array<[string, string]> = [
+  ["America/New_York", "UTC-05:00"],
+  ["America/Los_Angeles", "UTC-08:00"],
+  ["Asia/Kolkata", "UTC+05:30"],
+  ["Pacific/Chatham", "UTC+12:45"],
+  ["UTC", "UTC+00:00"],
+];
+
+let failed = 0;
+for (const [input, expected] of cases) {
+  try {
+    const got = ianaToEtc(input);
+    if (got !== expected) {
+      console.error(`FAIL: ${input} -> expected ${expected}, got ${got}`);
+      failed++;
+    } else {
+      console.log(`ok: ${input} -> ${got}`);
+    }
+  } catch (e) {
+    console.error(`ERROR: ${input} threw`, e);
+    failed++;
+  }
+}
+
+// Basic etc parsing test
+const etcCases: Array<[string, string]> = [
+  ["Etc/GMT+5", "UTC-05:00"],
+  ["Etc/GMT-3", "UTC+03:00"],
+  ["GMT+05:30", "UTC+05:30"],
+];
+for (const [input, expected] of etcCases) {
+  try {
+    const got = offsetKeyFromEtc(input);
+    if (got !== expected) {
+      console.error(`FAIL: ${input} -> expected ${expected}, got ${got}`);
+      failed++;
+    } else {
+      console.log(`ok: ${input} -> ${got}`);
+    }
+  } catch (e) {
+    console.error(`ERROR: ${input} threw`, e);
+    failed++;
+  }
+}
+
+if (failed > 0) {
+  console.error(`${failed} tests failed`);
+  process.exit(1);
+}
+console.log("All tests passed");