timezone-overlap-map 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Santiago Palenque
+
+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,111 @@
-# Temporary Holding Version
+# timezone-overlap-map
 
-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.
+A web component that shows your timezone next to your visitor's on a world map, and how your working hours overlap. Built with React and TypeScript, shipped as a standard custom element, so it works in any framework or in plain HTML.
+
+- A world map with each zone's UTC-offset strip, a dot per city, and the live day/night line with the sun's position.
+- Both clocks and a zone picker that starts at the visitor's zone.
+- A 24-hour timeline in the visitor's local time, and the overlap as text for screen readers.
+
+About 15 KB gzipped, map included, plus React.
+
+## Install
+
+```sh
+npm install timezone-overlap-map react react-dom
+```
+
+React is a peer dependency: your bundler provides it.
+
+## Usage
+
+```js
+import 'timezone-overlap-map';
+```
+
+```html
+<timezone-overlap-map
+  home-zone="America/Argentina/Buenos_Aires"
+  home-label="Santiago"
+></timezone-overlap-map>
+```
+
+The visitor's zone comes from the browser (`Intl`), with no IP lookup. A selector lets them pick another one, for example a recruiter hiring for a team in a different zone.
+
+### Attributes
+
+| Attribute | Default | |
+|---|---|---|
+| `home-zone` | `UTC` | IANA zone you work from |
+| `home-label` | city of `home-zone` | Name shown for your side |
+| `visitor-zone` | the browser's zone | Starting zone for the visitor |
+| `work-start` | `9` | Start of working hours, local time in each zone |
+| `work-end` | `18` | End of working hours (a value before `work-start` means a night shift) |
+| `lang` | the closest `lang` up the tree | `en` or `es`; any other language falls back to English |
+
+The language is read when the element renders and whenever its own attributes change; if you switch the page's `<html lang>` on the client, set `lang` on the element too.
+
+Offsets are computed with `Intl` for the current date, so daylight saving time on either side is always right.
+
+### Events
+
+`zonechange` fires when the visitor picks another zone:
+
+```js
+el.addEventListener('zonechange', (event) => console.log(event.detail.zone));
+```
+
+### Theming
+
+Styles live in the shadow DOM. Custom properties cross it, so set them on the element or any ancestor:
+
+```css
+timezone-overlap-map {
+  --tom-fg: #e8e6e3;
+  --tom-muted: #9a9894;
+  --tom-track: #ffffff1a;
+  --tom-home: #4fd1c5;
+  --tom-visitor: #f6ad55;
+  --tom-overlap: #68d391;
+  --tom-land: #ffffff38;
+  --tom-night: #00000066;
+  --tom-sun: #fff7d6;
+  --tom-radius: 4px;
+  --tom-font: 14px/1.5 system-ui;
+}
+```
+
+The night and the sun have defaults for both light and dark pages, picked through the page's `color-scheme`.
+
+### Server rendering
+
+Importing the package on the server is safe: the element registers only where `customElements` exists.
+
+## Development
+
+```sh
+yarn
+yarn dev       # demo page at http://localhost:5173
+yarn test
+yarn build     # dist/: ES module + type declarations
+yarn geo       # regenerate src/geo.ts (map outline + zone coordinates)
+```
+
+## Releasing
+
+Push a `v*` tag matching `version` in `package.json`; the Release workflow tests, builds and publishes to npm with [provenance](https://docs.npmjs.com/generating-provenance-statements), through npm trusted publishing (no token stored in the repo).
+
+```sh
+npm version patch   # bumps package.json and creates the tag
+git push --follow-tags
+```
+
+## Data
+
+- Land outline: [Natural Earth](https://www.naturalearthdata.com/) 1:110m (public domain), via [world-atlas](https://github.com/topojson/world-atlas).
+- Zone locations: [IANA tz database](https://www.iana.org/time-zones) (`zone.tab`, plus links so the names `Intl` returns resolve).
+
+Both are converted once by `scripts/build-geo.mjs` into a compact SVG path and a coordinate table; the package has no runtime dependencies besides React.
+
+## License
+
+MIT

package/dist/TimezoneOverlap.d.ts

@@ -0,0 +1,12 @@
+import { type Lang } from './messages';
+export type TimezoneOverlapProps = {
+    homeZone: string;
+    homeLabel?: string;
+    visitorZone: string;
+    /** Working hours, in each zone's local time. */
+    workStart: number;
+    workEnd: number;
+    lang: Lang;
+    onVisitorZoneChange?: (zone: string) => void;
+};
+export declare function TimezoneOverlap({ homeZone, homeLabel, visitorZone: initialVisitorZone, workStart, workEnd, lang, onVisitorZoneChange, }: TimezoneOverlapProps): import("react").JSX.Element;

package/dist/WorldMap.d.ts

@@ -0,0 +1,5 @@
+export declare function WorldMap({ homeZone, visitorZone, now }: {
+    homeZone: string;
+    visitorZone: string;
+    now: Date;
+}): import("react").JSX.Element;

package/dist/element.d.ts

@@ -0,0 +1,31 @@
+export declare const TAG_NAME = "timezone-overlap-map";
+export type ZoneChangeEvent = CustomEvent<{
+    zone: string;
+}>;
+declare const BaseElement: typeof HTMLElement;
+/**
+ * `<timezone-overlap-map home-zone="America/Argentina/Buenos_Aires">`
+ *
+ * Attributes: `home-zone` (IANA name), `home-label`, `visitor-zone` (defaults to the
+ * browser's zone), `work-start` / `work-end` (local hours, default 9 and 18), `lang`
+ * (`en` or `es`; defaults to the closest `lang` up the tree, like the page's `<html lang>`).
+ * Fires `zonechange` (detail: `{ zone }`) when the visitor picks another zone.
+ */
+export declare class TimezoneOverlapMapElement extends BaseElement {
+    #private;
+    static observedAttributes: readonly ["home-zone", "home-label", "visitor-zone", "work-start", "work-end", "lang"];
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+}
+/** Registers the element under `tagName`; safe to call twice and on the server. */
+export declare function defineTimezoneOverlapMap(tagName?: string): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        'timezone-overlap-map': TimezoneOverlapMapElement;
+    }
+    interface HTMLElementEventMap {
+        zonechange: ZoneChangeEvent;
+    }
+}
+export {};

package/dist/geo.d.ts

@@ -0,0 +1,7 @@
+/** Equirectangular map: x = longitude + 180, y = 84 - latitude. */
+export declare const MAP_NORTH = 84;
+export declare const MAP_WIDTH = 360;
+export declare const MAP_HEIGHT = 142;
+export declare const LAND_PATH: string;
+/** [latitude, longitude] of each zone's main location. */
+export declare const ZONE_COORDS: Record<string, readonly [number, number]>;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { TAG_NAME, TimezoneOverlapMapElement, defineTimezoneOverlapMap, type ZoneChangeEvent } from './element';
+export { MESSAGES, resolveLang, type Lang, type Messages } from './messages';
+export { offsetMinutes, overlap, type Overlap, type Segment } from './overlap';

package/dist/messages.d.ts

@@ -0,0 +1,14 @@
+export type Messages = {
+    /** Accessible name of the zone picker. */
+    zoneLabel: string;
+    /** `duration` is already formatted ("2 h 30 min"), `ranges` is in the visitor's local time. */
+    overlap: (duration: string, home: string, ranges: string) => string;
+    none: (home: string) => string;
+};
+export declare const MESSAGES: {
+    en: Messages;
+    es: Messages;
+};
+export type Lang = keyof typeof MESSAGES;
+/** "es-AR" → "es"; anything without a translation → "en". */
+export declare function resolveLang(tag: string | null | undefined): Lang;

package/dist/overlap.d.ts

@@ -0,0 +1,41 @@
+export declare const DAY: number;
+/** A half-open range of minutes within one day: [start, end). */
+export type Segment = {
+    start: number;
+    end: number;
+};
+export type Overlap = {
+    /** Working hours of each zone and their intersection, in UTC minutes. */
+    home: Segment[];
+    visitor: Segment[];
+    both: Segment[];
+    /** Length of the overlap in minutes. */
+    minutes: number;
+};
+export declare function mod(n: number, m?: number): number;
+export declare function isValidZone(zone: string): boolean;
+/** Minutes ahead of UTC for `timeZone` at `date` (Buenos Aires → -180). */
+export declare function offsetMinutes(timeZone: string, date: Date): number;
+/** A range that may cross midnight, split into segments that don't, in order. */
+export declare function toSegments(start: number, length: number): Segment[];
+/**
+ * Moves segments by `minutes` (e.g. UTC → a zone's local time), re-splitting at midnight
+ * and joining pieces that now touch: a range split at UTC midnight is whole again locally.
+ */
+export declare function shift(segments: Segment[], minutes: number): Segment[];
+export declare function intersect(a: Segment[], b: Segment[]): Segment[];
+export declare function totalMinutes(segments: Segment[]): number;
+/**
+ * Ranges for display: a segment ending at midnight joins one starting at midnight,
+ * so 22:00–24:00 + 00:00–02:00 reads as 22:00–02:00 (`end` is then past DAY).
+ */
+export declare function joinAcrossMidnight(segments: Segment[]): Segment[];
+/** Working hours from `startHour` to `endHour` local time (a night shift may wrap), in UTC. */
+export declare function workSegmentsUtc(zone: string, startHour: number, endHour: number, date: Date): Segment[];
+export declare function overlap(homeZone: string, visitorZone: string, { workStart, workEnd, date }: {
+    workStart: number;
+    workEnd: number;
+    date: Date;
+}): Overlap;
+/** Sorted, with touching or overlapping segments joined. */
+export declare function merge(segments: Segment[]): Segment[];

package/dist/sun.d.ts

@@ -0,0 +1,12 @@
+/** Latitude and longitude, in degrees, of the point with the sun at its zenith. */
+export declare function subsolarPoint(date: Date): {
+    lat: number;
+    lon: number;
+};
+/** Latitude of the day/night line at `lon`, for the sun over `sun`. */
+export declare function terminatorLat(lon: number, sun: {
+    lat: number;
+    lon: number;
+}): number;
+/** The night side as an SVG path in map coordinates (x = lon + 180, y = MAP_NORTH - lat). */
+export declare function nightPath(date: Date, step?: number): string;