@charlite/react-temporal 0.0.0-stage → 1.1.1

package/docs/polyfill.md

@@ -0,0 +1,89 @@
+# Polyfill guide
+
+**react-temporal** uses native `Temporal` when available and falls back to a polyfill automatically.
+
+## How runtime resolution works
+
+```ts
+import { getTemporal, Temporal } from '@charlite/react-temporal';
+
+// getTemporal() checks globalThis.Temporal first, then falls back to temporal-polyfill
+const T = getTemporal();
+```
+
+Resolution order:
+
+1. **`globalThis.Temporal`** — used when the host provides native Temporal
+2. **`temporal-polyfill`** — loaded when native Temporal is unavailable (optional dependency)
+
+You rarely need to call `getTemporal()` directly; hooks use it internally.
+
+## Browser support (2026)
+
+| Browser | Native Temporal | Action |
+| --- | --- | --- |
+| Chrome 144+ | Yes | No polyfill needed |
+| Firefox 139+ | Yes | No polyfill needed |
+| Edge 144+ | Yes | No polyfill needed |
+| Safari | Partial / preview | Use a polyfill |
+| Older browsers | No | Use a polyfill |
+
+## Node.js
+
+**Node.js 26+** ships Temporal by default in current releases. Older Node versions and some test environments (for example jsdom) still need a polyfill for SSR and unit tests:
+
+```bash
+npm install temporal-polyfill
+```
+
+```ts
+import 'temporal-polyfill/global';
+```
+
+## Choosing a polyfill
+
+### temporal-polyfill (recommended)
+
+- Smaller bundle (~20 KB gzip)
+- Maintained by the FullCalendar team
+- Near-perfect TC39 spec compliance
+
+```ts
+import 'temporal-polyfill/global';
+```
+
+### @js-temporal/polyfill
+
+- Official reference implementation from Temporal proposal champions
+- Larger (~44 KB gzip)
+- Installed automatically as an optional dependency of `@charlite/react-temporal`
+
+No global import is required — the package loads it when native Temporal is missing.
+
+## SSR checklist
+
+1. Install `temporal-polyfill` or ensure `@js-temporal/polyfill` is available
+2. Import the polyfill at the server entry point **before** any hook runs
+3. Verify your SSR bundle does not tree-shake away the polyfill import
+
+## Testing
+
+In **Vitest** with `jsdom`, native Temporal is typically unavailable. This library imports `temporal-polyfill` inside `src/temporal.ts`, so tests do not need to assign `globalThis.Temporal` unless your app code reads the global directly.
+
+## FAQ
+
+**Do I need to import Temporal separately?**
+
+No. Import `Temporal` from `@charlite/react-temporal`:
+
+```ts
+import { Temporal } from '@charlite/react-temporal';
+```
+
+**Can I use only native Temporal and skip the polyfill?**
+
+Yes, if you only support browsers with native Temporal and run Node.js 26+ on the server. Remove optional polyfill dependencies and ensure your build does not resolve `@js-temporal/polyfill`.
+
+**Does the polyfill get bundled into my app?**
+
+No. The polyfill is an external dependency — your bundler includes it only if you import it (or if the fallback path resolves at runtime in Node).

package/docs/typescript.md

@@ -0,0 +1,86 @@
+# TypeScript
+
+**react-temporal** is written in TypeScript and ships `.d.ts` declarations with the package.
+
+## Importing types
+
+```ts
+import type {
+  TemporalInstant,
+  TemporalPlainDate,
+  TemporalPlainDateTime,
+  TemporalZonedDateTime,
+  TemporalDuration,
+  TemporalDurationLike,
+  UseTemporalNowOptions,
+  UseTemporalClockOptions,
+  TemporalNamespace,
+} from '@charlite/react-temporal';
+```
+
+## Importing values and types together
+
+```ts
+import { Temporal, useTemporalNow } from '@charlite/react-temporal';
+import type { TemporalInstant } from '@charlite/react-temporal';
+
+function logInstant(instant: TemporalInstant) {
+  console.log(instant.toString());
+}
+```
+
+## Hook return types
+
+| Hook | Return type |
+| --- | --- |
+| `useTemporalNow()` | `TemporalInstant` |
+| `useTemporalNow({ timeZone })` | `TemporalZonedDateTime` |
+| `useTemporalClock()` | `TemporalInstant` |
+| `useTemporalZonedNow(tz)` | `TemporalZonedDateTime` |
+| `useTemporalDuration(a, b)` | `TemporalDuration` |
+| `useTemporalDiff(a, b)` | `TemporalDuration` |
+| `useTemporalParse(iso)` | `TemporalInstant` |
+| `useTemporalCountdown(target)` | `number` |
+| `useTemporalRelative(...)` | `string` |
+| `useTemporalFormat(obj, ...)` | `string` |
+| `useTemporalCalendar(id)` | `string` |
+| `useTemporalTimeZone(id)` | `string` |
+| `useTemporalRange(start, end)` | `TemporalPlainDate[]` |
+| `useTemporalWeek(date)` | `TemporalPlainDate[]` |
+| `useTemporalMonth(date)` | `TemporalPlainDate[]` |
+| `useTemporalYear(date)` | `TemporalPlainDate[]` |
+
+## Typing component props
+
+```tsx
+import type { TemporalInstant, TemporalPlainDate } from '@charlite/react-temporal';
+
+interface EventCardProps {
+  startsAt: TemporalInstant;
+  date: TemporalPlainDate;
+}
+
+export function EventCard({ startsAt, date }: EventCardProps) {
+  // ...
+}
+```
+
+## `TemporalNamespace`
+
+Use this when you need the type of the full `Temporal` namespace:
+
+```ts
+import type { TemporalNamespace } from '@charlite/react-temporal';
+
+function useTemporalSafe(): TemporalNamespace {
+  return getTemporal();
+}
+```
+
+## Strict mode
+
+The package is built with `strict: true`. All hooks use explicit parameter and return types.
+
+## Source of Temporal types
+
+Runtime types are sourced from `temporal-polyfill`, which tracks the TC39 Temporal specification. Native `Temporal` in modern browsers is structurally compatible at runtime.

package/package.json

@@ -1,6 +1,119 @@
 {
   "name": "@charlite/react-temporal",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.1",
+  "description": "React hooks for date and time using the JavaScript Temporal API — native in modern browsers and Node.js 26+, polyfill-ready elsewhere.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.cjs",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "rollup -c",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint \"src/**/*.{ts,tsx}\"",
+    "lint:fix": "eslint \"src/**/*.{ts,tsx}\" --fix",
+    "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx,json,md}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx,js,jsx,json,md}\"",
+    "typecheck": "tsc --noEmit",
+    "dev": "pwsh -ExecutionPolicy Bypass -File scripts/dev.ps1",
+    "dev:test": "pwsh -ExecutionPolicy Bypass -File scripts/dev.ps1 -Task test",
+    "dev:build": "pwsh -ExecutionPolicy Bypass -File scripts/dev.ps1 -Task build",
+    "dev:lint": "pwsh -ExecutionPolicy Bypass -File scripts/dev.ps1 -Task lint",
+    "dev:typecheck": "pwsh -ExecutionPolicy Bypass -File scripts/dev.ps1 -Task typecheck",
+    "prepublishOnly": "npm run build && npm run test && npm run lint && npm run typecheck",
+    "setup": "node scripts/setup.js",
+    "setup:ps": "pwsh -ExecutionPolicy Bypass -File scripts/setup.ps1",
+    "release": "node scripts/release.js patch",
+    "release:minor": "node scripts/release.js minor",
+    "release:major": "node scripts/release.js major",
+    "release:ps": "pwsh -ExecutionPolicy Bypass -File scripts/release.ps1",
+    "release:ps:minor": "pwsh -ExecutionPolicy Bypass -File scripts/release.ps1 -VersionType minor",
+    "release:ps:major": "pwsh -ExecutionPolicy Bypass -File scripts/release.ps1 -VersionType major"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/charlite/react-temporal.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/charlite/react-temporal#readme",
+  "bugs": {
+    "url": "https://github.com/charlite/react-temporal/issues"
+  },
+  "keywords": [
+    "react",
+    "react-hooks",
+    "temporal",
+    "temporal-api",
+    "date",
+    "time",
+    "calendar",
+    "timezone",
+    "hooks",
+    "datetime",
+    "javascript",
+    "intl",
+    "polyfill",
+    "okf"
+  ],
+  "author": {
+    "name": "charlite",
+    "email": "38315638+charlite@users.noreply.github.com",
+    "url": "https://github.com/charlite"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=26.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitest/coverage-v8": "^5.0.3",
+    "eslint": "^10.12.0",
+    "jsdom": "^27.0.0",
+    "prettier": "^3.6.2",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "rollup": "^4.52.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.3",
+    "temporal-polyfill": "^1.0.5",
+    "typescript-eslint": "^8.46.0",
+    "vitest": "^5.0.3"
+  },
+  "peerDependencies": {
+    "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
+    "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@js-temporal/polyfill": {
+      "optional": true
+    },
+    "temporal-polyfill": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "temporal-polyfill": "^1.0.5"
+  }
+}