V0

.ai/AGENTS.md

@@ -0,0 +1,64 @@
+# AI Agent Instructions
+
+## Project Context
+
+TanStack Time is a headless time/calendar utility library for TS/JS, React, Solid, Vue, Svelte, Angular. Uses Temporal API polyfill. Monorepo under pnpm + nx.
+
+## Core Constraints
+
+- All public API methods return Date or string. Never Temporal objects.
+- Input dates: RFC 3339 string, epoch numeric, or Date object.
+- Formatting via Intl.DateTimeFormat parts, not string tokens.
+- Timezone and calendar are always tracked. Defaults from Intl.DateTimeFormat.
+- Date objects are mutable. Never mutate inputs.
+
+## Package Hierarchy
+
+- `@tanstack/time` — core logic (calendar, date ops, formatting)
+- `@tanstack/react-time` — React hooks (useCalendar), re-exports from core
+- `@tanstack/time-devtools` — devtools UI, depends on core
+- `@tanstack/solid-time` — Solid adapter (mirrors react-time)
+- `@tanstack/solid-time-devtools` — Solid devtools
+
+## File Organization
+
+- `packages/time/src/date/` — date manipulation (add, subtract, startOf, endOf, format, parse, etc.)
+- `packages/time/src/calendar/` — calendar engine (CalendarCore, DateCore, event rendering, recurrence, resizing)
+- `packages/time/src/client/` — client-side utilities
+- `packages/time/src/formatter/` — Intl.DateTimeFormat wrappers
+- `packages/time/src/utils/` — shared helpers
+
+## Testing
+
+- Vitest for unit tests. `*.test.ts` co-located with source.
+- React tests use `@testing-library/react`.
+- No comment policy: zero comments in source. Prefer naming, types, structure.
+
+## Build
+
+- `tsdown` for bundling. Outputs ESM + CJS.
+- `nx` for task orchestration.
+- `pnpm` for package management.
+
+## Key Files
+
+- `packages/time/src/calendar/calendar.ts` — CalendarCore class
+- `packages/time/src/calendar/date-core.ts` — DateCore abstract class
+- `packages/time/src/date/index.ts` — date utility exports
+- `packages/time/src/index.ts` — top-level exports
+- `Methodology.md` — API design philosophy
+- `TODO.md` — roadmap
+
+## Navigation
+
+- Read `.ai/graph.json` before exploring. It contains the full package map, file lists, exports, dependencies, and test locations.
+- Use the `edges` array to trace internal dependencies and identify affected packages before modifying core logic.
+- If `graph.json` is stale or missing, run `pnpm run graphify` to regenerate it.
+
+## Agent Rules
+
+- Do not add comments to source code.
+- Follow existing code style. Use explicit types.
+- When changing core, check react-time and devtools for breakage.
+- Run `pnpm test:lib` and `pnpm test:types` before declaring done.
+- All new date logic must handle timezone and calendar correctly.

.ai/README.md

@@ -0,0 +1,20 @@
+# AI Infrastructure
+
+Generated and maintained for AI agents working on TanStack Time.
+
+## Graphify
+
+`pnpm run graphify` generates `.ai/graph.json` — a machine-readable graph of the monorepo (packages, exports, dependencies, files, tests).
+
+## Spec Kit
+
+`.ai/spec-kit/` contains domain-specific specifications:
+
+- `architecture.md` — monorepo structure, package relationships, build system
+- `testing.md` — test framework, commands, coverage expectations
+- `api-design.md` — input/output contracts, method signatures, design philosophy
+- `calendar-domain.md` — Temporal API, event model, recurrence, availability, views
+
+## Agent Context
+
+`.ai/AGENTS.md` — top-level instructions for AI agents. Read this first.

.ai/spec-kit/api-design.md

@@ -0,0 +1,53 @@
+# API Design Spec
+
+## Design Philosophy
+
+TanStack Time is designed after TanStack Query and TanStack Table: headless, framework-agnostic core with thin framework adapters. See `Methodology.md` for detailed rationale.
+
+## Input Contracts
+
+- Dates accepted as RFC 3339 string, epoch milliseconds (number), or Date object.
+- Timezone and calendar are explicit parameters. If omitted, defaults from `Intl.DateTimeFormat`.
+- Never mutate input Date objects. Always clone or create new Temporal instances.
+
+## Output Contracts
+
+- Public methods return either Date objects or strings.
+- Never return Temporal objects directly to consumers.
+- Methods return `{ value, options }` tuple where `options` carries timezone/calendar used.
+- Formatting methods return string parts via Intl.DateTimeFormat.
+
+## Method Signature Pattern
+
+```ts
+function operationName({
+  date,
+  unit,
+  returnFormat,
+  options,
+}: {
+  date: Date | string | number
+  unit: DateUnit
+  returnFormat?: 'standard' | 'long' | 'epoch' | 'Date' | 'ZonedDateTime'
+  options?: { timeZone?: string; calendar?: string }
+}): { value: ReturnType; options: { timeZone: string; calendar: string } }
+```
+
+## Chaining vs Standalone
+
+- Prefer standalone functions over fluent/chaining APIs.
+- Chaining creates object overhead and hinders treeshaking.
+- Each function is idempotent and composable.
+
+## TypeScript Requirements
+
+- All public APIs must be fully typed.
+- Generic parameters for calendar resources and events.
+- No `any` in public surface.
+
+## Framework Adapter Pattern
+
+- Core is pure TS/JS. No framework dependencies.
+- React adapter: `useCalendar` hook that creates `CalendarCore` instance and exposes reactive selectors.
+- Solid adapter: equivalent `useCalendar` using Solid's reactive primitives.
+- Devtools are separate packages that inject into core store.

.ai/spec-kit/architecture.md

@@ -0,0 +1,62 @@
+# Architecture Spec
+
+## Monorepo Layout
+
+```
+packages/
+  time/              — core package
+    src/date/        — date manipulation primitives
+    src/calendar/    — calendar engine
+    src/client/      — client utilities
+    src/formatter/   — Intl.DateTimeFormat wrappers
+    src/utils/       — shared helpers
+    src/index.ts     — public API surface
+  react-time/        — React adapter
+    src/useCalendar/ — useCalendar hook
+    src/index.ts     — re-exports core + React-specific
+  time-devtools/     — devtools UI
+    src/components/  — UI components (Solid-based via goober)
+    src/store/       — devtools state
+    src/core.tsx     — devtools core
+  solid-time/        — Solid adapter (mirrors react-time)
+  solid-time-devtools/ — Solid devtools
+```
+
+## Dependency Graph
+
+- `react-time` → `time`
+- `time-devtools` → `time`
+- `solid-time` → `time`
+- `solid-time-devtools` → `time`
+
+## Build System
+
+- `tsdown` bundles each package. Produces `dist/index.js` (ESM) and `dist/index.cjs` (CJS).
+- `nx` caches builds and runs tests selectively.
+- Root scripts run via `nx run-many` or `nx affected`.
+
+## Public API Surface
+
+Core exports from `@tanstack/time`:
+
+- Date primitives: `add`, `subtract`, `startOf`, `endOf`, `format`, `parse`, `equals`, `isBefore`, `isAfter`, `isBetween`, `range`, `since`, `until`
+- Calendar: `CalendarCore`, `DateCore`, event helpers, recurrence logic
+- Types: `CalendarEvent`, `CalendarResource`, `ResizeState`, etc.
+
+React exports from `@tanstack/react-time`:
+
+- `useCalendar` hook
+- `ResizeState`, `ResizeOptions`, `UseCalendarOptions`
+- Re-exports of core event utilities and types
+
+## State Management
+
+- Core uses `@tanstack/store` for reactive state.
+- React adapter uses `@tanstack/react-store`.
+- CalendarCore maintains event collections, selected dates, current view.
+
+## Key Abstractions
+
+- `DateCore` — abstract base for date operations and navigation
+- `CalendarCore<TResource, TEvent>` — concrete calendar with events, resources, availability
+- `useCalendar` — React hook that instantiates CalendarCore and provides reactive selectors

.ai/spec-kit/calendar-domain.md

@@ -0,0 +1,51 @@
+# Calendar Domain Spec
+
+## Temporal API
+
+- Until native browser support, use `@js-temporal/polyfill`.
+- Internal computations use `Temporal.ZonedDateTime` and `Temporal.PlainDate`.
+- Public API never exposes Temporal objects.
+
+## Timezone and Calendar
+
+- A date/time instance is not a static point; it is relative to timezone and calendar.
+- Always track timezone and calendar alongside the instant value.
+- RFC 3339 extended format may include timezone and calendar: `2024-03-05T12:34:56.789Z[America/New_York][u-ca=gregory]`.
+
+## Event Model
+
+- `CalendarEvent` has: id, start, end, title, allDay flag, recurrence rule, resources, dependencies, metadata.
+- `CalendarResource` has: id, title, availability windows, unavailability rules.
+- Events can span multiple days. Split multi-day events into per-day segments for rendering.
+- All-day events have no time component. Rendered at top of day view.
+
+## Recurrence
+
+- Supported: daily, weekly, monthly, yearly.
+- Recurrence exceptions: EXDATE (skip occurrences), modified single occurrences.
+- End conditions: UNTIL date, COUNT number.
+- Expand recurring events into individual occurrences before rendering.
+
+## Resizing and Dragging
+
+- `ResizeController` handles pointer events for event resizing.
+- `calculateSegmentResizePreview` computes preview state during resize.
+- `calculateGhostPreviewStyle` computes CSS for drag ghost.
+- `calculateTimelineResizePreview` computes timeline-specific resize preview.
+- `getResizeProps` returns styling props for resize handles.
+
+## Availability
+
+- Resources define availability windows (start/end times per day).
+- Unavailability rules define blocked ranges.
+- `validateEventDependencies` checks if placing an event satisfies dependency constraints.
+- `getUnavailableRanges` returns blocked ranges for a date.
+
+## Views
+
+- CalendarCore supports: day, week, month, year, agenda, timeline.
+- `groupDaysBy` groups days by unit (week, month) for grid layouts.
+- `goToSpecificPeriod` navigates to a specific date with view context.
+- `getEventsByDate` retrieves all events for a date (including multi-day segments).
+- `getAllDayEventsByDate` retrieves all-day events for a date.
+- `getTimeSlots` generates time slots for day/week views.

.ai/spec-kit/testing.md

@@ -0,0 +1,36 @@
+# Testing Spec
+
+## Test Framework
+
+- Vitest for all unit and integration tests.
+- Co-located tests: `*.test.ts` in same directory as source.
+- React tests use `@testing-library/react` + `@testing-library/jest-dom` matchers.
+- Faker via `@faker-js/faker` for test data generation.
+
+## Test Commands
+
+- `pnpm test:lib` — run Vitest tests
+- `pnpm test:lib:dev` — watch mode
+- `pnpm test:types` — TypeScript type checking via `tsc --noEmit`
+- `pnpm test:lint` — linting
+- `pnpm test:ci` — full CI suite (oxlint, sherif, knip, docs, lib, types, build)
+
+## Coverage Expectations
+
+- Date primitives: edge cases around leap years, timezone transitions, calendar variants
+- Calendar engine: event overlap, multi-day splitting, recurrence, resize, availability
+- React hooks: render cycles, state updates, unmount cleanup
+
+## Test Patterns
+
+- Use explicit timezones in calendar tests. Avoid relying on local system time.
+- Create helper functions for common calendar setup to reduce boilerplate.
+- Mock Temporal API polyfill behavior when testing edge cases.
+- For resize/drag tests, simulate pointer events and verify state transitions.
+
+## CI Requirements
+
+- `pnpm test:pr` must pass before merge.
+- `pnpm test:sherif` ensures dependency consistency across packages.
+- `pnpm test:knip` detects unused exports and dependencies.
+- `pnpm test:docs` verifies all markdown links are valid.

.changeset/config.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
+  "changelog": ["@changesets/changelog-github", { "repo": "TanStack/time", "disableThanks": true }],
+  "commit": false,
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "fixed": [],
+  "linked": [],
+  "ignore": [],
+  "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
+    "onlyUpdatePeerDependentsWhenOutOfRange": true
+  }
+}

.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: tannerlinsley