nexus-shared 1.1.20 → 2.0.0

package/dist/Components/Inputs/DateRangePicker.js

@@ -0,0 +1,283 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconCalendar, iconX, InlineIcon } from "nexus-icons";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { addDays, formatDate, formatDateRange, parseDateRangeText, toDateRange, usesDevanagari } from "../../Helpers/DateHelpers.js";
+import { useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { DEFAULT_FIELD_NAME, validateDateRange } from "../../Helpers/ValidationHelpers.js";
+import { Calendar } from "./Calendar.js";
+import { Field, hasContent } from "./Field.js";
+import { setInputValue, useInputField } from "./InputField.js";
+import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
+const GAP = 4;
+const MARGIN = 8;
+// Two months of the small calendar are about 480px wide; a narrower window gets one month.
+const TWO_MONTHS_MIN_WIDTH = 520;
+const EMPTY = [null, null];
+const sameRange = (a, b) => (a === null || b === null ? a === b : a[0] === b[0] && a[1] === b[1]);
+/**
+ * A start and an end in one box: type them as "2026-09-17 – 2026-09-24" in the user's format, or pick them in the
+ * calendar that opens under the box, the start first and then the end, with a live preview of the days between.
+ * Shows the English (AD) or Nepali (BS) calendar from the user's settings, two months side by side when there is
+ * room, and always holds Gregorian ISO dates, which a form sends through hidden inputs (`startName` and `endName`,
+ * or both under `name`). Uncontrolled by default, so typing re-renders nothing.
+ *
+ * @example <DateRangePicker startName="checkIn" endName="checkOut" label="Stay" required min={todayIsoDate()} minDistance={1} />
+ */
+export function DateRangePicker(props) {
+    const { label, hint, error, design = "standard", size = "md", icon, prefix, months = 2, clearable = true, closeOnSelect = true, fieldName, readOnlyMessage = "Read-only: these dates cannot be changed.", validateOn, value, defaultValue, onValueChange, startName, endName, weekStart, weekendDays, isDateDisabled, showOutsideDays, className, inputClassName, style, required, min, max, minDistance, maxDistance, validate, name, form, placeholder, disabled, readOnly, ref, onChange, onBlur, onFocus, onInvalid, onKeyDown, onClick, ...inputProps } = props;
+    const preferences = useDatePreferences();
+    const settings = {
+        calendar: props.calendar ?? preferences.calendar,
+        format: props.format ?? preferences.format,
+        script: props.script ?? preferences.script,
+    };
+    const editable = !disabled && !readOnly;
+    const initial = toDateRange(value !== undefined ? value : defaultValue);
+    const initialKey = `${initial[0]}|${initial[1]}`;
+    const text = (range) => formatDateRange(range, settings);
+    const day = (iso) => formatDate(iso, settings);
+    const messageName = fieldName ?? (typeof label === "string" ? label : DEFAULT_FIELD_NAME);
+    // The range, or `null` while the box holds text that is not a range.
+    const valueRef = useRef(initial);
+    const editedRef = useRef(false);
+    const startRef = useRef(null);
+    const endRef = useRef(null);
+    const panelRef = useRef(null);
+    const focusInPanelRef = useRef(false);
+    const focusCalendarRef = useRef(false);
+    const [open, setOpen] = useState(false);
+    // Re-renders the calendar's selection while it is open; typing with it closed re-renders nothing.
+    const [panelRange, setPanelRange] = useState(initial);
+    const [panelMonths, setPanelMonths] = useState(months);
+    const rules = {
+        required,
+        min,
+        max,
+        minDistance,
+        maxDistance,
+        validate: range => {
+            const [start, end] = range;
+            // A range cannot include an unavailable day, such as a booked night.
+            if (isDateDisabled && start && end) {
+                for (let iso = start; iso <= end; iso = addDays(iso, 1))
+                    if (isDateDisabled(iso))
+                        return `${messageName} cannot include ${day(iso)}.`;
+            }
+            return validate?.(range);
+        },
+    };
+    const field = useInputField({
+        ...props,
+        onChange: event => {
+            const input = event.currentTarget;
+            const range = parseDateRangeText(input.value, settings);
+            const changed = !sameRange(range, valueRef.current);
+            editedRef.current = true;
+            valueRef.current = range;
+            sync(range);
+            if (open)
+                setPanelRange(range ?? EMPTY);
+            onChange?.(event);
+            if (changed)
+                onValueChange?.(range ?? EMPTY, event);
+        },
+    }, {
+        // Text that is not a range is checked as itself, so the message says what to type.
+        check: (input, messageName) => validateDateRange(valueRef.current ?? (input.value.trim() || null), rules, messageName, day),
+        checkKeys: [initialKey, required, min, max, minDistance, maxDistance, validate, isDateDisabled, settings.calendar, settings.format, settings.script],
+        onReset: input => {
+            // Back to the range the field started with, written in the current format.
+            editedRef.current = false;
+            valueRef.current = initial;
+            input.value = text(initial);
+            sync(initial);
+        },
+    });
+    // A read-only box has no calendar: a lock, and a note when someone tries to open or change it, say why.
+    const readOnlyNotice = useReadOnlyNotice(Boolean(readOnly) && !disabled, field.elementRef, readOnlyMessage, { keys: ["ArrowDown"] });
+    /** Writes what depends on the value straight to the DOM: the hidden inputs a form sends. */
+    function sync(range) {
+        if (startRef.current)
+            startRef.current.value = range?.[0] ?? "";
+        if (endRef.current)
+            endRef.current.value = range?.[1] ?? "";
+    }
+    // A controlled value that differs from the box replaces its text. So does a default value that arrives after
+    // mount (from an API, say), as long as the user has not typed anything yet.
+    useLayoutEffect(() => {
+        const input = field.elementRef.current;
+        if (!input || (value === undefined && editedRef.current) || sameRange(initial, valueRef.current))
+            return;
+        valueRef.current = initial;
+        input.value = text(initial);
+        sync(initial);
+        setPanelRange(initial);
+    }, [initialKey]);
+    // New settings (another calendar, format, or script) rewrite the same dates.
+    useLayoutEffect(() => {
+        const input = field.elementRef.current;
+        const range = valueRef.current;
+        if (input && range && (range[0] || range[1]))
+            input.value = text(range);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [settings.calendar, settings.format, settings.script]);
+    // React sets a hidden input's default value again on every render, and for a hidden input that is its value.
+    // After each render, before paint, the hidden inputs take the box's dates back.
+    useLayoutEffect(() => {
+        sync(valueRef.current);
+    });
+    // The popover is a native one, placed under the box (above it when there is no room); it is shown once the calendar
+    // has rendered inside it.
+    useLayoutEffect(() => {
+        const panel = panelRef.current;
+        if (!open || !panel)
+            return;
+        if (!panel.matches(":popover-open"))
+            panel.showPopover();
+        place();
+        if (focusCalendarRef.current) {
+            focusCalendarRef.current = false;
+            panel.querySelector('[role="gridcell"][tabindex="0"]')?.focus();
+        }
+        // The panel is fixed, so it follows the box when the page scrolls or the window changes size.
+        let frame = 0;
+        const reposition = () => {
+            cancelAnimationFrame(frame);
+            frame = requestAnimationFrame(place);
+        };
+        const resize = () => {
+            fitMonths();
+            reposition();
+        };
+        window.addEventListener("scroll", reposition, { capture: true, passive: true });
+        window.addEventListener("resize", resize);
+        return () => {
+            cancelAnimationFrame(frame);
+            window.removeEventListener("scroll", reposition, { capture: true });
+            window.removeEventListener("resize", resize);
+        };
+    }, [open, panelMonths]);
+    useEffect(() => () => panelRef.current?.hidePopover?.(), []);
+    function place() {
+        const panel = panelRef.current;
+        const box = field.elementRef.current?.closest(".nx-field__box");
+        if (!panel || !box)
+            return;
+        const anchor = box.getBoundingClientRect();
+        const { width, height } = panel.getBoundingClientRect();
+        const below = anchor.bottom + GAP;
+        const fitsBelow = below + height <= window.innerHeight - MARGIN;
+        const top = fitsBelow || anchor.top - GAP - height < MARGIN ? below : anchor.top - GAP - height;
+        const left = Math.max(MARGIN, Math.min(anchor.left, window.innerWidth - width - MARGIN));
+        panel.style.top = `${Math.round(top)}px`;
+        panel.style.left = `${Math.round(left)}px`;
+    }
+    /** Two months when the window has room for them, else one. */
+    function fitMonths() {
+        setPanelMonths(months > 1 && window.innerWidth >= TWO_MONTHS_MIN_WIDTH ? months : 1);
+    }
+    function openPanel(focusCalendar) {
+        if (!editable)
+            return;
+        // The box is the control: it keeps focus while the calendar is open, so Esc and Enter reach it.
+        field.elementRef.current?.focus();
+        focusCalendarRef.current = focusCalendar;
+        fitMonths();
+        setPanelRange(valueRef.current ?? EMPTY);
+        setOpen(true);
+    }
+    function closePanel() {
+        panelRef.current?.hidePopover();
+        setOpen(false);
+    }
+    // Whether the calendar holds focus is known only before it hides: hiding it moves focus to the body.
+    function onBeforeToggle(event) {
+        if (event.newState === "closed")
+            focusInPanelRef.current = event.currentTarget.contains(document.activeElement);
+    }
+    function onToggle(event) {
+        if (event.newState !== "closed")
+            return;
+        setOpen(false);
+        // Focus returns to the box when the calendar had it.
+        if (focusInPanelRef.current) {
+            focusInPanelRef.current = false;
+            field.elementRef.current?.focus();
+        }
+    }
+    /** The calendar chose a start (end `null`), an end, or nothing. The box shows it; a complete range is checked and closes the calendar. */
+    function pickRange(range) {
+        const input = field.elementRef.current;
+        if (!input)
+            return;
+        setPanelRange(range);
+        setInputValue(input, text(range));
+        if (range[0] && range[1]) {
+            field.touch();
+            if (closeOnSelect)
+                closePanel();
+        }
+    }
+    function clear() {
+        const input = field.elementRef.current;
+        if (!input)
+            return;
+        setInputValue(input, "");
+        input.focus();
+    }
+    function handleKeyDown(event) {
+        const { key } = event;
+        readOnlyNotice.onKeyDown(event);
+        if (editable && key === "ArrowDown") {
+            event.preventDefault();
+            openPanel(true);
+        }
+        else if (key === "Escape" && open) {
+            // The popover closes itself; the page (a dialog, say) does not see this Esc.
+            event.stopPropagation();
+        }
+        else if (clearable && editable && key === "Escape" && event.currentTarget.value) {
+            event.preventDefault();
+            event.stopPropagation();
+            clear();
+        }
+        else if (key === "Enter" && open) {
+            event.preventDefault();
+            closePanel();
+        }
+        else if (key === "Tab" && open) {
+            // Tab moves on to the next field, not into the calendar; ArrowDown is the way in.
+            closePanel();
+        }
+        onKeyDown?.(event);
+    }
+    function handleClick(event) {
+        if (!open)
+            openPanel(false);
+        readOnlyNotice.onClick(event);
+        onClick?.(event);
+    }
+    function handleBlur(event) {
+        // Typed text takes the canonical form once it is a range.
+        const input = event.currentTarget;
+        const range = valueRef.current;
+        if (range && (range[0] || range[1]) && input.value !== text(range))
+            input.value = text(range);
+        // Focus moving anywhere but the calendar (its month and year menus) closes it.
+        if (open && !(event.relatedTarget instanceof Node && panelRef.current?.contains(event.relatedTarget)))
+            closePanel();
+        readOnlyNotice.hide();
+        field.controlProps.onBlur(event);
+    }
+    const showClear = clearable && editable;
+    const startField = startName ?? name;
+    const endField = endName ?? name;
+    return (_jsxs(_Fragment, { children: [_jsxs(Field, { controlId: field.controlId, messageId: field.messageId, label: label, required: required, design: design, size: size, hint: hint, error: field.error, icon: icon, prefix: prefix, actions: _jsxs(_Fragment, { children: [showClear && (_jsx("button", { type: "button", className: "nx-field__action nx-field__action--clear", tabIndex: -1, "aria-label": "Clear", title: "Clear", onMouseDown: event => event.preventDefault(), onClick: clear, children: _jsx(InlineIcon, { icon: iconX }) })), readOnlyNotice.lock, !readOnly && (_jsx("button", { type: "button", className: "nx-field__action nx-field__action--calendar", tabIndex: -1, "aria-label": "Open calendar", "aria-haspopup": "dialog", "aria-expanded": open, "aria-controls": open ? `${field.controlId}-calendar` : undefined, title: "Open calendar", disabled: disabled, onMouseDown: event => event.preventDefault(), onClick: () => (open ? closePanel() : openPanel(false)), children: _jsx(InlineIcon, { icon: iconCalendar }) }))] }), disabled: disabled, readOnly: readOnly, raiseLabel: Boolean(placeholder) || hasContent(prefix), className: cx("nx-field--date", "nx-field--date-range", className), style: style, children: [_jsx("input", { autoComplete: "off", spellCheck: false, ...inputProps, ...field.controlProps, type: "text", name: undefined, form: form, lang: usesDevanagari(settings.calendar, settings.script) ? "ne" : undefined, defaultValue: text(initial), className: cx("nx-field__control", "nx-field__control--date", inputClassName), placeholder: placeholder || " ", disabled: disabled, readOnly: readOnly, onBlur: handleBlur, onFocus: onFocus, onKeyDown: handleKeyDown, onClick: handleClick }), startField && _jsx("input", { ref: startRef, type: "hidden", name: startField, form: form, disabled: disabled, defaultValue: initial[0] ?? "" }), endField && _jsx("input", { ref: endRef, type: "hidden", name: endField, form: form, disabled: disabled, defaultValue: initial[1] ?? "" })] }), readOnlyNotice.notice, !readOnly && (_jsx("div", { ref: panelRef, id: `${field.controlId}-calendar`, popover: "auto", role: "dialog", "aria-label": "Calendar", className: "nx-popover nx-date-popover", onBeforeToggle: onBeforeToggle, onToggle: onToggle, 
+                // The box keeps focus while days and buttons are clicked; the month and year menus need focus to open.
+                onMouseDown: event => {
+                    if (!event.target.closest("select"))
+                        event.preventDefault();
+                }, children: open && (_jsx(Calendar, { size: "sm", mode: "range", months: panelMonths, calendar: settings.calendar, script: settings.script, range: panelRange, onRangeChange: pickRange, min: min, max: max, isDateDisabled: isDateDisabled, weekStart: weekStart, weekendDays: weekendDays, showOutsideDays: showOutsideDays, "aria-label": "Calendar" })) }))] }));
+}

package/dist/Components/Inputs/DateTimePicker.d.ts

@@ -0,0 +1,75 @@
+import { type ChangeEvent, type ComponentPropsWithRef, type ReactNode } from "react";
+import type { CalendarType, DateScript, DateTimeInput, DateTimeRules, TimeInput } from "../../Interfaces/DateInterfaces.ts";
+import type { InputDesign, ValidateOn } from "../../Interfaces/InputInterfaces.ts";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+import { type CalendarProps } from "./Calendar.tsx";
+import { type TimePanelView } from "./TimePanel.tsx";
+type NativeInputProps = Omit<ComponentPropsWithRef<"input">, "type" | "size" | "value" | "defaultValue" | "min" | "max" | "step" | "prefix" | "pattern" | "minLength" | "maxLength" | "children" | keyof DateTimeRules>;
+export interface DateTimePickerProps extends NativeInputProps, DateTimeRules, Pick<CalendarProps, "weekStart" | "weekendDays" | "showOutsideDays"> {
+    label?: ReactNode;
+    /** Help text under the box. */
+    hint?: ReactNode;
+    /** An error from outside, such as a server message. Shown before the field's own message. */
+    error?: string | null;
+    /** Default `standard`. */
+    design?: InputDesign;
+    /** Default `md`. */
+    size?: Size;
+    /** Decorative icon at the start. The calendar and clock button is always at the end. */
+    icon?: ReactNode;
+    /** Text before the value inside the box. */
+    prefix?: ReactNode;
+    /** The calendar the date is shown and picked in: `ad` or `bs`. Default: the user's setting. */
+    calendar?: CalendarType;
+    /** How the date is written: `YYYY-MM-DD`, `DD/MM/YYYY`, `MMM D, YYYY`, ... Default: the user's setting. */
+    format?: string;
+    /** How the time is written: `hh:mm A` (02:30 PM), `HH:mm` (14:30), ... Seconds are added when `step` needs them. Default: the user's setting. */
+    timeFormat?: string;
+    /** Digits and names of Nepali dates, and the digits of the time with them. Default: the user's setting. */
+    script?: DateScript;
+    /**
+     * IANA id of the time zone the value is shown and picked in, such as "Asia/Kathmandu" or "UTC". Default: the
+     * browser's, so every user sees their own local time. The value is the same UTC moment whatever the zone.
+     */
+    timeZone?: string;
+    /** Writes the zone's city after the value in the box, e.g. "Kathmandu". Default: on when `timeZone` is given. */
+    showTimeZone?: boolean;
+    /** The time panel: `columns` (default) of hours, minutes, and AM/PM, or `list`, a slot every `step`, for bookings. */
+    view?: TimePanelView;
+    /** The time a day takes when it is picked, or typed, before any time: "12:00" for a check-in. Default: `minTime`, or midnight. */
+    defaultTime?: TimeInput;
+    /** Days that cannot be picked, such as fully booked days. Receives the ISO date where the user is. */
+    isDateDisabled?: (date: string) => boolean;
+    /** Times that cannot be picked on a day, such as booked slots. Receives the ISO time ("14:30") and date where the user is. */
+    isTimeDisabled?: (time: string, date: string) => boolean;
+    /** Shows a clear button while there is a value. Default true. */
+    clearable?: boolean;
+    /** What a read-only field says when someone tries to change it. Default "Read-only: this date and time cannot be changed." */
+    readOnlyMessage?: string;
+    /** Name used in messages, e.g. "Pickup is required." Default: the label, when it is text. */
+    fieldName?: string;
+    /** When the field shows its own message. Default `blur`; submitting a form always shows it. */
+    validateOn?: ValidateOn;
+    /**
+     * The moment, or `null` for empty. Held and sent as a UTC ISO string, "2026-09-17T08:45:00.000Z". An ISO date-time
+     * with a zone, one without a zone (read as UTC), a `Date`, or milliseconds are accepted; see `DateTimeInput`.
+     */
+    value?: DateTimeInput;
+    defaultValue?: DateTimeInput;
+    /** After each change: the UTC ISO value, or `null` when the box is empty or holds text that is not a date and time. */
+    onValueChange?: (value: string | null, event: ChangeEvent<HTMLInputElement>) => void;
+    /** Class of the outer field. `inputClassName` goes on the input. */
+    className?: string;
+    inputClassName?: string;
+}
+/**
+ * A date and time input for moments, such as a pickup, a deadline, or a reminder: type a date and time, or pick a day
+ * and a time from the panel that opens under the box. People see and pick their own local time, in their date and time
+ * formats (English or Nepali calendar, 12- or 24-hour clock); the value is always the UTC moment, which a form sends
+ * through a hidden input with the field's `name`, so no time zone ever moves it. A value is replaced only when the
+ * user changes what it shows: seconds and milliseconds the box does not show stay as they arrived.
+ *
+ * @example <DateTimePicker name="pickupAt" label="Pickup" required min={new Date()} step={900} />
+ */
+export declare function DateTimePicker(props: DateTimePickerProps): import("react").JSX.Element;
+export {};