@getmicdrop/svelte-components 5.17.3 → 5.17.4

package/dist/datetime/README.md

@@ -0,0 +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.

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', () => {

package/dist/datetime/parse.js

@@ -6,7 +6,7 @@
  *
  * @module datetime/parse
  */
-import { format, parse } from 'date-fns';
+import { format } from 'date-fns';
 import { fromZonedTime, toZonedTime } from 'date-fns-tz';
 import { DATE_FORMATS } from './constants';
 import { isValidTimezone } from './timezone';

package/dist/forms/createFormStore.svelte.js

@@ -7,7 +7,6 @@
  * - UI states (loading, saving, saved)
  * - Section-level validation for progressive forms
  */
-import { z } from 'zod';
 // ============================================================================
 // Implementation
 // ============================================================================

package/dist/forms/createFormStore.svelte.spec.js

@@ -1,7 +1,6 @@
 import { describe, it, expect, vi, afterEach } from 'vitest';
 import { z } from 'zod';
 import { createFormStore } from './createFormStore.svelte';
-import { flushSync } from 'svelte';
 const testSchema = z.object({
     name: z.string().min(1, 'Name is required'),
     email: z.string().email('Invalid email'),

package/dist/index.js

@@ -1,57 +1,57 @@
-// =============================================================================
-// PRIMITIVES - Pure visual components (Layer 1)
-// =============================================================================
-
-export * from './primitives/index.js';
-
-// =============================================================================
-// COMPONENTS - Semantic wrappers and layout components
-// =============================================================================
-
-export * from './components/index.js';
-
-// =============================================================================
-// RECIPES - Domain-agnostic compositions (Layer 2)
-// =============================================================================
-
-export * from './recipes/index.js';
-
-// =============================================================================
-// PATTERNS - Layout & flow components (Layer 3)
-// =============================================================================
-
-export * from './patterns/index.js';
-
-// =============================================================================
-// CALENDAR - Domain components (deferred migration to apps)
-// =============================================================================
-
-export * from './calendar/index.js';
-
-// =============================================================================
-// NON-COMPONENT EXPORTS
-// =============================================================================
-
-// Note: config.js and telemetry.js removed - they use import.meta.env which
-// is Vite-specific. Apps should define their own config/telemetry locally.
-
-// Constants
-export * from './constants/formOptions.js';
-export * from './constants/validation.js';
-
-// Presets - Domain-to-color mappings for migration
-export * from './presets/index.js';
-
-// Utils / Actions
-export { portal } from './utils/portal.js';
-export { safeSlide, bloom } from './utils/transitions.js';
-export { optimizeImage, supportsWebP, createImage } from './utils/imageOptimizer.js';
-export {
-  triggerHaptic,
-  isHapticAvailable,
-  getHapticForButtonVariant,
-} from './utils/haptic.js';
-/** @typedef {import('./utils/haptic.js').HapticStyle} HapticStyle */
-
-// Design Tokens
-export { typography } from './tokens/typography.js';
+// =============================================================================
+// PRIMITIVES - Pure visual components (Layer 1)
+// =============================================================================
+
+export * from './primitives/index.js';
+
+// =============================================================================
+// COMPONENTS - Semantic wrappers and layout components
+// =============================================================================
+
+export * from './components/index.js';
+
+// =============================================================================
+// RECIPES - Domain-agnostic compositions (Layer 2)
+// =============================================================================
+
+export * from './recipes/index.js';
+
+// =============================================================================
+// PATTERNS - Layout & flow components (Layer 3)
+// =============================================================================
+
+export * from './patterns/index.js';
+
+// =============================================================================
+// CALENDAR - Domain components (deferred migration to apps)
+// =============================================================================
+
+export * from './calendar/index.js';
+
+// =============================================================================
+// NON-COMPONENT EXPORTS
+// =============================================================================
+
+// Note: config.js and telemetry.js removed - they use import.meta.env which
+// is Vite-specific. Apps should define their own config/telemetry locally.
+
+// Constants
+export * from './constants/formOptions.js';
+export * from './constants/validation.js';
+
+// Presets - Domain-to-color mappings for migration
+export * from './presets/index.js';
+
+// Utils / Actions
+export { portal } from './utils/portal.js';
+export { safeSlide, bloom } from './utils/transitions.js';
+export { optimizeImage, supportsWebP, createImage } from './utils/imageOptimizer.js';
+export {
+  triggerHaptic,
+  isHapticAvailable,
+  getHapticForButtonVariant,
+} from './utils/haptic.js';
+/** @typedef {import('./utils/haptic.js').HapticStyle} HapticStyle */
+
+// Design Tokens
+export { typography } from './tokens/typography.js';