Date Primitives surface completion

[bart-krakowski]

Parent

#25

What to build

Complete the Date Primitives surface to cover the full date-fns / d3-time utility vocabulary. All functions are pure, stateless, tree-shakeable, and timezone/calendar-correct via Temporal internally. Public return types follow ADR-0002: instant-bearing results return a native `Date`; civil values return `YYYY-MM-DD` ISO strings. No Temporal objects in any public signature.

Functions already implemented: `add`, `subtract`, `startOf`, `endOf`, `round`, `format`, `parse`, `equals`, `isBefore`, `isAfter`, `isBetween`, `isSameOrBefore`, `isSameOrAfter`, `intersects`, `since`, `until`, `range`, `isLeapYear`, `isWeekend`, `isValidDate`.

Functions to add (from `UTILITY_RESEARCH.md`):

• `ceil(date, unit)` — round up to nearest unit
• `clamp(date, range)` — constrain date within a range
• `set(date, fields)` — set specific date components
• `count(start, end, unit)` — count discrete intervals
• `min(dates[])` / `max(dates[])` — earliest/latest in array
• `isPast(date)` / `isFuture(date)` — relative to now
• `fromUnixTime(timestamp)` / `getUnixTime(date)` — Unix timestamp conversion
• `getDayOfYear(date)` / `getWeek(date)` — numeric getters

Acceptance criteria

• All listed functions are exported from `@tanstack/time`
• Each function accepts `DateInput` (string | number | Date) and `DateOptions` (`{ timeZone?, calendar? }`)
• Each function returns a native `Date` for instant results or a `YYYY-MM-DD` string for civil results
• No `Temporal` objects appear in any public signature
• Each function has unit tests covering timezone-correct behaviour, DST transitions, and edge cases (leap year, month-end arithmetic)
• Tree-shaking verified: importing a single function does not pull in unrelated functions

Blocked by

None — can start immediately.