@sixthshift/design-system 0.1.0 → 0.2.1

package/dist/date-time/elapsed.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 declare function elapsedMs(start: Temporal.Instant): number;
+export declare function epochMs(instant: Temporal.Instant): number;
+//# sourceMappingURL=elapsed.d.ts.map

package/dist/date-time/elapsed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elapsed.d.ts","sourceRoot":"","sources":["../../src/date-time/elapsed.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,wBAAgB,SAAS,CAAC,KAAK,EAAE,QAAQ,CAAC,OAAO,GAAG,MAAM,CAGzD;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,GAAG,MAAM,CAEzD"}

package/dist/date-time/elapsed.js

@@ -0,0 +1,16 @@
+/**
+ * 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) {
+    const ms = Temporal.Now.instant().since(start).total({ unit: "milliseconds" });
+    return Math.max(0, Math.round(ms));
+}
+export function epochMs(instant) {
+    return Number(instant.epochMilliseconds);
+}
+//# sourceMappingURL=elapsed.js.map

package/dist/date-time/elapsed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"elapsed.js","sourceRoot":"","sources":["../../src/date-time/elapsed.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,MAAM,UAAU,SAAS,CAAC,KAAuB;IAC/C,MAAM,EAAE,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAC;IAC/E,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,OAAyB;IAC/C,OAAO,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAC3C,CAAC"}

package/dist/date-time/format.d.ts

@@ -0,0 +1,341 @@
+/**
+ * Formatting utilities: Human-readable display strings
+ *
+ * For ISO 8601 serialization (APIs/storage), use serialize() from serialize.ts
+ * This module provides only human-readable formatting for UI display.
+ *
+ * API Overview (31 functions):
+ *
+ * Date Formats (PlainDate input):
+ *   formatDateShort             "Jan 15"
+ *   formatDateShortYear         "Jan 15, 2025"
+ *   formatDateMedium            "January 15"
+ *   formatDateMediumYear        "January 15, 2025"
+ *   formatDateShortWeekday      "Wed, Jan 15"
+ *   formatDateShortWeekdayYear  "Wed, Jan 15, 2025"
+ *   formatDateLong              "Wednesday, January 15"
+ *   formatDateFull              "Wednesday, January 15, 2025"
+ *   formatDateNumeric           "1/15"
+ *   formatDateNumericYear       "1/15/2025"
+ *   formatMonthYear             "January 2025"
+ *   formatMonthYearShort        "Jan 2025"
+ *
+ * Time Formats (PlainTime input):
+ *   formatTime                  "2:30 PM"
+ *   formatTimePadded            "02:30 PM"
+ *   formatTimeCompact           "2 PM" / "2:30 PM"
+ *   formatTimeHour              "2pm"
+ *   formatTime24                "14:30:45"
+ *
+ * Composite Type Formats (DateTime/Zoned/Instant input):
+ *   formatDateTimeTime          PlainDateTime → "2:30 PM"
+ *   formatZonedTime             ZonedDateTime → "2:30 PM"
+ *   formatInstantTime           Instant → "2:30 PM"
+ *   formatInstantDateTime       Instant → "Jan 24, 2026, 3:30 PM"
+ *   formatInstantShortYear      Instant → "Jan 24, 2026"
+ *
+ * Pattern-Based Formatting:
+ *   formatDate                  PlainDate + pattern → custom string
+ *
+ * Date Range Formats:
+ *   formatDateRange             "Jan 24 - 25, 2026"
+ *   formatWeekRange             "Jan 12 - 18, 2025"
+ *
+ * Relative Formats:
+ *   formatRelative              "today" / "tomorrow" / "3 days ago"
+ *   formatRelativeInstant       "just now" / "5m ago" / "2h ago"
+ *   formatRelativeToNow         "3 hours ago" / "in 2 days"
+ *
+ * Duration Formats:
+ *   formatMilliseconds          "1.5s" / "5m 30s"
+ *   formatDurationShort         "5min" / "1hr 30min"
+ */
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Format a date as "Jan 15" (short month, day)
+ *
+ * @example
+ * formatDateShort(parseDate('2025-01-15'))
+ * // → 'Jan 15'
+ */
+export declare function formatDateShort(date: Temporal.PlainDate): string;
+/**
+ * Format a date as "Jan 15, 2025" (short month, day, year)
+ *
+ * @example
+ * formatDateShortYear(parseDate('2025-01-15'))
+ * // → 'Jan 15, 2025'
+ */
+export declare function formatDateShortYear(date: Temporal.PlainDate): string;
+/**
+ * Format a date as "January 15" (long month, day)
+ *
+ * @example
+ * formatDateMedium(parseDate('2025-01-15'))
+ * // → 'January 15'
+ */
+export declare function formatDateMedium(date: Temporal.PlainDate): string;
+/**
+ * Format a date as "January 15, 2025" (long month, day, year)
+ *
+ * @example
+ * formatDateMediumYear(parseDate('2025-01-15'))
+ * // → 'January 15, 2025'
+ */
+export declare function formatDateMediumYear(date: Temporal.PlainDate): string;
+/**
+ * Format a date as "Wed, Jan 15" (short weekday, short month, day)
+ *
+ * @example
+ * formatDateShortWeekday(parseDate('2025-01-15'))
+ * // → 'Wed, Jan 15'
+ */
+export declare function formatDateShortWeekday(date: Temporal.PlainDate): string;
+/**
+ * Format a date as "Wed, Jan 15, 2025" (short weekday, short month, day, year)
+ *
+ * @example
+ * formatDateShortWeekdayYear(parseDate('2025-01-15'))
+ * // → 'Wed, Jan 15, 2025'
+ */
+export declare function formatDateShortWeekdayYear(date: Temporal.PlainDate): string;
+/**
+ * Format a date as "Wednesday, January 15" (long weekday, long month, day)
+ *
+ * @example
+ * formatDateLong(parseDate('2025-01-15'))
+ * // → 'Wednesday, January 15'
+ */
+export declare function formatDateLong(date: Temporal.PlainDate): string;
+/**
+ * Format a date as "Wednesday, January 15, 2025" (long weekday, long month, day, year)
+ *
+ * @example
+ * formatDateFull(parseDate('2025-01-15'))
+ * // → 'Wednesday, January 15, 2025'
+ */
+export declare function formatDateFull(date: Temporal.PlainDate): string;
+/**
+ * Format a date as "1/15" (numeric month/day)
+ *
+ * @example
+ * formatDateNumeric(parseDate('2025-01-15'))
+ * // → '1/15'
+ */
+export declare function formatDateNumeric(date: Temporal.PlainDate): string;
+/**
+ * Format a date as "1/15/2025" (numeric month/day/year)
+ *
+ * @example
+ * formatDateNumericYear(parseDate('2025-01-15'))
+ * // → '1/15/2025'
+ */
+export declare function formatDateNumericYear(date: Temporal.PlainDate): string;
+/**
+ * Format a date as "January 2025" (long month, year)
+ *
+ * @example
+ * formatMonthYear(parseDate('2025-01-15'))
+ * // → 'January 2025'
+ */
+export declare function formatMonthYear(date: Temporal.PlainDate): string;
+/**
+ * Format a date as "Jan 2025" (short month, year)
+ *
+ * @example
+ * formatMonthYearShort(parseDate('2025-01-15'))
+ * // → 'Jan 2025'
+ */
+export declare function formatMonthYearShort(date: Temporal.PlainDate): string;
+/**
+ * Format a time as "2:30 PM" (unpadded hour, standard UI format)
+ *
+ * @example
+ * formatTime(parseTime('14:30:00'))
+ * // → '2:30 PM'
+ */
+export declare function formatTime(time: Temporal.PlainTime): string;
+/**
+ * Format a time as "02:30 PM" (padded hour)
+ *
+ * @example
+ * formatTimePadded(parseTime('14:30:00'))
+ * // → '02:30 PM'
+ */
+export declare function formatTimePadded(time: Temporal.PlainTime): string;
+/**
+ * Format a time compactly: omits minutes when :00 (e.g., "2 PM", "2:30 PM")
+ * Ideal for calendar entries and space-constrained time displays.
+ *
+ * @example
+ * formatTimeCompact(parseTime('14:00:00'))
+ * // → '2 PM'
+ *
+ * formatTimeCompact(parseTime('14:30:00'))
+ * // → '2:30 PM'
+ *
+ * formatTimeCompact(parseTime('00:00:00'))
+ * // → '12 AM'
+ */
+export declare function formatTimeCompact(time: Temporal.PlainTime): string;
+/**
+ * Format an hour as compact string (e.g., "2pm", "11am")
+ * No space, lowercase - ideal for timeline x-axis labels
+ *
+ * @example
+ * formatTimeHour(parseTime('14:00:00'))
+ * // → '2pm'
+ *
+ * formatTimeHour(parseTime('09:00:00'))
+ * // → '9am'
+ */
+export declare function formatTimeHour(time: Temporal.PlainTime): string;
+/**
+ * Format a time as 24-hour HH:mm:ss (e.g., "14:30:45")
+ * Useful for logs and technical displays
+ *
+ * @example
+ * formatTime24(parseTime('14:30:45'))
+ * // → '14:30:45'
+ *
+ * formatTime24(parseTime('09:05:03'))
+ * // → '09:05:03'
+ */
+export declare function formatTime24(time: Temporal.PlainTime): string;
+/**
+ * Format a datetime's time portion for display
+ *
+ * @example
+ * formatDateTimeTime(parseDateTime('2025-01-15T14:30:00'))
+ * // → '2:30 PM'
+ */
+export declare function formatDateTimeTime(dateTime: Temporal.PlainDateTime): string;
+/**
+ * Format a zoned datetime's time portion for display
+ *
+ * @example
+ * formatZonedTime(parseZoned('2025-01-15T14:30:00-05:00[America/New_York]'))
+ * // → '2:30 PM'
+ */
+export declare function formatZonedTime(zoned: Temporal.ZonedDateTime): string;
+/**
+ * Format an instant's time portion for display in the local timezone
+ *
+ * @example
+ * formatInstantTime(parseInstant('2025-01-15T19:30:00Z'))
+ * // → '2:30 PM' (in America/New_York)
+ */
+export declare function formatInstantTime(instant: Temporal.Instant): string;
+/**
+ * Format an instant as date and time with year (e.g., "Jan 24, 2026, 3:30 PM")
+ *
+ * @example
+ * formatInstantDateTime(parseInstant('2026-01-24T23:30:00Z'), 'America/Los_Angeles')
+ * // → 'Jan 24, 2026, 3:30 PM'
+ */
+export declare function formatInstantDateTime(instant: Temporal.Instant, timeZone?: string): string;
+/**
+ * Format Instant as short date with year in user's timezone
+ *
+ * @example
+ * formatInstantShortYear(Temporal.Instant.from("2026-01-24T08:00:00Z"), "America/New_York")
+ * // → "Jan 24, 2026"
+ */
+export declare function formatInstantShortYear(instant: Temporal.Instant, timeZone?: string): string;
+export declare function formatDate(date: Temporal.PlainDate, pattern: string): string;
+/**
+ * Format a week date range (e.g., "Jan 12 - 18, 2025")
+ *
+ * @example
+ * formatWeekRange(parseDate('2025-01-12'), parseDate('2025-01-18'))
+ * // → 'Jan 12 - 18, 2025' (same month)
+ *
+ * formatWeekRange(parseDate('2025-01-26'), parseDate('2025-02-01'))
+ * // → 'Jan 26 - Feb 1, 2025' (different months, same year)
+ *
+ * formatWeekRange(parseDate('2024-12-29'), parseDate('2025-01-04'))
+ * // → 'Dec 29, 2024 - Jan 4, 2025' (different years)
+ */
+export declare function formatWeekRange(startDate: Temporal.PlainDate, endDate: Temporal.PlainDate): string;
+/**
+ * Format a date range intelligently
+ * - Same day: "Jan 24, 2026"
+ * - Same month: "Jan 24 - 25, 2026"
+ * - Same year: "Jan 24 - Feb 2, 2026"
+ * - Different years: "Dec 31, 2025 - Jan 1, 2026"
+ *
+ * @example
+ * formatDateRange(parseDate('2026-01-24'), parseDate('2026-01-24'))
+ * // → 'Jan 24, 2026'
+ *
+ * formatDateRange(parseDate('2026-01-24'), parseDate('2026-01-25'))
+ * // → 'Jan 24 - 25, 2026'
+ *
+ * formatDateRange(parseDate('2026-01-24'), parseDate('2026-02-02'))
+ * // → 'Jan 24 - Feb 2, 2026'
+ */
+export declare function formatDateRange(startDate: Temporal.PlainDate, endDate: Temporal.PlainDate): string;
+/**
+ * Format a date as a relative string (today, tomorrow, 3 days ago, etc.)
+ *
+ * @example
+ * formatRelative(parseDate('2025-01-15'))
+ * // → 'today' | 'tomorrow' | 'yesterday' | 'in 3 days' | '3 days ago' | 'Jan 15, 2025'
+ */
+export declare function formatRelative(date: Temporal.PlainDate): string;
+/**
+ * Format an instant as a relative string (just now, 5m ago, 2h ago, etc.)
+ *
+ * @example
+ * formatRelativeInstant(parseInstant('2025-01-15T14:30:00Z'))
+ * // → 'just now' | '5m ago' | '2h ago' | '3d ago' | 'Jan 15, 2025'
+ */
+export declare function formatRelativeInstant(instant: Temporal.Instant): string;
+/**
+ * Format a Temporal.Instant relative to now ("3 hours ago", "in 2 days")
+ *
+ * @example
+ * formatRelativeToNow(parseInstant('2025-01-15T14:30:00Z'))
+ * // → '3 hours ago' | 'in 2 days' | 'just now'
+ */
+export declare function formatRelativeToNow(instant: Temporal.Instant): string;
+/**
+ * Compact recency label. Used in lists and rows where space is tight and
+ * relative time scans as a single rhythm across pages.
+ *
+ *   today → "today"
+ *   1–60 days → "1d", "2d", … "60d"
+ *   61–364 days → "2mo", "3mo", … "11mo"
+ *   365+ days → "1y", "2y", …
+ *
+ * Negative ranges (future instants) are not handled — this is for past-only
+ * recency on entity rows.
+ *
+ * @example
+ * formatRecency(Temporal.Now.instant())     // → 'today'
+ * formatRecency(twoDaysAgo)                  // → '2d'
+ * formatRecency(threeMonthsAgo)              // → '3mo'
+ */
+export declare function formatRecency(instant: Temporal.Instant): string;
+/**
+ * Format milliseconds duration as human-readable string (e.g., "1.2s", "5m 30s")
+ *
+ * @example
+ * formatMilliseconds(1500)  // → '1.5s'
+ * formatMilliseconds(65000) // → '1m 5s'
+ * formatMilliseconds(500)   // → '500ms'
+ */
+export declare function formatMilliseconds(ms: number): string;
+/**
+ * Format a Temporal.Duration as a compact human-readable string
+ *
+ * @example
+ * formatDurationShort(minutes(5))    // → '5min'
+ * formatDurationShort(hours(1))      // → '1hr'
+ * formatDurationShort(hours(6))      // → '6hr'
+ * formatDurationShort(days(1))       // → '1 day'
+ * formatDurationShort(days(7))       // → '7 days'
+ * formatDurationShort(Temporal.Duration.from({ hours: 1, minutes: 30 })) // → '1hr 30min'
+ */
+export declare function formatDurationShort(duration: Temporal.Duration): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/date-time/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/date-time/format.ts"],"names":[],"mappings":"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"}