@ethisyscore/core-utils 1.21.0

package/dist/date/index.d.cts

@@ -0,0 +1,206 @@
+/**
+ * Shared date/time format tokens (date-fns syntax).
+ *
+ * These are the canonical formats used across the EthisysCore monolith and
+ * plugins. Change a value here for a global locale requirement rather than
+ * hardcoding a format string at a call site.
+ */
+/** ISO wire format `yyyy-MM-dd` — the standard date-only format throughout the app. */
+declare const DATE_FORMAT = "yyyy-MM-dd";
+/** Audit-log timestamp, e.g. `5 March 2026, 14:30`. */
+declare const AUDIT_DATE_FORMAT = "d MMMM yyyy, HH:mm";
+/** User-facing date display, e.g. `5 Mar 2026`. */
+declare const DISPLAY_DATE_FORMAT = "d MMM yyyy";
+/** Weekday + day + month, e.g. `Monday, 5 March`. */
+declare const DAY_DATE_FORMAT = "EEEE, d MMMM";
+/** Abbreviated day + month, e.g. `Mar 5`. */
+declare const DAY_MONTH_FORMAT = "MMM d";
+/** Abbreviated day + month + year, e.g. `Mar 5, 2026`. */
+declare const DAY_MONTH_YEAR_FORMAT = "MMM d, yyyy";
+/** 12-hour time, e.g. `2:30 PM`. */
+declare const TIME_FORMAT = "h:mm a";
+/** Short datetime, e.g. `Mar 5, 2:30 PM`. */
+declare const SHORT_DATETIME_FORMAT = "MMM d, h:mm a";
+
+/** Type guard: is `value` a bare `yyyy-MM-dd` date-only string? */
+declare const isDateOnlyString: (value: unknown) => value is string;
+/**
+ * Formats a `Date`, defaulting to the standard application ISO date format
+ * (`yyyy-MM-dd`). Pass `dateFormat` to override.
+ */
+declare const formatDate: (date: Date, dateFormat?: string) => string;
+/** Today's date as a `yyyy-MM-dd` ISO string (local calendar day). */
+declare const getTodayIsoDate: () => string;
+/** First day of the given date's month, as a `yyyy-MM-dd` ISO string. */
+declare const getMonthStartIso: (date: Date) => string;
+/** Last day of the given date's month, as a `yyyy-MM-dd` ISO string. */
+declare const getMonthEndIso: (date: Date) => string;
+/**
+ * Parses a date-only `yyyy-MM-dd` string as a LOCAL date. Returns `null` when
+ * the value is not a date-only string or is not a valid calendar date. Avoids
+ * the `new Date("yyyy-MM-dd")` UTC parse, which shifts the day in non-UTC zones.
+ */
+declare const parseIsoDateLocal: (value: string | null | undefined) => Date | null;
+/**
+ * Adds `days` to an ISO `yyyy-MM-dd` date and returns the result as a `yyyy-MM-dd`
+ * string. Parses and formats in local time (via `parseIsoDateLocal` / `formatDate`)
+ * so the arithmetic can't drift across a day boundary in non-UTC timezones/DST.
+ * Returns the input unchanged when it is not a valid date-only string.
+ */
+declare const addDaysToIsoDate: (isoDate: string, days: number) => string;
+/**
+ * Extracts a date-only string (`yyyy-MM-dd`) from a date string.
+ * - Date-only strings (`2024-05-15`) are returned as-is.
+ * - ISO datetime strings (`2024-05-15T00:00:00+05:30`) have the date portion
+ *   extracted directly from the string to preserve the original calendar date
+ *   without timezone conversion.
+ * - Returns empty string for null, undefined, or unparseable values.
+ */
+declare const toDateOnlyString: (value: string | null | undefined) => string;
+
+/**
+ * Formats a date string, defaulting to the standard application format
+ * (`yyyy-MM-dd`). Uses `parseISO` to safely handle ISO strings. Pass
+ * `dateFormat` to override. Returns `"-"` for empty, missing, or unparseable
+ * input rather than throwing.
+ */
+declare const formatDateString: (date?: string | null, dateFormat?: string) => string;
+/**
+ * Safely formats a date string or `Date`. Handles null, undefined, and invalid
+ * dates by returning a fallback string.
+ * @param date - The date to format (string, Date, null, or undefined)
+ * @param formatStr - The desired output format (defaults to `DATE_FORMAT`)
+ * @param fallback - Returned when the date is invalid or missing (defaults to `"—"`)
+ */
+declare const formatDateSafe: (date: string | Date | null | undefined, formatStr?: string, fallback?: string) => string;
+/**
+ * Formats a date string or `Date` to a format like `31st Aug 2025`.
+ * Handles date-only strings (`yyyy-MM-dd`) as local dates to avoid timezone shifts.
+ * @param date - Date string (`yyyy-MM-dd`) or `Date`
+ * @returns Formatted date string with ordinal suffix
+ */
+declare const formatDateWithOrdinal: (date: string | Date | null | undefined) => string;
+/**
+ * Formats a date as a relative time string (e.g. `2h ago`, `Just now`).
+ * Optimised for short labels in dropdowns; anything older than a week falls
+ * back to the standard date format.
+ * @param date - ISO string or `Date`
+ */
+declare const formatTimeAgo: (date: string | Date | null | undefined) => string;
+
+/**
+ * Pure duration / timespan helpers — no external dependencies.
+ *
+ * Cover the two duration shapes that flow across the EthisysCore wire: a
+ * `"HH:mm:ss"` timespan string (.NET `TimeSpan`) and a millisecond count.
+ */
+/** Converts a `"HH:mm:ss"` timespan string to milliseconds. */
+declare const timespanToMilliseconds: (timespan: string) => number;
+/** Converts milliseconds to hours (as a float). */
+declare const millisecondsToHours: (ms: number) => number;
+/** Converts hours to milliseconds. */
+declare const hoursToMilliseconds: (hours: number) => number;
+/** Formats a milliseconds count as `4h 15min`. */
+declare const formatMillisecondsAsTimeSpent: (ms: number) => string;
+/** Formats a `"HH:mm:ss"` duration string as human readable (e.g. `2h 30m 0s`). */
+declare function formatDuration(duration?: string): string;
+/**
+ * Formats a fractional-hours number as a compact human-readable duration
+ * (`45m`, `2h 30m`, `3d 4h`). Defensively caps unreasonable values.
+ */
+declare const formatDurationNumber: (durationHours?: number | null) => string;
+/**
+ * Trims an API-supplied `"HH:mm:ss"` down to the `"HH:mm"` string used by
+ * MUI `TimePicker`-backed forms. Returns the supplied fallback when the value
+ * is missing or shorter than five characters.
+ */
+declare function toHHmm(value: string | null | undefined, fallback: string): string;
+/**
+ * Serialises a non-empty `"HH:mm"` / `"HH:mm:ss"` value back to the canonical
+ * `"HH:mm:ss"` API format. Returns `null` for empty input so callers can block
+ * the save rather than silently persisting midnight — an empty TimePicker
+ * (cleared via keyboard) is an unsaved edit, not a legitimate `00:00:00` value.
+ */
+declare function toHHmmss(value: string): string | null;
+
+/** Converts an ISO date string to date-input format (`yyyy-MM-dd`). */
+declare const isoToDateInput: (isoString: string | undefined) => string;
+/** Converts date-input format (`yyyy-MM-dd`) to a UTC ISO string at midnight UTC. */
+declare const dateInputToIso: (dateString: string) => string;
+/**
+ * Normalises a date-only value from `<input type="date">` (`yyyy-MM-dd`) into a
+ * canonical UTC ISO-8601 timestamp at midnight UTC, e.g.
+ * `2026-07-14` → `2026-07-14T00:00:00.000Z`. Use at the API-payload boundary
+ * for fields the BE types as `DateTimeOffset` — a bare date-only string risks
+ * ambiguous/failed deserialisation. A value that is already a full ISO
+ * timestamp is passed through unchanged. Empty/invalid → `undefined` so callers
+ * omit the field (BE clears it).
+ */
+declare function dateOnlyToIsoUtc(value: string | null | undefined): string | undefined;
+/**
+ * Returns the current local wall-clock as a `yyyy-MM-ddTHH:mm` string — the
+ * format an `<input type="datetime-local">` element expects. Minute precision;
+ * seconds and timezone deliberately omitted.
+ */
+declare function nowLocalDateTimeInputValue(): string;
+/**
+ * Converts a naive local-time string from `<input type="datetime-local">`
+ * (shape `yyyy-MM-ddTHH:mm` or `yyyy-MM-ddTHH:mm:ss`) into a full ISO-8601 UTC
+ * string with `Z` suffix that .NET `DateTimeOffset` cannot ambiguously
+ * interpret. Empty / undefined inputs pass through as `undefined`.
+ */
+declare function localDateTimeInputToIsoUtc(value: string | null | undefined): string | undefined;
+/**
+ * Ensures an ISO-8601 string is treated as UTC by appending a `Z` suffix when
+ * no explicit offset or UTC indicator is present. The backend may emit
+ * timestamps like `2026-05-26T06:21:00` (no Z), which JS would otherwise parse
+ * as local time.
+ */
+declare function ensureUtcIso(value: string): string;
+/**
+ * Converts an ISO-8601 string (with or without explicit offset) into the naive
+ * local-time shape `yyyy-MM-ddTHH:mm` expected by `<input type="datetime-local">`.
+ * Returns the supplied fallback (default empty string) when the input is
+ * missing or unparseable. When `value` carries no offset or `Z` suffix it is
+ * treated as UTC before converting to local time, so the edit form displays the
+ * correct time regardless of the user's timezone.
+ */
+declare function isoUtcToLocalDateTimeInput(value: string | null | undefined, fallback?: string): string;
+
+interface DateRange {
+    startDate: string;
+    endDate: string;
+}
+/**
+ * Returns a `{ startDate, endDate }` date range for a named relative period,
+ * formatted with `dateFormat` (defaults to the ISO date-only format). Unknown
+ * periods fall back to the last week.
+ * @param timePeriod - one of `week` | `month` | `quarter` | `year`
+ * @param dateFormat - output format for both bounds (defaults to `DATE_FORMAT`)
+ */
+declare const getDateRange: (timePeriod: string, dateFormat?: string) => DateRange;
+/** Computes an ISO timestamp range from a number of days back to now. */
+declare function computeDateRange(days: number): {
+    from: string;
+    to: string;
+};
+/**
+ * Returns the current calendar month as a half-open UTC range `[fromUtc, beforeUtc)`,
+ * suitable for "this month" count filters. `fromUtc` is the first instant of the
+ * month; `beforeUtc` is the first instant of the next month (exclusive).
+ */
+declare function currentMonthRangeUtc(today?: Date): {
+    fromUtc: string;
+    beforeUtc: string;
+};
+/**
+ * Computes the current UTC-offset minutes for a given IANA zone name using the
+ * runtime's `Intl` implementation. Returns `null` when the zone is unknown.
+ *
+ * Used by timezone auto-populate fallbacks so a browser reporting an IANA zone
+ * that isn't in the backend seed (e.g. `Europe/London` during BST) can still
+ * match against a seeded zone sharing the same current offset.
+ */
+declare function getCurrentOffsetMinutes(iana: string): number | null;
+
+export { AUDIT_DATE_FORMAT, DATE_FORMAT, DAY_DATE_FORMAT, DAY_MONTH_FORMAT, DAY_MONTH_YEAR_FORMAT, DISPLAY_DATE_FORMAT, type DateRange, SHORT_DATETIME_FORMAT, TIME_FORMAT, addDaysToIsoDate, computeDateRange, currentMonthRangeUtc, dateInputToIso, dateOnlyToIsoUtc, ensureUtcIso, formatDate, formatDateSafe, formatDateString, formatDateWithOrdinal, formatDuration, formatDurationNumber, formatMillisecondsAsTimeSpent, formatTimeAgo, getCurrentOffsetMinutes, getDateRange, getMonthEndIso, getMonthStartIso, getTodayIsoDate, hoursToMilliseconds, isDateOnlyString, isoToDateInput, isoUtcToLocalDateTimeInput, localDateTimeInputToIsoUtc, millisecondsToHours, nowLocalDateTimeInputValue, parseIsoDateLocal, timespanToMilliseconds, toDateOnlyString, toHHmm, toHHmmss };

package/dist/date/index.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Shared date/time format tokens (date-fns syntax).
+ *
+ * These are the canonical formats used across the EthisysCore monolith and
+ * plugins. Change a value here for a global locale requirement rather than
+ * hardcoding a format string at a call site.
+ */
+/** ISO wire format `yyyy-MM-dd` — the standard date-only format throughout the app. */
+declare const DATE_FORMAT = "yyyy-MM-dd";
+/** Audit-log timestamp, e.g. `5 March 2026, 14:30`. */
+declare const AUDIT_DATE_FORMAT = "d MMMM yyyy, HH:mm";
+/** User-facing date display, e.g. `5 Mar 2026`. */
+declare const DISPLAY_DATE_FORMAT = "d MMM yyyy";
+/** Weekday + day + month, e.g. `Monday, 5 March`. */
+declare const DAY_DATE_FORMAT = "EEEE, d MMMM";
+/** Abbreviated day + month, e.g. `Mar 5`. */
+declare const DAY_MONTH_FORMAT = "MMM d";
+/** Abbreviated day + month + year, e.g. `Mar 5, 2026`. */
+declare const DAY_MONTH_YEAR_FORMAT = "MMM d, yyyy";
+/** 12-hour time, e.g. `2:30 PM`. */
+declare const TIME_FORMAT = "h:mm a";
+/** Short datetime, e.g. `Mar 5, 2:30 PM`. */
+declare const SHORT_DATETIME_FORMAT = "MMM d, h:mm a";
+
+/** Type guard: is `value` a bare `yyyy-MM-dd` date-only string? */
+declare const isDateOnlyString: (value: unknown) => value is string;
+/**
+ * Formats a `Date`, defaulting to the standard application ISO date format
+ * (`yyyy-MM-dd`). Pass `dateFormat` to override.
+ */
+declare const formatDate: (date: Date, dateFormat?: string) => string;
+/** Today's date as a `yyyy-MM-dd` ISO string (local calendar day). */
+declare const getTodayIsoDate: () => string;
+/** First day of the given date's month, as a `yyyy-MM-dd` ISO string. */
+declare const getMonthStartIso: (date: Date) => string;
+/** Last day of the given date's month, as a `yyyy-MM-dd` ISO string. */
+declare const getMonthEndIso: (date: Date) => string;
+/**
+ * Parses a date-only `yyyy-MM-dd` string as a LOCAL date. Returns `null` when
+ * the value is not a date-only string or is not a valid calendar date. Avoids
+ * the `new Date("yyyy-MM-dd")` UTC parse, which shifts the day in non-UTC zones.
+ */
+declare const parseIsoDateLocal: (value: string | null | undefined) => Date | null;
+/**
+ * Adds `days` to an ISO `yyyy-MM-dd` date and returns the result as a `yyyy-MM-dd`
+ * string. Parses and formats in local time (via `parseIsoDateLocal` / `formatDate`)
+ * so the arithmetic can't drift across a day boundary in non-UTC timezones/DST.
+ * Returns the input unchanged when it is not a valid date-only string.
+ */
+declare const addDaysToIsoDate: (isoDate: string, days: number) => string;
+/**
+ * Extracts a date-only string (`yyyy-MM-dd`) from a date string.
+ * - Date-only strings (`2024-05-15`) are returned as-is.
+ * - ISO datetime strings (`2024-05-15T00:00:00+05:30`) have the date portion
+ *   extracted directly from the string to preserve the original calendar date
+ *   without timezone conversion.
+ * - Returns empty string for null, undefined, or unparseable values.
+ */
+declare const toDateOnlyString: (value: string | null | undefined) => string;
+
+/**
+ * Formats a date string, defaulting to the standard application format
+ * (`yyyy-MM-dd`). Uses `parseISO` to safely handle ISO strings. Pass
+ * `dateFormat` to override. Returns `"-"` for empty, missing, or unparseable
+ * input rather than throwing.
+ */
+declare const formatDateString: (date?: string | null, dateFormat?: string) => string;
+/**
+ * Safely formats a date string or `Date`. Handles null, undefined, and invalid
+ * dates by returning a fallback string.
+ * @param date - The date to format (string, Date, null, or undefined)
+ * @param formatStr - The desired output format (defaults to `DATE_FORMAT`)
+ * @param fallback - Returned when the date is invalid or missing (defaults to `"—"`)
+ */
+declare const formatDateSafe: (date: string | Date | null | undefined, formatStr?: string, fallback?: string) => string;
+/**
+ * Formats a date string or `Date` to a format like `31st Aug 2025`.
+ * Handles date-only strings (`yyyy-MM-dd`) as local dates to avoid timezone shifts.
+ * @param date - Date string (`yyyy-MM-dd`) or `Date`
+ * @returns Formatted date string with ordinal suffix
+ */
+declare const formatDateWithOrdinal: (date: string | Date | null | undefined) => string;
+/**
+ * Formats a date as a relative time string (e.g. `2h ago`, `Just now`).
+ * Optimised for short labels in dropdowns; anything older than a week falls
+ * back to the standard date format.
+ * @param date - ISO string or `Date`
+ */
+declare const formatTimeAgo: (date: string | Date | null | undefined) => string;
+
+/**
+ * Pure duration / timespan helpers — no external dependencies.
+ *
+ * Cover the two duration shapes that flow across the EthisysCore wire: a
+ * `"HH:mm:ss"` timespan string (.NET `TimeSpan`) and a millisecond count.
+ */
+/** Converts a `"HH:mm:ss"` timespan string to milliseconds. */
+declare const timespanToMilliseconds: (timespan: string) => number;
+/** Converts milliseconds to hours (as a float). */
+declare const millisecondsToHours: (ms: number) => number;
+/** Converts hours to milliseconds. */
+declare const hoursToMilliseconds: (hours: number) => number;
+/** Formats a milliseconds count as `4h 15min`. */
+declare const formatMillisecondsAsTimeSpent: (ms: number) => string;
+/** Formats a `"HH:mm:ss"` duration string as human readable (e.g. `2h 30m 0s`). */
+declare function formatDuration(duration?: string): string;
+/**
+ * Formats a fractional-hours number as a compact human-readable duration
+ * (`45m`, `2h 30m`, `3d 4h`). Defensively caps unreasonable values.
+ */
+declare const formatDurationNumber: (durationHours?: number | null) => string;
+/**
+ * Trims an API-supplied `"HH:mm:ss"` down to the `"HH:mm"` string used by
+ * MUI `TimePicker`-backed forms. Returns the supplied fallback when the value
+ * is missing or shorter than five characters.
+ */
+declare function toHHmm(value: string | null | undefined, fallback: string): string;
+/**
+ * Serialises a non-empty `"HH:mm"` / `"HH:mm:ss"` value back to the canonical
+ * `"HH:mm:ss"` API format. Returns `null` for empty input so callers can block
+ * the save rather than silently persisting midnight — an empty TimePicker
+ * (cleared via keyboard) is an unsaved edit, not a legitimate `00:00:00` value.
+ */
+declare function toHHmmss(value: string): string | null;
+
+/** Converts an ISO date string to date-input format (`yyyy-MM-dd`). */
+declare const isoToDateInput: (isoString: string | undefined) => string;
+/** Converts date-input format (`yyyy-MM-dd`) to a UTC ISO string at midnight UTC. */
+declare const dateInputToIso: (dateString: string) => string;
+/**
+ * Normalises a date-only value from `<input type="date">` (`yyyy-MM-dd`) into a
+ * canonical UTC ISO-8601 timestamp at midnight UTC, e.g.
+ * `2026-07-14` → `2026-07-14T00:00:00.000Z`. Use at the API-payload boundary
+ * for fields the BE types as `DateTimeOffset` — a bare date-only string risks
+ * ambiguous/failed deserialisation. A value that is already a full ISO
+ * timestamp is passed through unchanged. Empty/invalid → `undefined` so callers
+ * omit the field (BE clears it).
+ */
+declare function dateOnlyToIsoUtc(value: string | null | undefined): string | undefined;
+/**
+ * Returns the current local wall-clock as a `yyyy-MM-ddTHH:mm` string — the
+ * format an `<input type="datetime-local">` element expects. Minute precision;
+ * seconds and timezone deliberately omitted.
+ */
+declare function nowLocalDateTimeInputValue(): string;
+/**
+ * Converts a naive local-time string from `<input type="datetime-local">`
+ * (shape `yyyy-MM-ddTHH:mm` or `yyyy-MM-ddTHH:mm:ss`) into a full ISO-8601 UTC
+ * string with `Z` suffix that .NET `DateTimeOffset` cannot ambiguously
+ * interpret. Empty / undefined inputs pass through as `undefined`.
+ */
+declare function localDateTimeInputToIsoUtc(value: string | null | undefined): string | undefined;
+/**
+ * Ensures an ISO-8601 string is treated as UTC by appending a `Z` suffix when
+ * no explicit offset or UTC indicator is present. The backend may emit
+ * timestamps like `2026-05-26T06:21:00` (no Z), which JS would otherwise parse
+ * as local time.
+ */
+declare function ensureUtcIso(value: string): string;
+/**
+ * Converts an ISO-8601 string (with or without explicit offset) into the naive
+ * local-time shape `yyyy-MM-ddTHH:mm` expected by `<input type="datetime-local">`.
+ * Returns the supplied fallback (default empty string) when the input is
+ * missing or unparseable. When `value` carries no offset or `Z` suffix it is
+ * treated as UTC before converting to local time, so the edit form displays the
+ * correct time regardless of the user's timezone.
+ */
+declare function isoUtcToLocalDateTimeInput(value: string | null | undefined, fallback?: string): string;
+
+interface DateRange {
+    startDate: string;
+    endDate: string;
+}
+/**
+ * Returns a `{ startDate, endDate }` date range for a named relative period,
+ * formatted with `dateFormat` (defaults to the ISO date-only format). Unknown
+ * periods fall back to the last week.
+ * @param timePeriod - one of `week` | `month` | `quarter` | `year`
+ * @param dateFormat - output format for both bounds (defaults to `DATE_FORMAT`)
+ */
+declare const getDateRange: (timePeriod: string, dateFormat?: string) => DateRange;
+/** Computes an ISO timestamp range from a number of days back to now. */
+declare function computeDateRange(days: number): {
+    from: string;
+    to: string;
+};
+/**
+ * Returns the current calendar month as a half-open UTC range `[fromUtc, beforeUtc)`,
+ * suitable for "this month" count filters. `fromUtc` is the first instant of the
+ * month; `beforeUtc` is the first instant of the next month (exclusive).
+ */
+declare function currentMonthRangeUtc(today?: Date): {
+    fromUtc: string;
+    beforeUtc: string;
+};
+/**
+ * Computes the current UTC-offset minutes for a given IANA zone name using the
+ * runtime's `Intl` implementation. Returns `null` when the zone is unknown.
+ *
+ * Used by timezone auto-populate fallbacks so a browser reporting an IANA zone
+ * that isn't in the backend seed (e.g. `Europe/London` during BST) can still
+ * match against a seeded zone sharing the same current offset.
+ */
+declare function getCurrentOffsetMinutes(iana: string): number | null;
+
+export { AUDIT_DATE_FORMAT, DATE_FORMAT, DAY_DATE_FORMAT, DAY_MONTH_FORMAT, DAY_MONTH_YEAR_FORMAT, DISPLAY_DATE_FORMAT, type DateRange, SHORT_DATETIME_FORMAT, TIME_FORMAT, addDaysToIsoDate, computeDateRange, currentMonthRangeUtc, dateInputToIso, dateOnlyToIsoUtc, ensureUtcIso, formatDate, formatDateSafe, formatDateString, formatDateWithOrdinal, formatDuration, formatDurationNumber, formatMillisecondsAsTimeSpent, formatTimeAgo, getCurrentOffsetMinutes, getDateRange, getMonthEndIso, getMonthStartIso, getTodayIsoDate, hoursToMilliseconds, isDateOnlyString, isoToDateInput, isoUtcToLocalDateTimeInput, localDateTimeInputToIsoUtc, millisecondsToHours, nowLocalDateTimeInputValue, parseIsoDateLocal, timespanToMilliseconds, toDateOnlyString, toHHmm, toHHmmss };

package/dist/date/index.js

@@ -0,0 +1,241 @@
+import { format, isValid, parseISO, subDays, subYears, subMonths } from 'date-fns';
+
+// src/date/constants.ts
+var DATE_FORMAT = "yyyy-MM-dd";
+var AUDIT_DATE_FORMAT = "d MMMM yyyy, HH:mm";
+var DISPLAY_DATE_FORMAT = "d MMM yyyy";
+var DAY_DATE_FORMAT = "EEEE, d MMMM";
+var DAY_MONTH_FORMAT = "MMM d";
+var DAY_MONTH_YEAR_FORMAT = "MMM d, yyyy";
+var TIME_FORMAT = "h:mm a";
+var SHORT_DATETIME_FORMAT = "MMM d, h:mm a";
+var isDateOnlyString = (value) => {
+  return typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value);
+};
+var formatDate = (date, dateFormat = DATE_FORMAT) => {
+  return format(date, dateFormat);
+};
+var getTodayIsoDate = () => {
+  return formatDate(/* @__PURE__ */ new Date());
+};
+var getMonthStartIso = (date) => formatDate(new Date(date.getFullYear(), date.getMonth(), 1));
+var getMonthEndIso = (date) => formatDate(new Date(date.getFullYear(), date.getMonth() + 1, 0));
+var parseIsoDateLocal = (value) => {
+  if (!value || !isDateOnlyString(value)) return null;
+  const [year, month, day] = value.split("-").map(Number);
+  const d = new Date(year, month - 1, day);
+  return isValid(d) ? d : null;
+};
+var addDaysToIsoDate = (isoDate, days) => {
+  const base = parseIsoDateLocal(isoDate);
+  if (!base) return isoDate;
+  base.setDate(base.getDate() + days);
+  return formatDate(base);
+};
+var toDateOnlyString = (value) => {
+  if (!value) return "";
+  const datepart = value.split("T")[0];
+  return isDateOnlyString(datepart) ? datepart : "";
+};
+var formatDateString = (date, dateFormat = DATE_FORMAT) => {
+  if (!date) return "-";
+  const parsed = parseISO(date);
+  if (!isValid(parsed)) return "-";
+  return format(parsed, dateFormat);
+};
+var formatDateSafe = (date, formatStr = DATE_FORMAT, fallback = "\u2014") => {
+  if (!date) return fallback;
+  try {
+    const dateObj = typeof date === "string" ? parseISO(date) : date;
+    if (!isValid(dateObj)) return fallback;
+    return format(dateObj, formatStr);
+  } catch {
+    return fallback;
+  }
+};
+var getOrdinalSuffix = (day) => {
+  if (day > 3 && day < 21) return "th";
+  switch (day % 10) {
+    case 1:
+      return "st";
+    case 2:
+      return "nd";
+    case 3:
+      return "rd";
+    default:
+      return "th";
+  }
+};
+var formatDateWithOrdinal = (date) => {
+  if (!date) return "Not specified";
+  let dateObj;
+  if (typeof date === "string") {
+    if (isDateOnlyString(date)) {
+      const [year2, month2, day2] = date.split("-").map(Number);
+      dateObj = new Date(year2, month2 - 1, day2);
+    } else {
+      dateObj = parseISO(date);
+    }
+  } else {
+    dateObj = date;
+  }
+  if (!isValid(dateObj)) return "Invalid date";
+  const day = dateObj.getDate();
+  const month = format(dateObj, "MMM");
+  const year = dateObj.getFullYear();
+  return `${day}${getOrdinalSuffix(day)} ${month} ${year}`;
+};
+var formatTimeAgo = (date) => {
+  if (!date) return "";
+  const dateObj = typeof date === "string" ? parseISO(date) : date;
+  if (!isValid(dateObj)) return "";
+  const now = /* @__PURE__ */ new Date();
+  const seconds = Math.floor((now.getTime() - dateObj.getTime()) / 1e3);
+  if (seconds < 60) return "Just now";
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  if (days < 7) return `${days}d ago`;
+  return formatDate(dateObj);
+};
+
+// src/date/duration.ts
+var timespanToMilliseconds = (timespan) => {
+  if (!timespan) return 0;
+  const [h = "0", m = "0", s = "0"] = timespan.split(":");
+  const hours = parseInt(h || "0", 10);
+  const minutes = parseInt(m || "0", 10);
+  const seconds = parseInt(s || "0", 10);
+  return (isNaN(hours) ? 0 : hours) * 60 * 60 * 1e3 + (isNaN(minutes) ? 0 : minutes) * 60 * 1e3 + (isNaN(seconds) ? 0 : seconds) * 1e3;
+};
+var millisecondsToHours = (ms) => ms / (1e3 * 60 * 60);
+var hoursToMilliseconds = (hours) => hours * (1e3 * 60 * 60);
+var formatMillisecondsAsTimeSpent = (ms) => {
+  if (!ms || ms < 0) return "0h 0min";
+  const totalMinutes = Math.floor(ms / (1e3 * 60));
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  let result = "";
+  if (hours > 0) result += `${hours}h`;
+  if (minutes > 0 || hours === 0) result += (hours > 0 ? " " : "") + `${minutes}min`;
+  return result;
+};
+function formatDuration(duration) {
+  if (!duration) return "-";
+  const [hours, minutes, seconds] = duration.split(":").map(Number);
+  let result = "";
+  if (hours) result += `${hours}h`;
+  if (minutes) result += (result ? " " : "") + `${minutes}m`;
+  if (seconds) result += (result ? " " : "") + `${seconds}s`;
+  return result || "0m";
+}
+var formatDurationNumber = (durationHours) => {
+  if (durationHours == null || durationHours === 0) return "\u2014";
+  if (durationHours > 8760) return "Unknown";
+  if (durationHours < 0) return "Error";
+  const hours = Math.floor(durationHours);
+  const minutes = Math.floor(durationHours % 1 * 60);
+  if (durationHours < 1) return `${minutes}m`;
+  if (hours < 24) {
+    if (minutes === 0) return `${hours}h`;
+    return `${hours}h ${minutes}m`;
+  }
+  const days = Math.floor(hours / 24);
+  const remainingHours = hours % 24;
+  if (remainingHours === 0) return `${days}d`;
+  return `${days}d ${remainingHours}h`;
+};
+function toHHmm(value, fallback) {
+  if (!value || value.length < 5) return fallback;
+  return value.slice(0, 5);
+}
+function toHHmmss(value) {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  return trimmed.length === 5 ? `${trimmed}:00` : trimmed;
+}
+var isoToDateInput = (isoString) => {
+  if (!isoString) return "";
+  try {
+    return new Date(isoString).toISOString().split("T")[0];
+  } catch {
+    return "";
+  }
+};
+var dateInputToIso = (dateString) => {
+  if (!dateString) return "";
+  const parsed = /* @__PURE__ */ new Date(dateString + "T00:00:00Z");
+  return Number.isNaN(parsed.getTime()) ? "" : parsed.toISOString();
+};
+function dateOnlyToIsoUtc(value) {
+  if (!value) return void 0;
+  const parsed = value.includes("T") ? new Date(value) : /* @__PURE__ */ new Date(`${value}T00:00:00Z`);
+  return Number.isNaN(parsed.getTime()) ? void 0 : parsed.toISOString();
+}
+function nowLocalDateTimeInputValue() {
+  return format(/* @__PURE__ */ new Date(), "yyyy-MM-dd'T'HH:mm");
+}
+function localDateTimeInputToIsoUtc(value) {
+  if (!value) return void 0;
+  const parsed = new Date(value);
+  if (!isValid(parsed)) return void 0;
+  return parsed.toISOString();
+}
+function ensureUtcIso(value) {
+  return /[Zz]|[+-]\d{2}:?\d{2}$/.test(value) ? value : value + "Z";
+}
+function isoUtcToLocalDateTimeInput(value, fallback = "") {
+  if (!value) return fallback;
+  const parsed = new Date(ensureUtcIso(value));
+  if (!isValid(parsed)) return fallback;
+  return format(parsed, "yyyy-MM-dd'T'HH:mm");
+}
+var getDateRange = (timePeriod, dateFormat = DATE_FORMAT) => {
+  const today = /* @__PURE__ */ new Date();
+  switch (timePeriod) {
+    case "month":
+      return { startDate: format(subMonths(today, 1), dateFormat), endDate: format(today, dateFormat) };
+    case "quarter":
+      return { startDate: format(subMonths(today, 3), dateFormat), endDate: format(today, dateFormat) };
+    case "year":
+      return { startDate: format(subYears(today, 1), dateFormat), endDate: format(today, dateFormat) };
+    case "week":
+    default:
+      return { startDate: format(subDays(today, 7), dateFormat), endDate: format(today, dateFormat) };
+  }
+};
+function computeDateRange(days) {
+  const to = (/* @__PURE__ */ new Date()).toISOString();
+  const from = new Date(Date.now() - days * 864e5).toISOString();
+  return { from, to };
+}
+function currentMonthRangeUtc(today = /* @__PURE__ */ new Date()) {
+  const year = today.getUTCFullYear();
+  const month = today.getUTCMonth();
+  return {
+    fromUtc: new Date(Date.UTC(year, month, 1)).toISOString(),
+    beforeUtc: new Date(Date.UTC(year, month + 1, 1)).toISOString()
+  };
+}
+function getCurrentOffsetMinutes(iana) {
+  try {
+    const parts = new Intl.DateTimeFormat("en", {
+      timeZone: iana,
+      timeZoneName: "longOffset"
+    }).formatToParts(/* @__PURE__ */ new Date());
+    const label = parts.find((p) => p.type === "timeZoneName")?.value ?? "";
+    if (label === "GMT" || label === "UTC") return 0;
+    const m = label.match(/GMT([+-])(\d{2}):(\d{2})/);
+    if (!m) return null;
+    const sign = m[1] === "+" ? 1 : -1;
+    return sign * (parseInt(m[2], 10) * 60 + parseInt(m[3], 10));
+  } catch {
+    return null;
+  }
+}
+
+export { AUDIT_DATE_FORMAT, DATE_FORMAT, DAY_DATE_FORMAT, DAY_MONTH_FORMAT, DAY_MONTH_YEAR_FORMAT, DISPLAY_DATE_FORMAT, SHORT_DATETIME_FORMAT, TIME_FORMAT, addDaysToIsoDate, computeDateRange, currentMonthRangeUtc, dateInputToIso, dateOnlyToIsoUtc, ensureUtcIso, formatDate, formatDateSafe, formatDateString, formatDateWithOrdinal, formatDuration, formatDurationNumber, formatMillisecondsAsTimeSpent, formatTimeAgo, getCurrentOffsetMinutes, getDateRange, getMonthEndIso, getMonthStartIso, getTodayIsoDate, hoursToMilliseconds, isDateOnlyString, isoToDateInput, isoUtcToLocalDateTimeInput, localDateTimeInputToIsoUtc, millisecondsToHours, nowLocalDateTimeInputValue, parseIsoDateLocal, timespanToMilliseconds, toDateOnlyString, toHHmm, toHHmmss };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map