nexus-shared 1.1.21 → 2.0.0

package/dist/Helpers/DateHelpers.js

@@ -0,0 +1,363 @@
+import { DEFAULT_DATE_PREFERENCES } from "../Interfaces/DateInterfaces.js";
+import { BS_FIRST_YEAR, BS_LAST_YEAR, BS_MAX_DAY_NUMBER, BS_MIN_DAY_NUMBER, bsMonthLength, bsToDayNumber, dayNumberToBs } from "./NepaliCalendar.js";
+/*
+ * Pure date helpers. A date is an ISO string "YYYY-MM-DD" in the Gregorian calendar, with no time and no zone, so the
+ * same value means the same day on every machine. Arithmetic runs on day numbers (days since 1970-01-01), never on
+ * `Date` objects, which carry the browser's zone and shift a day at midnight. The Nepali calendar (Bikram Sambat) is
+ * a second way of naming the same days: `toCalendar` and `fromCalendar` convert, and the value stays Gregorian.
+ */
+export const ISO_DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+const pad = (value, width) => String(value).padStart(width, "0");
+/** Day number of a Gregorian date: days since 1970-01-01, proleptic, no zone (Howard Hinnant's algorithm). */
+export function daysFromCivil(year, month, day) {
+    const y = month <= 2 ? year - 1 : year;
+    const era = Math.floor(y / 400);
+    const yearOfEra = y - era * 400;
+    const dayOfYear = Math.floor((153 * (month + (month > 2 ? -3 : 9)) + 2) / 5) + day - 1;
+    const dayOfEra = yearOfEra * 365 + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100) + dayOfYear;
+    return era * 146097 + dayOfEra - 719468;
+}
+/** The Gregorian date of a day number. */
+export function civilFromDays(dayNumber) {
+    const z = dayNumber + 719468;
+    const era = Math.floor(z / 146097);
+    const dayOfEra = z - era * 146097;
+    const yearOfEra = Math.floor((dayOfEra - Math.floor(dayOfEra / 1460) + Math.floor(dayOfEra / 36524) - Math.floor(dayOfEra / 146096)) / 365);
+    const dayOfYear = dayOfEra - (365 * yearOfEra + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100));
+    const monthIndex = Math.floor((5 * dayOfYear + 2) / 153);
+    const day = dayOfYear - Math.floor((153 * monthIndex + 2) / 5) + 1;
+    const month = monthIndex + (monthIndex < 10 ? 3 : -9);
+    return { year: yearOfEra + era * 400 + (month <= 2 ? 1 : 0), month, day };
+}
+export const partsToIsoDate = ({ year, month, day }) => `${pad(year, 4)}-${pad(month, 2)}-${pad(day, 2)}`;
+/** The parts of an ISO date. The text must be a valid date (`isIsoDate`). */
+export function isoDateToParts(iso) {
+    return { year: Number(iso.slice(0, 4)), month: Number(iso.slice(5, 7)), day: Number(iso.slice(8, 10)) };
+}
+export const isoDateToDayNumber = (iso) => {
+    const { year, month, day } = isoDateToParts(iso);
+    return daysFromCivil(year, month, day);
+};
+export const dayNumberToIsoDate = (dayNumber) => partsToIsoDate(civilFromDays(dayNumber));
+const isLeapYear = (year) => (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+const GREGORIAN_MONTHS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+export function gregorianMonthLength(year, month) {
+    if (month < 1 || month > 12)
+        return 0;
+    return month === 2 && isLeapYear(year) ? 29 : GREGORIAN_MONTHS[month - 1];
+}
+/** Whether text is an ISO date that exists: "2026-02-30" is not. */
+export function isIsoDate(text) {
+    if (typeof text !== "string")
+        return false;
+    const match = ISO_DATE_PATTERN.exec(text);
+    if (!match)
+        return false;
+    const year = Number(match[1]);
+    const day = Number(match[3]);
+    return year >= 1 && day >= 1 && day <= gregorianMonthLength(year, Number(match[2]));
+}
+/**
+ * Turns anything a date can arrive as into an ISO date, or `null`:
+ * - "2026-09-17" (or "2026-9-7") stays that day;
+ * - an ISO date-time with a zone, "2026-09-16T18:15:00Z", becomes the browser's local date of that instant;
+ * - one without a zone, "2026-09-17T00:00:00", keeps its date part;
+ * - a `Date` is read in local time, like `new Date()` for today.
+ * Text that is not a date, or a day that does not exist, gives `null`.
+ */
+export function toIsoDate(input) {
+    if (input === null || input === undefined || input === "")
+        return null;
+    if (input instanceof Date) {
+        return Number.isNaN(input.getTime()) ? null : partsToIsoDate({ year: input.getFullYear(), month: input.getMonth() + 1, day: input.getDate() });
+    }
+    const text = input.trim();
+    const dateOnly = /^(\d{4})-(\d{1,2})-(\d{1,2})$/.exec(text);
+    if (dateOnly) {
+        const iso = partsToIsoDate({ year: Number(dateOnly[1]), month: Number(dateOnly[2]), day: Number(dateOnly[3]) });
+        return isIsoDate(iso) ? iso : null;
+    }
+    const dateTime = /^(\d{4}-\d{2}-\d{2})[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?$/i.exec(text);
+    if (!dateTime)
+        return null;
+    if (!dateTime[2])
+        return isIsoDate(dateTime[1]) ? dateTime[1] : null;
+    return toIsoDate(new Date(text));
+}
+/** A `Date` at midnight of the day: in UTC (the default, for JSON and APIs) or in the browser's local time. */
+export function isoDateToDate(iso, zone = "utc") {
+    const { year, month, day } = isoDateToParts(iso);
+    return zone === "utc" ? new Date(Date.UTC(year, month - 1, day)) : new Date(year, month - 1, day);
+}
+/** Today's date where the browser is. */
+export function todayIsoDate() {
+    return toIsoDate(new Date());
+}
+export const addDays = (iso, days) => dayNumberToIsoDate(isoDateToDayNumber(iso) + days);
+/** Negative when `a` is before `b`. ISO dates compare as text. */
+export const compareIsoDates = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/** Days from one date to another: `diffDays("2026-09-17", "2026-09-20")` is 3. */
+export const diffDays = (from, to) => isoDateToDayNumber(to) - isoDateToDayNumber(from);
+/** 0 for Sunday to 6 for Saturday. */
+export const weekdayOf = (iso) => (((isoDateToDayNumber(iso) + 4) % 7) + 7) % 7;
+export function clampIsoDate(iso, min, max) {
+    if (min && iso < min)
+        return min;
+    if (max && iso > max)
+        return max;
+    return iso;
+}
+/** The days the calendar covers: Gregorian years 1 to 9999, Bikram Sambat 1975 to 2100 (AD 1918 to 2044). */
+export const CALENDAR_RANGE = {
+    ad: { min: "0001-01-01", max: "9999-12-31" },
+    bs: { min: dayNumberToIsoDate(BS_MIN_DAY_NUMBER), max: dayNumberToIsoDate(BS_MAX_DAY_NUMBER) },
+};
+export function daysInMonth(year, month, calendar) {
+    return calendar === "bs" ? bsMonthLength(year, month) : gregorianMonthLength(year, month);
+}
+/** Whether the parts name a day of the calendar. */
+export function isValidParts(parts, calendar) {
+    const { year, month, day } = parts;
+    if (!Number.isInteger(year) || !Number.isInteger(month) || !Number.isInteger(day))
+        return false;
+    if (calendar === "ad" ? year < 1 || year > 9999 : year < BS_FIRST_YEAR || year > BS_LAST_YEAR)
+        return false;
+    return day >= 1 && day <= daysInMonth(year, month, calendar);
+}
+/** The day as parts of the calendar, or `null` when the Nepali table does not reach it. */
+export function toCalendar(iso, calendar) {
+    return calendar === "bs" ? dayNumberToBs(isoDateToDayNumber(iso)) : isoDateToParts(iso);
+}
+/** The ISO date of parts in the calendar, or `null` when the day does not exist. */
+export function fromCalendar(parts, calendar) {
+    if (calendar === "bs") {
+        const dayNumber = bsToDayNumber(parts.year, parts.month, parts.day);
+        return dayNumber === null ? null : dayNumberToIsoDate(dayNumber);
+    }
+    return isValidParts(parts, "ad") ? partsToIsoDate(parts) : null;
+}
+/** The same day of another month, or the month's last day when it is shorter. Years stay inside the calendar. */
+export function addMonths(parts, months, calendar) {
+    const index = parts.year * 12 + parts.month - 1 + months;
+    let year = Math.floor(index / 12);
+    let month = index - year * 12 + 1;
+    const first = calendar === "bs" ? BS_FIRST_YEAR : 1;
+    const last = calendar === "bs" ? BS_LAST_YEAR : 9999;
+    if (year < first)
+        [year, month] = [first, 1];
+    if (year > last)
+        [year, month] = [last, 12];
+    return { year, month, day: Math.min(parts.day, daysInMonth(year, month, calendar)) };
+}
+// Names
+const EN_MONTHS = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+const EN_MONTHS_SHORT = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+const NE_MONTHS = ["Baisakh", "Jestha", "Asar", "Shrawan", "Bhadra", "Ashwin", "Kartik", "Mangsir", "Poush", "Magh", "Falgun", "Chaitra"];
+const NE_MONTHS_SHORT = ["Bai", "Jes", "Asa", "Shr", "Bha", "Ash", "Kar", "Man", "Pou", "Mag", "Fal", "Cha"];
+const NE_MONTHS_DEVA = ["बैशाख", "जेठ", "असार", "साउन", "भदौ", "असोज", "कात्तिक", "मंसिर", "पुष", "माघ", "फागुन", "चैत"];
+const EN_WEEKDAYS = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+const EN_WEEKDAYS_SHORT = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+const EN_WEEKDAYS_MIN = ["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa"];
+const NE_WEEKDAYS_DEVA = ["आइतबार", "सोमबार", "मङ्गलबार", "बुधबार", "बिहिबार", "शुक्रबार", "शनिबार"];
+const NE_WEEKDAYS_DEVA_SHORT = ["आइत", "सोम", "मङ्गल", "बुध", "बिहि", "शुक्र", "शनि"];
+const NE_WEEKDAYS_DEVA_MIN = ["आ", "सो", "मं", "बु", "बि", "शु", "श"];
+// Other spellings a typed month name may use, in lower case.
+const NE_MONTH_ALIASES = [
+    ["baishakh", "vaishakh", "vaisakh", "baisak", "वैशाख"],
+    ["jeth", "jyestha", "jyeshtha", "ज्येष्ठ", "जेष्ठ"],
+    ["ashar", "ashad", "ashadh", "asadh", "asadha", "आषाढ", "असाढ"],
+    ["sawan", "saun", "shravan", "sravan", "srawan", "श्रावण", "सावन"],
+    ["bhadau", "bhadow", "bhado", "भाद्र", "भदो"],
+    ["asoj", "aswin", "ashoj", "ashwini", "आश्विन", "आसोज"],
+    ["kattik", "karttik", "कार्तिक", "कातिक"],
+    ["marga", "mangshir", "mansir", "margashirsha", "मार्ग", "मङ्सिर", "मङ्गसिर"],
+    ["push", "pus", "paush", "pausa", "पौष", "पूस", "पुस"],
+    ["maagh"],
+    ["fagun", "phalgun", "phagun", "फाल्गुन", "फागुण"],
+    ["chait", "चैत्र"],
+];
+/** Nepali dates use Devanagari digits and names only when both the calendar and the script say so. */
+export const usesDevanagari = (calendar, script) => calendar === "bs" && script === "devanagari";
+export function getMonthNames(calendar, script = "latin", short = false) {
+    if (calendar === "ad")
+        return short ? EN_MONTHS_SHORT : EN_MONTHS;
+    if (script === "devanagari")
+        return NE_MONTHS_DEVA;
+    return short ? NE_MONTHS_SHORT : NE_MONTHS;
+}
+export function getWeekdayNames(calendar, script = "latin", length = "long") {
+    if (usesDevanagari(calendar, script))
+        return length === "long" ? NE_WEEKDAYS_DEVA : length === "short" ? NE_WEEKDAYS_DEVA_SHORT : NE_WEEKDAYS_DEVA_MIN;
+    return length === "long" ? EN_WEEKDAYS : length === "short" ? EN_WEEKDAYS_SHORT : EN_WEEKDAYS_MIN;
+}
+// Devanagari digits: U+0966 (०) to U+096F (९).
+const DEVANAGARI_ZERO = "०".charCodeAt(0);
+export const toDevanagariDigits = (text) => text.replace(/[0-9]/g, digit => String.fromCharCode(DEVANAGARI_ZERO + Number(digit)));
+export const toLatinDigits = (text) => text.replace(/[०-९]/g, digit => String(digit.charCodeAt(0) - DEVANAGARI_ZERO));
+// Formatting and parsing
+/** Tokens of a date format. Text between them is kept as it is. */
+const FORMAT_TOKENS = /YYYY|YY|MMMM|MMM|MM|M|dddd|ddd|DD|D/g;
+function resolve(options) {
+    return {
+        calendar: options.calendar ?? DEFAULT_DATE_PREFERENCES.calendar,
+        format: options.format || DEFAULT_DATE_PREFERENCES.format,
+        script: options.script ?? DEFAULT_DATE_PREFERENCES.script,
+    };
+}
+/**
+ * Writes a day with a format of tokens: `YYYY` `YY` year, `MMMM` `MMM` month name, `MM` `M` month number, `DD` `D` day,
+ * `dddd` `ddd` weekday name. "YYYY-MM-DD" gives 2026-09-17; "dddd, MMMM D, YYYY" gives Thursday, September 17, 2026.
+ * In the Nepali calendar with the Devanagari script, digits and names are Nepali: २०८३-०६-०१.
+ * Returns "" for an empty or invalid input. A day outside the Nepali table is written as its ISO date.
+ */
+export function formatDate(input, options = {}) {
+    const iso = toIsoDate(input);
+    if (!iso)
+        return "";
+    const { calendar, format, script } = resolve(options);
+    const parts = toCalendar(iso, calendar);
+    return parts ? formatDateParts(parts, calendar, format, script, weekdayOf(iso)) : iso;
+}
+/** Writes parts of a calendar with a format. `weekday` (0 = Sunday) is needed only for the `dddd` and `ddd` tokens. */
+export function formatDateParts(parts, calendar, format, script = "latin", weekday) {
+    const devanagari = usesDevanagari(calendar, script);
+    const digits = (value, width) => (devanagari ? toDevanagariDigits(pad(value, width)) : pad(value, width));
+    const weekdayIndex = weekday ?? weekdayOf(fromCalendar(parts, calendar) ?? "1970-01-04");
+    return format.replace(FORMAT_TOKENS, token => {
+        switch (token) {
+            case "YYYY":
+                return digits(parts.year, 4);
+            case "YY":
+                return digits(parts.year % 100, 2);
+            case "MMMM":
+                return getMonthNames(calendar, script)[parts.month - 1] ?? "";
+            case "MMM":
+                return getMonthNames(calendar, script, true)[parts.month - 1] ?? "";
+            case "MM":
+                return digits(parts.month, 2);
+            case "M":
+                return digits(parts.month, 1);
+            case "DD":
+                return digits(parts.day, 2);
+            case "D":
+                return digits(parts.day, 1);
+            case "dddd":
+                return getWeekdayNames(calendar, script)[weekdayIndex] ?? "";
+            default:
+                return getWeekdayNames(calendar, script, "short")[weekdayIndex] ?? "";
+        }
+    });
+}
+/** Finds the month a typed word names, by its start (three letters or more in Latin), in any spelling or script. */
+function monthFromWord(word, calendar) {
+    const text = word.toLowerCase();
+    if (/^[a-z]+$/.test(text) && text.length < 3)
+        return null;
+    const names = calendar === "ad" ? [EN_MONTHS] : [NE_MONTHS, NE_MONTHS_DEVA];
+    for (const list of names) {
+        const index = list.findIndex(name => name.toLowerCase().startsWith(text));
+        if (index >= 0)
+            return index + 1;
+    }
+    if (calendar === "bs") {
+        const index = NE_MONTH_ALIASES.findIndex(aliases => aliases.some(alias => alias.startsWith(text)));
+        if (index >= 0)
+            return index + 1;
+    }
+    return null;
+}
+/**
+ * Reads a date the user typed, following the order of the format's tokens: with "DD/MM/YYYY", "17/9/2026" and
+ * "17-09-2026" both give "2026-09-17". Month names are matched by their start in any spelling ("Sep", "September",
+ * "Asoj", "असोज"), weekday names are ignored, Devanagari digits are read, and a four-digit number is the year wherever
+ * it stands. In the Nepali calendar the text is a Nepali date, and the result is still the Gregorian ISO date.
+ * Returns `null` for text that is not a date.
+ */
+export function parseDateText(text, options = {}) {
+    const { calendar, format } = resolve(options);
+    const clean = toLatinDigits(text).trim();
+    if (!clean)
+        return null;
+    if (calendar === "ad" && /^\d{4}-\d{1,2}-\d{1,2}$/.test(clean))
+        return toIsoDate(clean);
+    const kinds = (format.match(/YYYY|YY|MMMM|MMM|MM|M|DD|D/g) ?? ["YYYY", "MM", "DD"]).map(token => token[0]);
+    const numbers = (clean.match(/\d+/g) ?? []).map(Number);
+    const words = clean.match(/[\p{L}\p{M}]+/gu) ?? [];
+    const values = {};
+    for (const word of words) {
+        const month = monthFromWord(word, calendar);
+        if (month) {
+            values.M = month;
+            break;
+        }
+    }
+    let rest = numbers;
+    let order = kinds.filter((kind, index) => kinds.indexOf(kind) === index && !(kind === "M" && values.M));
+    const yearIndex = rest.findIndex(value => value >= 1000);
+    if (yearIndex >= 0 && order.includes("Y")) {
+        values.Y = rest[yearIndex];
+        rest = rest.filter((_, index) => index !== yearIndex);
+        order = order.filter(kind => kind !== "Y");
+    }
+    if (rest.length !== order.length)
+        return null;
+    order.forEach((kind, index) => (values[kind] = rest[index]));
+    let { Y: year } = values;
+    const { M: month, D: day } = values;
+    if (year === undefined || month === undefined || day === undefined)
+        return null;
+    if (year < 100)
+        year += calendar === "bs" ? 2000 : year < 50 ? 2000 : 1900;
+    const parts = { year, month, day };
+    return isValidParts(parts, calendar) ? fromCalendar(parts, calendar) : null;
+}
+// Ranges
+/** Between the start and the end of a range written as text: an en dash with a space on each side. */
+export const DATE_RANGE_SEPARATOR = " – ";
+/** Reads a range input as two ISO dates, `null` for an end not given. A start after the end is swapped. */
+export function toDateRange(input) {
+    const start = toIsoDate(input?.[0]);
+    const end = toIsoDate(input?.[1]);
+    return start && end && start > end ? [end, start] : [start, end];
+}
+/**
+ * Writes a range as "start – end" in a calendar and format: "2026-09-17 – 2026-09-24". With only a start it is
+ * "2026-09-17 –", with only an end "– 2026-09-24", and "" when empty.
+ */
+export function formatDateRange(input, options = {}) {
+    const [start, end] = toDateRange(input);
+    const from = formatDate(start, options);
+    const to = formatDate(end, options);
+    if (from && to)
+        return from + DATE_RANGE_SEPARATOR + to;
+    if (from)
+        return from + DATE_RANGE_SEPARATOR.trimEnd();
+    if (to)
+        return DATE_RANGE_SEPARATOR.trimStart() + to;
+    return "";
+}
+// What separates the two dates of a typed range: an en or em dash or an arrow, or a hyphen or "to" between spaces.
+const RANGE_SEPARATOR_PATTERN = /\s*[–—→]+\s*|\s+(?:-+|to)\s+/i;
+/**
+ * Reads a range the user typed: two dates, each read like `parseDateText`, around " – ", " - ", "—", "→", or " to ",
+ * e.g. "17/9/2026 - 24/9/2026" or "2026-09-17 to 2026-09-24". A date on its own, or with a separator after it, gives
+ * `[date, null]`; a separator before it gives `[null, date]`; an end before the start is swapped. "" gives an empty
+ * range, and text that is not a range gives `null`.
+ */
+export function parseDateRangeText(text, options = {}) {
+    const clean = text.trim();
+    if (!clean)
+        return [null, null];
+    let parts = clean.split(RANGE_SEPARATOR_PATTERN);
+    // "17/09/2026-24/09/2026": a lone hyphen splits the dates when the format has no hyphen of its own.
+    if (parts.length === 1 && !resolve(options).format.includes("-") && clean.indexOf("-") === clean.lastIndexOf("-"))
+        parts = clean.split("-");
+    if (parts.length > 2)
+        return null;
+    const [from = "", to = ""] = parts.map(part => part.trim());
+    const start = from ? parseDateText(from, options) : null;
+    const end = to ? parseDateText(to, options) : null;
+    if ((from && !start) || (to && !end))
+        return null;
+    return toDateRange([start, end]);
+}

package/dist/Helpers/DatePreferences.d.ts

@@ -0,0 +1,14 @@
+import { type DatePreferences } from "../Interfaces/DateInterfaces.ts";
+/** The saved date settings, with the defaults for anything missing or invalid. Safe to call on the server. */
+export declare function readDatePreferences(): Required<DatePreferences>;
+/** Saves date and time settings and updates every date and time component on the page. Settings left out keep their value. */
+export declare function setDatePreferences(changes: Partial<DatePreferences>): void;
+/** Calls back when the settings change here or in another tab. Returns the function that stops listening. */
+export declare function subscribeDatePreferences(listener: () => void): () => void;
+/** The current date and time settings; the component renders again when they change. */
+export declare function useDatePreferences(): Required<DatePreferences>;
+/**
+ * The browser's time zone, such as "Asia/Kathmandu", or `null` on the server and while the page hydrates, where it is
+ * not known yet: a date-time shows nothing until then rather than another zone's time.
+ */
+export declare function useBrowserTimeZone(): string | null;

package/dist/Helpers/DatePreferences.js

@@ -0,0 +1,94 @@
+"use client";
+import { useSyncExternalStore } from "react";
+import { DATE_STORAGE_KEYS, DEFAULT_DATE_PREFERENCES } from "../Interfaces/DateInterfaces.js";
+import { getBrowserTimeZone } from "./DateTimeHelpers.js";
+/*
+ * The user's date settings: the calendar (English or Nepali), the format, the script of Nepali dates, and the time
+ * format. They are saved in local storage under the DATE_STORAGE_KEYS and read by every date and time component, so
+ * a settings page changes every date on the page at once, and in other open tabs. Without a saved value, the defaults
+ * apply. On the server there is no storage, so pages render with the defaults and take the saved settings right
+ * after hydration.
+ */
+const listeners = new Set();
+let snapshot = DEFAULT_DATE_PREFERENCES;
+function read(key) {
+    try {
+        return localStorage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+/** The saved date settings, with the defaults for anything missing or invalid. Safe to call on the server. */
+export function readDatePreferences() {
+    if (typeof localStorage === "undefined")
+        return DEFAULT_DATE_PREFERENCES;
+    const calendar = read(DATE_STORAGE_KEYS.calendar);
+    const format = read(DATE_STORAGE_KEYS.format)?.trim();
+    const script = read(DATE_STORAGE_KEYS.script);
+    const timeFormat = read(DATE_STORAGE_KEYS.timeFormat)?.trim();
+    const next = {
+        calendar: calendar === "bs" ? "bs" : DEFAULT_DATE_PREFERENCES.calendar,
+        format: format || DEFAULT_DATE_PREFERENCES.format,
+        script: script === "devanagari" ? "devanagari" : DEFAULT_DATE_PREFERENCES.script,
+        timeFormat: timeFormat || DEFAULT_DATE_PREFERENCES.timeFormat,
+    };
+    // The same object while nothing changed, so React sees a stable snapshot.
+    if (next.calendar !== snapshot.calendar ||
+        next.format !== snapshot.format ||
+        next.script !== snapshot.script ||
+        next.timeFormat !== snapshot.timeFormat) {
+        snapshot = next;
+    }
+    return snapshot;
+}
+/** Saves date and time settings and updates every date and time component on the page. Settings left out keep their value. */
+export function setDatePreferences(changes) {
+    try {
+        if (changes.calendar !== undefined)
+            localStorage.setItem(DATE_STORAGE_KEYS.calendar, changes.calendar);
+        if (changes.format !== undefined)
+            localStorage.setItem(DATE_STORAGE_KEYS.format, changes.format);
+        if (changes.script !== undefined)
+            localStorage.setItem(DATE_STORAGE_KEYS.script, changes.script);
+        if (changes.timeFormat !== undefined)
+            localStorage.setItem(DATE_STORAGE_KEYS.timeFormat, changes.timeFormat);
+    }
+    catch {
+        // Storage blocked (private mode, for example): the components keep what they have.
+    }
+    for (const listener of listeners)
+        listener();
+}
+// One storage listener for the page, however many date components are mounted.
+const STORAGE_KEY_LIST = Object.values(DATE_STORAGE_KEYS);
+const onStorage = (event) => {
+    if (event.key === null || STORAGE_KEY_LIST.includes(event.key))
+        for (const listener of listeners)
+            listener();
+};
+/** Calls back when the settings change here or in another tab. Returns the function that stops listening. */
+export function subscribeDatePreferences(listener) {
+    if (listeners.size === 0)
+        window.addEventListener("storage", onStorage);
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0)
+            window.removeEventListener("storage", onStorage);
+    };
+}
+const serverSnapshot = () => DEFAULT_DATE_PREFERENCES;
+/** The current date and time settings; the component renders again when they change. */
+export function useDatePreferences() {
+    return useSyncExternalStore(subscribeDatePreferences, readDatePreferences, serverSnapshot);
+}
+const noSubscription = () => () => { };
+const unknownTimeZone = () => null;
+/**
+ * The browser's time zone, such as "Asia/Kathmandu", or `null` on the server and while the page hydrates, where it is
+ * not known yet: a date-time shows nothing until then rather than another zone's time.
+ */
+export function useBrowserTimeZone() {
+    return useSyncExternalStore(noSubscription, getBrowserTimeZone, unknownTimeZone);
+}

package/dist/Helpers/DateTimeHelpers.d.ts

@@ -0,0 +1,87 @@
+import { type DatePreferences, type DateScript, type DateTimeInput, type LocalDateTime, type TimeInput } from "../Interfaces/DateInterfaces.ts";
+/** A UTC date-time as `toISOString` writes it: "2026-09-17T08:45:00.000Z". */
+export declare const UTC_DATE_TIME_PATTERN: RegExp;
+/** Whether text is a date-time value in the shape the components give, "2026-09-17T08:45:00.000Z", on a day that exists. */
+export declare function isUtcDateTime(text: unknown): text is string;
+/** The browser's time zone as an IANA id, such as "Asia/Kathmandu"; "UTC" where Intl does not tell. Read once. */
+export declare function getBrowserTimeZone(): string;
+/** A zone's current IANA id ("asia/katmandu" gives "Asia/Kathmandu"), or `null` for a zone Intl does not know. */
+export declare function toTimeZone(timeZone: string | null | undefined): string | null;
+/** The zone to show moments in: `timeZone` when Intl knows it, otherwise the browser's. */
+export declare const resolveTimeZone: (timeZone?: string | null) => string;
+/** An offset in minutes as "UTC+05:45", "UTC-04:00", or "UTC+00:00". */
+export declare function formatUtcOffset(minutes: number): string;
+/** Minutes a zone's clocks are ahead of UTC at a moment (now by default): 345 in Kathmandu, -240 in New York in summer. */
+export declare function getTimeZoneOffset(timeZone?: string, at?: DateTimeInput): number;
+/** How a zone reads to a person at a moment. */
+export interface TimeZoneInfo {
+    /** The IANA id: "Asia/Kathmandu". */
+    id: string;
+    /** The last part of the id, for short labels: "Kathmandu", "New York", "UTC". */
+    city: string;
+    /** "UTC+05:45" */
+    offset: string;
+    /** The long English name at that moment: "Nepal Time", "Eastern Daylight Time". */
+    name: string;
+}
+/** Names a zone (the browser's by default) at a moment (now by default): its id, a city, its offset, and its long name. */
+export declare function describeTimeZone(timeZone?: string, at?: DateTimeInput): TimeZoneInfo;
+/**
+ * Turns anything a moment can arrive as into the value the components hold, a UTC ISO string, or `null`:
+ * - "2026-09-17T08:45:00Z" or "2026-09-17T14:30:00+05:45" is that moment: "2026-09-17T08:45:00.000Z";
+ * - "2026-09-17T08:45:00", without a zone, is read as UTC (see `DateTimeInput`);
+ * - "2026-09-17" is the first moment of that day in `timeZone` (the browser's by default);
+ * - a `Date` or milliseconds since 1970 is that moment.
+ * Text that is not a date-time, a day that does not exist, or a year past 9999 gives `null`.
+ */
+export declare function toUtcDateTime(input: DateTimeInput, timeZone?: string): string | null;
+/** Now, as a UTC ISO string. */
+export declare function nowUtcDateTime(): string;
+/**
+ * The date and the time of day a moment shows in a zone (the browser's by default): "2026-09-17T08:45:00Z" is
+ * `{ date: "2026-09-17", time: "14:30:00" }` in Kathmandu. Milliseconds are dropped. `null` for an input that is not a moment.
+ */
+export declare function toLocalDateTime(input: DateTimeInput, timeZone?: string): LocalDateTime | null;
+/**
+ * The moment a date and a time of day name in a zone (the browser's by default), as a UTC ISO string:
+ * `fromLocalDateTime("2026-09-17", "14:30", "Asia/Kathmandu")` is "2026-09-17T08:45:00.000Z". When clocks go back, a
+ * time that happens twice is the first of the two, or, with `reference` (the moment being changed), the one at the
+ * reference's offset, so an edit near the second 01:30 stays in the second hour. When clocks go forward, a skipped time
+ * moves forward by the gap. `null` when the date or the time is not valid.
+ */
+export declare function fromLocalDateTime(date: string, time: TimeInput, timeZone?: string, reference?: DateTimeInput): string | null;
+/** Today's date in a zone (the browser's by default). */
+export declare function todayIsoDateIn(timeZone?: string): string;
+/** Options of `formatDateTime`, `parseDateTimeText`, and `validateDateTime`: the date settings, the time format, and the zone. */
+export interface DateTimeFormatOptions extends Partial<DatePreferences> {
+    /** IANA id of the zone moments are shown in, such as "Asia/Kathmandu". Default: the browser's. */
+    timeZone?: string;
+    /** Whether times have seconds: `true` adds them to a time format without them, `false` removes them. Default: as the time format says. */
+    seconds?: boolean;
+}
+/** The script of a date-time's time: Devanagari digits when its date is Nepali in Devanagari, as `DatePicker` and `TimePicker` agree. */
+export declare const timeScriptOf: (options: Partial<DatePreferences>) => DateScript;
+/**
+ * Writes a moment as the date and the time it shows in a zone, in the date and time formats: "2026-09-17 02:30 PM"
+ * for "2026-09-17T08:45:00Z" in Kathmandu with the default settings, "२०८३-०६-०१ ०२:३० अपराह्न" in the Nepali calendar
+ * in Devanagari. Returns "" for an empty or invalid input.
+ */
+export declare function formatDateTime(input: DateTimeInput, options?: DateTimeFormatOptions): string;
+/**
+ * Reads a date and time the user typed as the wall clock they name: the date as `parseDateText` reads it in the
+ * calendar and format, then a time of day as `parseTimeText` reads it, on either clock. "17/09/2026 2:30 pm",
+ * "2026-09-17T14:30", "Sep 17, 2026 at 14:30", and "२०८३-०६-०१ ०२:३० अपराह्न" all work. The time has seconds
+ * ("14:30:00"); a date typed without a time gives `time: null`. Returns `null` for text that is not a date.
+ */
+export declare function parseLocalDateTimeText(text: string, options?: DateTimeFormatOptions): {
+    date: string;
+    time: string | null;
+} | null;
+/**
+ * Reads a date and time the user typed (see `parseLocalDateTimeText`) as the moment it names in `options.timeZone`,
+ * a UTC ISO string. With `seconds: false`, typed seconds are dropped. A date typed without a time takes
+ * `defaultTime`, when there is one. Returns `null` for text that is not a date and time.
+ */
+export declare function parseDateTimeText(text: string, options?: DateTimeFormatOptions & {
+    defaultTime?: TimeInput;
+}): string | null;