@charlite/react-temporal 0.0.0-stage → 1.1.1

package/docs/api-reference.md

@@ -0,0 +1,331 @@
+# API reference
+
+All exports from `@charlite/react-temporal`.
+
+## Utilities
+
+### `Temporal`
+
+Re-exported Temporal namespace (native or polyfill).
+
+```ts
+import { Temporal } from '@charlite/react-temporal';
+
+const date = Temporal.PlainDate.from('2026-07-05');
+const now = Temporal.Now.instant();
+```
+
+### `getTemporal()`
+
+Returns the resolved Temporal namespace. Prefer using `Temporal` directly.
+
+```ts
+import { getTemporal } from '@charlite/react-temporal';
+
+const T = getTemporal();
+```
+
+### `hasNativeTemporal()`
+
+Returns `true` when `globalThis.Temporal` is defined.
+
+---
+
+## Parsing
+
+### `useTemporalFrom(kind, input)`
+
+Parses an ISO string into the requested Temporal type.
+
+**Kinds:** `'instant' | 'plainDate' | 'plainTime' | 'plainDateTime' | 'zonedDateTime'`
+
+### `useTemporalSafeParse(kind, input)`
+
+Same as `useTemporalFrom`, but returns `{ value, error }` instead of throwing.
+
+---
+
+## Clock hooks
+
+### `useTemporalNow(options?)`
+
+Returns the current time, updating at a configurable interval.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `intervalMs` | `number` | `1000` | Tick interval in milliseconds |
+| `timeZone` | `string` | — | IANA time zone; when set, returns `ZonedDateTime` |
+| `pauseWhenHidden` | `boolean` | `false` | Skip ticks while the document is hidden |
+
+**Returns:** `Temporal.Instant` or `Temporal.ZonedDateTime`
+
+```tsx
+const now = useTemporalNow();
+const madrid = useTemporalNow({ timeZone: 'Europe/Madrid', intervalMs: 5000 });
+```
+
+---
+
+### `useTemporalClock(options?)`
+
+Live clock returning `Temporal.Instant`. Simpler alternative to `useTemporalNow` without time zone support.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `intervalMs` | `number` | `1000` | Tick interval in milliseconds |
+
+**Returns:** `Temporal.Instant`
+
+```tsx
+const now = useTemporalClock({ intervalMs: 100 });
+```
+
+---
+
+### `useTemporalZonedNow(timeZone, options?)`
+
+Live clock for a specific IANA time zone.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `timeZone` | `string` | IANA time zone identifier (e.g. `'Asia/Tokyo'`) |
+| `options.intervalMs` | `number` | Tick interval (default `1000`) |
+
+**Returns:** `Temporal.ZonedDateTime`
+
+```tsx
+const tokyo = useTemporalZonedNow('Asia/Tokyo');
+```
+
+---
+
+## Duration and difference
+
+### `useTemporalDuration(start, end)`
+
+Returns the duration from `start` to `end` using `start.until(end)`.
+
+**Returns:** `Temporal.Duration`
+
+```tsx
+const duration = useTemporalDuration(startInstant, endInstant);
+duration.total('minutes'); // 90
+```
+
+---
+
+### `useTemporalDiff(a, b)`
+
+Alias-style hook returning `a.until(b)`.
+
+**Returns:** `Temporal.Duration`
+
+```tsx
+const diff = useTemporalDiff(earlier, later);
+diff.total('hours');
+```
+
+---
+
+## Formatting and parsing
+
+### `useTemporalFormat(temporalObj, locales?, options?)`
+
+Formats a Temporal value using `toLocaleString`.
+
+**Accepts:** `Instant`, `PlainDate`, `PlainTime`, `PlainDateTime`, `ZonedDateTime`
+
+**Returns:** `string`
+
+```tsx
+const formatted = useTemporalFormat(
+  Temporal.PlainDateTime.from('2026-07-05T14:30:00'),
+  'en-US',
+  { dateStyle: 'full', timeStyle: 'short' },
+);
+```
+
+---
+
+### `useTemporalParse(isoString)`
+
+Parses an ISO 8601 string to `Temporal.Instant`. Memoized on `isoString`.
+
+**Returns:** `Temporal.Instant`
+
+```tsx
+const instant = useTemporalParse('2026-07-05T12:00:00Z');
+```
+
+---
+
+### `useTemporalRelative(from, to, locales?, options?)`
+
+Locale-aware relative time via `Intl.RelativeTimeFormat`.
+
+**Returns:** `string` (e.g. `"in 3 hours"`, `"2 days ago"`)
+
+```tsx
+const label = useTemporalRelative(past, future, 'en', { numeric: 'auto' });
+```
+
+---
+
+## Calendar and ranges
+
+### `useTemporalRange(start, end)`
+
+Inclusive array of `PlainDate` from `start` to `end`.
+
+**Returns:** `Temporal.PlainDate[]`
+
+```tsx
+const dates = useTemporalRange(
+  Temporal.PlainDate.from('2026-07-01'),
+  Temporal.PlainDate.from('2026-07-07'),
+);
+```
+
+---
+
+### `useTemporalWeek(date)`
+
+All dates in the ISO week (Monday–Sunday) containing `date`.
+
+**Returns:** `Temporal.PlainDate[]` (7 items)
+
+```tsx
+const week = useTemporalWeek(Temporal.PlainDate.from('2026-07-05'));
+```
+
+---
+
+### `useTemporalMonth(date)`
+
+All dates in the month of `date`.
+
+**Returns:** `Temporal.PlainDate[]`
+
+```tsx
+const days = useTemporalMonth(Temporal.PlainDate.from('2026-07-15'));
+```
+
+---
+
+### `useTemporalYear(date)`
+
+First day of each month in the year of `date`.
+
+**Returns:** `Temporal.PlainDate[]` (12 items)
+
+```tsx
+const months = useTemporalYear(Temporal.PlainDate.from('2026-07-05'));
+```
+
+---
+
+## Validation
+
+### `useTemporalCalendar(id)`
+
+Validates a calendar identifier and returns the resolved calendar ID.
+
+**Returns:** `string`
+
+```tsx
+const id = useTemporalCalendar('iso8601'); // 'iso8601'
+```
+
+---
+
+### `useTemporalTimeZone(id)`
+
+Validates an IANA time zone and returns the resolved time zone ID.
+
+**Returns:** `string`
+
+```tsx
+const id = useTemporalTimeZone('Europe/Madrid'); // 'Europe/Madrid'
+```
+
+---
+
+## Timers and scheduling
+
+### `useTemporalInterval(callback, duration)`
+
+Runs `callback` repeatedly at the given `Temporal.DurationLike` interval. Uses a ref for the callback to avoid stale closures.
+
+```tsx
+useTemporalInterval(() => refresh(), { seconds: 30 });
+```
+
+---
+
+### `useTemporalCountdown(target, options?)`
+
+Seconds remaining until `target`. Returns `0` after the target passes.
+
+| Option | Description |
+| --- | --- |
+| `intervalMs` | Tick interval (default `1000`) |
+| `onComplete` | Called once when countdown reaches zero |
+
+### `useTemporalCountdownStatus(target, options?)`
+
+Same as countdown but returns `{ seconds, isComplete }`.
+
+### `useTemporalElapsed(since, options?)`
+
+Live seconds elapsed since `since` (0 if `since` is in the future).
+
+### `useTemporalStopwatch(start, options?)`
+
+Returns `{ elapsed: Duration, seconds }` updating from `start`.
+
+### `useTemporalLocalDate(timeZone, options?)`
+
+Today's `PlainDate` in the given IANA zone (default tick: 60s).
+
+---
+
+### `useTemporalSchedule(callback, instant, options?)`
+
+Schedules `callback` once at `instant`. Runs immediately when already past unless `runIfPast: false`.
+
+```tsx
+useTemporalSchedule(() => alert('Done!'), Temporal.Now.instant().add({ minutes: 5 }));
+```
+
+---
+
+### `useTemporalCompare(a, b)`
+
+Memoized `Temporal.Instant.compare` or `PlainDate.compare`.
+
+### `useTemporalWithin(value, start, end)`
+
+Inclusive range check (matching `Instant` or `PlainDate` operands).
+
+### `useTemporalAdd(value, duration)`
+
+Memoized `.add(duration)` for `Instant` or `PlainDate`.
+
+---
+
+## Type exports
+
+| Export | Description |
+| --- | --- |
+| `TemporalInstant` | `Temporal.Instant` |
+| `TemporalPlainDate` | `Temporal.PlainDate` |
+| `TemporalPlainTime` | `Temporal.PlainTime` |
+| `TemporalPlainDateTime` | `Temporal.PlainDateTime` |
+| `TemporalZonedDateTime` | `Temporal.ZonedDateTime` |
+| `TemporalDuration` | `Temporal.Duration` |
+| `TemporalDurationLike` | `Temporal.DurationLike` |
+| `TemporalNamespace` | `typeof Temporal` |
+| `UseTemporalNowOptions` | Options for `useTemporalNow` |
+| `UseTemporalClockOptions` | Options for `useTemporalClock` / `useTemporalZonedNow` |
+
+See [TypeScript](./typescript.md) for usage examples.

package/docs/getting-started.md

@@ -0,0 +1,111 @@
+# Getting started
+
+This guide walks you through installing **react-temporal** and using it in a React app.
+
+## Prerequisites
+
+- Node.js **26** or later (for local development of this repo)
+- React **17**, **18**, or **19**
+- A bundler that supports ES modules (Vite, Next.js, Webpack 5, etc.)
+
+## 1. Install the package
+
+```bash
+npm install @charlite/react-temporal
+```
+
+## 2. Add a polyfill (if needed)
+
+Skip this step if you only target browsers with native Temporal (Chrome 144+, Firefox 139+, Edge 144+) **and** run Node.js 26+ on the server without needing a fallback.
+
+For **Safari**, **Node.js < 26**, or mixed environments:
+
+```bash
+# Recommended — smaller bundle (~20 KB gzip)
+npm install temporal-polyfill
+
+# Or the official reference implementation
+npm install @js-temporal/polyfill
+```
+
+Add the polyfill once at your app entry point:
+
+```ts
+// main.tsx or _app.tsx
+import 'temporal-polyfill/global';
+```
+
+See the [Polyfill guide](./polyfill.md) for details.
+
+## 3. Use a hook
+
+```tsx
+import { useTemporalNow } from '@charlite/react-temporal';
+
+export function Clock() {
+  const now = useTemporalNow();
+  return <time dateTime={now.toString()}>{now.toLocaleString()}</time>;
+}
+```
+
+## 4. Import Temporal types
+
+You do not need a separate polyfill import for types or values — the package re-exports `Temporal`:
+
+```tsx
+import { Temporal, useTemporalMonth } from '@charlite/react-temporal';
+
+export function JulyCalendar() {
+  const dates = useTemporalMonth(Temporal.PlainDate.from('2026-07-01'));
+
+  return (
+    <ul>
+      {dates.map((date) => (
+        <li key={date.toString()}>{date.day}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## Common patterns
+
+### Live clock with time zone
+
+```tsx
+import { useTemporalZonedNow } from '@charlite/react-temporal';
+
+export function LocalClock({ timeZone }: { timeZone: string }) {
+  const now = useTemporalZonedNow(timeZone, { intervalMs: 1000 });
+  return <span>{now.toLocaleString()}</span>;
+}
+```
+
+### Countdown timer
+
+```tsx
+import { useTemporalCountdown, Temporal } from '@charlite/react-temporal';
+
+export function Countdown({ iso }: { iso: string }) {
+  const target = Temporal.Instant.from(iso);
+  const seconds = useTemporalCountdown(target);
+  return <span>{seconds}s remaining</span>;
+}
+```
+
+### Relative time label
+
+```tsx
+import { useTemporalRelative, Temporal } from '@charlite/react-temporal';
+
+export function RelativeLabel({ instant }: { instant: Temporal.Instant }) {
+  const label = useTemporalRelative(Temporal.Now.instant(), instant, 'en');
+  return <span>{label}</span>;
+}
+```
+
+## Next steps
+
+- [API reference](./api-reference.md) — full hook documentation
+- [TypeScript](./typescript.md) — type exports and annotations
+- [Examples](../examples/README.md) — one example per hook

package/docs/installation.md

@@ -0,0 +1,87 @@
+# Installation
+
+## npm
+
+```bash
+npm install @charlite/react-temporal
+```
+
+## yarn
+
+```bash
+yarn add @charlite/react-temporal
+```
+
+## pnpm
+
+```bash
+pnpm add @charlite/react-temporal
+```
+
+## Peer dependencies
+
+`@charlite/react-temporal` expects React to already be installed in your project:
+
+| Package | Supported versions |
+| --- | --- |
+| `react` | `^17.0.0 \|\| ^18.0.0 \|\| ^19.0.0` |
+| `react-dom` | `^17.0.0 \|\| ^18.0.0 \|\| ^19.0.0` |
+
+If npm warns about missing peers, install React explicitly:
+
+```bash
+npm install react react-dom
+```
+
+## Optional polyfill dependencies
+
+For environments without native Temporal, install **one** of:
+
+| Package | Size (gzip) | Notes |
+| --- | --- | --- |
+| [`temporal-polyfill`](https://www.npmjs.com/package/temporal-polyfill) | ~20 KB | Recommended; installed automatically with `@charlite/react-temporal` |
+| [`@js-temporal/polyfill`](https://www.npmjs.com/package/@js-temporal/polyfill) | ~44 KB | Official reference implementation (install manually if needed) |
+
+```bash
+npm install temporal-polyfill
+# or
+npm install @js-temporal/polyfill
+```
+
+## Node.js version
+
+Development and CI for this package require **Node.js 26+**. Your end-user app can run on older Node versions if you install a Temporal polyfill when native Temporal is missing.
+
+## Package exports
+
+The package ships ESM and CommonJS builds:
+
+```json
+{
+  "import": "./dist/index.esm.js",
+  "require": "./dist/index.cjs",
+  "types": "./dist/index.d.ts"
+}
+```
+
+Tree-shaking is supported (`"sideEffects": false`).
+
+## Bundler notes
+
+### Vite / CRA / Webpack
+
+No special configuration required. Install a polyfill for SSR or test environments running in Node.js without native Temporal.
+
+### Next.js
+
+Add the polyfill import in `instrumentation.ts` or your root layout for server components that use Temporal hooks on the server:
+
+```ts
+import 'temporal-polyfill/global';
+```
+
+Client components can use hooks normally.
+
+### Vitest
+
+Ensure the test environment loads a polyfill before tests run (see root `vitest.setup.ts` in this repository).

package/docs/migration.md

@@ -0,0 +1,143 @@
+# Migration guide
+
+## Upgrading to 1.1.0 from 1.0.0
+
+### Polyfill default
+
+The built-in fallback is now **`temporal-polyfill`** instead of `@js-temporal/polyfill`. No app changes are required unless you relied on `@js-temporal/polyfill` being installed automatically — add it explicitly if you still need it for code outside `@charlite/react-temporal`.
+
+### New hooks (optional)
+
+See [API reference](./api-reference.md) for `useTemporalFrom`, `useTemporalElapsed`, `useTemporalStopwatch`, `useTemporalLocalDate`, and related utilities.
+
+### Schedule behavior
+
+`useTemporalSchedule` now invokes the callback immediately when the target instant is in the past (use `{ runIfPast: false }` to restore the old no-op behavior).
+
+---
+
+## Upgrading to 1.0.0 from 0.0.3
+
+Version **1.0.0** aligns the repo with the 2026 Temporal ecosystem and modern tooling. Library APIs are unchanged; development and CI requirements changed.
+
+### Node.js
+
+**Before:** Node.js 22+
+
+**After:** Node.js **26+** (native Temporal in supported releases)
+
+```bash
+nvm install 26
+nvm use 26
+```
+
+Update GitHub Actions / CI images to Node 26. End-user apps on older Node versions can still use **@charlite/react-temporal** with a Temporal polyfill.
+
+### Testing (contributors)
+
+**Before:** Jest + `jest.config.json`
+
+**After:** Vitest + `vitest.config.ts`
+
+```bash
+npm test          # vitest run
+npm run test:watch
+npm run test:coverage
+```
+
+Timer mocks use `vi` instead of `jest`:
+
+```diff
+- jest.useFakeTimers();
++ vi.useFakeTimers();
+```
+
+### Linting (contributors)
+
+**Before:** `.eslintrc.json`
+
+**After:** `eslint.config.js` (ESLint 10 flat config)
+
+### Agent / knowledge layout
+
+New OKF v0.2 bundle at [`knowledge/`](../knowledge/index.md) and [`AGENTS.md`](../AGENTS.md). No runtime impact on published npm code.
+
+---
+
+## Upgrading to 0.0.3 from 0.0.1 / 0.0.2
+
+Version **0.0.3** modernizes the library for 2026 Temporal adoption. Most changes are additive; a few APIs changed behavior.
+
+### Install / dependency changes
+
+**Before (0.0.2):**
+
+```bash
+npm install @charlite/react-temporal
+# react and react-dom were bundled as direct dependencies
+# polyfill was bundled inside the package
+```
+
+**After (0.0.3):**
+
+```bash
+npm install @charlite/react-temporal
+npm install temporal-polyfill   # recommended for SSR / Safari / Node
+```
+
+Ensure `react` and `react-dom` are in your app's `package.json` (peer dependencies).
+
+### Import changes
+
+You can now import `Temporal` from the package instead of `@js-temporal/polyfill`:
+
+```diff
+- import { useTemporalMonth } from '@charlite/react-temporal';
+- import { Temporal } from '@js-temporal/polyfill';
++ import { useTemporalMonth, Temporal } from '@charlite/react-temporal';
+```
+
+### `useTemporalFormat`
+
+Signature changed to match `toLocaleString`:
+
+```diff
+- useTemporalFormat(date, { dateStyle: 'full' })
++ useTemporalFormat(date, undefined, { dateStyle: 'full' })
++ useTemporalFormat(date, 'en-US', { dateStyle: 'full' })
+```
+
+### `useTemporalRelative`
+
+Output format changed from manual strings (`"10 seconds ago"`) to `Intl.RelativeTimeFormat` (`"in 10 seconds"`). Pass a locale as the third argument:
+
+```diff
+- useTemporalRelative(from, to)
++ useTemporalRelative(from, to, 'en')
+```
+
+### `useTemporalDuration` / `useTemporalDiff`
+
+These now use `until()` internally. Access total units with `.total()`:
+
+```diff
+- diff.hours
++ diff.total('hours')
+```
+
+### New hooks (optional adoption)
+
+- `useTemporalClock({ intervalMs })` — configurable live clock
+- `useTemporalZonedNow(timeZone, { intervalMs })` — zoned live clock
+- `useTemporalNow({ intervalMs, timeZone })` — extended options
+
+### No action needed
+
+These hooks work the same way, with improved internals:
+
+- `useTemporalParse`
+- `useTemporalRange`
+- `useTemporalWeek` / `useTemporalMonth` / `useTemporalYear`
+- `useTemporalCalendar` / `useTemporalTimeZone`
+- `useTemporalInterval`
+- `useTemporalSchedule`