@sixthshift/design-system 0.1.0

package/src/date-time/arithmetic.ts

@@ -0,0 +1,101 @@
+/**
+ * Date/time arithmetic utilities
+ *
+ * Functions that modify or calculate differences between dates
+ */
+
+import { Temporal } from "@js-temporal/polyfill";
+
+/**
+ * Add days to a date
+ */
+export function addDays(date: Temporal.PlainDate, days: number): Temporal.PlainDate {
+  return date.add({ days });
+}
+
+/**
+ * Subtract days from a date
+ */
+export function subtractDays(date: Temporal.PlainDate, days: number): Temporal.PlainDate {
+  return date.subtract({ days });
+}
+
+/**
+ * Add months to a date
+ */
+export function addMonths(date: Temporal.PlainDate, months: number): Temporal.PlainDate {
+  return date.add({ months });
+}
+
+/**
+ * Subtract months from a date
+ */
+export function subtractMonths(date: Temporal.PlainDate, months: number): Temporal.PlainDate {
+  return date.subtract({ months });
+}
+
+/**
+ * Add weeks to a date
+ */
+export function addWeeks(date: Temporal.PlainDate, weeks: number): Temporal.PlainDate {
+  return date.add({ weeks });
+}
+
+/**
+ * Subtract weeks from a date
+ */
+export function subtractWeeks(date: Temporal.PlainDate, weeks: number): Temporal.PlainDate {
+  return date.subtract({ weeks });
+}
+
+/**
+ * Get the difference in days between two dates
+ */
+export function diffInDays(from: Temporal.PlainDate, to: Temporal.PlainDate): number {
+  return from.until(to, { largestUnit: "day" }).days;
+}
+
+/**
+ * Get the difference in months between two dates
+ */
+export function diffInMonths(from: Temporal.PlainDate, to: Temporal.PlainDate): number {
+  const diff = from.until(to, { largestUnit: "month" });
+  return diff.months + diff.years * 12;
+}
+
+/**
+ * Get the difference in minutes between two instants
+ */
+export function differenceInMinutes(from: Temporal.Instant, to: Temporal.Instant): number {
+  const diff = from.until(to, { largestUnit: "minute" });
+  return Math.floor(diff.total("minutes"));
+}
+
+/**
+ * Generate an array of dates from start to end (inclusive)
+ *
+ * @example
+ * eachDayOfInterval(parseDate('2025-01-15'), parseDate('2025-01-17'))
+ * // → [2025-01-15, 2025-01-16, 2025-01-17]
+ */
+export function eachDayOfInterval(start: Temporal.PlainDate, end: Temporal.PlainDate): Temporal.PlainDate[] {
+  const dates: Temporal.PlainDate[] = [];
+  let current = start;
+
+  // Handle both forward and backward intervals
+  if (Temporal.PlainDate.compare(start, end) <= 0) {
+    // Forward: start <= end
+    while (Temporal.PlainDate.compare(current, end) <= 0) {
+      dates.push(current);
+      current = current.add({ days: 1 });
+    }
+  } else {
+    // Backward: start > end
+    while (Temporal.PlainDate.compare(current, end) >= 0) {
+      dates.push(current);
+      current = current.subtract({ days: 1 });
+    }
+  }
+
+  return dates;
+}

package/src/date-time/boundaries.ts

@@ -0,0 +1,91 @@
+/**
+ * Time period boundary utilities
+ *
+ * Functions that find the start/end of time periods (day, week, month, year)
+ */
+
+import type { Temporal } from "@js-temporal/polyfill";
+
+/**
+ * Get the start of the day (midnight)
+ */
+export function startOfDay(date: Temporal.PlainDate): Temporal.PlainDateTime {
+  return date.toPlainDateTime({ hour: 0, minute: 0, second: 0 });
+}
+
+/**
+ * Get the end of the day (23:59:59.999999999)
+ */
+export function endOfDay(date: Temporal.PlainDate): Temporal.PlainDateTime {
+  return date.toPlainDateTime({
+    hour: 23,
+    minute: 59,
+    second: 59,
+    millisecond: 999,
+    microsecond: 999,
+    nanosecond: 999,
+  });
+}
+
+/**
+ * First day of the week, as used by calendars: 0 = Sunday through 6 = Saturday.
+ * Note this is NOT Temporal's `dayOfWeek`, which is ISO 8601 (1 = Monday,
+ * 7 = Sunday) — `daysSinceWeekStart` converts between the two.
+ */
+export type WeekStartsOn = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
+/**
+ * How many days `date` sits past the start of its week, 0-6.
+ */
+function daysSinceWeekStart(date: Temporal.PlainDate, weekStartsOn: WeekStartsOn): number {
+  // weekStartsOn counts from Sunday; dayOfWeek counts from Monday and uses 7
+  // for Sunday, so Sunday maps to 7 rather than 0.
+  const isoWeekStart = weekStartsOn === 0 ? 7 : weekStartsOn;
+  return (date.dayOfWeek - isoWeekStart + 7) % 7;
+}
+
+/**
+ * Get the start of the week (Monday by default, configurable)
+ * @param date The date to find the week start for
+ * @param weekStartsOn 0 = Sunday, 1 = Monday (default), through 6 = Saturday
+ */
+export function startOfWeek(date: Temporal.PlainDate, weekStartsOn: WeekStartsOn = 1): Temporal.PlainDate {
+  return date.subtract({ days: daysSinceWeekStart(date, weekStartsOn) });
+}
+
+/**
+ * Get the end of the week — the day before the next week's start.
+ * @param date The date to find the week end for
+ * @param weekStartsOn 0 = Sunday, 1 = Monday (default), through 6 = Saturday
+ */
+export function endOfWeek(date: Temporal.PlainDate, weekStartsOn: WeekStartsOn = 1): Temporal.PlainDate {
+  return date.add({ days: 6 - daysSinceWeekStart(date, weekStartsOn) });
+}
+
+/**
+ * Get the start of the month
+ */
+export function startOfMonth(date: Temporal.PlainDate): Temporal.PlainDate {
+  return date.with({ day: 1 });
+}
+
+/**
+ * Get the end of the month
+ */
+export function endOfMonth(date: Temporal.PlainDate): Temporal.PlainDate {
+  return date.with({ day: date.daysInMonth });
+}
+
+/**
+ * Get the start of the year
+ */
+export function startOfYear(date: Temporal.PlainDate): Temporal.PlainDate {
+  return date.with({ month: 1, day: 1 });
+}
+
+/**
+ * Get the end of the year
+ */
+export function endOfYear(date: Temporal.PlainDate): Temporal.PlainDate {
+  return date.with({ month: 12, day: 31 });
+}

package/src/date-time/compare.ts

@@ -0,0 +1,85 @@
+/**
+ * Comparison utilities
+ *
+ * Boolean comparison operations for dates and instants
+ */
+
+import { Temporal } from "@js-temporal/polyfill";
+import { now, today } from "./now";
+
+/**
+ * Check if date A is before date B
+ */
+export function isBefore(a: Temporal.PlainDate, b: Temporal.PlainDate): boolean {
+  return Temporal.PlainDate.compare(a, b) < 0;
+}
+
+/**
+ * Check if date A is after date B
+ */
+export function isAfter(a: Temporal.PlainDate, b: Temporal.PlainDate): boolean {
+  return Temporal.PlainDate.compare(a, b) > 0;
+}
+
+/**
+ * Check if two dates are the same day
+ */
+export function isSameDay(a: Temporal.PlainDate, b: Temporal.PlainDate): boolean {
+  return Temporal.PlainDate.compare(a, b) === 0;
+}
+
+/**
+ * Check if two dates are in the same month and year
+ */
+export function isSameMonth(a: Temporal.PlainDate, b: Temporal.PlainDate): boolean {
+  return a.year === b.year && a.month === b.month;
+}
+
+/**
+ * Check if instant A is before instant B
+ */
+export function isInstantBefore(a: Temporal.Instant, b: Temporal.Instant): boolean {
+  return Temporal.Instant.compare(a, b) < 0;
+}
+
+/**
+ * Check if instant A is after instant B
+ */
+export function isInstantAfter(a: Temporal.Instant, b: Temporal.Instant): boolean {
+  return Temporal.Instant.compare(a, b) > 0;
+}
+
+/**
+ * Check if a date is today
+ */
+export function isToday(date: Temporal.PlainDate): boolean {
+  return isSameDay(date, today());
+}
+
+/**
+ * Check if a date is in the past
+ */
+export function isPast(date: Temporal.PlainDate): boolean {
+  return isBefore(date, today());
+}
+
+/**
+ * Check if a date is in the future
+ */
+export function isFuture(date: Temporal.PlainDate): boolean {
+  return isAfter(date, today());
+}
+
+/**
+ * Check if an instant is in the past
+ */
+export function isInstantPast(instant: Temporal.Instant): boolean {
+  return isInstantBefore(instant, now());
+}
+
+/**
+ * Check if an instant is in the future
+ */
+export function isInstantFuture(instant: Temporal.Instant): boolean {
+  return isInstantAfter(instant, now());
+}

package/src/date-time/duration.ts

@@ -0,0 +1,63 @@
+/**
+ * Duration utilities
+ *
+ * Functions for creating and converting Duration objects
+ */
+
+import { Temporal } from "@js-temporal/polyfill";
+
+/**
+ * Create a duration from hours
+ */
+export function hours(n: number): Temporal.Duration {
+  return Temporal.Duration.from({ hours: n });
+}
+
+/**
+ * Create a duration from minutes
+ */
+export function minutes(n: number): Temporal.Duration {
+  return Temporal.Duration.from({ minutes: n });
+}
+
+/**
+ * Create a duration from days
+ */
+export function days(n: number): Temporal.Duration {
+  return Temporal.Duration.from({ days: n });
+}
+
+/**
+ * Create a duration from weeks
+ */
+export function weeks(n: number): Temporal.Duration {
+  return Temporal.Duration.from({ weeks: n });
+}
+
+/**
+ * Get the total milliseconds of a duration
+ */
+export function toMilliseconds(duration: Temporal.Duration): number {
+  return duration.total({ unit: "milliseconds" });
+}
+
+/**
+ * Get the total seconds of a duration
+ */
+export function toSeconds(duration: Temporal.Duration): number {
+  return duration.total({ unit: "seconds" });
+}
+
+/**
+ * Get the total minutes of a duration
+ */
+export function toMinutes(duration: Temporal.Duration): number {
+  return duration.total({ unit: "minutes" });
+}
+
+/**
+ * Get the total hours of a duration
+ */
+export function toHours(duration: Temporal.Duration): number {
+  return duration.total({ unit: "hours" });
+}

package/src/date-time/elapsed.ts

@@ -0,0 +1,18 @@
+/**
+ * Elapsed-time helpers
+ *
+ * Replaces the legacy `Date.now() - start` pattern with Temporal-native
+ * equivalents. Native `Date` is banned codebase-wide — see ADR 0003 and
+ * `docs/engineering/reference/conventions/logging-conventions.md`.
+ */
+
+import { Temporal } from "@js-temporal/polyfill";
+
+export function elapsedMs(start: Temporal.Instant): number {
+  const ms = Temporal.Now.instant().since(start).total({ unit: "milliseconds" });
+  return Math.max(0, Math.round(ms));
+}
+
+export function epochMs(instant: Temporal.Instant): number {
+  return Number(instant.epochMilliseconds);
+}