@sixthshift/design-system 0.1.0

package/src/date-time/index.ts

@@ -0,0 +1,279 @@
+/**
+ * @sixthshift/design-system/date-time - Date/time utilities using Temporal API
+ *
+ * This package provides:
+ * - Re-export of Temporal from @js-temporal/polyfill
+ * - Parsing utilities (ISO string → Temporal)
+ * - Serialization utilities (Temporal → ISO strings for APIs/storage)
+ * - Formatting utilities (Temporal → human-readable strings for UI)
+ * - Common utility functions
+ *
+ * When native Temporal lands in browsers/Node, update the Temporal export
+ * in this file and all consuming packages get native support automatically.
+ *
+ * @example
+ * import { Temporal, parseDate, serialize, formatDateShort, isToday } from '@sixthshift/design-system/date-time';
+ *
+ * // Parse ISO string from API
+ * const dueDate = parseDate('2025-01-15');
+ *
+ * // Work with Temporal
+ * const tomorrow = dueDate.add({ days: 1 });
+ * const overdue = isToday(dueDate);
+ *
+ * // Serialize back to ISO for API
+ * const isoString = serialize(tomorrow); // '2025-01-16'
+ *
+ * // Format for UI display
+ * const display = formatDateShort(tomorrow); // 'Jan 16'
+ */
+
+// =============================================================================
+// Temporal API (re-export from polyfill)
+// =============================================================================
+// When native Temporal lands, change this to:
+// export const { Temporal } = globalThis;
+
+// Re-export the Temporal namespace type for convenience
+export type { Temporal as TemporalNamespace } from "@js-temporal/polyfill";
+export { Temporal } from "@js-temporal/polyfill";
+
+// =============================================================================
+// Parsing: ISO 8601 string → Temporal
+// =============================================================================
+
+export {
+  fromDate,
+  parseDate,
+  parseDateOrUndefined,
+  parseDateTime,
+  parseDateTimeOrUndefined,
+  parseDuration,
+  parseDurationOrUndefined,
+  parseInstant,
+  parseInstantOrUndefined,
+  parseTime,
+  parseTimeOrUndefined,
+  parseZoned,
+  parseZonedOrUndefined,
+} from "./parse";
+
+// =============================================================================
+// Formatting: Temporal → strings
+// =============================================================================
+
+export {
+  // Pattern-based formatting
+  formatDate,
+  formatDateFull,
+  formatDateLong,
+  formatDateMedium,
+  formatDateMediumYear,
+  formatDateNumeric,
+  formatDateNumericYear,
+  // Date range formats
+  formatDateRange,
+  // Date formats
+  formatDateShort,
+  formatDateShortWeekday,
+  formatDateShortWeekdayYear,
+  formatDateShortYear,
+  // Composite type formats
+  formatDateTimeTime,
+  formatDurationShort,
+  formatInstantDateTime,
+  formatInstantShortYear,
+  formatInstantTime,
+  // Duration formats
+  formatMilliseconds,
+  formatMonthYear,
+  formatMonthYearShort,
+  // Compact recency (1d/60d/2mo/1y) for index rows
+  formatRecency,
+  // Relative formats
+  formatRelative,
+  formatRelativeInstant,
+  formatRelativeToNow,
+  // Time formats
+  formatTime,
+  formatTime24,
+  formatTimeCompact,
+  formatTimeHour,
+  formatTimePadded,
+  formatWeekRange,
+  formatZonedTime,
+} from "./format";
+
+// =============================================================================
+// Validation
+// =============================================================================
+
+export type { ValidationResult } from "./validate";
+export {
+  isDuration,
+  isInstant,
+  // String validation
+  isISODate,
+  isISODateTime,
+  isISODuration,
+  isISOInstant,
+  isISOString,
+  isISOTime,
+  isISOZoned,
+  // Type guards
+  isPlainDate,
+  isPlainDateTime,
+  isPlainTime,
+  isTemporal,
+  isZonedDateTime,
+  // Validation with errors
+  validateISODate,
+  validateISODuration,
+  validateISOInstant,
+  validateISOZoned,
+} from "./validate";
+
+// =============================================================================
+// Current time
+// =============================================================================
+
+export {
+  currentTime,
+  now,
+  nowDateTime,
+  nowDateTimeISO,
+  nowInTimezone,
+  nowISO,
+  nowZoned,
+  today,
+  todayISO,
+} from "./now";
+
+// =============================================================================
+// Comparison
+// =============================================================================
+
+export {
+  isAfter,
+  isBefore,
+  isFuture,
+  isInstantAfter,
+  isInstantBefore,
+  isInstantFuture,
+  isInstantPast,
+  isPast,
+  isSameDay,
+  isSameMonth,
+  isToday,
+} from "./compare";
+
+// =============================================================================
+// Arithmetic
+// =============================================================================
+
+export {
+  addDays,
+  addMonths,
+  addWeeks,
+  differenceInMinutes,
+  diffInDays,
+  diffInMonths,
+  eachDayOfInterval,
+  subtractDays,
+  subtractMonths,
+  subtractWeeks,
+} from "./arithmetic";
+
+// =============================================================================
+// Boundaries
+// =============================================================================
+
+export type { WeekStartsOn } from "./boundaries";
+export {
+  endOfDay,
+  endOfMonth,
+  endOfWeek,
+  endOfYear,
+  startOfDay,
+  startOfMonth,
+  startOfWeek,
+  startOfYear,
+} from "./boundaries";
+
+// =============================================================================
+// Serialization: Temporal → ISO 8601 strings
+// =============================================================================
+
+export {
+  serialize,
+  serializeDate,
+  serializeDateTime,
+  serializeDuration,
+  serializeInstant,
+  serializeOptional,
+  serializeTime,
+  serializeZonedDateTime,
+} from "./serialize";
+
+// =============================================================================
+// Timezone
+// =============================================================================
+
+export {
+  changeTimezone,
+  plainDateTimeToZonedDateTime,
+  plainDateToZonedDateTime,
+  toTimezone,
+} from "./timezone";
+
+// =============================================================================
+// API Boundary Pattern
+// =============================================================================
+//
+// When sending Temporal types to the API, use these patterns:
+//
+// For Instant (timezone-aware absolute time) values:
+//   serialize(instant)
+//   → "2026-01-24T23:30:00Z"
+//
+// For PlainDate (date-only, timezone-agnostic) values:
+//   serialize(plainDateToZonedDateTime(date))
+//   → "2026-01-24T00:00:00-08:00[America/Los_Angeles]"
+//
+// Why?
+// - Instant is already absolute UTC time - serialize directly
+// - PlainDate needs timezone context - interpret in user's timezone, then serialize
+// - Server parseInstant() handles both formats correctly
+//
+// PREFER Instant for all datetime values in UI components and API hooks.
+// PlainDate is only for date-only values (birthdays, all-day events).
+//
+// Example in API hook (CURRENT PATTERN):
+//   const params = {
+//     since: dateRange?.from ? serialize(dateRange.from) : undefined,  // dateRange uses Instant
+//     until: dateRange?.to ? serialize(dateRange.to) : undefined,
+//   };
+//
+// See: packages/web/src/api/activity-log/useActivityLog.ts for reference implementation
+// =============================================================================
+
+// =============================================================================
+// Duration
+// =============================================================================
+
+export {
+  days,
+  hours,
+  minutes,
+  toHours,
+  toMilliseconds,
+  toMinutes,
+  toSeconds,
+  weeks,
+} from "./duration";
+
+// =============================================================================
+// Elapsed time
+// =============================================================================
+
+export { elapsedMs, epochMs } from "./elapsed";

package/src/date-time/now.ts

@@ -0,0 +1,70 @@
+/**
+ * Current time/date utilities
+ *
+ * Functions that answer "what time/date is it right now?"
+ */
+
+import { Temporal } from "@js-temporal/polyfill";
+
+/**
+ * Get the current instant (point in time)
+ */
+export function now(): Temporal.Instant {
+  return Temporal.Now.instant();
+}
+
+/**
+ * Get the current instant as an ISO 8601 string
+ */
+export function nowISO(): string {
+  return Temporal.Now.instant().toString();
+}
+
+/**
+ * Get today's date in the system timezone
+ */
+export function today(): Temporal.PlainDate {
+  return Temporal.Now.plainDateISO();
+}
+
+/**
+ * Get today's date as an ISO 8601 string
+ */
+export function todayISO(): string {
+  return Temporal.Now.plainDateISO().toString();
+}
+
+/**
+ * Get the current time in the system timezone
+ */
+export function currentTime(): Temporal.PlainTime {
+  return Temporal.Now.plainTimeISO();
+}
+
+/**
+ * Get the current date/time in the system timezone (without timezone info)
+ */
+export function nowDateTime(): Temporal.PlainDateTime {
+  return Temporal.Now.plainDateTimeISO();
+}
+
+/**
+ * Get the current date/time as an ISO 8601 string (without timezone info)
+ */
+export function nowDateTimeISO(): string {
+  return Temporal.Now.plainDateTimeISO().toString();
+}
+
+/**
+ * Get the current zoned date/time in the system timezone
+ */
+export function nowZoned(): Temporal.ZonedDateTime {
+  return Temporal.Now.zonedDateTimeISO();
+}
+
+/**
+ * Get the current zoned date/time in a specific timezone
+ */
+export function nowInTimezone(timezone: string): Temporal.ZonedDateTime {
+  return Temporal.Now.zonedDateTimeISO(timezone);
+}

package/src/date-time/parse.ts

@@ -0,0 +1,170 @@
+/**
+ * Parsing utilities: External data → Temporal
+ *
+ * Use these at integration boundaries when receiving data from external sources:
+ * - ISO 8601 strings from APIs
+ * - Date objects from Node.js APIs or third-party libraries
+ */
+
+import { Temporal } from "@js-temporal/polyfill";
+
+/**
+ * Parse an ISO 8601 instant string to Temporal.Instant
+ *
+ * @example
+ * parseInstant('2025-01-15T14:30:00.000Z')
+ * // → Temporal.Instant
+ */
+export function parseInstant(iso: string): Temporal.Instant {
+  return Temporal.Instant.from(iso);
+}
+
+/**
+ * Parse an ISO 8601 instant string to Temporal.Instant, or undefined if input is nullish
+ */
+export function parseInstantOrUndefined(iso: string | null | undefined): Temporal.Instant | undefined {
+  return iso ? Temporal.Instant.from(iso) : undefined;
+}
+
+/**
+ * Parse an ISO 8601 date string to Temporal.PlainDate
+ *
+ * Accepts formats:
+ * - '2025-01-15' (date only)
+ * - '2025-01-15T14:30:00' (datetime, time portion ignored)
+ * - '2025-01-15T14:30:00Z' (datetime with Z, time portion ignored)
+ * - '2025-01-15T14:30:00.000Z' (datetime with milliseconds and Z)
+ *
+ * @example
+ * parseDate('2025-01-15')
+ * // → Temporal.PlainDate
+ */
+export function parseDate(iso: string): Temporal.PlainDate {
+  // Extract just the date portion (first 10 characters: YYYY-MM-DD)
+  const datePart = iso.slice(0, 10);
+  return Temporal.PlainDate.from(datePart);
+}
+
+/**
+ * Parse an ISO 8601 date string to Temporal.PlainDate, or undefined if input is nullish
+ *
+ * Accepts same formats as parseDate.
+ */
+export function parseDateOrUndefined(iso: string | null | undefined): Temporal.PlainDate | undefined {
+  if (!iso) return undefined;
+  const datePart = iso.slice(0, 10);
+  return Temporal.PlainDate.from(datePart);
+}
+
+/**
+ * Parse an ISO 8601 time string to Temporal.PlainTime
+ *
+ * @example
+ * parseTime('14:30:00')
+ * // → Temporal.PlainTime
+ */
+export function parseTime(iso: string): Temporal.PlainTime {
+  return Temporal.PlainTime.from(iso);
+}
+
+/**
+ * Parse an ISO 8601 time string to Temporal.PlainTime, or undefined if input is nullish
+ */
+export function parseTimeOrUndefined(iso: string | null | undefined): Temporal.PlainTime | undefined {
+  return iso ? Temporal.PlainTime.from(iso) : undefined;
+}
+
+/**
+ * Parse an ISO 8601 datetime string to Temporal.PlainDateTime
+ *
+ * Accepts formats:
+ * - '2025-01-15T14:30:00' (datetime)
+ * - '2025-01-15T14:30:00Z' (datetime with Z, Z is stripped)
+ * - '2025-01-15T14:30:00.000Z' (datetime with milliseconds and Z)
+ *
+ * @example
+ * parseDateTime('2025-01-15T14:30:00')
+ * // → Temporal.PlainDateTime
+ */
+export function parseDateTime(iso: string): Temporal.PlainDateTime {
+  // Strip trailing Z if present (PlainDateTime doesn't accept timezone designators)
+  const normalized = iso.endsWith("Z") ? iso.slice(0, -1) : iso;
+  return Temporal.PlainDateTime.from(normalized);
+}
+
+/**
+ * Parse an ISO 8601 datetime string to Temporal.PlainDateTime, or undefined if input is nullish
+ *
+ * Accepts same formats as parseDateTime.
+ */
+export function parseDateTimeOrUndefined(iso: string | null | undefined): Temporal.PlainDateTime | undefined {
+  if (!iso) return undefined;
+  const normalized = iso.endsWith("Z") ? iso.slice(0, -1) : iso;
+  return Temporal.PlainDateTime.from(normalized);
+}
+
+/**
+ * Parse an ISO 8601 zoned datetime string to Temporal.ZonedDateTime
+ *
+ * Accepts formats:
+ * - '2025-01-15T14:30:00[America/New_York]'
+ * - '2025-01-15T14:30:00-05:00[America/New_York]'
+ *
+ * @example
+ * parseZoned('2025-01-15T14:30:00[America/New_York]')
+ * // → Temporal.ZonedDateTime
+ */
+export function parseZoned(iso: string): Temporal.ZonedDateTime {
+  return Temporal.ZonedDateTime.from(iso);
+}
+
+/**
+ * Parse an ISO 8601 zoned datetime string to Temporal.ZonedDateTime, or undefined if input is nullish
+ */
+export function parseZonedOrUndefined(iso: string | null | undefined): Temporal.ZonedDateTime | undefined {
+  return iso ? Temporal.ZonedDateTime.from(iso) : undefined;
+}
+
+// =============================================================================
+// Date object conversion
+// =============================================================================
+
+/**
+ * Convert a JavaScript Date object to Temporal.Instant
+ *
+ * Use this at API boundaries where external libraries return Date objects
+ * (e.g., Node.js fs.Stats.mtime, pg driver timestamptz columns, pg-boss next_run_on)
+ *
+ * @example
+ * // Converting fs.Stats mtime
+ * const instant = fromDate(stats.mtime);
+ *
+ * // Converting pg driver Date
+ * const instant = fromDate(pgResult.created_at);
+ */
+// biome-ignore lint/style/noRestrictedGlobals: Date parameter required for converting from external APIs
+export function fromDate(date: Date): Temporal.Instant {
+  return Temporal.Instant.fromEpochMilliseconds(date.getTime());
+}
+
+// =============================================================================
+// Duration parsing
+// =============================================================================
+
+/**
+ * Parse an ISO 8601 duration string to Temporal.Duration
+ *
+ * @example
+ * parseDuration('PT1H30M')
+ * // → Temporal.Duration (1 hour 30 minutes)
+ */
+export function parseDuration(iso: string): Temporal.Duration {
+  return Temporal.Duration.from(iso);
+}
+
+/**
+ * Parse an ISO 8601 duration string to Temporal.Duration, or undefined if input is nullish
+ */
+export function parseDurationOrUndefined(iso: string | null | undefined): Temporal.Duration | undefined {
+  return iso ? Temporal.Duration.from(iso) : undefined;
+}

package/src/date-time/serialize.ts

@@ -0,0 +1,90 @@
+/**
+ * Generic serialization utilities for Temporal types
+ *
+ * Provides a unified way to convert any Temporal type to its ISO string representation.
+ * These functions are simple wrappers around `.toString()` but provide:
+ * - Type safety
+ * - Consistent naming
+ * - Optional value handling
+ * - A single import point
+ *
+ * ## API Boundary Pattern
+ *
+ * When sending Temporal types to API endpoints, use this composition:
+ *
+ * ```typescript
+ * import { plainDateTimeToZonedDateTime, serialize } from "@sixthshift/design-system/date-time";
+ *
+ * // For PlainDateTime (timezone-naive) → API string
+ * const apiValue = serialize(plainDateTimeToZonedDateTime(dateTime));
+ * // → "2026-01-24T15:30:00-08:00[America/Los_Angeles]"
+ *
+ * // For PlainDate → API string (midnight in user's timezone)
+ * const apiValue = serialize(plainDateToZonedDateTime(date));
+ * // → "2026-01-24T00:00:00-08:00[America/Los_Angeles]"
+ *
+ * // Server receives and parses to UTC Instant
+ * parseInstant(apiValue) → Instant('2026-01-24T23:30:00Z')
+ * ```
+ *
+ */
+
+import type { Temporal } from "@js-temporal/polyfill";
+
+/**
+ * Serialize any Temporal type to its ISO 8601 string representation
+ *
+ * @example
+ * serialize(Temporal.PlainDate.from('2026-01-24'))
+ * // → '2026-01-24'
+ *
+ * serialize(Temporal.PlainDateTime.from('2026-01-24T15:30'))
+ * // → '2026-01-24T15:30:00'
+ *
+ * serialize(Temporal.Instant.from('2026-01-24T04:30:00Z'))
+ * // → '2026-01-24T04:30:00Z'
+ */
+export function serialize(
+  temporal: Temporal.Instant | Temporal.PlainDate | Temporal.PlainDateTime | Temporal.PlainTime | Temporal.ZonedDateTime | Temporal.Duration
+): string {
+  return temporal.toString();
+}
+
+/**
+ * Serialize optional Temporal type to ISO string or undefined
+ *
+ * @example
+ * serializeOptional(undefined) // → undefined
+ * serializeOptional(Temporal.PlainDate.from('2026-01-24')) // → '2026-01-24'
+ */
+export function serializeOptional(
+  temporal: Temporal.Instant | Temporal.PlainDate | Temporal.PlainDateTime | Temporal.PlainTime | Temporal.ZonedDateTime | Temporal.Duration | null | undefined
+): string | undefined {
+  return temporal?.toString();
+}
+
+// Type-specific convenience functions (optional, for clarity)
+
+export function serializeInstant(instant: Temporal.Instant): string {
+  return instant.toString();
+}
+
+export function serializeDate(date: Temporal.PlainDate): string {
+  return date.toString();
+}
+
+export function serializeDateTime(dateTime: Temporal.PlainDateTime): string {
+  return dateTime.toString();
+}
+
+export function serializeTime(time: Temporal.PlainTime): string {
+  return time.toString();
+}
+
+export function serializeZonedDateTime(zoned: Temporal.ZonedDateTime): string {
+  return zoned.toString();
+}
+
+export function serializeDuration(duration: Temporal.Duration): string {
+  return duration.toString();
+}

package/src/date-time/timezone.ts

@@ -0,0 +1,47 @@
+/**
+ * Timezone conversion utilities
+ *
+ * Functions for converting between timezones and working with ZonedDateTime
+ */
+
+import { Temporal } from "@js-temporal/polyfill";
+
+/**
+ * Convert an instant to a zoned date/time in a specific timezone
+ */
+export function toTimezone(instant: Temporal.Instant, timezone: string): Temporal.ZonedDateTime {
+  return instant.toZonedDateTimeISO(timezone);
+}
+
+/**
+ * Convert a zoned date/time to a different timezone
+ */
+export function changeTimezone(zoned: Temporal.ZonedDateTime, timezone: string): Temporal.ZonedDateTime {
+  return zoned.withTimeZone(timezone);
+}
+
+/**
+ * Interpret PlainDateTime in a specific timezone, returning ZonedDateTime
+ *
+ * @example
+ * const dt = Temporal.PlainDateTime.from('2026-01-24T15:30');
+ * const zoned = plainDateTimeToZonedDateTime(dt, 'America/Los_Angeles');
+ * // → 2026-01-24T15:30:00-08:00[America/Los_Angeles]
+ */
+export function plainDateTimeToZonedDateTime(dateTime: Temporal.PlainDateTime, timezone?: string): Temporal.ZonedDateTime {
+  const tz = timezone ?? Temporal.Now.timeZoneId();
+  return dateTime.toZonedDateTime(tz);
+}
+
+/**
+ * Interpret PlainDate as midnight in a specific timezone, returning ZonedDateTime
+ *
+ * @example
+ * const date = Temporal.PlainDate.from('2026-01-24');
+ * const zoned = plainDateToZonedDateTime(date, 'America/Los_Angeles');
+ * // → 2026-01-24T00:00:00-08:00[America/Los_Angeles]
+ */
+export function plainDateToZonedDateTime(date: Temporal.PlainDate, timezone?: string): Temporal.ZonedDateTime {
+  const tz = timezone ?? Temporal.Now.timeZoneId();
+  return date.toPlainDateTime(Temporal.PlainTime.from("00:00")).toZonedDateTime(tz);
+}