@getmicdrop/svelte-components 5.18.0 → 5.19.0

package/dist/utils/dateHelpers.js

@@ -0,0 +1,253 @@
+// ============================================
+// DATE/TIME FORMATTING UTILITIES
+// ============================================
+/**
+ * Convert a value to a date string using Date.toDateString().
+ * Returns null if the value is falsy.
+ */
+export function convertToDate(value) {
+    return value ? new Date(value).toDateString() : null;
+}
+/**
+ * Convert an ISO date string to a local Date using UTC components (date only, no time).
+ */
+export function convertToCustomDateFormat(isoString) {
+    const date = new Date(isoString);
+    const year = date.getUTCFullYear();
+    const month = date.getUTCMonth();
+    const day = date.getUTCDate();
+    return new Date(year, month, day);
+}
+/**
+ * Convert an ISO date string to a UTC Date preserving hours and minutes.
+ */
+export function convertToCustomDateTimeFormat(isoDateString) {
+    const date = new Date(isoDateString);
+    return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate(), date.getUTCHours(), date.getUTCMinutes()));
+}
+/**
+ * Format a date string's time as "H:MM AM/PM" using UTC hours.
+ */
+export function formatHour(dateString) {
+    const date = new Date(dateString);
+    const hour = date.getUTCHours();
+    const minutes = date.getUTCMinutes();
+    const suffix = hour >= 12 ? "PM" : "AM";
+    const displayHour = hour % 12 || 12;
+    const displayMinutes = minutes < 10 ? "0" + minutes : minutes;
+    return `${displayHour}:${displayMinutes} ${suffix}`;
+}
+/**
+ * Format a date as short form: "Thu, Oct 24".
+ */
+export function formattedDate(date) {
+    const options = {
+        weekday: "short",
+        month: "short",
+        day: "2-digit",
+    };
+    return new Date(date).toLocaleDateString("en-US", options);
+}
+/** Get the ordinal suffix (st, nd, rd, th) for a day of the month. */
+function getOrdinalSuffix(day) {
+    if (day >= 11 && day <= 13)
+        return "th";
+    switch (day % 10) {
+        case 1:
+            return "st";
+        case 2:
+            return "nd";
+        case 3:
+            return "rd";
+        default:
+            return "th";
+    }
+}
+/**
+ * Format a date as long form with ordinal: "Thursday, October 24th, 2024".
+ */
+export function formattedFullDate(date) {
+    const options = {
+        weekday: "long",
+        month: "long",
+        day: "numeric",
+        year: "numeric",
+    };
+    const formatted = new Date(date).toLocaleDateString("en-US", options);
+    const day = new Date(date).getDate();
+    const ordinalSuffix = getOrdinalSuffix(day);
+    return formatted.replace(/\d+/, day + ordinalSuffix);
+}
+/**
+ * Format a datetime string using Intl.DateTimeFormat with timezone support.
+ */
+export const formatDateTime = (dateTimeString, timeZone = "UTC") => {
+    const options = {
+        weekday: "short",
+        year: "numeric",
+        month: "short",
+        day: "numeric",
+        hour: "numeric",
+        minute: "numeric",
+        hour12: true,
+        timeZone: timeZone,
+    };
+    const date = new Date(dateTimeString);
+    return new Intl.DateTimeFormat("en-US", options).format(date);
+};
+/**
+ * Format a start datetime as a single "H:MM AM/PM" time string (UTC).
+ */
+export const formatTimeline = (startDateTime) => {
+    const formatHourInternal = (date) => {
+        let hours = date.getUTCHours();
+        const minutes = date.getUTCMinutes();
+        const suffix = hours >= 12 ? "PM" : "AM";
+        hours = hours % 12 || 12;
+        return `${hours}:${minutes < 10 ? "0" + minutes : minutes} ${suffix}`;
+    };
+    const start = formatHourInternal(new Date(startDateTime));
+    return `${start}`;
+};
+/**
+ * Format a time range as "H:MM AM - H:MM PM" (UTC).
+ */
+export function formatTimeRange(startDate, endDate) {
+    const start = new Date(startDate);
+    const end = new Date(endDate);
+    function formatTime(date) {
+        let hours = date.getUTCHours();
+        const minutes = date.getUTCMinutes();
+        const ampm = hours >= 12 ? "PM" : "AM";
+        hours = hours % 12;
+        hours = hours ? hours : 12;
+        const minutesStr = minutes < 10 ? "0" + minutes : minutes;
+        return hours + ":" + minutesStr + " " + ampm;
+    }
+    const startTime = formatTime(start);
+    const endTime = formatTime(end);
+    return `${startTime} - ${endTime}`;
+}
+/**
+ * Get an array of date strings between two dates (inclusive), formatted as "YYYY-M-D".
+ */
+export function getDateRange(startDate, endDate) {
+    const start = new Date(startDate);
+    const end = new Date(endDate);
+    const dateArray = [];
+    const currentDate = new Date(start);
+    while (currentDate <= end) {
+        dateArray.push(`${currentDate.getUTCFullYear()}-${currentDate.getUTCMonth() + 1}-${currentDate.getUTCDate()}`);
+        currentDate.setUTCDate(currentDate.getUTCDate() + 1);
+    }
+    return dateArray;
+}
+/**
+ * Get abbreviated day of week from a date string (e.g., "Mon", "Tue").
+ */
+export const getDay = (dateString) => {
+    const days = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+    const date = new Date(dateString);
+    return days[date.getUTCDay()];
+};
+/**
+ * Get abbreviated month from a date string (e.g., "Jan", "Feb").
+ */
+export const getMonth = (dateString) => {
+    const months = [
+        "Jan", "Feb", "Mar", "Apr", "May", "Jun",
+        "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
+    ];
+    const date = new Date(dateString);
+    return months[date.getUTCMonth()];
+};
+/**
+ * Get the day of the month (1-31) from a date string.
+ */
+export const getDateOfMonth = (dateString) => {
+    const date = new Date(dateString);
+    return date.getUTCDate();
+};
+/**
+ * Relative time string (e.g., "5 minutes ago", "2 days ago").
+ */
+export function timeAgo(date) {
+    const now = new Date();
+    const seconds = Math.floor((now.getTime() - new Date(date).getTime()) / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    const months = Math.floor(days / 30);
+    const years = Math.floor(months / 12);
+    if (seconds < 60) {
+        return `${seconds} second${seconds !== 1 ? "s" : ""} ago`;
+    }
+    else if (minutes < 60) {
+        return `${minutes} minute${minutes !== 1 ? "s" : ""} ago`;
+    }
+    else if (hours < 24) {
+        return `${hours} hour${hours !== 1 ? "s" : ""} ago`;
+    }
+    else if (days < 30) {
+        return `${days} day${days !== 1 ? "s" : ""} ago`;
+    }
+    else if (months < 12) {
+        return `${months} month${months !== 1 ? "s" : ""} ago`;
+    }
+    else {
+        return `${years} year${years !== 1 ? "s" : ""} ago`;
+    }
+}
+/**
+ * Get day options: weekdays if "weeks", or numbered days 1-31 with ordinal suffixes.
+ */
+export function getDays(params) {
+    if (params === "weeks") {
+        return [
+            { value: "monday", label: "Monday" },
+            { value: "tuesday", label: "Tuesday" },
+            { value: "wednesday", label: "Wednesday" },
+            { value: "thursday", label: "Thursday" },
+            { value: "friday", label: "Friday" },
+        ];
+    }
+    else {
+        return Array.from({ length: 31 }, (_, i) => {
+            const day = i + 1;
+            const suffix = day % 10 === 1 && day !== 11
+                ? "st"
+                : day % 10 === 2 && day !== 12
+                    ? "nd"
+                    : day % 10 === 3 && day !== 13
+                        ? "rd"
+                        : "th";
+            return {
+                value: day.toString(),
+                label: day + suffix,
+            };
+        });
+    }
+}
+/**
+ * Get numeric options based on time unit: 12 for months, 10 for weeks, 31 for days.
+ */
+export function getDaysNumberOptions(timeUnit) {
+    if (timeUnit === "months") {
+        return Array.from({ length: 12 }, (_, i) => ({
+            value: (i + 1).toString(),
+            label: (i + 1).toString(),
+        }));
+    }
+    else if (timeUnit === "weeks") {
+        return Array.from({ length: 10 }, (_, i) => ({
+            value: (i + 1).toString(),
+            label: (i + 1).toString(),
+        }));
+    }
+    else {
+        return Array.from({ length: 31 }, (_, i) => ({
+            value: (i + 1).toString(),
+            label: (i + 1).toString(),
+        }));
+    }
+}

package/dist/utils/eventFormatters.d.ts

@@ -0,0 +1,9 @@
+export declare const getRoleFromRoleOnStage: (roleOnStage: number | undefined) => string;
+/**
+ * Format an event performer invite or event-performer join into a normalized show object.
+ * Handles both V1 (EventPerformer with event.Event) and V2 (PerformerInvite with event.event) shapes.
+ */
+export declare const formatEvent: (event: Record<string, any>) => Record<string, any>;
+export declare const formatRosterEventPerformerInvite: (event: Record<string, any>) => Record<string, any>;
+export declare const formatVenue: (event: Record<string, any>) => Record<string, any>;
+//# sourceMappingURL=eventFormatters.d.ts.map

package/dist/utils/eventFormatters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventFormatters.d.ts","sourceRoot":"","sources":["../../src/lib/utils/eventFormatters.ts"],"names":[],"mappings":"AAmBA,eAAO,MAAM,sBAAsB,GAAI,aAAa,MAAM,GAAG,SAAS,KAAG,MAExE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CA4C1E,CAAC;AAEF,eAAO,MAAM,gCAAgC,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAc/F,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAmB1E,CAAC"}

package/dist/utils/eventFormatters.js

@@ -0,0 +1,96 @@
+import { formatTimeRange, getDateRange } from "./dateHelpers";
+// ============================================
+// EVENT FORMATTING UTILITIES
+// ============================================
+/** Map roleOnStage numeric value to role name string. */
+const ROLE_ON_STAGE_MAP = {
+    0: "Performer",
+    1: "Host",
+    2: "Headliner",
+    3: "Feature",
+    4: "Special Guest",
+    5: "Opener",
+    6: "Guest",
+    7: "Teacher",
+    8: "Assistant",
+};
+export const getRoleFromRoleOnStage = (roleOnStage) => {
+    return ROLE_ON_STAGE_MAP[roleOnStage] || "Performer";
+};
+/**
+ * Format an event performer invite or event-performer join into a normalized show object.
+ * Handles both V1 (EventPerformer with event.Event) and V2 (PerformerInvite with event.event) shapes.
+ */
+export const formatEvent = (event) => {
+    // V2 uses lowercase "event", V1 uses uppercase "Event"
+    const eventData = event.event || event.Event;
+    // Get venue stage name (the physical stage at the venue, e.g., "Main Room", "Showroom")
+    // Not to be confused with performer's stage name (their performance alias)
+    const venueStageName = eventData?.stage?.name || eventData?.stage?.googleName || eventData?.googleName || "";
+    const venueAddress = eventData?.venue?.address || "";
+    const role = getRoleFromRoleOnStage(event.roleOnStage);
+    // Get custom booking notification message from venue (set in venue edit page)
+    const bookingMessage = eventData?.venue?.booking_notification || "No additional details available.";
+    // V2 returns "status" string, V1 returns numeric "acceptedState"
+    const status = event.status || (event.acceptedState !== undefined
+        ? { 0: "invited", 2: "confirmed", 1: "declined", 3: "declined", 4: "cancelled" }[event.acceptedState]
+        : "unknown");
+    const setLength = event.setLength ?? 0;
+    return {
+        eventId: eventData?.ID,
+        venueId: eventData?.venue?.ID,
+        title: eventData?.title,
+        role: role,
+        startDateTime: eventData?.startDateTime,
+        status: status,
+        doorsOpenTime: eventData?.doorsOpenTime,
+        spotDuration: `${setLength} min spot`,
+        venueName: eventData?.venue?.name,
+        location: venueAddress,
+        id: event.invitationId || String(event.id || event.ID),
+        image: eventData?.image,
+        details: {
+            venue: eventData?.venue?.name,
+            stageName: venueStageName,
+            address: venueAddress,
+            setLength: `${setLength} min`,
+            eventDetails: bookingMessage,
+        },
+        lastUpdated: event.updatedAt || event.UpdatedAt,
+    };
+};
+export const formatRosterEventPerformerInvite = (event) => {
+    return {
+        venueId: event.venueId,
+        role: event.role || "Performer",
+        acceptedState: event.acceptedState,
+        name: event.Venue.name,
+        shortVenue: `${event.Venue.firstName} ${event.Venue.lastName} - ${event.Venue.role}`,
+        location: `${event.Venue.address}`,
+        id: event.invitationId,
+        lastUpdated: event.UpdatedAt,
+        image: event.Venue.image,
+        hasAvailability: true,
+        invitationAccepted: event.acceptedState === 2,
+    };
+};
+export const formatVenue = (event) => {
+    return {
+        venueId: event.Event.venueId,
+        name: event.Event.venue.name,
+        image: event.Event.venue.squareImageUrl || event.Event.venue.image,
+        location: `${event.Event.venue.address}`,
+        start: event.Event.startDateTime,
+        end: event.Event.endDateTime,
+        doorOpen: event.Event.doorsOpenTime,
+        email: event.Event.venue.email,
+        phone: event.Event.venue.phone,
+        description: event.Event.venue.description,
+        instagram: event.Event.venue.instagram,
+        facebook: event.Event.venue.facebook,
+        twitter: event.Event.venue.twitter,
+        lastUpdated: event.UpdatedAt,
+        timeRange: formatTimeRange(event.Event.startDateTime, event.Event.endDateTime),
+        dateRange: getDateRange(event.Event.startDateTime, event.Event.endDateTime),
+    };
+};

package/dist/utils/fetchHelpers.d.ts

@@ -0,0 +1,17 @@
+interface FetchResult<T = unknown> {
+    data: T | null;
+    error: string | null;
+}
+interface PostResult<T = unknown> extends FetchResult<T> {
+    ok: boolean;
+}
+/**
+ * Fetch data from an API endpoint with error handling.
+ */
+export declare function fetchData<T = unknown>(endpoint: string, options?: RequestInit): Promise<FetchResult<T>>;
+/**
+ * Post JSON data to an API endpoint.
+ */
+export declare function postData<T = unknown>(endpoint: string, data: unknown): Promise<PostResult<T>>;
+export {};
+//# sourceMappingURL=fetchHelpers.d.ts.map

package/dist/utils/fetchHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchHelpers.d.ts","sourceRoot":"","sources":["../../src/lib/utils/fetchHelpers.ts"],"names":[],"mappings":"AAIA,UAAU,WAAW,CAAC,CAAC,GAAG,OAAO;IAC/B,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,UAAU,UAAU,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAC;IACtD,EAAE,EAAE,OAAO,CAAC;CACb;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EACzC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAiBzB;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,CAAC,GAAG,OAAO,EACxC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAkBxB"}

package/dist/utils/fetchHelpers.js

@@ -0,0 +1,44 @@
+// ============================================
+// DATA FETCHING UTILITIES
+// ============================================
+/**
+ * Fetch data from an API endpoint with error handling.
+ */
+export async function fetchData(endpoint, options = {}) {
+    try {
+        const res = await fetch(endpoint, {
+            headers: { "Content-Type": "application/json", ...options.headers },
+            ...options,
+        });
+        if (!res.ok) {
+            const errorText = await res.text().catch(() => "Unknown error");
+            throw new Error(errorText || `Request failed with status ${res.status}`);
+        }
+        const data = await res.json();
+        return { data, error: null };
+    }
+    catch (err) {
+        return { data: null, error: err.message };
+    }
+}
+/**
+ * Post JSON data to an API endpoint.
+ */
+export async function postData(endpoint, data) {
+    try {
+        const res = await fetch(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(data),
+        });
+        const responseData = await res.json().catch(() => ({}));
+        return {
+            data: responseData,
+            error: res.ok ? null : (responseData?.message || "Request failed"),
+            ok: res.ok,
+        };
+    }
+    catch (err) {
+        return { data: null, error: err.message, ok: false };
+    }
+}

package/dist/utils/formatters.d.ts

@@ -1,3 +1,64 @@
+/**
+ * Rounds a number to 2 decimal places (cents precision).
+ * Use after any arithmetic on currency values to avoid IEEE 754 drift.
+ * e.g. roundCurrency(167.79999999999) → 167.8
+ */
+export declare function roundCurrency(value: number): number;
+/**
+ * Formats a currency value using Intl.NumberFormat.
+ * Returns empty string for null/undefined.
+ *
+ * @param value    - Amount in dollars (e.g. 25.5)
+ * @param currency - ISO 4217 currency code (default: 'USD')
+ * @param locale   - BCP 47 locale tag (default: 'en-US')
+ * @returns Formatted string (e.g. "$25.50")
+ */
+export declare function formatCurrency(value: number | null | undefined, currency?: string, locale?: string): string;
+type DateInput = Date | string | number | null | undefined;
+/**
+ * Formats a date according to a locale.
+ * Default output: abbreviated month, day, year (e.g. "Dec 15, 2025" in en-US).
+ *
+ * @param value   - Date, ISO string, or epoch ms
+ * @param options - Intl.DateTimeFormatOptions overrides
+ * @param locale  - BCP 47 locale tag (default: 'en-US')
+ */
+export declare function formatDate(value: DateInput, options?: Intl.DateTimeFormatOptions, locale?: string): string;
+/**
+ * Formats a date with time.
+ * Default output: abbreviated month, day, year, hour, minute
+ * (e.g. "Dec 15, 2025, 3:30 PM" in en-US).
+ *
+ * @param value   - Date, ISO string, or epoch ms
+ * @param options - Intl.DateTimeFormatOptions overrides
+ * @param locale  - BCP 47 locale tag (default: 'en-US')
+ */
+export declare function formatDateTime(value: DateInput, options?: Intl.DateTimeFormatOptions, locale?: string): string;
+/**
+ * Formats time-only.
+ * Default output: hour and minute (e.g. "3:30 PM" in en-US).
+ *
+ * @param value   - Date, ISO string, or epoch ms
+ * @param options - Intl.DateTimeFormatOptions overrides
+ * @param locale  - BCP 47 locale tag (default: 'en-US')
+ */
+export declare function formatTime(value: DateInput, options?: Intl.DateTimeFormatOptions, locale?: string): string;
+/**
+ * Formats a number according to a locale.
+ * Returns empty string for null/undefined.
+ *
+ * @param value   - Number to format
+ * @param options - Intl.NumberFormatOptions overrides
+ * @param locale  - BCP 47 locale tag (default: 'en-US')
+ */
+export declare function formatNumber(value: number | null | undefined, options?: Intl.NumberFormatOptions, locale?: string): string;
+/**
+ * Truncates a string to maxLength characters, appending "..." when truncated.
+ *
+ * @param title     - Text to truncate
+ * @param maxLength - Maximum character count before truncation (default: 50)
+ */
+export declare function truncateTitle(title: string, maxLength?: number): string;
 /**
  * Format a credit card number with spaces every 4 digits
  * @param value - Raw input (digits only)
@@ -10,4 +71,5 @@ export declare function formatCreditCardNumber(value: string): string;
  * @returns Formatted phone number (e.g., "123-456-7890")
  */
 export declare function formatPhoneNumber(value: string): string;
+export {};
 //# sourceMappingURL=formatters.d.ts.map

package/dist/utils/formatters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../../src/lib/utils/formatters.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOvD"}
+{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../../src/lib/utils/formatters.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,QAAQ,SAAQ,EAChB,MAAM,SAAU,GACf,MAAM,CAMR;AAMD,KAAK,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAY3D;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,SAAS,EAChB,OAAO,CAAC,EAAE,IAAI,CAAC,qBAAqB,EACpC,MAAM,SAAU,GACf,MAAM,CASR;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,EAChB,OAAO,CAAC,EAAE,IAAI,CAAC,qBAAqB,EACpC,MAAM,SAAU,GACf,MAAM,CAWR;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,SAAS,EAChB,OAAO,CAAC,EAAE,IAAI,CAAC,qBAAqB,EACpC,MAAM,SAAU,GACf,MAAM,CAQR;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,OAAO,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAClC,MAAM,SAAU,GACf,MAAM,CAGR;AAMD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,SAAK,GAAG,MAAM,CAKnE;AAMD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOvD"}

package/dist/utils/formatters.js

@@ -1,3 +1,131 @@
+// =============================================================================
+// Currency
+// =============================================================================
+/**
+ * Rounds a number to 2 decimal places (cents precision).
+ * Use after any arithmetic on currency values to avoid IEEE 754 drift.
+ * e.g. roundCurrency(167.79999999999) → 167.8
+ */
+export function roundCurrency(value) {
+    return Math.round(value * 100) / 100;
+}
+/**
+ * Formats a currency value using Intl.NumberFormat.
+ * Returns empty string for null/undefined.
+ *
+ * @param value    - Amount in dollars (e.g. 25.5)
+ * @param currency - ISO 4217 currency code (default: 'USD')
+ * @param locale   - BCP 47 locale tag (default: 'en-US')
+ * @returns Formatted string (e.g. "$25.50")
+ */
+export function formatCurrency(value, currency = 'USD', locale = 'en-US') {
+    if (value === null || value === undefined)
+        return '';
+    return new Intl.NumberFormat(locale, {
+        style: 'currency',
+        currency,
+    }).format(value);
+}
+/**
+ * Converts various date input types to a Date object.
+ * Returns null for invalid or missing inputs.
+ */
+function toDate(value) {
+    if (value === null || value === undefined)
+        return null;
+    const date = value instanceof Date ? value : new Date(value);
+    return isNaN(date.getTime()) ? null : date;
+}
+/**
+ * Formats a date according to a locale.
+ * Default output: abbreviated month, day, year (e.g. "Dec 15, 2025" in en-US).
+ *
+ * @param value   - Date, ISO string, or epoch ms
+ * @param options - Intl.DateTimeFormatOptions overrides
+ * @param locale  - BCP 47 locale tag (default: 'en-US')
+ */
+export function formatDate(value, options, locale = 'en-US') {
+    const date = toDate(value);
+    if (!date)
+        return '';
+    const defaults = {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+    };
+    return new Intl.DateTimeFormat(locale, { ...defaults, ...options }).format(date);
+}
+/**
+ * Formats a date with time.
+ * Default output: abbreviated month, day, year, hour, minute
+ * (e.g. "Dec 15, 2025, 3:30 PM" in en-US).
+ *
+ * @param value   - Date, ISO string, or epoch ms
+ * @param options - Intl.DateTimeFormatOptions overrides
+ * @param locale  - BCP 47 locale tag (default: 'en-US')
+ */
+export function formatDateTime(value, options, locale = 'en-US') {
+    const date = toDate(value);
+    if (!date)
+        return '';
+    const defaults = {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+        hour: 'numeric',
+        minute: '2-digit',
+    };
+    return new Intl.DateTimeFormat(locale, { ...defaults, ...options }).format(date);
+}
+/**
+ * Formats time-only.
+ * Default output: hour and minute (e.g. "3:30 PM" in en-US).
+ *
+ * @param value   - Date, ISO string, or epoch ms
+ * @param options - Intl.DateTimeFormatOptions overrides
+ * @param locale  - BCP 47 locale tag (default: 'en-US')
+ */
+export function formatTime(value, options, locale = 'en-US') {
+    const date = toDate(value);
+    if (!date)
+        return '';
+    const defaults = {
+        hour: 'numeric',
+        minute: '2-digit',
+    };
+    return new Intl.DateTimeFormat(locale, { ...defaults, ...options }).format(date);
+}
+/**
+ * Formats a number according to a locale.
+ * Returns empty string for null/undefined.
+ *
+ * @param value   - Number to format
+ * @param options - Intl.NumberFormatOptions overrides
+ * @param locale  - BCP 47 locale tag (default: 'en-US')
+ */
+export function formatNumber(value, options, locale = 'en-US') {
+    if (value === null || value === undefined)
+        return '';
+    return new Intl.NumberFormat(locale, options).format(value);
+}
+// =============================================================================
+// Text
+// =============================================================================
+/**
+ * Truncates a string to maxLength characters, appending "..." when truncated.
+ *
+ * @param title     - Text to truncate
+ * @param maxLength - Maximum character count before truncation (default: 50)
+ */
+export function truncateTitle(title, maxLength = 50) {
+    if (title.length > maxLength) {
+        return title.slice(0, maxLength) + '...';
+    }
+    return title;
+}
+// =============================================================================
+// Input formatting (credit card, phone)
+// =============================================================================
 /**
  * Format a credit card number with spaces every 4 digits
  * @param value - Raw input (digits only)