nexus-shared 1.1.20 → 2.0.0

package/dist/Helpers/TimeHelpers.js

@@ -0,0 +1,253 @@
+import { DEFAULT_TIME_FORMAT } from "../Interfaces/DateInterfaces.js";
+import { toDevanagariDigits, toLatinDigits } from "./DateHelpers.js";
+/*
+ * Pure time helpers. A time of day is an ISO string "HH:mm" or "HH:mm:ss" on a 24-hour clock, with no date and no zone,
+ * so the same value means the same time on every machine (a .NET `TimeOnly`). Arithmetic runs on seconds since
+ * midnight. How a time is written (12 or 24 hours, Devanagari digits) is only its display.
+ */
+export const SECONDS_PER_DAY = 86400;
+/** "14:30" or "14:30:15": hours 00 to 23, a two-digit minute, an optional two-digit second. */
+export const ISO_TIME_PATTERN = /^([01]\d|2[0-3]):([0-5]\d)(?::([0-5]\d))?$/;
+const pad = (value) => String(value).padStart(2, "0");
+/** Whether text is an ISO time: "14:30" or "14:30:15". */
+export function isIsoTime(text) {
+    return typeof text === "string" && ISO_TIME_PATTERN.test(text);
+}
+/** Seconds since midnight of an ISO time. The text must be an ISO time (`isIsoTime`). */
+export function timeToSeconds(iso) {
+    return Number(iso.slice(0, 2)) * 3600 + Number(iso.slice(3, 5)) * 60 + (iso.length > 5 ? Number(iso.slice(6, 8)) : 0);
+}
+/** The ISO time of seconds since midnight, wrapping past midnight both ways: "HH:mm", or "HH:mm:ss" with `seconds`. */
+export function secondsToIsoTime(total, seconds = false) {
+    const value = ((Math.floor(total) % SECONDS_PER_DAY) + SECONDS_PER_DAY) % SECONDS_PER_DAY;
+    const time = `${pad(Math.floor(value / 3600))}:${pad(Math.floor(value / 60) % 60)}`;
+    return seconds ? `${time}:${pad(value % 60)}` : time;
+}
+/**
+ * Turns anything a time can arrive as into an ISO time, or `null`:
+ * - "14:30", "9:05", "14:30:15", "14:30:15.250" (a .NET `TimeOnly` or SQL `time`);
+ * - an ISO date-time with a zone, "2026-09-17T08:45:00Z", becomes the browser's local time of that instant;
+ * - one without a zone, "2026-09-17T14:30:00", keeps its time part;
+ * - a `Date` gives its local time, like `new Date()` for now.
+ * Without `seconds` the result is "HH:mm" and any seconds are dropped; with it, "HH:mm:ss".
+ */
+export function toIsoTime(input, seconds = false) {
+    if (input === null || input === undefined || input === "")
+        return null;
+    if (input instanceof Date) {
+        return Number.isNaN(input.getTime()) ? null : secondsToIsoTime(input.getHours() * 3600 + input.getMinutes() * 60 + input.getSeconds(), seconds);
+    }
+    const text = input.trim();
+    const time = /^(\d{1,2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?$/.exec(text);
+    if (time) {
+        const hour = Number(time[1]);
+        const minute = Number(time[2]);
+        const second = Number(time[3] ?? 0);
+        if (hour > 23 || minute > 59 || second > 59)
+            return null;
+        return secondsToIsoTime(hour * 3600 + minute * 60 + second, seconds);
+    }
+    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 toIsoTime(dateTime[1], seconds);
+    return toIsoTime(new Date(text), seconds);
+}
+/** The time now where the browser is. */
+export function nowIsoTime(seconds = false) {
+    return toIsoTime(new Date(), seconds);
+}
+/** Adds minutes (negative to go back), wrapping past midnight: `addMinutes("23:30", 45)` is "00:15". Keeps the value's seconds. */
+export function addMinutes(iso, minutes) {
+    return secondsToIsoTime(timeToSeconds(iso) + minutes * 60, iso.length > 5);
+}
+/** Negative when `a` is earlier than `b`. "14:30" and "14:30:00" are the same time. */
+export const compareIsoTimes = (a, b) => timeToSeconds(a) - timeToSeconds(b);
+/**
+ * Whether a time lies within inclusive limits, given as seconds since midnight. With `max` earlier than `min` the
+ * range runs past midnight: 22:00 to 06:00 allows 23:00 and 05:00, not 12:00.
+ */
+export function isSecondsInRange(value, min, max) {
+    if (min !== null && max !== null && max < min)
+        return value >= min || value <= max;
+    return (min === null || value >= min) && (max === null || value <= max);
+}
+/** Whether an ISO time lies within limits given as time inputs; see `isSecondsInRange` for ranges past midnight. */
+export function isTimeInRange(iso, min, max) {
+    const from = toIsoTime(min, true);
+    const to = toIsoTime(max, true);
+    return isSecondsInRange(timeToSeconds(iso), from === null ? null : timeToSeconds(from), to === null ? null : timeToSeconds(to));
+}
+/** A step in seconds as the components use it: a whole number from 1 to a day, 60 when missing or invalid. */
+export function normalizeTimeStep(step) {
+    return step !== undefined && Number.isFinite(step) && step >= 1 ? Math.min(Math.round(step), SECONDS_PER_DAY) : 60;
+}
+/** Whether a step needs seconds: any step that is not a whole number of minutes. */
+export const stepHasSeconds = (step) => normalizeTimeStep(step) % 60 !== 0;
+/** "15 minutes", "1 hour", "30 seconds", "1 minute 30 seconds": a step as words, for messages. */
+export function describeTimeStep(step) {
+    const value = normalizeTimeStep(step);
+    const units = [
+        [Math.floor(value / 3600), "hour"],
+        [Math.floor(value / 60) % 60, "minute"],
+        [value % 60, "second"],
+    ];
+    return units
+        .filter(([count]) => count > 0)
+        .map(([count, unit]) => `${count} ${unit}${count === 1 ? "" : "s"}`)
+        .join(" ");
+}
+// Formatting and parsing
+const FORMAT_TOKENS = /HH|H|hh|h|mm|m|ss|s|A|a/g;
+const MERIDIEM_LATIN = ["AM", "PM"];
+const MERIDIEM_DEVANAGARI = ["पूर्वाह्न", "अपराह्न"];
+/** Whether a time format is on a 12-hour clock: it has an `hh` or `h` token. */
+export const isTwelveHourFormat = (format) => /h/.test(format);
+/** The names of the two halves of the day: AM and PM, or पूर्वाह्न and अपराह्न. */
+export function getMeridiemNames(script = "latin") {
+    return script === "devanagari" ? MERIDIEM_DEVANAGARI : MERIDIEM_LATIN;
+}
+/**
+ * A format with or without seconds: `true` adds ":ss" after the minutes of a format that has none ("hh:mm A" gives
+ * "hh:mm:ss A"), `false` removes the seconds and the separator before them. `undefined` keeps the format.
+ */
+export function timeFormatWithSeconds(format, seconds) {
+    if (seconds === undefined)
+        return format;
+    if (seconds)
+        return /s/.test(format) ? format : format.replace(/mm|m/, token => `${token}:ss`);
+    return format.replace(/[:.]?ss?/g, "");
+}
+/**
+ * Writes a time with a format of tokens: `HH` `H` 24-hour, `hh` `h` 12-hour, `mm` `m` minute, `ss` `s` second, `A`
+ * AM/PM, `a` am/pm. "hh:mm A" gives 02:30 PM; "HH:mm" gives 14:30. With the Devanagari script, digits and the
+ * halves of the day are Nepali: ०२:३० अपराह्न. Returns "" for an empty or invalid input.
+ */
+export function formatTime(input, options = {}) {
+    const iso = toIsoTime(input, true);
+    if (!iso)
+        return "";
+    const script = options.script ?? "latin";
+    const format = timeFormatWithSeconds(options.format || DEFAULT_TIME_FORMAT, options.seconds);
+    const total = timeToSeconds(iso);
+    const hour = Math.floor(total / 3600);
+    const hour12 = hour % 12 || 12;
+    const minute = Math.floor(total / 60) % 60;
+    const second = total % 60;
+    const digits = (value, width) => {
+        const text = width === 2 ? pad(value) : String(value);
+        return script === "devanagari" ? toDevanagariDigits(text) : text;
+    };
+    const meridiem = getMeridiemNames(script)[hour < 12 ? 0 : 1];
+    return format.replace(FORMAT_TOKENS, token => {
+        switch (token) {
+            case "HH":
+                return digits(hour, 2);
+            case "H":
+                return digits(hour, 1);
+            case "hh":
+                return digits(hour12, 2);
+            case "h":
+                return digits(hour12, 1);
+            case "mm":
+                return digits(minute, 2);
+            case "m":
+                return digits(minute, 1);
+            case "ss":
+                return digits(second, 2);
+            case "s":
+                return digits(second, 1);
+            case "A":
+                return meridiem;
+            default:
+                return script === "devanagari" ? meridiem : meridiem.toLowerCase();
+        }
+    });
+}
+/** AM or PM from the letters of typed text: "am", "a.m.", "A", "p", "PM", पूर्वाह्न, अपराह्न. `undefined` for other words. */
+function meridiemFromLetters(letters) {
+    if (!letters)
+        return null;
+    if (letters === "a" || letters === "am")
+        return "am";
+    if (letters === "p" || letters === "pm")
+        return "pm";
+    if (letters.startsWith("पूर्व") || letters.startsWith("पुर्व"))
+        return "am";
+    if (letters.startsWith("अपर"))
+        return "pm";
+    return undefined;
+}
+/**
+ * Reads a time the user typed, on either clock: "14:30", "2:30 pm", "2.30p", "230 PM", "1430", "9", "12 am",
+ * "14:30:15", "०२:३० अपराह्न". Without AM or PM the hours are read on a 24-hour clock, so "2:30" is 02:30. Returns the
+ * ISO time, "HH:mm" (typed seconds are dropped) or "HH:mm:ss" with `seconds`, or `null` for text that is not a time.
+ */
+export function parseTimeText(text, options = {}) {
+    const clean = toLatinDigits(text).trim().toLowerCase();
+    if (!clean)
+        return null;
+    const meridiem = meridiemFromLetters(clean.replace(/[^\p{L}\p{M}]/gu, ""));
+    if (meridiem === undefined)
+        return null;
+    // Only digits, separators, and the letters of AM or PM.
+    if (/[^\d\s:.\p{L}\p{M}]/u.test(clean))
+        return null;
+    const groups = clean.match(/\d+/g) ?? [];
+    let parts;
+    if (groups.length === 1) {
+        const digits = groups[0];
+        if (digits.length <= 2)
+            parts = [Number(digits), 0, 0];
+        else if (digits.length <= 6 && digits.length !== 5) {
+            // 230, 1430, 143015: the hour first, then two digits for each of minutes and seconds.
+            const hourDigits = digits.length === 3 ? 1 : 2;
+            parts = [Number(digits.slice(0, hourDigits)), Number(digits.slice(hourDigits, hourDigits + 2)), Number(digits.slice(hourDigits + 2) || 0)];
+        }
+        else
+            return null;
+    }
+    else if (groups.length === 2 || groups.length === 3) {
+        if (groups.slice(1).some(group => group.length !== 2) || groups[0].length > 2)
+            return null;
+        parts = [Number(groups[0]), Number(groups[1]), Number(groups[2] ?? 0)];
+    }
+    else
+        return null;
+    let [hour, minute, second] = parts;
+    if (minute > 59 || second > 59)
+        return null;
+    if (meridiem) {
+        // 12 am is midnight and 12 pm is noon; an hour past 12 already says which half it is.
+        if (hour > 23)
+            return null;
+        if (hour <= 12)
+            hour = (hour % 12) + (meridiem === "pm" ? 12 : 0);
+    }
+    else if (hour > 23)
+        return null;
+    return secondsToIsoTime(hour * 3600 + minute * 60 + second, options.seconds ?? false);
+}
+/**
+ * The times a list of slots offers: every `step` seconds from `min` (or midnight) to `max` (or the end of the day),
+ * past midnight when `max` is earlier than `min`. Returns ISO times, with seconds when the step needs them.
+ */
+export function listTimeSlots(step, min, max) {
+    const size = normalizeTimeStep(step);
+    const seconds = size % 60 !== 0;
+    const from = toIsoTime(min, true);
+    const to = toIsoTime(max, true);
+    const start = from === null ? null : timeToSeconds(from);
+    const end = to === null ? null : timeToSeconds(to);
+    // Slots are counted from midnight, as the step is.
+    const before = [];
+    const after = [];
+    for (let value = 0; value < SECONDS_PER_DAY; value += size) {
+        if (!isSecondsInRange(value, start, end))
+            continue;
+        // A range past midnight lists the evening first, then the morning after.
+        (start !== null && value < start ? after : before).push(secondsToIsoTime(value, seconds));
+    }
+    return before.concat(after);
+}

package/dist/Helpers/TreeStore.d.ts

@@ -0,0 +1,188 @@
+export type TreeValue = string | number;
+/** An item of a tree: any object with a value, a parent value, and a label under the keys the tree is given. */
+export type TreeItem = object;
+/** A box: checked, unchecked, or `mixed` for a parent with some of its items checked. */
+export type TreeCheckState = "checked" | "mixed" | "unchecked";
+/**
+ * Which checked items make up the value, with `cascade`:
+ * - `leaves`: items without children, such as the actions of a permission tree. A parent follows its items.
+ * - `checked`: every checked item, and a parent when all of its items are checked.
+ * - `any`: every checked item, and every parent with at least one checked item (a menu to show because one of its actions is allowed).
+ */
+export type TreeValueMode = "leaves" | "checked" | "any";
+export interface TreeStoreOptions<TItem extends TreeItem = TreeItem> {
+    /** The item field that holds its value. Default `id`. */
+    valueKey?: string;
+    /** The item field that holds its parent's value; empty for a top-level item. Default `parentId`. */
+    parentKey?: string;
+    /** The item field shown as its name. Default `label`. */
+    labelKey?: string;
+    /** Items that cannot be checked, changed, or deleted, and pass that on to their children. Default: `disabled: true` or `isDisabled: true`. */
+    isItemDisabled?: (item: TItem) => boolean;
+    /** Items checked at the start when no value is given. Default: `checked: true` or `isChecked: true`. */
+    isItemChecked?: (item: TItem) => boolean;
+    /** Checking a parent checks its items, and a parent shows the state of its items. Default true. */
+    cascade?: boolean;
+    /** Default `leaves`. Ignored without `cascade`, where the value is every checked item. */
+    valueMode?: TreeValueMode;
+}
+export interface TreeNode<TItem extends TreeItem = TreeItem> {
+    /** A number unique to this node for its whole life, for React keys and element ids. */
+    readonly uid: number;
+    /** The value as text: the key in maps, so `7` and `"7"` are the same item. */
+    key: string;
+    value: TreeValue;
+    item: TItem;
+    label: string;
+    parent: TreeNode<TItem> | null;
+    children: TreeNode<TItem>[];
+    /** 0 for a top-level item. */
+    depth: number;
+    /** The index among its siblings. */
+    position: number;
+    /** The item's own flag. */
+    disabled: boolean;
+    /** The item or one of its parents is disabled. */
+    disabledPath: boolean;
+    /** Cannot be checked, changed, or deleted: disabled, under a disabled parent, or every child is locked. */
+    locked: boolean;
+    expanded: boolean;
+    /** A leaf's state with `cascade`; any node's state without it. */
+    checked: boolean;
+    /** Leaves in this subtree, 1 for a leaf. */
+    leaves: number;
+    /** Checked leaves in this subtree. */
+    checkedLeaves: number;
+    /** Leaves in this subtree that are not locked. */
+    openLeaves: number;
+    /** Checked leaves in this subtree that are not locked. */
+    openChecked: number;
+    /** Being created and not saved yet: not part of the value or the items. */
+    draft: boolean;
+}
+/** What expanding or collapsing did to the visible rows, for an animation. */
+export interface TreeRowsChange<TItem extends TreeItem = TreeItem> {
+    /** The row index where rows were added or removed. */
+    at: number;
+    /** How many rows were added or removed. */
+    count: number;
+    /** The rows before the change. */
+    before: readonly TreeNode<TItem>[];
+}
+export declare const TREE_DEFAULT_KEYS: {
+    readonly value: "id";
+    readonly parent: "parentId";
+    readonly label: "label";
+};
+/** The text key of a value, or `null` for no value. */
+export declare function treeKey(value: unknown): string | null;
+/**
+ * A tree built from a flat list. Items whose parent is missing become top-level items, and a loop of parents is
+ * broken at the first item of the loop. Siblings keep the order of the list; a repeated value keeps its first item.
+ */
+export declare class TreeStore<TItem extends TreeItem = TreeItem> {
+    readonly valueKey: string;
+    readonly parentKey: string;
+    readonly labelKey: string;
+    readonly cascade: boolean;
+    readonly valueMode: TreeValueMode;
+    private readonly isDisabled;
+    private readonly isChecked;
+    roots: TreeNode<TItem>[];
+    /** The visible rows in order: top-level items, and the children of every expanded item whose parents are expanded. A new array after each change. */
+    rows: readonly TreeNode<TItem>[];
+    private byKey;
+    /** Without `cascade`: checked nodes, nodes that are not locked, and the checked ones among them. */
+    private checkedNodes;
+    private openNodes;
+    private openCheckedNodes;
+    private indexCache;
+    constructor(items?: readonly TItem[], options?: TreeStoreOptions<TItem>, value?: readonly TreeValue[]);
+    /** Items in the tree, drafts included. */
+    get size(): number;
+    /** The node of a value. */
+    get(value: TreeValue | null | undefined): TreeNode<TItem> | undefined;
+    /**
+     * Replaces the items. Expanded items stay expanded. The checked items come from `value` when given, otherwise from
+     * the items' own flags.
+     */
+    setItems(items: readonly TItem[], value?: readonly TreeValue[]): void;
+    /** Every item in tree order, without drafts. */
+    items(): TItem[];
+    /** A node and everything under it, in tree order. */
+    subtree(node: TreeNode<TItem>): TreeNode<TItem>[];
+    /** The node's parents, the top-level one first. */
+    path(node: TreeNode<TItem>): TreeNode<TItem>[];
+    /** The state of a node's box. */
+    state(node: TreeNode<TItem>): TreeCheckState;
+    /** Checked boxes and all boxes: leaves with `cascade`, every item without it. Drafts count. */
+    counts(): {
+        checked: number;
+        total: number;
+    };
+    /** The checked values, in tree order, following `valueMode`. */
+    value(): TreeValue[];
+    /** The items of the value, in the same order. */
+    valueItems(): TItem[];
+    /** Checks exactly these values. Locks do not apply: this is the saved state, not a user's change. Returns whether anything changed. */
+    setValue(values: readonly TreeValue[]): boolean;
+    /**
+     * What a click on the node's box does. With `cascade` it checks every item under the node that is not locked, or
+     * unchecks them when they are all checked already. Returns whether anything changed; nothing does on a locked node.
+     */
+    toggle(node: TreeNode<TItem>): boolean;
+    /** Checks or unchecks a node; with `cascade`, every item under it that is not locked. Returns whether anything changed. */
+    setChecked(node: TreeNode<TItem>, checked: boolean): boolean;
+    /** The state of a "select all" box, over the items that are not locked; `null` when every item is locked. */
+    allState(): TreeCheckState | null;
+    /** What a click on a "select all" box does: checks every item that is not locked, or unchecks them all when all are checked. */
+    toggleAll(): boolean;
+    /** Checks or unchecks every item that is not locked. Returns whether anything changed. */
+    checkAll(checked: boolean): boolean;
+    /** Whether every parent of the node is expanded, so the node is a row. */
+    isVisible(node: TreeNode<TItem>): boolean;
+    /** The node's row index, or -1 when it is not a row. */
+    indexOf(node: TreeNode<TItem>): number;
+    /** Expands a node. Returns the rows it added, or `null` when no rows changed. */
+    expand(node: TreeNode<TItem>): TreeRowsChange<TItem> | null;
+    /** Collapses a node. Returns the rows it removed, or `null` when no rows changed. */
+    collapse(node: TreeNode<TItem>): TreeRowsChange<TItem> | null;
+    /** Expands every item, or only the first `levels` levels (1 expands the top-level items). */
+    expandAll(levels?: number): void;
+    collapseAll(): void;
+    /** Expands these items and their parents, so the items and their children show. */
+    expandValues(values: readonly TreeValue[]): void;
+    /** The values of the expanded items, in tree order. */
+    expandedValues(): TreeValue[];
+    /** Expands the parents of a node so it becomes a row. Returns whether rows changed. */
+    reveal(node: TreeNode<TItem>): boolean;
+    /**
+     * Adds an item under `parent` (at the top level for `null`), as its last child unless `index` is given, and expands
+     * the parent. A `draft` is not part of the value or the items until `update` saves it. Throws on a value in use.
+     */
+    insert(parent: TreeNode<TItem> | null, item: TItem, options?: {
+        index?: number;
+        draft?: boolean;
+    }): TreeNode<TItem>;
+    /**
+     * Replaces a node's item, e.g. after a rename, or once a draft is saved and the server gave it an id. The value can
+     * change; the parent cannot. Throws on a value another item uses.
+     */
+    update(node: TreeNode<TItem>, item: TItem, options?: {
+        draft?: boolean;
+    }): void;
+    /** Removes a node and everything under it. Returns the removed nodes in tree order. */
+    remove(node: TreeNode<TItem>): TreeNode<TItem>[];
+    private createNode;
+    private keysOf;
+    /** With `valueMode: "checked"`, a parent in the value stands for all of its items. */
+    private checkedByParent;
+    /** Locks and counts for every node, given in tree order: parents pass locks down, children pass counts up. */
+    private recount;
+    /** Sets every open leaf under a node (the node itself for a leaf), updating counts up the path of each leaf that changes. */
+    private setLeaves;
+    private setNodeChecked;
+    private checkedInOrder;
+}
+/** Nodes in tree order: each node, then its children. No recursion, so even a chain 100,000 levels deep works. */
+export declare function preOrder<TItem extends TreeItem>(nodes: readonly TreeNode<TItem>[]): TreeNode<TItem>[];