@getmicdrop/svelte-components 5.19.0 → 5.20.0

package/dist/datetime/README.md

@@ -1,323 +1,323 @@
-# DateTime Module
-
-Centralized date/time handling for the MicDrop platform. This module eliminates timezone bugs by enforcing consistent patterns across the application.
-
-## Golden Rules
-
-1. **Backend is King** - All API requests send/receive UTC ISO strings (`2023-12-25T20:00:00Z`)
-2. **Display is Local** - All UI components receive UTC strings + Timezone ID
-3. **No `new Date()` in components** - Use these helpers instead
-4. **Timezone is always required** - Every function requires explicit timezone parameter
-
-## Quick Start
-
-```typescript
-import * as datetime from '$lib/datetime';
-
-// Get timezone from venue (throws if missing)
-const tz = datetime.getVenueTimezone(venue);
-
-// Format for display
-const time = datetime.formatEventTime(event.startTime, tz); // "7:00 PM"
-const date = datetime.formatEventDate(event.startTime, tz); // "Dec 25, 2023"
-const full = datetime.formatEventDateTime(event.startTime, tz); // "Dec 25, 2023 at 7:00 PM"
-
-// 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 Structure
-
-```
-src/lib/datetime/
-├── index.ts           # Clean exports
-├── types.ts           # Type definitions
-├── constants.ts       # Duration constants, format strings
-├── timezone.ts        # Timezone utilities
-├── format.ts          # Formatting functions
-├── parse.ts           # Parsing functions
-├── __tests__/         # Comprehensive tests
-│   ├── timezone.test.ts
-│   ├── format.test.ts
-│   ├── parse.test.ts
-│   └── integration.test.ts
-└── README.md          # This file
-```
-
-## API Reference
-
-### Timezone Utilities
-
-```typescript
-// Validate timezone
-isValidTimezone('America/Los_Angeles'); // true
-isValidTimezone('PST'); // false (abbreviations not valid)
-
-// Get venue timezone (throws if missing)
-const tz = getVenueTimezone(venue);
-
-// Get user's browser timezone
-const userTz = getUserTimezone();
-
-// Get timezone offset string
-getTimezoneOffset('America/Los_Angeles'); // "PST (UTC-8)"
-
-// Normalize legacy timezone abbreviations
-normalizeTimezone('PST'); // "America/Los_Angeles"
-
-// Check if DST is active
-isDST('America/Los_Angeles', new Date()); // true/false
-```
-
-### Format Functions
-
-All format functions require timezone - no defaults!
-
-```typescript
-// Time only
-formatEventTime('2023-12-26T03:00:00Z', 'America/Los_Angeles');
-// "7:00 PM"
-
-// Date only
-formatEventDate('2023-12-26T03:00:00Z', 'America/Los_Angeles');
-// "Dec 25, 2023"
-
-// Full datetime
-formatEventDateTime('2023-12-26T03:00:00Z', 'America/Los_Angeles');
-// "Dec 25, 2023 at 7:00 PM"
-
-// Time range
-formatTimeRange(startUtc, endUtc, 'America/Los_Angeles');
-// "7:00 PM - 10:00 PM"
-
-// Date range
-formatDateRange(startUtc, endUtc, 'America/Los_Angeles');
-// "Dec 25 - 27, 2023"
-
-// Relative time
-formatRelativeTime(utcIso, 'America/Los_Angeles');
-// "2 hours ago" or "in 3 days"
-
-// Date parts
-getDateParts('2023-12-25T20:00:00Z', 'America/Los_Angeles');
-// { day: 'Mon', month: 'Dec', date: 25, year: 2023 }
-
-// Get hour (0-23)
-getHourInTimezone('2023-12-25T20:00:00Z', 'America/Los_Angeles');
-// 12
-
-// Get date string
-getDateInTimezone('2023-12-25T20:00:00Z', 'America/Los_Angeles');
-// "2023-12-25"
-```
-
-### Parse Functions
-
-```typescript
-// Local datetime to UTC
-parseLocalToUTC('2023-12-25T19:00:00', 'America/Los_Angeles');
-// "2023-12-26T03:00:00.000Z"
-
-// UTC to local datetime
-parseUTCToLocal('2023-12-26T03:00:00Z', 'America/Los_Angeles');
-// "2023-12-25T19:00:00"
-
-// Combine date and time
-combineDateAndTime('2023-12-25', '19:00', 'America/Los_Angeles');
-// "2023-12-26T03:00:00.000Z"
-
-// Parse API response for form
-parseDateTimeFromAPI('2023-12-26T03:00:00Z', 'America/Los_Angeles');
-// { date: '2023-12-25', time: '19:00' }
-
-// Start of day in UTC
-parseStartOfDay('2023-12-25', 'America/Los_Angeles');
-// "2023-12-25T08:00:00.000Z"
-
-// End of day in UTC
-parseEndOfDay('2023-12-25', 'America/Los_Angeles');
-// "2023-12-26T07:59:59.000Z"
-```
-
-### Next-Day Time Handling
-
-For overnight events (e.g., 10 PM - 2 AM):
-
-```typescript
-// Check for next-day prefix
-isNextDayTime('+1_02:00'); // true
-isNextDayTime('14:00'); // false
-
-// Strip prefix
-stripNextDayPrefix('+1_02:00'); // '02:00'
-
-// Convert to minutes
-parseTimeToMinutes('22:00'); // 1320
-parseTimeToMinutes('+1_02:00'); // 1560 (26 hours)
-
-// Convert back
-minutesToTimeString(1320); // '22:00'
-minutesToTimeString(1560, true); // '+1_02:00'
-```
-
-### Constants
-
-```typescript
-import {
-  DURATIONS,
-  DATE_FORMATS,
-  EVENT_DEFAULTS,
-  COMMON_US_TIMEZONES,
-} from '$lib/datetime';
-
-// Durations in milliseconds
-DURATIONS.MINUTE; // 60000
-DURATIONS.HOUR; // 3600000
-DURATIONS.DAY; // 86400000
-
-// Event defaults
-EVENT_DEFAULTS.DEFAULT_DURATION_MINUTES; // 120
-EVENT_DEFAULTS.MIN_DURATION_MINUTES; // 15
-EVENT_DEFAULTS.DEFAULT_DOORS_BEFORE_MINUTES; // 30
-
-// Common US timezones for selects
-COMMON_US_TIMEZONES;
-// [{ id: 'America/Los_Angeles', label: 'Pacific Time (PT)', abbr: 'PT' }, ...]
-```
-
-## Common Patterns
-
-### Event Form
-
-```typescript
-// Populating form from API response
-function populateForm(event: Event) {
-  const tz = datetime.getVenueTimezone(event.venue);
-  const start = datetime.parseDateTimeFromAPI(event.startTime, tz);
-  const end = datetime.parseDateTimeFromAPI(event.endTime, tz);
-
-  return {
-    date: start.date,
-    startTime: start.time,
-    endTime: end.time,
-  };
-}
-
-// Submitting form to API
-function submitForm(form: FormData, venue: Venue) {
-  const tz = datetime.getVenueTimezone(venue);
-
-  return {
-    startTime: datetime.combineDateAndTime(form.date, form.startTime, tz),
-    endTime: datetime.combineDateAndTime(form.date, form.endTime, tz),
-  };
-}
-```
-
-### Calendar Display
-
-```typescript
-// Display events in venue timezone
-function renderEvent(event: Event, venue: Venue) {
-  const tz = datetime.getVenueTimezone(venue);
-
-  return {
-    time: datetime.formatEventTime(event.startTime, tz),
-    date: datetime.formatEventDate(event.startTime, tz),
-    dateRange: datetime.formatTimeRange(event.startTime, event.endTime, tz),
-    dateParts: datetime.getDateParts(event.startTime, tz),
-  };
-}
-```
-
-### Grouping Events by Date
-
-```typescript
-function groupByDate(events: Event[], timezone: TimezoneId) {
-  const groups: Record<string, Event[]> = {};
-
-  for (const event of events) {
-    const dateKey = datetime.getDateInTimezone(event.startTime, timezone);
-    groups[dateKey] = groups[dateKey] || [];
-    groups[dateKey].push(event);
-  }
-
-  return groups;
-}
-```
-
-## Error Handling
-
-All functions throw `DateTimeError` for invalid inputs:
-
-```typescript
-import { DateTimeError, DateTimeErrorCode } from '$lib/datetime';
-
-try {
-  const tz = datetime.getVenueTimezone(venue);
-} catch (e) {
-  if (e instanceof DateTimeError) {
-    console.error(e.code); // DateTimeErrorCode.MISSING_TIMEZONE
-    console.error(e.message); // "Venue timezone is required"
-    console.error(e.details); // { venue: {...} }
-  }
-}
-```
-
-Error codes:
-
-- `INVALID_TIMEZONE` - Timezone string is not a valid IANA identifier
-- `INVALID_ISO_STRING` - ISO date string is malformed
-- `INVALID_DATE` - Date string is invalid
-- `INVALID_TIME` - Time string is invalid
-- `MISSING_TIMEZONE` - Required timezone is missing
-- `PARSE_ERROR` - General parsing error
-
-## Migration from Legacy Code
-
-### From `src/lib/utils/timezone.js`
-
-```typescript
-// Before
-import { localToUTC, utcToLocal, formatForDisplay } from '$lib/utils/timezone';
-
-// After
-import {
-  parseLocalToUTC,
-  parseUTCToLocal,
-  formatEventDateTime,
-} from '$lib/datetime';
-```
-
-### From `src/lib/utils/utils.js`
-
-```typescript
-// Before
-import { formatDateTime, formatTimeRange, getDay } from '$lib/utils/utils';
-
-// After
-import {
-  formatEventDateTime,
-  formatTimeRange,
-  formatDayOfWeek,
-} from '$lib/datetime';
-```
-
-## Testing
-
-Run tests:
-
-```bash
-npm run test -- src/lib/datetime
-```
-
-Run with coverage:
-
-```bash
-npm run test:coverage -- src/lib/datetime
-```
-
-Target: 100% coverage for this critical module.
+# DateTime Module
+
+Centralized date/time handling for the MicDrop platform. This module eliminates timezone bugs by enforcing consistent patterns across the application.
+
+## Golden Rules
+
+1. **Backend is King** - All API requests send/receive UTC ISO strings (`2023-12-25T20:00:00Z`)
+2. **Display is Local** - All UI components receive UTC strings + Timezone ID
+3. **No `new Date()` in components** - Use these helpers instead
+4. **Timezone is always required** - Every function requires explicit timezone parameter
+
+## Quick Start
+
+```typescript
+import * as datetime from '$lib/datetime';
+
+// Get timezone from venue (throws if missing)
+const tz = datetime.getVenueTimezone(venue);
+
+// Format for display
+const time = datetime.formatEventTime(event.startTime, tz); // "7:00 PM"
+const date = datetime.formatEventDate(event.startTime, tz); // "Dec 25, 2023"
+const full = datetime.formatEventDateTime(event.startTime, tz); // "Dec 25, 2023 at 7:00 PM"
+
+// 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 Structure
+
+```
+src/lib/datetime/
+├── index.ts           # Clean exports
+├── types.ts           # Type definitions
+├── constants.ts       # Duration constants, format strings
+├── timezone.ts        # Timezone utilities
+├── format.ts          # Formatting functions
+├── parse.ts           # Parsing functions
+├── __tests__/         # Comprehensive tests
+│   ├── timezone.test.ts
+│   ├── format.test.ts
+│   ├── parse.test.ts
+│   └── integration.test.ts
+└── README.md          # This file
+```
+
+## API Reference
+
+### Timezone Utilities
+
+```typescript
+// Validate timezone
+isValidTimezone('America/Los_Angeles'); // true
+isValidTimezone('PST'); // false (abbreviations not valid)
+
+// Get venue timezone (throws if missing)
+const tz = getVenueTimezone(venue);
+
+// Get user's browser timezone
+const userTz = getUserTimezone();
+
+// Get timezone offset string
+getTimezoneOffset('America/Los_Angeles'); // "PST (UTC-8)"
+
+// Normalize legacy timezone abbreviations
+normalizeTimezone('PST'); // "America/Los_Angeles"
+
+// Check if DST is active
+isDST('America/Los_Angeles', new Date()); // true/false
+```
+
+### Format Functions
+
+All format functions require timezone - no defaults!
+
+```typescript
+// Time only
+formatEventTime('2023-12-26T03:00:00Z', 'America/Los_Angeles');
+// "7:00 PM"
+
+// Date only
+formatEventDate('2023-12-26T03:00:00Z', 'America/Los_Angeles');
+// "Dec 25, 2023"
+
+// Full datetime
+formatEventDateTime('2023-12-26T03:00:00Z', 'America/Los_Angeles');
+// "Dec 25, 2023 at 7:00 PM"
+
+// Time range
+formatTimeRange(startUtc, endUtc, 'America/Los_Angeles');
+// "7:00 PM - 10:00 PM"
+
+// Date range
+formatDateRange(startUtc, endUtc, 'America/Los_Angeles');
+// "Dec 25 - 27, 2023"
+
+// Relative time
+formatRelativeTime(utcIso, 'America/Los_Angeles');
+// "2 hours ago" or "in 3 days"
+
+// Date parts
+getDateParts('2023-12-25T20:00:00Z', 'America/Los_Angeles');
+// { day: 'Mon', month: 'Dec', date: 25, year: 2023 }
+
+// Get hour (0-23)
+getHourInTimezone('2023-12-25T20:00:00Z', 'America/Los_Angeles');
+// 12
+
+// Get date string
+getDateInTimezone('2023-12-25T20:00:00Z', 'America/Los_Angeles');
+// "2023-12-25"
+```
+
+### Parse Functions
+
+```typescript
+// Local datetime to UTC
+parseLocalToUTC('2023-12-25T19:00:00', 'America/Los_Angeles');
+// "2023-12-26T03:00:00.000Z"
+
+// UTC to local datetime
+parseUTCToLocal('2023-12-26T03:00:00Z', 'America/Los_Angeles');
+// "2023-12-25T19:00:00"
+
+// Combine date and time
+combineDateAndTime('2023-12-25', '19:00', 'America/Los_Angeles');
+// "2023-12-26T03:00:00.000Z"
+
+// Parse API response for form
+parseDateTimeFromAPI('2023-12-26T03:00:00Z', 'America/Los_Angeles');
+// { date: '2023-12-25', time: '19:00' }
+
+// Start of day in UTC
+parseStartOfDay('2023-12-25', 'America/Los_Angeles');
+// "2023-12-25T08:00:00.000Z"
+
+// End of day in UTC
+parseEndOfDay('2023-12-25', 'America/Los_Angeles');
+// "2023-12-26T07:59:59.000Z"
+```
+
+### Next-Day Time Handling
+
+For overnight events (e.g., 10 PM - 2 AM):
+
+```typescript
+// Check for next-day prefix
+isNextDayTime('+1_02:00'); // true
+isNextDayTime('14:00'); // false
+
+// Strip prefix
+stripNextDayPrefix('+1_02:00'); // '02:00'
+
+// Convert to minutes
+parseTimeToMinutes('22:00'); // 1320
+parseTimeToMinutes('+1_02:00'); // 1560 (26 hours)
+
+// Convert back
+minutesToTimeString(1320); // '22:00'
+minutesToTimeString(1560, true); // '+1_02:00'
+```
+
+### Constants
+
+```typescript
+import {
+  DURATIONS,
+  DATE_FORMATS,
+  EVENT_DEFAULTS,
+  COMMON_US_TIMEZONES,
+} from '$lib/datetime';
+
+// Durations in milliseconds
+DURATIONS.MINUTE; // 60000
+DURATIONS.HOUR; // 3600000
+DURATIONS.DAY; // 86400000
+
+// Event defaults
+EVENT_DEFAULTS.DEFAULT_DURATION_MINUTES; // 120
+EVENT_DEFAULTS.MIN_DURATION_MINUTES; // 15
+EVENT_DEFAULTS.DEFAULT_DOORS_BEFORE_MINUTES; // 30
+
+// Common US timezones for selects
+COMMON_US_TIMEZONES;
+// [{ id: 'America/Los_Angeles', label: 'Pacific Time (PT)', abbr: 'PT' }, ...]
+```
+
+## Common Patterns
+
+### Event Form
+
+```typescript
+// Populating form from API response
+function populateForm(event: Event) {
+  const tz = datetime.getVenueTimezone(event.venue);
+  const start = datetime.parseDateTimeFromAPI(event.startTime, tz);
+  const end = datetime.parseDateTimeFromAPI(event.endTime, tz);
+
+  return {
+    date: start.date,
+    startTime: start.time,
+    endTime: end.time,
+  };
+}
+
+// Submitting form to API
+function submitForm(form: FormData, venue: Venue) {
+  const tz = datetime.getVenueTimezone(venue);
+
+  return {
+    startTime: datetime.combineDateAndTime(form.date, form.startTime, tz),
+    endTime: datetime.combineDateAndTime(form.date, form.endTime, tz),
+  };
+}
+```
+
+### Calendar Display
+
+```typescript
+// Display events in venue timezone
+function renderEvent(event: Event, venue: Venue) {
+  const tz = datetime.getVenueTimezone(venue);
+
+  return {
+    time: datetime.formatEventTime(event.startTime, tz),
+    date: datetime.formatEventDate(event.startTime, tz),
+    dateRange: datetime.formatTimeRange(event.startTime, event.endTime, tz),
+    dateParts: datetime.getDateParts(event.startTime, tz),
+  };
+}
+```
+
+### Grouping Events by Date
+
+```typescript
+function groupByDate(events: Event[], timezone: TimezoneId) {
+  const groups: Record<string, Event[]> = {};
+
+  for (const event of events) {
+    const dateKey = datetime.getDateInTimezone(event.startTime, timezone);
+    groups[dateKey] = groups[dateKey] || [];
+    groups[dateKey].push(event);
+  }
+
+  return groups;
+}
+```
+
+## Error Handling
+
+All functions throw `DateTimeError` for invalid inputs:
+
+```typescript
+import { DateTimeError, DateTimeErrorCode } from '$lib/datetime';
+
+try {
+  const tz = datetime.getVenueTimezone(venue);
+} catch (e) {
+  if (e instanceof DateTimeError) {
+    console.error(e.code); // DateTimeErrorCode.MISSING_TIMEZONE
+    console.error(e.message); // "Venue timezone is required"
+    console.error(e.details); // { venue: {...} }
+  }
+}
+```
+
+Error codes:
+
+- `INVALID_TIMEZONE` - Timezone string is not a valid IANA identifier
+- `INVALID_ISO_STRING` - ISO date string is malformed
+- `INVALID_DATE` - Date string is invalid
+- `INVALID_TIME` - Time string is invalid
+- `MISSING_TIMEZONE` - Required timezone is missing
+- `PARSE_ERROR` - General parsing error
+
+## Migration from Legacy Code
+
+### From `src/lib/utils/timezone.js`
+
+```typescript
+// Before
+import { localToUTC, utcToLocal, formatForDisplay } from '$lib/utils/timezone';
+
+// After
+import {
+  parseLocalToUTC,
+  parseUTCToLocal,
+  formatEventDateTime,
+} from '$lib/datetime';
+```
+
+### From `src/lib/utils/utils.js`
+
+```typescript
+// Before
+import { formatDateTime, formatTimeRange, getDay } from '$lib/utils/utils';
+
+// After
+import {
+  formatEventDateTime,
+  formatTimeRange,
+  formatDayOfWeek,
+} from '$lib/datetime';
+```
+
+## Testing
+
+Run tests:
+
+```bash
+npm run test -- src/lib/datetime
+```
+
+Run with coverage:
+
+```bash
+npm run test:coverage -- src/lib/datetime
+```
+
+Target: 100% coverage for this critical module.

package/dist/datetime/__tests__/format.test.js

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { formatCleanTimeRange, formatDateRange, formatDayOfWeek, formatEventDate, formatEventDateTime, formatEventTime, formatHour, formatMonth, formatNotificationTime, formatRelativeTime, formatTimeRange, getDateInTimezone, getDateParts, getHourInTimezone, isToday, } from '../format';
-import { DateTimeError, DateTimeErrorCode } from '../types';
+import { DateTimeError } from '../types';
 describe('format utilities', () => {
     describe('formatEventTime', () => {
         it('formats time in specified timezone', () => {

package/dist/datetime/__tests__/parse.test.js

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { combineDateAndTime, formatDateTimeForAPI, isNextDayTime, minutesToTimeString, parseDateTimeFromAPI, parseEndOfDay, parseLocalToUTC, parseStartOfDay, parseTimeToMinutes, parseUTCToLocal, stripNextDayPrefix, } from '../parse';
-import { DateTimeError, DateTimeErrorCode } from '../types';
+import { DateTimeError } from '../types';
 describe('parse utilities', () => {
     describe('parseLocalToUTC', () => {
         it('converts local datetime to UTC', () => {

package/dist/datetime/__tests__/timezone.test.js

@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { describe, expect, it } from 'vitest';
 import { getTimezoneDisplayName, getTimezoneOffset, getUserTimezone, getVenueTimezone, isDST, isValidTimezone, normalizeTimezone, getIANATimezone, isValidIANATimezone, getAllTimezones, formatTimezoneForDisplay, getTimezoneOptions, getCommonUSTimezoneOptions, } from '../timezone';
 import { DateTimeError, DateTimeErrorCode } from '../types';
 describe('timezone utilities', () => {