nexus-shared 1.1.20 → 2.0.0

package/dist/Helpers/DateTimeHelpers.js

@@ -0,0 +1,286 @@
+import { DEFAULT_DATE_PREFERENCES } from "../Interfaces/DateInterfaces.js";
+import { dayNumberToIsoDate, daysFromCivil, formatDate, isIsoDate, isoDateToDayNumber, parseDateText, partsToIsoDate, toLatinDigits, usesDevanagari } from "./DateHelpers.js";
+import { formatTime, parseTimeText, secondsToIsoTime, timeToSeconds, toIsoTime } from "./TimeHelpers.js";
+/*
+ * Pure date-time helpers. A date-time value is a moment, held as a UTC ISO string in the shape `toISOString` writes:
+ * "2026-09-17T08:45:00.000Z". It is the same moment on every machine, so a time saved in Kathmandu is still that
+ * moment when it is opened in London, and values of this one shape sort as text. People see and pick it as a date and
+ * a time of day in a time zone: the browser's by default, or one named by its IANA id ("Asia/Kathmandu",
+ * "America/New_York", "UTC"). Intl supplies each zone's offsets and daylight saving rules; the date and the time are
+ * then written and read like `formatDate` and `formatTime`.
+ */
+const MS_PER_SECOND = 1000;
+const MS_PER_MINUTE = 60_000;
+const MS_PER_DAY = 86_400_000;
+const pad = (value) => String(value).padStart(2, "0");
+/** A UTC date-time as `toISOString` writes it: "2026-09-17T08:45:00.000Z". */
+export const UTC_DATE_TIME_PATTERN = /^\d{4}-\d{2}-\d{2}T([01]\d|2[0-3]):[0-5]\d:[0-5]\d\.\d{3}Z$/;
+/** 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 function isUtcDateTime(text) {
+    return typeof text === "string" && UTC_DATE_TIME_PATTERN.test(text) && isIsoDate(text.slice(0, 10));
+}
+/** The value of milliseconds since 1970, or `null` outside years 1 to 9999, where ISO strings have four-digit years. */
+function msToUtcDateTime(ms) {
+    if (!Number.isFinite(ms))
+        return null;
+    const date = new Date(ms);
+    const year = date.getUTCFullYear();
+    return Number.isNaN(date.getTime()) || year < 1 || year > 9999 ? null : date.toISOString();
+}
+/** A wall-clock date and time counted as if it were UTC: the side of a zone's offset that people read. */
+const wallMs = (date, seconds) => isoDateToDayNumber(date) * MS_PER_DAY + seconds * MS_PER_SECOND;
+// Time zones
+const zoneFormatters = new Map();
+const knownZones = new Map();
+let browserZone = null;
+function zoneFormatter(timeZone) {
+    let formatter = zoneFormatters.get(timeZone);
+    if (!formatter) {
+        formatter = new Intl.DateTimeFormat("en-US", { timeZone, hourCycle: "h23", year: "numeric", month: "numeric", day: "numeric", hour: "numeric", minute: "numeric", second: "numeric" });
+        zoneFormatters.set(timeZone, formatter);
+    }
+    return formatter;
+}
+/** Milliseconds a zone's clocks are ahead of UTC at a moment: 20,700,000 (+05:45) in Kathmandu. Whole seconds. */
+function zoneOffsetMs(ms, timeZone) {
+    const whole = Math.floor(ms / MS_PER_SECOND) * MS_PER_SECOND;
+    const parts = {};
+    for (const part of zoneFormatter(timeZone).formatToParts(whole))
+        parts[part.type] = Number(part.value);
+    const { year = 1970, month = 1, day = 1, hour = 0, minute = 0, second = 0 } = parts;
+    return daysFromCivil(year, month, day) * MS_PER_DAY + (hour * 3600 + minute * 60 + second) * MS_PER_SECOND - whole;
+}
+// Intl (through CLDR) still names some zones by their old spellings; people read the current IANA ids. Intl accepts both.
+const CURRENT_ZONE_IDS = {
+    "Africa/Asmera": "Africa/Asmara",
+    "America/Buenos_Aires": "America/Argentina/Buenos_Aires",
+    "America/Catamarca": "America/Argentina/Catamarca",
+    "America/Coral_Harbour": "America/Atikokan",
+    "America/Cordoba": "America/Argentina/Cordoba",
+    "America/Godthab": "America/Nuuk",
+    "America/Indianapolis": "America/Indiana/Indianapolis",
+    "America/Jujuy": "America/Argentina/Jujuy",
+    "America/Louisville": "America/Kentucky/Louisville",
+    "America/Mendoza": "America/Argentina/Mendoza",
+    "Asia/Calcutta": "Asia/Kolkata",
+    "Asia/Katmandu": "Asia/Kathmandu",
+    "Asia/Rangoon": "Asia/Yangon",
+    "Asia/Saigon": "Asia/Ho_Chi_Minh",
+    "Atlantic/Faeroe": "Atlantic/Faroe",
+    "Europe/Kiev": "Europe/Kyiv",
+    "Pacific/Enderbury": "Pacific/Kanton",
+    "Pacific/Ponape": "Pacific/Pohnpei",
+    "Pacific/Truk": "Pacific/Chuuk",
+};
+const currentZoneId = (id) => CURRENT_ZONE_IDS[id] ?? id;
+/** The browser's time zone as an IANA id, such as "Asia/Kathmandu"; "UTC" where Intl does not tell. Read once. */
+export function getBrowserTimeZone() {
+    if (browserZone === null) {
+        try {
+            browserZone = currentZoneId(new Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC");
+        }
+        catch {
+            browserZone = "UTC";
+        }
+    }
+    return browserZone;
+}
+/** A zone's current IANA id ("asia/katmandu" gives "Asia/Kathmandu"), or `null` for a zone Intl does not know. */
+export function toTimeZone(timeZone) {
+    if (!timeZone)
+        return null;
+    let id = knownZones.get(timeZone);
+    if (id === undefined) {
+        try {
+            id = currentZoneId(new Intl.DateTimeFormat("en-US", { timeZone }).resolvedOptions().timeZone);
+        }
+        catch {
+            id = null;
+        }
+        knownZones.set(timeZone, id);
+    }
+    return id;
+}
+/** The zone to show moments in: `timeZone` when Intl knows it, otherwise the browser's. */
+export const resolveTimeZone = (timeZone) => toTimeZone(timeZone) ?? getBrowserTimeZone();
+/** An offset in minutes as "UTC+05:45", "UTC-04:00", or "UTC+00:00". */
+export function formatUtcOffset(minutes) {
+    const whole = Math.round(minutes);
+    const size = Math.abs(whole);
+    return `UTC${whole < 0 ? "-" : "+"}${pad(Math.floor(size / 60))}:${pad(size % 60)}`;
+}
+/** 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 function getTimeZoneOffset(timeZone, at = Date.now()) {
+    const zone = resolveTimeZone(timeZone);
+    return Math.round(zoneOffsetMs(instantMs(at, zone) ?? Date.now(), zone) / MS_PER_MINUTE);
+}
+/** 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 function describeTimeZone(timeZone, at = Date.now()) {
+    const id = resolveTimeZone(timeZone);
+    const ms = instantMs(at, id) ?? Date.now();
+    const city = id.slice(id.lastIndexOf("/") + 1).replaceAll("_", " ");
+    let name = id;
+    try {
+        name = new Intl.DateTimeFormat("en-US", { timeZone: id, timeZoneName: "long" }).formatToParts(ms).find(part => part.type === "timeZoneName")?.value ?? id;
+    }
+    catch {
+        // Keeps the id.
+    }
+    return { id, city, offset: formatUtcOffset(zoneOffsetMs(ms, id) / MS_PER_MINUTE), name };
+}
+// Moments and wall clocks
+/**
+ * The moment a wall-clock date and time name in a zone. A time that happens twice, when clocks go back, is the one at
+ * `preferredOffset` when that is one of the two, otherwise the first; a time that is skipped, when clocks go forward,
+ * moves forward by the gap, so 02:30 on that night is 03:30. `Date` and Temporal resolve both the same way.
+ */
+function localToMs(date, seconds, timeZone, preferredOffset = null) {
+    const wall = wallMs(date, seconds);
+    // The offsets a day before and a day after are the zone's offsets on either side of any change of clocks near this time.
+    const before = zoneOffsetMs(wall - MS_PER_DAY, timeZone);
+    const after = zoneOffsetMs(wall + MS_PER_DAY, timeZone);
+    const early = wall - before;
+    if (before === after)
+        return early;
+    const matches = [early, wall - after].filter(ms => zoneOffsetMs(ms, timeZone) === wall - ms);
+    if (preferredOffset !== null && matches.includes(wall - preferredOffset))
+        return wall - preferredOffset;
+    // Skipped: the offset from before the change carries the time forward, past the gap.
+    return matches.length > 0 ? Math.min(...matches) : early;
+}
+// "2026-09-17", "2026-09-17T14:30", "2026-09-17 14:30:15.250", each with an optional "Z" or offset: +05:45, +0545, +05.
+const DATE_TIME_TEXT = /^(\d{4})-(\d{1,2})-(\d{1,2})(?:[T ](\d{1,2}):(\d{2})(?::(\d{2})(?:[.,](\d+))?)?\s*(Z|[+-]\d{2}(?::?\d{2})?)?)?$/i;
+/** Milliseconds since 1970 of anything a moment can arrive as (see `DateTimeInput`), or `null`. */
+function instantMs(input, timeZone) {
+    if (input === null || input === undefined || input === "")
+        return null;
+    if (input instanceof Date)
+        return Number.isNaN(input.getTime()) ? null : input.getTime();
+    if (typeof input === "number")
+        return Number.isFinite(input) ? input : null;
+    if (typeof input !== "string")
+        return null;
+    const match = DATE_TIME_TEXT.exec(input.trim());
+    if (!match)
+        return null;
+    const date = partsToIsoDate({ year: Number(match[1]), month: Number(match[2]), day: Number(match[3]) });
+    if (!isIsoDate(date))
+        return null;
+    // A day alone: its first moment in the zone.
+    if (match[4] === undefined)
+        return localToMs(date, 0, timeZone);
+    const hour = Number(match[4]);
+    const minute = Number(match[5]);
+    const second = Number(match[6] ?? 0);
+    if (hour > 23 || minute > 59 || second > 59)
+        return null;
+    const wall = wallMs(date, hour * 3600 + minute * 60 + second) + Number((match[7] ?? "").slice(0, 3).padEnd(3, "0"));
+    const zone = match[8];
+    // No zone: UTC, the way a .NET DateTime saved as UTC often comes back without its "Z".
+    if (!zone || zone.toUpperCase() === "Z")
+        return wall;
+    const digits = zone.slice(1).replace(":", "");
+    const offsetHours = Number(digits.slice(0, 2));
+    const offsetMinutes = Number(digits.slice(2) || 0);
+    if (offsetHours > 23 || offsetMinutes > 59)
+        return null;
+    return wall - (zone[0] === "-" ? -1 : 1) * (offsetHours * 60 + offsetMinutes) * MS_PER_MINUTE;
+}
+/**
+ * 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 function toUtcDateTime(input, timeZone) {
+    const ms = instantMs(input, resolveTimeZone(timeZone));
+    return ms === null ? null : msToUtcDateTime(ms);
+}
+/** Now, as a UTC ISO string. */
+export function nowUtcDateTime() {
+    return new Date().toISOString();
+}
+/**
+ * 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 function toLocalDateTime(input, timeZone) {
+    const zone = resolveTimeZone(timeZone);
+    const ms = instantMs(input, zone);
+    if (ms === null || msToUtcDateTime(ms) === null)
+        return null;
+    const wall = Math.floor(ms / MS_PER_SECOND) * MS_PER_SECOND + zoneOffsetMs(ms, zone);
+    const dayNumber = Math.floor(wall / MS_PER_DAY);
+    return { date: dayNumberToIsoDate(dayNumber), time: secondsToIsoTime((wall - dayNumber * MS_PER_DAY) / MS_PER_SECOND, true) };
+}
+/**
+ * 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 function fromLocalDateTime(date, time, timeZone, reference) {
+    const iso = toIsoTime(time, true);
+    if (!isIsoDate(date) || !iso)
+        return null;
+    const zone = resolveTimeZone(timeZone);
+    const referenceMs = instantMs(reference, zone);
+    return msToUtcDateTime(localToMs(date, timeToSeconds(iso), zone, referenceMs === null ? null : zoneOffsetMs(referenceMs, zone)));
+}
+/** Today's date in a zone (the browser's by default). */
+export function todayIsoDateIn(timeZone) {
+    return toLocalDateTime(Date.now(), timeZone).date;
+}
+/** The script of a date-time's time: Devanagari digits when its date is Nepali in Devanagari, as `DatePicker` and `TimePicker` agree. */
+export const timeScriptOf = (options) => usesDevanagari(options.calendar ?? DEFAULT_DATE_PREFERENCES.calendar, options.script) ? "devanagari" : "latin";
+/**
+ * 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 function formatDateTime(input, options = {}) {
+    const local = toLocalDateTime(input, options.timeZone);
+    if (!local)
+        return "";
+    return `${formatDate(local.date, options)} ${formatTime(local.time, { format: options.timeFormat, script: timeScriptOf(options), seconds: options.seconds })}`;
+}
+// Words that may stand between a typed date and its time: "Sep 17, 2026 at 2:30 PM".
+const DATE_TIME_JOINER = /(?:[\s,]+(?:at|@))?[\s,]*$/i;
+/**
+ * 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 function parseLocalDateTimeText(text, options = {}) {
+    const clean = toLatinDigits(text).trim().replace(/(\d)T(\d)/i, "$1 $2");
+    if (!clean)
+        return null;
+    const words = clean.split(/\s+/);
+    // The time is the last word or two ("14:30", "2:30 pm"); the date is what stands before it.
+    for (let cut = words.length - 1; cut >= Math.max(1, words.length - 2); cut--) {
+        const time = parseTimeText(words.slice(cut).join(" "), { seconds: true });
+        if (!time)
+            continue;
+        const date = parseDateText(words.slice(0, cut).join(" ").replace(DATE_TIME_JOINER, ""), options);
+        if (date)
+            return { date, time };
+    }
+    const date = parseDateText(clean, options);
+    return date ? { date, time: 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 function parseDateTimeText(text, options = {}) {
+    const local = parseLocalDateTimeText(text, options);
+    const time = local?.time ?? toIsoTime(options.defaultTime, true);
+    if (!local || !time)
+        return null;
+    return fromLocalDateTime(local.date, options.seconds === false ? time.slice(0, 5) : time, options.timeZone);
+}

package/dist/Helpers/DragHelpers.d.ts

@@ -0,0 +1,129 @@
+import { type RefObject } from "react";
+/** A box in viewport pixels. */
+export interface BoundsRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** A point, or an offset, in pixels. */
+export interface DragPoint {
+    x: number;
+    y: number;
+}
+/**
+ * Where a dragged element may go: `viewport` (the browser window), `parent` (inside the borders of the element its
+ * position is measured from, else its parent), an element (inside its borders), a fixed box, a function returning a
+ * box when the drag starts, or `null` for anywhere.
+ */
+export type DragBounds = "viewport" | "parent" | Element | BoundsRect | (() => BoundsRect | null) | null;
+export interface ClampOptions {
+    /** Space kept from the edges of the bounds, in pixels. Default 0. */
+    margin?: number;
+    /**
+     * How many pixels of the box must stay inside. Leave it out to keep the whole box inside; a box larger than the bounds
+     * then lines up with their top and left edges, so a window's title bar stays reachable.
+     */
+    keepVisible?: number;
+}
+/** Reads and writes a target's position: an offset in pixels from where the layout puts it. */
+export interface DragPosition {
+    get: () => DragPoint;
+    set: (point: DragPoint) => void;
+}
+/** What a drag callback receives. */
+export interface DragState {
+    /** The target being moved. */
+    target: HTMLElement;
+    /** The pointer where the press started, in viewport pixels. */
+    start: DragPoint;
+    /** The pointer now, in viewport pixels. */
+    pointer: DragPoint;
+    /** The target's position: an offset from its place in the layout. */
+    position: DragPoint;
+    /** How far the target has moved since the drag started, after the bounds. */
+    delta: DragPoint;
+}
+export interface DragOptions extends ClampOptions {
+    /** Where the target may go. Default `viewport`; `null` lets it go anywhere. */
+    bounds?: DragBounds;
+    /** Move along one axis only. Default `both`. */
+    axis?: "x" | "y" | "both";
+    /** How far the pointer must travel before the target moves, in pixels, so a click or a double-click stays one. Default 3. */
+    threshold?: number;
+    /** Reads and writes the position. Default: the target's CSS `translate` property (`translatePosition`). */
+    position?: DragPosition;
+    /**
+     * When the pointer has passed the threshold, before the target moves. Return `false` to cancel the drag. It may change
+     * the target first (restore a maximized window, for example); the position and the bounds are read after it.
+     */
+    onStart?: (state: DragState) => void | false;
+    /** On every move, after the position is written. */
+    onMove?: (state: DragState) => void;
+    /** When the drag ends; `cancelled` is true when Esc put the target back where it started. */
+    onEnd?: (state: DragState, cancelled: boolean) => void;
+}
+export interface StartDragOptions extends DragOptions {
+    /** The element that moves. */
+    target: HTMLElement;
+    /** The element pressed, which keeps the pointer while dragging. Default: the event's current target, else the target. In React, pass `event.currentTarget`. */
+    handle?: Element;
+}
+export interface DraggableOptions extends DragOptions {
+    /** The element that moves. Default: the handle itself. `null` (a ref not set yet) starts no drag. */
+    target?: HTMLElement | null | (() => HTMLElement | null);
+    /** A press on an element matching this selector, inside the handle, does not start a drag. Default: buttons, links, and form controls. */
+    cancel?: string;
+    /** Whether a press may start a drag now. */
+    enabled?: () => boolean;
+}
+/** Controls inside a handle keep their own clicks and text selection. */
+export declare const DRAG_CANCEL_SELECTOR = "button, a[href], input, select, textarea, label, summary, [contenteditable]:not([contenteditable=\"false\"]), [data-nx-no-drag]";
+/** The browser window, without its scrollbars. */
+export declare function viewportBounds(): BoundsRect;
+/** The inside of an element's borders (its padding box), without a scrollbar, in viewport pixels. */
+export declare function elementBounds(element: Element): BoundsRect;
+/** Turns a `DragBounds` into a box, for an element being moved. */
+export declare function resolveBounds(bounds: DragBounds | undefined, element: HTMLElement): BoundsRect | null;
+/**
+ * The top-left corner a box must move to, the least distance, to stay inside bounds.
+ *
+ * @example clampToBounds({ left: -20, top: 40, width: 300, height: 200 }, viewportBounds()) // { x: 0, y: 40 }
+ */
+export declare function clampToBounds(box: BoundsRect, bounds: BoundsRect, options?: ClampOptions): DragPoint;
+/** The default position: the element's inline CSS `translate`, in pixels. */
+export declare function translatePosition(element: HTMLElement): DragPosition;
+/** A position kept in two CSS variables on the element, for a stylesheet that places it with them (and can ignore them, e.g. when maximized). */
+export declare function cssVariablePosition(element: HTMLElement, xVariable: string, yVariable: string): DragPosition;
+/**
+ * Moves an element by an offset, kept inside bounds, and returns its new position. With no offset it pulls an element
+ * back inside, e.g. after the window got smaller or the element grew. Also the way to move an element from the keyboard.
+ */
+export declare function moveWithin(element: HTMLElement, by: DragPoint, options?: Omit<DragOptions, "threshold" | "onStart" | "onMove" | "onEnd">): DragPoint;
+/**
+ * Starts dragging `target` from a `pointerdown` event, e.g. in a React `onPointerDown` on a title bar. The target
+ * follows the pointer once it has moved past the threshold, stays inside the bounds, and goes back where it started on
+ * Esc. The handle needs `touch-action: none` in its CSS, or a touch pans the page instead. Returns a function that ends
+ * the drag early.
+ */
+export declare function startDrag(event: PointerEvent, options: StartDragOptions): () => void;
+/**
+ * Makes `handle` drag `options.target` (or itself), and returns a function that stops it. Options can be a function,
+ * read at every press, so a component can pass its latest props.
+ *
+ * @example
+ * const stop = makeDraggable(card.querySelector(".title"), { target: card, bounds: "parent" });
+ */
+export declare function makeDraggable(handle: HTMLElement, options?: DraggableOptions | (() => DraggableOptions)): () => void;
+/**
+ * React: the element in `handleRef` drags the target (or itself). The options may change on every render; the latest
+ * are used at each press.
+ *
+ * @example
+ * const card = useRef<HTMLDivElement>(null);
+ * const title = useRef<HTMLDivElement>(null);
+ * useDraggable(title, { target: () => card.current, bounds: "parent" });
+ */
+export declare function useDraggable(handleRef: RefObject<HTMLElement | null>, options?: DraggableOptions & {
+    disabled?: boolean;
+}): void;