0
Fork 0
mirror of https://github.com/TanStack/time.git synced 2026-11-16 19:09:47 +00:00
time/CONTEXT.md
2026-06-21 09:46:03 +00:00

7.5 KiB

TanStack Time

A comprehensive, Temporal-native library for date/time problems. Two layers: a set of pure date/time functions, and a stateful core extended by feature modules (calendar, scheduling, undo/redo, …) in the style of TanStack Table v9 / AG Grid modules.

Language

Date Primitive: A pure, stateless date/time function (e.g. add, startOf, format). Operates on a single value, holds no state, belongs to no module. The "alternative to date-fns" layer. Returns a native Date for instant-bearing results. Avoid: helper, util (too vague)

Instant: An exact moment in time (UTC milliseconds). The public boundary represents instants as native Date objects. A Date carries no timezone or calendar. Avoid: timestamp, moment (Moment.js baggage)

Civil Date: A calendar-civil value with no instant — a day, month, or all-day boundary (e.g. Day.date, currentPeriod). Represented at the public boundary as an ISO string (YYYY-MM-DD), never as a Date, to avoid the all-day off-by-one. Temporal PlainDate is the internal-only counterpart. Avoid: plain date (Temporal-internal term), date-only

Data Strategy: The pluggable choice (client | server) of where the projection/validation pipeline executes, analogous to AG Grid's row model. In client mode every stage runs in-process over a supplied event set; in server mode the delegatable stages (sourcing, recurrence-expand, conflict, slot-generation) run on the server via the shared Validation Core, returning materialized results. Clip-to-viewport and layout always run client-side. The consumer's calendar API is the same in both. Avoid: mode (informal), row model (AG Grid's term)

Kernel: The single stateful core every product shares. It owns the event collection, the viewport (current period + view mode) with its navigation, the date-range projection (events mapped to the visible range), and plain create/edit/remove. Nothing domain-specific (no availability, recurrence, dependencies, drag, or undo) lives here. Analogous to the one TanStack Table core (table instance + row model). Avoid: core, engine (informal synonyms; "kernel" is canonical)

Module: A unit of opt-in feature behavior that extends the kernel (recurrence, availability, dependencies, drag-resize, undo/redo, scheduling). Modeled on TanStack Table v9 / AG Grid modules so unused features tree-shake away. A module adds capability and state. Avoid: plugin, feature, extension (pick one canonical term — see open question)

Product: A user-facing bundle = the kernel + a preset of modules + a chosen view. Calendar, Scheduler (Calendly-style), and Timeline/Gantt are products, not separate kernels. A product is a convenience preset, not a new core. Avoid: app, preset (informal)

Master Event / Occurrence: A Master Event carries the recurrence rule; Occurrences are the individual instances expanded from it for the current viewport. Occurrences are ephemeral (derived in the projection), not stored. Avoid: parent/child, series/instance (mix freely — pick master/occurrence)

Override / Exception: An Override is a single Occurrence modified in place (moved, retitled), keyed by its original start (RECURRENCE-ID). An Exception is an Occurrence removed from the series (EXDATE). Both live on the Master Event's rule. Avoid: edit/delete-this-one (describe the data, not the gesture)

Recurrence Rule: The structured repeat definition on a Master Event, scoped to the UI-builder subset (frequency, interval, until/count, byWeekday with optional ordinal, byMonthDay). Full RFC 5545 RRULE is an optional interop adapter, not this model. Avoid: RRULE (that names the iCal string form, not our structured model)

Viewport: The kernel's window onto time: the current period plus the view mode that determines its span. Navigation moves the viewport; it does not change the event collection. Avoid: window, range (overloaded), current view

Projection: The derived, read-only result the kernel computes from the event collection for the current viewport (events mapped onto the visible range). Views and modules transform the projection; they never mutate the event collection through it. Avoid: render, output, derived state

Advisory Validation: Client-side conflict/availability checking run by the kernel over the events currently loaded. Instant UX feedback only — never authoritative, because the client may hold a partial dataset and cannot see other users' concurrent writes. Avoid: client validation (describe the role, not the location)

Authoritative Validation: The same validation logic run server-side against the full dataset, ideally inside the write transaction. The source of truth for whether a write is allowed. Avoid: server check, backend validation

Required Range: The date range the kernel declares it must have loaded to validate a proposed write (getRequiredRange). The orchestration layer ensures that range is loaded (via TanStack Query) before the sync validation runs. The kernel declares the need; it never fetches. Avoid: fetch range, query range

Validation Core: The pure, isomorphic rule logic (validate(write, events, config) → conflicts) shared by the client (advisory) and server (authoritative). No store, no viewport, no DOM, no DB. Avoid: validator, rules engine (informal)

loadEvents Adapter: A consumer-implemented function the server package calls to read events for a Required Range from the consumer's own database, inside the consumer's transaction. The only DB seam; the library never opens a connection. Avoid: data source, repository

Event Layout: The logical placement of an event in the projection, independent of pixels: time-axis position as fractions (startFraction/endFraction), overlap position as column / columnCount, and lane for timelines. The view's prop-getter turns this into a percentage-based style object. Avoid: position, geometry, coordinates (imply pixels)

Lane: A horizontal track in a timeline that separates events which would otherwise overlap in time. Distinct from an overlap column (the day/week side-by-side split). Avoid: row, track

Adapter: A thin framework binding that wires the headless core into a framework's reactivity (e.g. @tanstack/react-time's useCalendar). Holds no domain logic. Solid serves as the proof that the core is framework-agnostic. Avoid: integration, binding, wrapper

Resource: A bookable/assignable entity an event consumes (a room, a person, a piece of equipment), carrying availability windows, capacity, and buffers. The unit availability and capacity rules are checked against. Avoid: asset, entity, calendar (overloaded)

Availability: The windows during which a Resource can hold events (weekday + start/end time), plus capacity and buffer rules. Drives both advisory conflict checks and the Scheduler's free-slot projection. Avoid: schedule, hours, working hours

Calendar / Scheduler / Timeline: Products. Calendar = kernel + recurrence/drag-resize/undo over a day/week/month view. Scheduler = kernel + availability + scheduling (free-slot projection + book()) over a slot-picker view. Timeline/Gantt = kernel + dependencies (events that push each other) over a timeline view.

View (a.k.a. Renderer): A way of presenting a kernel's projection (day, week, month, agenda, timeline strip). A view reads the projection; it does not add capability. This is the line that separates a view from a module. Avoid: layout, display (too vague)