mirror of
https://github.com/TanStack/time.git
synced 2026-11-16 19:09:47 +00:00
9 KiB
9 KiB
TanStack Time — Roadmap
Goal: a comprehensive headless library for all calendar / scheduling / date-operations cases. Strategy: ship an alpha, then layer the rest across subsequent releases. North star for feature parity: Bryntum Scheduler Pro — headless (data only; consumers render geometry, editors, arrows, histograms).
The phase ordering is gated by two rules the team confirmed:
- Kernel first. No new features land on the
CalendarCoremonolith (3,872 lines when this was written, 2,755 once Phase 0 landed). The ADR 0001 decomposition happens before the alpha; alpha slips rather than shipping the god class (resolves the "alpha now vs freeze features" tension in favour of freeze). - Breaking changes are fine pre-1.0. Calendar-hierarchy (ADR 0008) and solver-driven event-model additions (ADR 0007) land as breaking changes before/at the alpha so consumers migrate once.
Phase 0 — Foundation refactor (gates the alpha)
Prerequisite for everything. Nothing user-facing.
- Decompose
CalendarCoreinto one feature-agnostic kernel + modules as pipeline stages (ADR 0001).Kernel+{recurrence, availability, dependency, resize, undo, layout}modules;CalendarCorewrites through the kernel and the kernel owns the events. What is left on the class is orchestration and read-side indexes, not rules — seedocs/plans/phase-0-decomposition.md. - Extract pure, isomorphic validation core — no store/viewport/DOM (ADR 0004). The rules
live in
validation/{availability,dependency},recurrence/, andprojection/, called with plain serializable args; the kernel's veto stage is thevalidate(write, events, config) → conflictsentry point (availabilityModule). A test walks those directories and fails if any of them imports the store, the event client, the kernel orCalendarCore, or touches the DOM. - Migrate boundary types:
currentPeriod/activeDateare ISOYYYY-MM-DDstrings andDay.dateis gone (Day.isoDatewas already the documented field), so no Temporal value crosses the calendar boundary (ADR 0002). The{ value, options, asZonedDateTime }shape the Date Primitives returned contradicted the same ADR; that was the Phase 1 audit below, and it has since landed. - Remove pixels from the core:
containerHeightdropped fromgetUnavailableRanges(nowstartFraction/endFraction+%); logical layout (startFraction,endFraction,column,columnCount) lives in thelayoutprojection stage withtoLayoutStylefor%output.getEventProps/getTimelineLayoutdelegate to the pure cores (layoutDaySegments,layoutTimelineRange) and expose raw fractions (ADR 0003). - Undo/redo → command diffs, not full-event snapshots (memory).
undoModulerecords one entry per committed kernel batch and replays it throughhistory/undo/history/redointents;CalendarCorejournals its own mutations into the same{reason, ops}batches and replays them withinvertWriteOps, so an entry costs the ops touched instead of a copy of every event.
Phase 1 — Alpha (Calendar product, React)
Ships once Phase 0 lands. Scope from ADR 0005 plus the pre-alpha breaking model changes.
- Feature composition as the public API (ADR 0009) —
featuresbecomes a required option built bycalendarFeatures({ ... }); modules contribute their own methods and the instance surface is what was composed. Lands first in this phase: the hierarchy and solver items below attach as features, so doing it after means writing them twice. Slice plan indocs/plans/phase-1-feature-composition.md; the kernel'sModule.apiseam landed. - Date Primitives (already present — audited for the ADR 0002 return-type contract). The
twelve instant-bearing primitives returned the
{ value, options, asZonedDateTime }tuple the ADR rejects; they now return a nativeDate, which also makes them compose asDateInput. Seedocs/plans/phase-1-date-primitives-audit.md.DateInputstill accepts Temporal values — an input-side question the audit deliberately left open. - Kernel: event collection + viewport + projection + plain CRUD +
getRequiredRange/ rollback. - Calendar product modules: recurrence (UI-builder subset), drag-resize, advisory availability.
- Working-time calendar hierarchy (ADR 0008) — replaces flat
Resource.availability. Breaking; lands here so alpha ships the target shape. Resources reference shared calendars by id, resolution is root-to-leaf painting with a global specificity sort, andworkingTimeFeatureexposes it — seedocs/plans/phase-1-working-time-hierarchy.md. - Event-model additions for the solver (ADR 0007): dependency lag/lead,
constraints,manuallyScheduled,effort/duration. Types only + honoured by validation; full solver is Phase 2. All four slices landed — seedocs/plans/phase-1-solver-event-model.md. The write pipeline now vetoes through four validate stages (availability, constraint, duration, dependency). - Dependencies FS/SS/FF/SF (present) become a proper module —
dependencyModule, landed in Phase 0. - Undo/redo (present) becomes a module —
undoModule, landed in Phase 0. - Timeline/Gantt view (present) — ships as a view, not a separate product.
- React adapter supported; Solid kept as framework-agnostic proof. Both are thin wrappers over composed construction (ADR 0009) — Solid is written against the split rather than porting the monolith.
- Update README/package messaging: five-framework claim is aspirational, not alpha.
Phase 2 — Scheduling engine
The Bryntum moat. Requires Phase 0 purity + Phase 1 calendar hierarchy.
- Solver (ADR 0007): fixpoint
schedulestage, ASAP/ALAP, client-authoritative. - Scheduling constraints (SNET / MSO / FNLT / …) honoured by the solver.
- Solver consumes effective working-time (ADR 0008) for date skew.
- Conflict data + candidate fixes (headless; consumer renders resolution).
- Server re-validation of the solved schedule via the shared pure core.
Phase 3 — Scale & server mode
- Data Strategy
client | server(ADR 0006): per-stage execution location. - Server package handlers per delegatable op:
expandRange,getConflicts,generateSlots,validateWrite, plussolvere-validation. - Write-sync protocol (bidirectional; optimistic + server reconcile) beyond read-only
fetchEvents. - Virtualization contract for large datasets (windowed projection; no px in core).
generateSlots— free/available-slot generation (booking / Calendly use case).
Phase 4 — Scheduler product & richer scheduling
- Scheduler product as a preset over the kernel/modules (ADR 0001/0005).
- Resource assignment as a first-class M:N entity (per-assignment units/effort).
- Resource histogram / utilization data (bins; consumer renders).
- Recurrence completeness: BYMONTHDAY / BYSETPOS / BYYEARDAY, "2nd Tuesday", multi-rule.
- Recurring time ranges (highlighted zones).
- Non-continuous time axis (skip nights/weekends) + zoom/time presets, derived from working-time intervals.
- Event layering modes (pack / stack / mixed) beyond overlap-coloring.
- Baselines, progress / percent-done, travel/setup time as first-class.
Phase 5 — Interop, more frameworks, polish
- RRULE / .ics import-export (RFC 5545).
- MS Project import.
- Export data contracts for PDF/PNG/Excel/print (headless; consumer renders/serializes).
- Vue / Svelte / Angular adapters.
- RTL, deeper localization.
- Non-Gregorian calendar QA (must keep working via Temporal throughout; supported here).
- Cross-scheduler drag / partners (data contracts).
Deferred / explicitly out (revisit per phase)
- Rendering: arrows, editors, dialogs, histogram bars — consumer's job (headless).
Example:
examples/react/timelinerenders dependency arrows with@xyflow. - Concrete HTTP transport / routes — consumer owns transport (ADR 0004/0006).
- Batteries-included backend (storage, DB adapters, transactions).
ADR index
| ADR | Decision |
|---|---|
| 0001 | One kernel; modules as pipeline stages |
| 0002 | Public return types: Date for instants, ISO strings for civil values |
| 0003 | Logical layout in core; % prop-getter for positioning |
| 0004 | Advisory client validation; authoritative server via shared pure core |
| 0005 | v1 scope: Calendar product, React-only, some deferred |
| 0006 | Client/server Data Strategy (computation push-down) |
| 0007 | Scheduling solver: fixpoint stage in write pipeline, client-authoritative |
| 0008 | Working-time calendars as id-referenced shared entities with resolution hierarchy |