@getmicdrop/svelte-components 5.3.10 → 5.3.13

package/dist/datetime/constants.js

@@ -0,0 +1,112 @@
+/**
+ * DateTime Constants
+ *
+ * Centralized constants for datetime operations.
+ * Use these instead of magic numbers throughout the codebase.
+ *
+ * @module datetime/constants
+ */
+/**
+ * Duration constants in milliseconds.
+ */
+export const DURATIONS = {
+    /** One second in milliseconds */
+    SECOND: 1000,
+    /** One minute in milliseconds */
+    MINUTE: 60 * 1000,
+    /** One hour in milliseconds */
+    HOUR: 60 * 60 * 1000,
+    /** One day in milliseconds */
+    DAY: 24 * 60 * 60 * 1000,
+    /** One week in milliseconds */
+    WEEK: 7 * 24 * 60 * 60 * 1000,
+};
+/**
+ * Duration constants in minutes.
+ */
+export const DURATIONS_MINUTES = {
+    /** One hour in minutes */
+    HOUR: 60,
+    /** One day in minutes */
+    DAY: 24 * 60,
+    /** One week in minutes */
+    WEEK: 7 * 24 * 60,
+};
+/**
+ * Date format strings for use with date-fns.
+ */
+export const DATE_FORMATS = {
+    /** API format: UTC ISO string */
+    API: "yyyy-MM-dd'T'HH:mm:ss'Z'",
+    /** Date for API without time */
+    API_DATE: 'yyyy-MM-dd',
+    /** Display date (e.g., "Dec 20, 2025") */
+    DISPLAY_DATE: 'MMM d, yyyy',
+    /** Display date without year (e.g., "Dec 20") */
+    DISPLAY_DATE_SHORT: 'MMM d',
+    /** Display time (e.g., "7:00 PM") */
+    DISPLAY_TIME: 'h:mm a',
+    /** Display time with seconds (e.g., "7:00:00 PM") */
+    DISPLAY_TIME_SECONDS: 'h:mm:ss a',
+    /** Display datetime (e.g., "Dec 20, 2025 at 7:00 PM") */
+    DISPLAY_DATETIME: "MMM d, yyyy 'at' h:mm a",
+    /** Display full datetime with day (e.g., "Mon, Dec 20, 2025 at 7:00 PM") */
+    DISPLAY_DATETIME_FULL: "EEE, MMM d, yyyy 'at' h:mm a",
+    /** Day of week short (e.g., "Mon") */
+    DAY_SHORT: 'EEE',
+    /** Day of week full (e.g., "Monday") */
+    DAY_FULL: 'EEEE',
+    /** Month short (e.g., "Dec") */
+    MONTH_SHORT: 'MMM',
+    /** Month full (e.g., "December") */
+    MONTH_FULL: 'MMMM',
+    /** Year only (e.g., "2025") */
+    YEAR: 'yyyy',
+    /** 24-hour time (e.g., "19:00") */
+    TIME_24H: 'HH:mm',
+};
+/**
+ * Commonly used US timezones for quick selection.
+ */
+export const COMMON_US_TIMEZONES = [
+    { id: 'America/Los_Angeles', label: 'Pacific Time (PT)', abbr: 'PT' },
+    { id: 'America/Denver', label: 'Mountain Time (MT)', abbr: 'MT' },
+    { id: 'America/Chicago', label: 'Central Time (CT)', abbr: 'CT' },
+    { id: 'America/New_York', label: 'Eastern Time (ET)', abbr: 'ET' },
+    { id: 'America/Phoenix', label: 'Arizona (no DST)', abbr: 'AZ' },
+    { id: 'Pacific/Honolulu', label: 'Hawaii Time (HT)', abbr: 'HT' },
+    { id: 'America/Anchorage', label: 'Alaska Time (AKT)', abbr: 'AKT' },
+];
+/**
+ * Default timezone when none is specified (should rarely be used).
+ * Prefer explicitly passing timezone in all operations.
+ */
+export const DEFAULT_TIMEZONE = 'America/Los_Angeles';
+/**
+ * Relative time thresholds for formatRelativeTime.
+ */
+export const RELATIVE_TIME_THRESHOLDS = {
+    /** Under this many seconds, show "just now" */
+    JUST_NOW_SECONDS: 60,
+    /** Under this many minutes, show "X minutes ago/from now" */
+    MINUTES_THRESHOLD: 60,
+    /** Under this many hours, show "X hours ago/from now" */
+    HOURS_THRESHOLD: 24,
+    /** Under this many days, show "X days ago/from now" */
+    DAYS_THRESHOLD: 7,
+    /** Under this many weeks, show "X weeks ago/from now" */
+    WEEKS_THRESHOLD: 4,
+};
+/**
+ * MicDrop-specific event defaults.
+ */
+export const EVENT_DEFAULTS = {
+    /** Default event duration in minutes */
+    DEFAULT_DURATION_MINUTES: 120,
+    /** Minimum event duration in minutes */
+    MIN_DURATION_MINUTES: 15,
+    /** Maximum event duration in minutes (24 hours) */
+    MAX_DURATION_MINUTES: 24 * 60,
+    /** Default doors open time before event start (minutes) */
+    DEFAULT_DOORS_BEFORE_MINUTES: 30,
+};

package/dist/datetime/format.d.ts

@@ -0,0 +1,158 @@
+/**
+ * DateTime Formatting Functions
+ *
+ * All formatting functions require an explicit timezone parameter.
+ * No defaults - timezone must always be provided.
+ *
+ * @module datetime/format
+ */
+import type { DateParts, FormatOptions, ISODateString, TimezoneId } from './types';
+/**
+ * Formats a UTC datetime as a time string in the specified timezone.
+ *
+ * @param utcIso - UTC ISO datetime string
+ * @param timezone - IANA timezone ID
+ * @param options - Optional formatting options
+ * @returns Formatted time (e.g., "7:00 PM")
+ * @throws {DateTimeError} If timezone or ISO string is invalid
+ *
+ * @example
+ * formatEventTime('2023-12-25T03:00:00Z', 'America/Los_Angeles')
+ * // "7:00 PM" (Dec 24 in LA)
+ */
+export declare function formatEventTime(utcIso: ISODateString, timezone: TimezoneId, options?: FormatOptions): string;
+/**
+ * Formats a UTC datetime as a date string in the specified timezone.
+ *
+ * @param utcIso - UTC ISO datetime string
+ * @param timezone - IANA timezone ID
+ * @param options - Optional formatting options
+ * @returns Formatted date (e.g., "Dec 20, 2025")
+ * @throws {DateTimeError} If timezone or ISO string is invalid
+ *
+ * @example
+ * formatEventDate('2023-12-25T03:00:00Z', 'America/Los_Angeles')
+ * // "Dec 24, 2023" (still Dec 24 in LA at 7 PM)
+ */
+export declare function formatEventDate(utcIso: ISODateString, timezone: TimezoneId, options?: FormatOptions): string;
+/**
+ * Formats a UTC datetime as a full datetime string in the specified timezone.
+ *
+ * @param utcIso - UTC ISO datetime string
+ * @param timezone - IANA timezone ID
+ * @param options - Optional formatting options
+ * @returns Formatted datetime (e.g., "Dec 20, 2025 at 7:00 PM")
+ * @throws {DateTimeError} If timezone or ISO string is invalid
+ *
+ * @example
+ * formatEventDateTime('2023-12-26T03:00:00Z', 'America/Los_Angeles')
+ * // "Dec 25, 2023 at 7:00 PM"
+ */
+export declare function formatEventDateTime(utcIso: ISODateString, timezone: TimezoneId, options?: FormatOptions): string;
+/**
+ * Formats a time range in the specified timezone.
+ *
+ * @param startUtc - Start time as UTC ISO string
+ * @param endUtc - End time as UTC ISO string
+ * @param timezone - IANA timezone ID
+ * @returns Formatted time range (e.g., "7:00 PM - 10:00 PM")
+ * @throws {DateTimeError} If timezone or ISO strings are invalid
+ *
+ * @example
+ * formatTimeRange(
+ *   '2023-12-25T03:00:00Z',
+ *   '2023-12-25T06:00:00Z',
+ *   'America/Los_Angeles'
+ * )
+ * // "7:00 PM - 10:00 PM"
+ */
+export declare function formatTimeRange(startUtc: ISODateString, endUtc: ISODateString, timezone: TimezoneId): string;
+/**
+ * Formats a date range in the specified timezone.
+ * Handles same-day, same-month, and cross-month/year ranges intelligently.
+ *
+ * @param startUtc - Start date as UTC ISO string
+ * @param endUtc - End date as UTC ISO string
+ * @param timezone - IANA timezone ID
+ * @returns Formatted date range (e.g., "Dec 20 - 22, 2025" or "Dec 20 - Jan 5, 2026")
+ * @throws {DateTimeError} If timezone or ISO strings are invalid
+ *
+ * @example
+ * formatDateRange(
+ *   '2023-12-20T08:00:00Z',
+ *   '2023-12-22T08:00:00Z',
+ *   'America/Los_Angeles'
+ * )
+ * // "Dec 20 - 22, 2023"
+ */
+export declare function formatDateRange(startUtc: ISODateString, endUtc: ISODateString, timezone: TimezoneId): string;
+/**
+ * Formats a datetime as a relative time string (e.g., "2 hours ago", "in 3 days").
+ *
+ * @param utcIso - UTC ISO datetime string
+ * @param timezone - IANA timezone ID (used for consistency, though relative time is timezone-agnostic)
+ * @returns Relative time string
+ * @throws {DateTimeError} If timezone or ISO string is invalid
+ *
+ * @example
+ * formatRelativeTime(new Date(Date.now() - 30 * 60 * 1000).toISOString(), 'America/Los_Angeles')
+ * // "30 minutes ago"
+ */
+export declare function formatRelativeTime(utcIso: ISODateString, timezone: TimezoneId): string;
+/**
+ * Extracts date parts from a UTC datetime in the specified timezone.
+ *
+ * @param utcIso - UTC ISO datetime string
+ * @param timezone - IANA timezone ID
+ * @returns Object with day, month, date, and year
+ * @throws {DateTimeError} If timezone or ISO string is invalid
+ *
+ * @example
+ * getDateParts('2023-12-25T20:00:00Z', 'America/Los_Angeles')
+ * // { day: 'Mon', month: 'Dec', date: 25, year: 2023 }
+ */
+export declare function getDateParts(utcIso: ISODateString, timezone: TimezoneId): DateParts;
+/**
+ * Formats a datetime for display in notifications.
+ * Shows relative time for recent events, date for older ones.
+ *
+ * @param utcIso - UTC ISO datetime string
+ * @param timezone - IANA timezone ID
+ * @returns Formatted string suitable for notifications
+ */
+export declare function formatNotificationTime(utcIso: ISODateString, timezone: TimezoneId): string;
+/**
+ * Formats the day of week from a UTC datetime.
+ *
+ * @param utcIso - UTC ISO datetime string
+ * @param timezone - IANA timezone ID
+ * @param short - If true, returns short form (e.g., "Mon"), otherwise full (e.g., "Monday")
+ * @returns Day of week string
+ */
+export declare function formatDayOfWeek(utcIso: ISODateString, timezone: TimezoneId, short?: boolean): string;
+/**
+ * Formats the month from a UTC datetime.
+ *
+ * @param utcIso - UTC ISO datetime string
+ * @param timezone - IANA timezone ID
+ * @param short - If true, returns short form (e.g., "Dec"), otherwise full (e.g., "December")
+ * @returns Month string
+ */
+export declare function formatMonth(utcIso: ISODateString, timezone: TimezoneId, short?: boolean): string;
+/**
+ * Gets the hour in the specified timezone (0-23).
+ *
+ * @param utcIso - UTC ISO datetime string
+ * @param timezone - IANA timezone ID
+ * @returns Hour (0-23)
+ */
+export declare function getHourInTimezone(utcIso: ISODateString, timezone: TimezoneId): number;
+/**
+ * Gets the date string (YYYY-MM-DD) in the specified timezone.
+ *
+ * @param utcIso - UTC ISO datetime string
+ * @param timezone - IANA timezone ID
+ * @returns Date string in YYYY-MM-DD format
+ */
+export declare function getDateInTimezone(utcIso: ISODateString, timezone: TimezoneId): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/datetime/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/lib/datetime/format.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,OAAO,KAAK,EACV,SAAS,EACT,aAAa,EACb,aAAa,EACb,UAAU,EACX,MAAM,SAAS,CAAC;AA4CjB;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,UAAU,EACpB,OAAO,CAAC,EAAE,aAAa,GACtB,MAAM,CAMR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,UAAU,EACpB,OAAO,CAAC,EAAE,aAAa,GACtB,MAAM,CAOR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,UAAU,EACpB,OAAO,CAAC,EAAE,aAAa,GACtB,MAAM,CAiBR;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,UAAU,GACnB,MAAM,CAIR;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,UAAU,GACnB,MAAM,CA4BR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,UAAU,GACnB,MAAM,CAoDR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,UAAU,GACnB,SAAS,CASX;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,UAAU,GACnB,MAAM,CAkBR;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,UAAU,EACpB,KAAK,GAAE,OAAc,GACpB,MAAM,CAMR;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,UAAU,EACpB,KAAK,GAAE,OAAc,GACpB,MAAM,CAMR;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,UAAU,GACnB,MAAM,CAGR;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,UAAU,GACnB,MAAM,CAGR"}

package/dist/datetime/format.js

@@ -0,0 +1,315 @@
+/**
+ * DateTime Formatting Functions
+ *
+ * All formatting functions require an explicit timezone parameter.
+ * No defaults - timezone must always be provided.
+ *
+ * @module datetime/format
+ */
+import { format } from 'date-fns';
+import { toZonedTime } from 'date-fns-tz';
+import { DATE_FORMATS, DURATIONS, RELATIVE_TIME_THRESHOLDS } from './constants';
+import { isValidTimezone } from './timezone';
+import { DateTimeError, DateTimeErrorCode } from './types';
+/**
+ * Validates an ISO date string and returns a Date object.
+ * @internal
+ */
+function parseAndValidateISO(utcIso) {
+    if (!utcIso || typeof utcIso !== 'string') {
+        throw new DateTimeError('ISO date string is required', DateTimeErrorCode.INVALID_ISO_STRING, { value: utcIso });
+    }
+    const date = new Date(utcIso);
+    if (isNaN(date.getTime())) {
+        throw new DateTimeError(`Invalid ISO date string: ${utcIso}`, DateTimeErrorCode.INVALID_ISO_STRING, { value: utcIso });
+    }
+    return date;
+}
+/**
+ * Validates timezone and returns zoned date.
+ * @internal
+ */
+function getZonedDate(utcIso, timezone) {
+    if (!isValidTimezone(timezone)) {
+        throw new DateTimeError(`Invalid timezone: ${timezone}`, DateTimeErrorCode.INVALID_TIMEZONE, { timezone });
+    }
+    const date = parseAndValidateISO(utcIso);
+    return toZonedTime(date, timezone);
+}
+/**
+ * Formats a UTC datetime as a time string in the specified timezone.
+ *
+ * @param utcIso - UTC ISO datetime string
+ * @param timezone - IANA timezone ID
+ * @param options - Optional formatting options
+ * @returns Formatted time (e.g., "7:00 PM")
+ * @throws {DateTimeError} If timezone or ISO string is invalid
+ *
+ * @example
+ * formatEventTime('2023-12-25T03:00:00Z', 'America/Los_Angeles')
+ * // "7:00 PM" (Dec 24 in LA)
+ */
+export function formatEventTime(utcIso, timezone, options) {
+    const zonedDate = getZonedDate(utcIso, timezone);
+    const formatStr = options?.includeSeconds
+        ? DATE_FORMATS.DISPLAY_TIME_SECONDS
+        : DATE_FORMATS.DISPLAY_TIME;
+    return format(zonedDate, formatStr);
+}
+/**
+ * Formats a UTC datetime as a date string in the specified timezone.
+ *
+ * @param utcIso - UTC ISO datetime string
+ * @param timezone - IANA timezone ID
+ * @param options - Optional formatting options
+ * @returns Formatted date (e.g., "Dec 20, 2025")
+ * @throws {DateTimeError} If timezone or ISO string is invalid
+ *
+ * @example
+ * formatEventDate('2023-12-25T03:00:00Z', 'America/Los_Angeles')
+ * // "Dec 24, 2023" (still Dec 24 in LA at 7 PM)
+ */
+export function formatEventDate(utcIso, timezone, options) {
+    const zonedDate = getZonedDate(utcIso, timezone);
+    const formatStr = options?.includeYear === false
+        ? DATE_FORMATS.DISPLAY_DATE_SHORT
+        : DATE_FORMATS.DISPLAY_DATE;
+    return format(zonedDate, formatStr);
+}
+/**
+ * Formats a UTC datetime as a full datetime string in the specified timezone.
+ *
+ * @param utcIso - UTC ISO datetime string
+ * @param timezone - IANA timezone ID
+ * @param options - Optional formatting options
+ * @returns Formatted datetime (e.g., "Dec 20, 2025 at 7:00 PM")
+ * @throws {DateTimeError} If timezone or ISO string is invalid
+ *
+ * @example
+ * formatEventDateTime('2023-12-26T03:00:00Z', 'America/Los_Angeles')
+ * // "Dec 25, 2023 at 7:00 PM"
+ */
+export function formatEventDateTime(utcIso, timezone, options) {
+    const zonedDate = getZonedDate(utcIso, timezone);
+    // Respect includeDate/includeTime options
+    const includeDate = options?.includeDate !== false;
+    const includeTime = options?.includeTime !== false;
+    if (includeDate && includeTime) {
+        return format(zonedDate, DATE_FORMATS.DISPLAY_DATETIME);
+    }
+    else if (includeDate && !includeTime) {
+        return format(zonedDate, DATE_FORMATS.DISPLAY_DATE);
+    }
+    else if (!includeDate && includeTime) {
+        return format(zonedDate, DATE_FORMATS.DISPLAY_TIME);
+    }
+    // Fallback to full datetime
+    return format(zonedDate, DATE_FORMATS.DISPLAY_DATETIME);
+}
+/**
+ * Formats a time range in the specified timezone.
+ *
+ * @param startUtc - Start time as UTC ISO string
+ * @param endUtc - End time as UTC ISO string
+ * @param timezone - IANA timezone ID
+ * @returns Formatted time range (e.g., "7:00 PM - 10:00 PM")
+ * @throws {DateTimeError} If timezone or ISO strings are invalid
+ *
+ * @example
+ * formatTimeRange(
+ *   '2023-12-25T03:00:00Z',
+ *   '2023-12-25T06:00:00Z',
+ *   'America/Los_Angeles'
+ * )
+ * // "7:00 PM - 10:00 PM"
+ */
+export function formatTimeRange(startUtc, endUtc, timezone) {
+    const startTime = formatEventTime(startUtc, timezone);
+    const endTime = formatEventTime(endUtc, timezone);
+    return `${startTime} - ${endTime}`;
+}
+/**
+ * Formats a date range in the specified timezone.
+ * Handles same-day, same-month, and cross-month/year ranges intelligently.
+ *
+ * @param startUtc - Start date as UTC ISO string
+ * @param endUtc - End date as UTC ISO string
+ * @param timezone - IANA timezone ID
+ * @returns Formatted date range (e.g., "Dec 20 - 22, 2025" or "Dec 20 - Jan 5, 2026")
+ * @throws {DateTimeError} If timezone or ISO strings are invalid
+ *
+ * @example
+ * formatDateRange(
+ *   '2023-12-20T08:00:00Z',
+ *   '2023-12-22T08:00:00Z',
+ *   'America/Los_Angeles'
+ * )
+ * // "Dec 20 - 22, 2023"
+ */
+export function formatDateRange(startUtc, endUtc, timezone) {
+    const startZoned = getZonedDate(startUtc, timezone);
+    const endZoned = getZonedDate(endUtc, timezone);
+    const startYear = startZoned.getFullYear();
+    const endYear = endZoned.getFullYear();
+    const startMonth = startZoned.getMonth();
+    const endMonth = endZoned.getMonth();
+    const startDay = startZoned.getDate();
+    const endDay = endZoned.getDate();
+    // Same day
+    if (startYear === endYear && startMonth === endMonth && startDay === endDay) {
+        return format(startZoned, DATE_FORMATS.DISPLAY_DATE);
+    }
+    // Same month and year
+    if (startYear === endYear && startMonth === endMonth) {
+        return `${format(startZoned, 'MMM d')} - ${endDay}, ${startYear}`;
+    }
+    // Same year, different months
+    if (startYear === endYear) {
+        return `${format(startZoned, 'MMM d')} - ${format(endZoned, 'MMM d')}, ${startYear}`;
+    }
+    // Different years
+    return `${format(startZoned, DATE_FORMATS.DISPLAY_DATE)} - ${format(endZoned, DATE_FORMATS.DISPLAY_DATE)}`;
+}
+/**
+ * Formats a datetime as a relative time string (e.g., "2 hours ago", "in 3 days").
+ *
+ * @param utcIso - UTC ISO datetime string
+ * @param timezone - IANA timezone ID (used for consistency, though relative time is timezone-agnostic)
+ * @returns Relative time string
+ * @throws {DateTimeError} If timezone or ISO string is invalid
+ *
+ * @example
+ * formatRelativeTime(new Date(Date.now() - 30 * 60 * 1000).toISOString(), 'America/Los_Angeles')
+ * // "30 minutes ago"
+ */
+export function formatRelativeTime(utcIso, timezone) {
+    // Validate inputs
+    if (!isValidTimezone(timezone)) {
+        throw new DateTimeError(`Invalid timezone: ${timezone}`, DateTimeErrorCode.INVALID_TIMEZONE, { timezone });
+    }
+    const date = parseAndValidateISO(utcIso);
+    const now = new Date();
+    const diffMs = date.getTime() - now.getTime();
+    const absDiffMs = Math.abs(diffMs);
+    const isPast = diffMs < 0;
+    const seconds = Math.floor(absDiffMs / DURATIONS.SECOND);
+    const minutes = Math.floor(absDiffMs / DURATIONS.MINUTE);
+    const hours = Math.floor(absDiffMs / DURATIONS.HOUR);
+    const days = Math.floor(absDiffMs / DURATIONS.DAY);
+    const weeks = Math.floor(absDiffMs / DURATIONS.WEEK);
+    const formatUnit = (value, unit) => {
+        const plural = value === 1 ? '' : 's';
+        if (isPast) {
+            return `${value} ${unit}${plural} ago`;
+        }
+        return `in ${value} ${unit}${plural}`;
+    };
+    if (seconds < RELATIVE_TIME_THRESHOLDS.JUST_NOW_SECONDS) {
+        return 'just now';
+    }
+    if (minutes < RELATIVE_TIME_THRESHOLDS.MINUTES_THRESHOLD) {
+        return formatUnit(minutes, 'minute');
+    }
+    if (hours < RELATIVE_TIME_THRESHOLDS.HOURS_THRESHOLD) {
+        return formatUnit(hours, 'hour');
+    }
+    if (days < RELATIVE_TIME_THRESHOLDS.DAYS_THRESHOLD) {
+        return formatUnit(days, 'day');
+    }
+    if (weeks < RELATIVE_TIME_THRESHOLDS.WEEKS_THRESHOLD) {
+        return formatUnit(weeks, 'week');
+    }
+    // For older dates, show the actual date
+    return formatEventDate(utcIso, timezone);
+}
+/**
+ * Extracts date parts from a UTC datetime in the specified timezone.
+ *
+ * @param utcIso - UTC ISO datetime string
+ * @param timezone - IANA timezone ID
+ * @returns Object with day, month, date, and year
+ * @throws {DateTimeError} If timezone or ISO string is invalid
+ *
+ * @example
+ * getDateParts('2023-12-25T20:00:00Z', 'America/Los_Angeles')
+ * // { day: 'Mon', month: 'Dec', date: 25, year: 2023 }
+ */
+export function getDateParts(utcIso, timezone) {
+    const zonedDate = getZonedDate(utcIso, timezone);
+    return {
+        day: format(zonedDate, DATE_FORMATS.DAY_SHORT),
+        month: format(zonedDate, DATE_FORMATS.MONTH_SHORT),
+        date: zonedDate.getDate(),
+        year: zonedDate.getFullYear(),
+    };
+}
+/**
+ * Formats a datetime for display in notifications.
+ * Shows relative time for recent events, date for older ones.
+ *
+ * @param utcIso - UTC ISO datetime string
+ * @param timezone - IANA timezone ID
+ * @returns Formatted string suitable for notifications
+ */
+export function formatNotificationTime(utcIso, timezone) {
+    const date = parseAndValidateISO(utcIso);
+    const now = new Date();
+    const diffMs = now.getTime() - date.getTime();
+    // Less than 24 hours ago
+    if (diffMs < DURATIONS.DAY) {
+        return formatRelativeTime(utcIso, timezone);
+    }
+    // Less than 7 days ago
+    if (diffMs < DURATIONS.WEEK) {
+        const zonedDate = getZonedDate(utcIso, timezone);
+        return format(zonedDate, "EEEE 'at' h:mm a");
+    }
+    // Older - show full date
+    return formatEventDateTime(utcIso, timezone);
+}
+/**
+ * Formats the day of week from a UTC datetime.
+ *
+ * @param utcIso - UTC ISO datetime string
+ * @param timezone - IANA timezone ID
+ * @param short - If true, returns short form (e.g., "Mon"), otherwise full (e.g., "Monday")
+ * @returns Day of week string
+ */
+export function formatDayOfWeek(utcIso, timezone, short = true) {
+    const zonedDate = getZonedDate(utcIso, timezone);
+    return format(zonedDate, short ? DATE_FORMATS.DAY_SHORT : DATE_FORMATS.DAY_FULL);
+}
+/**
+ * Formats the month from a UTC datetime.
+ *
+ * @param utcIso - UTC ISO datetime string
+ * @param timezone - IANA timezone ID
+ * @param short - If true, returns short form (e.g., "Dec"), otherwise full (e.g., "December")
+ * @returns Month string
+ */
+export function formatMonth(utcIso, timezone, short = true) {
+    const zonedDate = getZonedDate(utcIso, timezone);
+    return format(zonedDate, short ? DATE_FORMATS.MONTH_SHORT : DATE_FORMATS.MONTH_FULL);
+}
+/**
+ * Gets the hour in the specified timezone (0-23).
+ *
+ * @param utcIso - UTC ISO datetime string
+ * @param timezone - IANA timezone ID
+ * @returns Hour (0-23)
+ */
+export function getHourInTimezone(utcIso, timezone) {
+    const zonedDate = getZonedDate(utcIso, timezone);
+    return zonedDate.getHours();
+}
+/**
+ * Gets the date string (YYYY-MM-DD) in the specified timezone.
+ *
+ * @param utcIso - UTC ISO datetime string
+ * @param timezone - IANA timezone ID
+ * @returns Date string in YYYY-MM-DD format
+ */
+export function getDateInTimezone(utcIso, timezone) {
+    const zonedDate = getZonedDate(utcIso, timezone);
+    return format(zonedDate, DATE_FORMATS.API_DATE);
+}

package/dist/datetime/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * DateTime Module
+ *
+ * Centralized date/time handling for the MicDrop platform.
+ * All datetime operations should use this module to ensure consistent
+ * timezone handling across the application.
+ *
+ * ## Golden Rules
+ *
+ * 1. **Backend is King** - All API requests send/receive UTC ISO strings
+ * 2. **Display is Local** - All UI components receive UTC + Timezone ID
+ * 3. **No `new Date()` in components** - Use these helpers instead
+ * 4. **Timezone is always required** - Every function requires explicit timezone
+ *
+ * ## Usage Examples
+ *
+ * ```typescript
+ * import * as datetime from './';
+ *
+ * // Get venue timezone
+ * const tz = datetime.getVenueTimezone(venue);
+ *
+ * // Format for display
+ * const time = datetime.formatEventTime(event.startTime, tz);
+ * const date = datetime.formatEventDate(event.startTime, tz);
+ *
+ * // Parse form input to UTC for API
+ * const utc = datetime.combineDateAndTime('2023-12-25', '19:00', tz);
+ *
+ * // Parse API response for form
+ * const { date, time } = datetime.parseDateTimeFromAPI(event.startTime, tz);
+ * ```
+ *
+ * @module datetime
+ */
+export type { DateParts, FormatOptions, FormattedTimeRange, ISODateString, LocalDateString, LocalDateTimeString, LocalTimeString, TimeRange, TimezoneId, VenueWithTimezone, } from './types';
+export { DateTimeError, DateTimeErrorCode } from './types';
+export { COMMON_US_TIMEZONES, DATE_FORMATS, DEFAULT_TIMEZONE, DURATIONS, DURATIONS_MINUTES, EVENT_DEFAULTS, RELATIVE_TIME_THRESHOLDS, } from './constants';
+export { getTimezoneDisplayName, getTimezoneOffset, getUserTimezone, getVenueTimezone, isDST, isValidTimezone, normalizeTimezone, } from './timezone';
+export { formatDateRange, formatDayOfWeek, formatEventDate, formatEventDateTime, formatEventTime, formatMonth, formatNotificationTime, formatRelativeTime, formatTimeRange, getDateInTimezone, getDateParts, getHourInTimezone, } from './format';
+export { combineDateAndTime, formatDateTimeForAPI, isNextDayTime, minutesToTimeString, parseDateTimeFromAPI, parseEndOfDay, parseLocalToUTC, parseStartOfDay, parseTimeToMinutes, parseUTCToLocal, stripNextDayPrefix, } from './parse';
+//# sourceMappingURL=index.d.ts.map

package/dist/datetime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/datetime/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,YAAY,EACV,SAAS,EACT,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,SAAS,EACT,UAAU,EACV,iBAAiB,GAClB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAG3D,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,EAChB,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,KAAK,EACL,eAAe,EACf,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,eAAe,EACf,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,WAAW,EACX,sBAAsB,EACtB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,kBAAkB,GACnB,MAAM,SAAS,CAAC"}

package/dist/datetime/index.js

@@ -0,0 +1,44 @@
+/**
+ * DateTime Module
+ *
+ * Centralized date/time handling for the MicDrop platform.
+ * All datetime operations should use this module to ensure consistent
+ * timezone handling across the application.
+ *
+ * ## Golden Rules
+ *
+ * 1. **Backend is King** - All API requests send/receive UTC ISO strings
+ * 2. **Display is Local** - All UI components receive UTC + Timezone ID
+ * 3. **No `new Date()` in components** - Use these helpers instead
+ * 4. **Timezone is always required** - Every function requires explicit timezone
+ *
+ * ## Usage Examples
+ *
+ * ```typescript
+ * import * as datetime from './';
+ *
+ * // Get venue timezone
+ * const tz = datetime.getVenueTimezone(venue);
+ *
+ * // Format for display
+ * const time = datetime.formatEventTime(event.startTime, tz);
+ * const date = datetime.formatEventDate(event.startTime, tz);
+ *
+ * // Parse form input to UTC for API
+ * const utc = datetime.combineDateAndTime('2023-12-25', '19:00', tz);
+ *
+ * // Parse API response for form
+ * const { date, time } = datetime.parseDateTimeFromAPI(event.startTime, tz);
+ * ```
+ *
+ * @module datetime
+ */
+export { DateTimeError, DateTimeErrorCode } from './types';
+// Constants
+export { COMMON_US_TIMEZONES, DATE_FORMATS, DEFAULT_TIMEZONE, DURATIONS, DURATIONS_MINUTES, EVENT_DEFAULTS, RELATIVE_TIME_THRESHOLDS, } from './constants';
+// Timezone utilities
+export { getTimezoneDisplayName, getTimezoneOffset, getUserTimezone, getVenueTimezone, isDST, isValidTimezone, normalizeTimezone, } from './timezone';
+// Format functions
+export { formatDateRange, formatDayOfWeek, formatEventDate, formatEventDateTime, formatEventTime, formatMonth, formatNotificationTime, formatRelativeTime, formatTimeRange, getDateInTimezone, getDateParts, getHourInTimezone, } from './format';
+// Parse functions
+export { combineDateAndTime, formatDateTimeForAPI, isNextDayTime, minutesToTimeString, parseDateTimeFromAPI, parseEndOfDay, parseLocalToUTC, parseStartOfDay, parseTimeToMinutes, parseUTCToLocal, stripNextDayPrefix, } from './parse';