@charlite/react-temporal 0.0.0-stage → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,94 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2026-10-08
+
+### Added
+
+- `hasNativeTemporal()` runtime probe.
+- Hooks: `useTemporalFrom`, `useTemporalSafeParse`, `useTemporalElapsed`, `useTemporalStopwatch`, `useTemporalLocalDate`, `useTemporalCompare`, `useTemporalWithin`, `useTemporalAdd`, `useTemporalCountdownStatus`.
+- `pauseWhenHidden` option on live clock hooks (battery-friendly tab background behavior).
+- `onComplete` / `intervalMs` options on `useTemporalCountdown`.
+- `runIfPast` option on `useTemporalSchedule`.
+
+### Changed
+
+- Default polyfill fallback is **`temporal-polyfill`** (smaller, spec-current) instead of `@js-temporal/polyfill` (`@js-temporal/polyfill` remains an optional peer for apps that prefer it).
+- TypeScript types sourced from `temporal-polyfill`.
+- Clock hooks share `useTemporalTicker`; interval hooks use stable duration dependency keys.
+- `useTemporalRelative` unit selection prefers the finest unit with magnitude ≥ 1 (e.g. 90 minutes, not 2 hours).
+- `useTemporalSchedule` runs immediately when the target instant is already past (configurable).
+
+## [1.0.0] - 2026-10-08
+
+### Added
+
+- [Open Knowledge Format (OKF) v0.2](https://github.com/GoogleCloudPlatform/open-knowledge-format) bundle in `knowledge/` for agent-friendly project context.
+- `AGENTS.md` entry point linking OKF concepts, docs, and tooling.
+- `.nvmrc` targeting Node.js 26.
+
+### Changed
+
+- **BREAKING**: Minimum Node.js version raised to **26** (`engines` field).
+- Replaced **Jest** with **Vitest** (`vitest.config.ts`, `vitest.setup.ts`).
+- Migrated to **ESLint 10** flat config (`eslint.config.js`).
+- Documentation updated for Node.js 26 native Temporal, Vitest, and OKF.
+
+## [0.0.3] - 2026-07-05
+
+### Added
+
+- Native Temporal support: uses `globalThis.Temporal` when available (Chrome 144+, Firefox 139+, Edge 144+), with automatic polyfill fallback.
+- `getTemporal()` utility and re-exported `Temporal` namespace from the package.
+- `useTemporalClock` — configurable-interval live clock hook.
+- `useTemporalZonedNow` — live `ZonedDateTime` for any IANA time zone.
+- `useTemporalNow` options: `intervalMs` and `timeZone`.
+- TypeScript type exports (`TemporalInstant`, `TemporalPlainDate`, `UseTemporalNowOptions`, etc.).
+- `Intl.RelativeTimeFormat` in `useTemporalRelative` for locale-aware output ("in 3 hours", "2 days ago").
+- `useTemporalFormat` now uses Temporal's native `toLocaleString` and accepts any formattable Temporal type.
+- Full documentation in the `docs/` folder.
+- Documentation for 2026 Temporal adoption, browser support, and polyfill setup.
+
+### Changed
+
+- `react` and `react-dom` are peer dependencies only (no longer direct dependencies).
+- Polyfill is no longer bundled — externalized via Rollup; install `@js-temporal/polyfill` or `temporal-polyfill` for non-native environments.
+- `useTemporalDuration` and `useTemporalDiff` now use `until()` instead of manual epoch arithmetic.
+- `useTemporalRelative` output format changed to `Intl.RelativeTimeFormat` strings.
+- `useTemporalFormat` signature now accepts `(obj, locales?, options?)` instead of `(obj, options?)`.
+- Minimum Node.js version raised to 22.
+- Peer dependencies expanded to React 17, 18, and 19.
+- CI updated to Node.js 22.
+- Migrated tests from deprecated `@testing-library/react-hooks` to `@testing-library/react`.
+
+### Fixed
+
+- `useTemporalCountdown` uses `until().total('seconds')` for correct remaining time.
+- `useTemporalSchedule` uses a ref for the callback to avoid stale closures.
+
+## [0.0.2] - 2025-07-23
+
+### Changed
+
+- `react` and `react-dom` accept `^17.0.0` versions instead of exact `17.0.0`.
+
+## [0.0.1] - 2025-07-21
+
+### Added
+
+- Initial release of `react-temporal`.
+- 15 custom React hooks for date and time management using the JavaScript Temporal API.
+- Example usage files for every hook in `examples/`.
+- Comprehensive test suite for all hooks in `src/__tests__/`.
+- Documentation and usage instructions in `README.md`.
+- Semantic versioning and changelog support.
+
+[1.1.0]: https://github.com/charlite/react-temporal/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/charlite/react-temporal/compare/v0.0.3...v1.0.0
+[0.0.3]: https://github.com/charlite/react-temporal/compare/v0.0.2...v0.0.3
+[0.0.2]: https://github.com/charlite/react-temporal/compare/v0.0.1...v0.0.2
+[0.0.1]: https://github.com/charlite/react-temporal/releases/tag/v0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Charlie Rios
+
+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,179 @@
-# Temporary Holding Version
+# react-temporal
 
-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.
+[![npm version](https://badge.fury.io/js/react-temporal.svg)](https://www.npmjs.com/package/@xarlizard/react-temporal)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![CI](https://github.com/charlite/react-temporal/actions/workflows/ci.yml/badge.svg)](https://github.com/charlite/react-temporal/actions/workflows/ci.yml)
+
+**react-temporal** is a React hooks library for date and time, built on the JavaScript [Temporal API](https://tc39.es/proposal-temporal/). Temporal reached **Stage 4** in 2026 and ships natively in Chrome 144+, Firefox 139+, Edge 144+, and **Node.js 26+**. This library uses native Temporal when available and falls back to a polyfill for Safari, older browsers, and test environments.
+
+Replace `Date`, Moment.js, and most `date-fns` use cases with immutable, time-zone-aware Temporal types — wrapped in idiomatic React hooks.
+
+📖 **[Full documentation](./docs/README.md)** — getting started, API reference, polyfill guide, and TypeScript types.
+
+🤖 **[Agent guide (OKF v0.2)](./AGENTS.md)** — machine-readable knowledge in [`knowledge/`](./knowledge/index.md).
+
+---
+
+## Why Temporal in 2026?
+
+| | Legacy `Date` | Temporal |
+| --- | --- | --- |
+| Immutability | Mutable | Immutable value objects |
+| Time zones | Error-prone offsets | First-class `ZonedDateTime` |
+| Arithmetic | Millisecond hacks | `add`, `subtract`, `until`, `since` |
+| Parsing | Implementation-defined | Strict ISO 8601 |
+| Browser support | Everywhere | Chrome 144+, Firefox 139+, Edge 144+ |
+| Node.js | Legacy APIs | **26+** native Temporal (polyfill optional) |
+
+---
+
+## Install
+
+```bash
+npm install react-temporal
+```
+
+### Polyfill (Safari, older browsers, Node < 26)
+
+Native Temporal is used automatically when available. For environments without it, install one polyfill:
+
+```bash
+# Smaller production polyfill (~20 KB gzip) — recommended
+npm install temporal-polyfill
+
+# Official reference implementation (~44 KB gzip)
+npm install @js-temporal/polyfill
+```
+
+For `temporal-polyfill`, add this once at your app entry point:
+
+```ts
+import 'temporal-polyfill/global';
+```
+
+`temporal-polyfill` is installed automatically as an optional dependency and used as the fallback when native Temporal is unavailable (`@js-temporal/polyfill` remains supported as an optional peer if you install it yourself).
+
+---
+
+## Usage
+
+All hooks are named exports. Import `Temporal` from the package or from your polyfill:
+
+```tsx
+import { useTemporalNow, useTemporalZonedNow, Temporal } from 'react-temporal';
+
+function Clock() {
+  const now = useTemporalNow();
+  const tokyo = useTemporalZonedNow('Asia/Tokyo');
+
+  return (
+    <div>
+      <p>UTC: {now.toString()}</p>
+      <p>Tokyo: {tokyo.toLocaleString()}</p>
+    </div>
+  );
+}
+```
+
+### Configurable clock
+
+```tsx
+import { useTemporalNow, useTemporalClock } from 'react-temporal';
+
+// Update every 100 ms for a smooth timer UI
+const now = useTemporalClock({ intervalMs: 100 });
+
+// Or get zoned time with a custom interval
+const local = useTemporalNow({ timeZone: 'Europe/Madrid', intervalMs: 5000 });
+```
+
+---
+
+## Hooks
+
+| Hook | Description |
+| --- | --- |
+| `useTemporalNow` | Current `Instant` or `ZonedDateTime` (with `timeZone` option), auto-updating |
+| `useTemporalClock` | Current `Instant` with configurable tick interval |
+| `useTemporalZonedNow` | Current `ZonedDateTime` for an IANA time zone |
+| `useTemporalInterval` | Run a callback on a `Duration` interval |
+| `useTemporalDuration` | `Duration` between two instants (`start.until(end)`) |
+| `useTemporalCalendar` | Validate and return a calendar ID |
+| `useTemporalTimeZone` | Validate and return a time zone ID |
+| `useTemporalFormat` | Locale-aware formatting via `toLocaleString` |
+| `useTemporalRange` | Inclusive array of `PlainDate` between two dates |
+| `useTemporalRelative` | Relative time via `Intl.RelativeTimeFormat` ("in 3 hours") |
+| `useTemporalCountdown` | Seconds remaining until a target instant |
+| `useTemporalSchedule` | `setTimeout` aligned to a target instant |
+| `useTemporalParse` | Parse an ISO string to `Instant` |
+| `useTemporalDiff` | `Duration` difference between two instants |
+| `useTemporalWeek` | All dates in the ISO week (Mon–Sun) |
+| `useTemporalMonth` | All dates in a month |
+| `useTemporalYear` | First day of each month in a year |
+| `useTemporalFrom` | Parse ISO strings into any Temporal type |
+| `useTemporalSafeParse` | Non-throwing parse (`{ value, error }`) |
+| `useTemporalElapsed` | Seconds since an instant (live) |
+| `useTemporalStopwatch` | Live `{ elapsed, seconds }` from a start instant |
+| `useTemporalLocalDate` | Today's `PlainDate` in a time zone |
+| `useTemporalCompare` | Memoized `Temporal.*.compare` |
+| `useTemporalWithin` | Inclusive range check for instants or dates |
+| `useTemporalAdd` | Memoized `.add(duration)` |
+| `useTemporalCountdownStatus` | `{ seconds, isComplete }` countdown |
+
+See [`examples/`](examples/README.md) for copy-paste examples, or the [`docs/`](docs/README.md) folder for full documentation.
+
+---
+
+## Utilities
+
+| Export | Description |
+| --- | --- |
+| `Temporal` | The Temporal namespace (native or polyfill) |
+| `getTemporal()` | Explicit resolver — native first, polyfill fallback |
+| `hasNativeTemporal()` | Whether `globalThis.Temporal` is available |
+
+---
+
+## TypeScript
+
+Full type exports are included. Types are sourced from `temporal-polyfill` and work with native Temporal at runtime:
+
+```ts
+import type { TemporalInstant, TemporalPlainDate, UseTemporalNowOptions } from 'react-temporal';
+```
+
+---
+
+## Testing
+
+```bash
+npm test
+```
+
+Unit tests use **Vitest** and live in [`src/__tests__/`](src/__tests__/).
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/charlite/react-temporal.git
+cd react-temporal
+nvm use 26   # requires Node.js 26+
+npm install
+npm test
+npm run build
+```
+
+---
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) and the [OKF knowledge bundle](./knowledge/index.md) for agent-oriented context.
+
+---
+
+## License
+
+MIT © [charlite](https://github.com/charlite)

package/dist/hooks/useTemporalAdd.d.ts

@@ -0,0 +1,7 @@
+import type { TemporalDurationLike, TemporalInstant, TemporalPlainDate } from '../types';
+type Addable = TemporalInstant | TemporalPlainDate;
+/**
+ * Memoized `temporal.add(duration)` for PlainDate or Instant values.
+ */
+export declare function useTemporalAdd<T extends Addable>(value: T, duration: TemporalDurationLike): T;
+export {};

package/dist/hooks/useTemporalCalendar.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Validates and returns the calendar ID for a given calendar name.
+ */
+export declare function useTemporalCalendar(id: string): string;

package/dist/hooks/useTemporalClock.d.ts

@@ -0,0 +1,5 @@
+import type { UseTemporalClockOptions, TemporalInstant } from '../types';
+/**
+ * Returns the current Temporal.Instant, updating at a configurable interval.
+ */
+export declare function useTemporalClock(options?: UseTemporalClockOptions): TemporalInstant;

package/dist/hooks/useTemporalCompare.d.ts

@@ -0,0 +1,7 @@
+import type { TemporalInstant, TemporalPlainDate } from '../types';
+type Comparable = TemporalInstant | TemporalPlainDate;
+/**
+ * Memoized Temporal compare result: negative if `a` is before `b`, positive if after, 0 if equal.
+ */
+export declare function useTemporalCompare(a: Comparable, b: Comparable): number;
+export {};

package/dist/hooks/useTemporalCountdown.d.ts

@@ -0,0 +1,5 @@
+import type { TemporalInstant, UseTemporalCountdownOptions } from '../types';
+/**
+ * Returns the remaining seconds until a target Temporal.Instant.
+ */
+export declare function useTemporalCountdown(target: TemporalInstant, options?: UseTemporalCountdownOptions): number;

package/dist/hooks/useTemporalCountdownStatus.d.ts

@@ -0,0 +1,11 @@
+import type { TemporalInstant, UseTemporalCountdownOptions } from '../types';
+export interface TemporalCountdownStatus {
+    /** Whole seconds remaining (0 when complete). */
+    seconds: number;
+    /** True when the target instant has been reached or passed. */
+    isComplete: boolean;
+}
+/**
+ * Countdown with structured status (seconds + completion flag).
+ */
+export declare function useTemporalCountdownStatus(target: TemporalInstant, options?: UseTemporalCountdownOptions): TemporalCountdownStatus;

package/dist/hooks/useTemporalDiff.d.ts

@@ -0,0 +1,5 @@
+import type { TemporalInstant } from '../types';
+/**
+ * Returns the difference between two instants as a Temporal.Duration.
+ */
+export declare function useTemporalDiff(a: TemporalInstant, b: TemporalInstant): import("temporal-spec").Temporal.Duration;

package/dist/hooks/useTemporalDuration.d.ts

@@ -0,0 +1,5 @@
+import type { TemporalInstant } from '../types';
+/**
+ * Returns a Temporal.Duration between two instants.
+ */
+export declare function useTemporalDuration(start: TemporalInstant, end: TemporalInstant): import("temporal-spec").Temporal.Duration;

package/dist/hooks/useTemporalElapsed.d.ts

@@ -0,0 +1,5 @@
+import type { TemporalInstant, UseTemporalClockOptions } from '../types';
+/**
+ * Returns elapsed whole seconds since a past `Temporal.Instant` (0 if the instant is in the future).
+ */
+export declare function useTemporalElapsed(since: TemporalInstant, options?: UseTemporalClockOptions): number;

package/dist/hooks/useTemporalFormat.d.ts

@@ -0,0 +1,7 @@
+import type { TemporalInstant, TemporalPlainDate, TemporalPlainTime, TemporalPlainDateTime, TemporalZonedDateTime } from '../types';
+type FormattableTemporal = TemporalInstant | TemporalPlainDate | TemporalPlainTime | TemporalPlainDateTime | TemporalZonedDateTime;
+/**
+ * Formats a Temporal object using Intl via Temporal's toLocaleString.
+ */
+export declare function useTemporalFormat(temporalObj: FormattableTemporal, locales?: string | string[], options?: Intl.DateTimeFormatOptions): string;
+export {};

package/dist/hooks/useTemporalFrom.d.ts

@@ -0,0 +1,5 @@
+import type { TemporalParseKind, TemporalParsedValue } from '../types';
+/**
+ * Parses an ISO string into the requested Temporal type (memoized on `input`).
+ */
+export declare function useTemporalFrom<K extends TemporalParseKind>(kind: K, input: string): TemporalParsedValue<K>;

package/dist/hooks/useTemporalInterval.d.ts

@@ -0,0 +1,6 @@
+import type { TemporalDurationLike } from '../types';
+/**
+ * Runs a callback at a given Temporal.Duration interval.
+ * Duration values are normalized for stable effect dependencies.
+ */
+export declare function useTemporalInterval(callback: () => void, duration: TemporalDurationLike): void;

package/dist/hooks/useTemporalLocalDate.d.ts

@@ -0,0 +1,5 @@
+import type { TemporalPlainDate, UseTemporalClockOptions } from '../types';
+/**
+ * Returns today's calendar date in the given IANA time zone, updating across midnight.
+ */
+export declare function useTemporalLocalDate(timeZone: string, options?: UseTemporalClockOptions): TemporalPlainDate;

package/dist/hooks/useTemporalMonth.d.ts

@@ -0,0 +1,5 @@
+import type { TemporalPlainDate } from '../types';
+/**
+ * Returns all dates in the month of a given Temporal.PlainDate.
+ */
+export declare function useTemporalMonth(date: TemporalPlainDate): import("temporal-spec").Temporal.PlainDate[];

package/dist/hooks/useTemporalNow.d.ts

@@ -0,0 +1,6 @@
+import type { UseTemporalNowOptions, TemporalInstant, TemporalZonedDateTime } from '../types';
+/**
+ * Returns the current time as a Temporal.Instant (or ZonedDateTime when timeZone is set),
+ * updating at the configured interval.
+ */
+export declare function useTemporalNow(options?: UseTemporalNowOptions): TemporalInstant | TemporalZonedDateTime;

package/dist/hooks/useTemporalParse.d.ts

@@ -0,0 +1,3 @@
+import type { TemporalInstant } from '../types';
+/** Parses an ISO string to Temporal.Instant. */
+export declare function useTemporalParse(isoString: string): TemporalInstant;

package/dist/hooks/useTemporalRange.d.ts

@@ -0,0 +1,5 @@
+import type { TemporalPlainDate } from '../types';
+/**
+ * Returns an array of Temporal.PlainDate between start and end (inclusive).
+ */
+export declare function useTemporalRange(start: TemporalPlainDate, end: TemporalPlainDate): import("temporal-spec").Temporal.PlainDate[];

package/dist/hooks/useTemporalRelative.d.ts

@@ -0,0 +1,6 @@
+import type { TemporalInstant } from '../types';
+/**
+ * Returns a locale-aware relative time string between two instants
+ * (e.g. "in 3 hours", "2 days ago") using Intl.RelativeTimeFormat.
+ */
+export declare function useTemporalRelative(from: TemporalInstant, to: TemporalInstant, locales?: string | string[], options?: Intl.RelativeTimeFormatOptions): string;

package/dist/hooks/useTemporalSafeParse.d.ts

@@ -0,0 +1,5 @@
+import type { TemporalParseKind, TemporalParsedValue, TemporalSafeParseResult } from '../types';
+/**
+ * Like `useTemporalFrom`, but returns `{ value, error }` instead of throwing.
+ */
+export declare function useTemporalSafeParse<K extends TemporalParseKind>(kind: K, input: string): TemporalSafeParseResult<TemporalParsedValue<K>>;

package/dist/hooks/useTemporalSchedule.d.ts

@@ -0,0 +1,9 @@
+import type { TemporalInstant } from '../types';
+export interface UseTemporalScheduleOptions {
+    /** When true (default), run immediately if the instant is already in the past. */
+    runIfPast?: boolean;
+}
+/**
+ * Schedules a callback to run at a specific Temporal.Instant.
+ */
+export declare function useTemporalSchedule(callback: () => void, instant: TemporalInstant, options?: UseTemporalScheduleOptions): void;

package/dist/hooks/useTemporalStopwatch.d.ts

@@ -0,0 +1,11 @@
+import type { TemporalDuration, TemporalInstant, UseTemporalClockOptions } from '../types';
+export interface UseTemporalStopwatchResult {
+    /** Elapsed time from `start` until now. */
+    elapsed: TemporalDuration;
+    /** Whole seconds elapsed (floor). */
+    seconds: number;
+}
+/**
+ * Live stopwatch from a fixed start instant, updating on an interval.
+ */
+export declare function useTemporalStopwatch(start: TemporalInstant, options?: UseTemporalClockOptions): UseTemporalStopwatchResult;

package/dist/hooks/useTemporalTimeZone.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Validates and returns the time zone ID for a given IANA time zone name.
+ */
+export declare function useTemporalTimeZone(id: string): string;

package/dist/hooks/useTemporalWeek.d.ts

@@ -0,0 +1,5 @@
+import type { TemporalPlainDate } from '../types';
+/**
+ * Returns all dates in the ISO week (Monday–Sunday) containing the given PlainDate.
+ */
+export declare function useTemporalWeek(date: TemporalPlainDate): import("temporal-spec").Temporal.PlainDate[];

package/dist/hooks/useTemporalWithin.d.ts

@@ -0,0 +1,5 @@
+import type { TemporalInstant, TemporalPlainDate } from '../types';
+/**
+ * True when `value` is inclusively between `start` and `end`.
+ */
+export declare function useTemporalWithin(value: TemporalInstant | TemporalPlainDate, start: TemporalInstant | TemporalPlainDate, end: TemporalInstant | TemporalPlainDate): boolean;

package/dist/hooks/useTemporalYear.d.ts

@@ -0,0 +1,5 @@
+import type { TemporalPlainDate } from '../types';
+/**
+ * Returns the first day of each month in the year of a given Temporal.PlainDate.
+ */
+export declare function useTemporalYear(date: TemporalPlainDate): import("temporal-spec").Temporal.PlainDate[];

package/dist/hooks/useTemporalZonedNow.d.ts

@@ -0,0 +1,6 @@
+import type { UseTemporalClockOptions, TemporalZonedDateTime } from '../types';
+/**
+ * Returns the current Temporal.ZonedDateTime for the given IANA time zone,
+ * updating at a configurable interval.
+ */
+export declare function useTemporalZonedNow(timeZone: string, options?: UseTemporalClockOptions): TemporalZonedDateTime;