nexus-shared 1.1.20 → 2.0.0

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

@@ -0,0 +1,122 @@
+import { type CSSProperties, type FocusEvent, type FormEvent, type MouseEvent, type ReactNode, type Ref } from "react";
+import type { ChoiceDesign, ChoiceOption, OptionValue, ValidateOn } from "../../Interfaces/InputInterfaces.ts";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+/** Marks the inputs that are options of a choice field, so a "select all" box beside them is not counted. */
+export declare const OPTION_ATTRIBUTE = "data-nx-option";
+export interface ChoiceFieldOptions {
+    id?: string;
+    label?: ReactNode;
+    fieldName?: string;
+    error?: string | null;
+    validateOn?: ValidateOn;
+    /** Uses a text label as the field name in messages. Off for a single checkbox, whose label is usually a sentence. */
+    nameFromLabel?: boolean;
+}
+export interface ChoiceFieldRules {
+    /** The field's message for its option inputs, or `null` when valid. */
+    check: (inputs: HTMLInputElement[], name: string | undefined) => string | null;
+    /** Everything `check` depends on (rules, a controlled value). The field is checked again when one changes. */
+    checkKeys: readonly unknown[];
+    /** Writes what follows from the choices straight to the DOM (a count, limits, a select-all box), after every change and reset. */
+    sync?: (inputs: HTMLInputElement[]) => void;
+}
+/**
+ * Behavior shared by checkboxes, switches, radio groups, and sliders (fields made of native inputs in a container): ids, validation messages, and form integration, with the
+ * same timing as a text box. A message shows once focus leaves a field that was changed, or on submit, and then follows
+ * every change. Validity is set on the first option with `setCustomValidity`, so a plain `<form>` blocks submit and
+ * focuses it. Clicking an option re-renders nothing unless its message changes.
+ */
+export declare function useChoiceField<E extends HTMLElement>(options: ChoiceFieldOptions, rules: ChoiceFieldRules): {
+    fieldId: string;
+    messageId: string;
+    containerRef: import("react").RefObject<E | null>;
+    error: string | null;
+    inputs: () => HTMLInputElement[];
+    onChange: () => void;
+    onBlur: (event: FocusEvent<E>) => void;
+    onInvalid: (event: FormEvent<HTMLInputElement>) => void;
+};
+/** Stops a click from changing a read-only option. The value stays in the form. */
+export declare function preventChange(event: MouseEvent<HTMLInputElement>): void;
+/**
+ * Where a read-only choice shows its note: under the option whose input was clicked (a click on its label text
+ * reaches the input too), or pressed with Space or an arrow key, which browsers turn into a click.
+ */
+export declare function optionAnchor(target: Element): Element | null;
+/** Hides a field's read-only note when focus leaves the field, not when it moves between its options. */
+export declare function leavesField(event: FocusEvent<HTMLElement>): boolean;
+/** Points a ref given by the caller at the same node as our own. */
+export declare function assignRef<T>(ref: Ref<T> | undefined, node: T | null): void;
+export interface ChoiceItemProps<T extends OptionValue> {
+    type: "checkbox" | "radio";
+    groupId: string;
+    name: string;
+    option: ChoiceOption<T>;
+    index: number;
+    size: Size;
+    /** Controlled state; `undefined` leaves the option uncontrolled with `defaultChecked`. */
+    checked?: boolean;
+    defaultChecked?: boolean;
+    invalid: boolean;
+    readOnly: boolean;
+    onInvalid: (event: FormEvent<HTMLInputElement>) => void;
+}
+/** One option of a group: a native input and its label, icon, and description, all inside one clickable label. */
+export declare function ChoiceItem<T extends OptionValue>({ type, groupId, name, option, index, size, checked, defaultChecked, invalid, readOnly, onInvalid }: ChoiceItemProps<T>): import("react").JSX.Element;
+/** The legend of a choice group, with the required mark and, when read-only, a lock. */
+export declare function ChoiceLegend({ label, required, lock }: {
+    label: ReactNode;
+    required?: boolean;
+    lock?: ReactNode;
+}): import("react").JSX.Element | null;
+/** Props shared by `CheckBoxGroup` and `RadioGroup`. */
+export interface ChoiceGroupProps<T extends OptionValue> {
+    options: readonly ChoiceOption<T>[];
+    /** Form field name. Default: a unique id. */
+    name?: string;
+    /** The group's legend. Without one, pass `aria-label` or `aria-labelledby`. */
+    label?: ReactNode;
+    /** Help text under the options. An error takes its place. */
+    hint?: ReactNode;
+    /** An error from outside, such as a server message. */
+    error?: string | null;
+    /** Default `md`. */
+    size?: Size;
+    /** `default`: a box or circle beside each label. `cards`: each option is a card. */
+    design?: ChoiceDesign;
+    /** `vertical` (default) stacks options, in `columns` when set; `horizontal` puts them in a wrapping row. */
+    orientation?: "vertical" | "horizontal";
+    /** Columns for vertical options. They drop to fewer columns when each would be narrower than 160px. */
+    columns?: number;
+    required?: boolean;
+    disabled?: boolean;
+    /** Options can be focused but not changed; the value is still sent with a form. A lock follows the label, and a click shows a note. */
+    readOnly?: boolean;
+    /** What a read-only group says when someone tries to change it. */
+    readOnlyMessage?: string;
+    /** Name used in messages. Default: the label, when it is text. */
+    fieldName?: string;
+    /** When the message shows. Default `blur` (when focus leaves the group); submitting a form always shows it. */
+    validateOn?: ValidateOn;
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+}
+type GroupStyle = CSSProperties & {
+    "--nx-choices-columns"?: number;
+};
+/** Class names and inline style of a group's fieldset and options list. */
+export declare function groupLayout(props: ChoiceGroupProps<OptionValue>): {
+    className: string;
+    optionsStyle: GroupStyle | undefined;
+};
+/** The hint or error line under a group. */
+export declare function GroupFooter({ id, hint, error, aside }: {
+    id: string;
+    hint?: ReactNode;
+    error?: ReactNode;
+    aside?: ReactNode;
+}): import("react").JSX.Element | null;
+export {};

package/dist/Components/Inputs/ChoiceField.js

@@ -0,0 +1,169 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { InlineIcon, iconAlertCircle } from "nexus-icons";
+import { useEffect, useEffectEvent, useId, useRef, useState } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { hasContent } from "./Field.js";
+import { isFirstInvalid } from "./InputField.js";
+/** Marks the inputs that are options of a choice field, so a "select all" box beside them is not counted. */
+export const OPTION_ATTRIBUTE = "data-nx-option";
+/**
+ * Behavior shared by checkboxes, switches, radio groups, and sliders (fields made of native inputs in a container): ids, validation messages, and form integration, with the
+ * same timing as a text box. A message shows once focus leaves a field that was changed, or on submit, and then follows
+ * every change. Validity is set on the first option with `setCustomValidity`, so a plain `<form>` blocks submit and
+ * focuses it. Clicking an option re-renders nothing unless its message changes.
+ */
+export function useChoiceField(options, rules) {
+    const { id, label, fieldName, error, validateOn = "blur", nameFromLabel = true } = options;
+    const generatedId = useId();
+    const fieldId = id ?? generatedId;
+    const messageId = `${fieldId}-message`;
+    const name = fieldName ?? (nameFromLabel && typeof label === "string" ? label : undefined);
+    const containerRef = useRef(null);
+    const touchedRef = useRef(false);
+    const editedRef = useRef(false);
+    const shownRef = useRef(null);
+    const [shownError, setShownError] = useState(null);
+    function inputs() {
+        return Array.from(containerRef.current?.querySelectorAll(`input[${OPTION_ATTRIBUTE}]`) ?? []);
+    }
+    function check() {
+        const list = inputs();
+        const message = rules.check(list, name);
+        // One option carries the message, the first that can take focus, so a form moves focus there.
+        const target = list.find(input => !input.disabled);
+        for (const input of list)
+            input.setCustomValidity(input === target ? (message ?? "") : "");
+        return message;
+    }
+    function show(message) {
+        if (shownRef.current === message)
+            return;
+        shownRef.current = message;
+        setShownError(message);
+    }
+    useEffect(() => {
+        rules.sync?.(inputs());
+        const message = check();
+        if (touchedRef.current)
+            show(message);
+    }, [...rules.checkKeys, name]);
+    // A form reset restores the default choices in the DOM; bring the derived state, validity, and message back too.
+    const onFormReset = useEffectEvent(() => {
+        touchedRef.current = false;
+        editedRef.current = false;
+        // React fires onChange only when an input's state differs from the last state it saw, and a reset changes the DOM
+        // without telling it. Assigning the restored state through the property lets React see it, so checking the same
+        // box again after a reset still reports the change.
+        for (const input of inputs()) {
+            if (input.type === "checkbox" || input.type === "radio")
+                input.checked = input.checked;
+            else
+                input.value = input.value;
+        }
+        rules.sync?.(inputs());
+        check();
+        show(null);
+    });
+    useEffect(() => {
+        const form = inputs()[0]?.form;
+        if (!form)
+            return;
+        // The reset event fires before the browser restores the values.
+        const onReset = () => setTimeout(() => onFormReset());
+        form.addEventListener("reset", onReset);
+        return () => form.removeEventListener("reset", onReset);
+    }, []);
+    /** For the container's `onChange`: every option's change bubbles here. */
+    function onChange() {
+        editedRef.current = true;
+        if (validateOn === "change")
+            touchedRef.current = true;
+        rules.sync?.(inputs());
+        const message = check();
+        if (touchedRef.current)
+            show(message);
+    }
+    /** For the container's `onBlur`: moving between options of the same field does not count as leaving it. */
+    function onBlur(event) {
+        if (event.relatedTarget instanceof Node && containerRef.current?.contains(event.relatedTarget))
+            return;
+        if (validateOn !== "submit" && editedRef.current) {
+            touchedRef.current = true;
+            show(check());
+        }
+    }
+    /** For each option's `onInvalid`, which does not bubble. */
+    function onInvalid(event) {
+        // Our message replaces the browser's bubble.
+        event.preventDefault();
+        const input = event.currentTarget;
+        touchedRef.current = true;
+        show(check() ?? input.validationMessage);
+        if (isFirstInvalid(input))
+            input.focus();
+    }
+    return {
+        fieldId,
+        messageId,
+        containerRef,
+        error: error || shownError,
+        inputs,
+        onChange,
+        onBlur,
+        onInvalid,
+    };
+}
+/** Stops a click from changing a read-only option. The value stays in the form. */
+export function preventChange(event) {
+    event.preventDefault();
+}
+/**
+ * Where a read-only choice shows its note: under the option whose input was clicked (a click on its label text
+ * reaches the input too), or pressed with Space or an arrow key, which browsers turn into a click.
+ */
+export function optionAnchor(target) {
+    return target instanceof HTMLInputElement ? target.closest(".nx-choice") : null;
+}
+/** Hides a field's read-only note when focus leaves the field, not when it moves between its options. */
+export function leavesField(event) {
+    return !(event.relatedTarget instanceof Node && event.currentTarget.contains(event.relatedTarget));
+}
+/** Points a ref given by the caller at the same node as our own. */
+export function assignRef(ref, node) {
+    if (typeof ref === "function")
+        ref(node);
+    else if (ref)
+        ref.current = node;
+}
+/** One option of a group: a native input and its label, icon, and description, all inside one clickable label. */
+export function ChoiceItem({ type, groupId, name, option, index, size, checked, defaultChecked, invalid, readOnly, onInvalid }) {
+    const descriptionId = hasContent(option.description) ? `${groupId}-${index}-description` : undefined;
+    // With a description, the name comes from the label text alone; the description is read as a description.
+    const labelId = descriptionId ? `${groupId}-${index}-label` : undefined;
+    return (_jsxs("label", { className: cx("nx-choice", `nx-choice--${size}`), children: [_jsx("input", { id: `${groupId}-${index}`, type: type, name: name, value: String(option.value), [OPTION_ATTRIBUTE]: index, className: cx("nx-choice__control", `nx-choice__control--${type}`), checked: checked, defaultChecked: checked === undefined ? defaultChecked : undefined, disabled: option.disabled, "aria-invalid": invalid || undefined, "aria-labelledby": labelId, "aria-describedby": descriptionId, "aria-readonly": type === "checkbox" && readOnly ? true : undefined, onClick: readOnly ? preventChange : undefined, onInvalid: onInvalid, 
+                // A controlled option changes through the group's onValueChange; this silences React's missing-onChange warning.
+                onChange: checked === undefined ? undefined : noop }), hasContent(option.icon) && (_jsx("span", { className: "nx-choice__icon", "aria-hidden": "true", children: option.icon })), _jsxs("span", { className: "nx-choice__text", children: [_jsx("span", { id: labelId, className: "nx-choice__label", children: option.label }), descriptionId && (_jsx("span", { id: descriptionId, className: "nx-choice__description", children: option.description }))] })] }));
+}
+function noop() { }
+/** The legend of a choice group, with the required mark and, when read-only, a lock. */
+export function ChoiceLegend({ label, required, lock }) {
+    if (!hasContent(label))
+        return null;
+    return (_jsxs("legend", { className: "nx-field__label nx-choices__legend", children: [label, required && (_jsx("span", { className: "nx-field__required", "aria-hidden": "true", children: "*" })), lock] }));
+}
+/** Class names and inline style of a group's fieldset and options list. */
+export function groupLayout(props) {
+    const { size = "md", design = "default", orientation = "vertical", columns } = props;
+    return {
+        className: cx("nx-choices", `nx-choices--${size}`, design === "cards" && "nx-choices--cards", orientation === "horizontal" && "nx-choices--horizontal", props.className),
+        optionsStyle: (columns && columns > 1 ? { "--nx-choices-columns": columns } : undefined),
+    };
+}
+/** The hint or error line under a group. */
+export function GroupFooter({ id, hint, error, aside }) {
+    const hasError = hasContent(error);
+    if (!hasError && !hasContent(hint) && !aside)
+        return null;
+    return (_jsxs("div", { className: "nx-field__footer", children: [(hasError || hasContent(hint)) && (_jsxs("p", { id: id, className: cx("nx-field__message", hasError && "nx-field__message--error"), children: [hasError && _jsx(InlineIcon, { icon: iconAlertCircle }), _jsx("span", { children: hasError ? error : hint })] })), aside && _jsx("span", { className: "nx-field__aside", children: aside })] }));
+}

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

@@ -0,0 +1,54 @@
+import { type ChangeEvent, type ComponentPropsWithRef, type ReactNode } from "react";
+import type { CalendarType, DateInput, DateRules, DateScript } 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";
+type NativeInputProps = Omit<ComponentPropsWithRef<"input">, "type" | "size" | "value" | "defaultValue" | "min" | "max" | "step" | "prefix" | "pattern" | "minLength" | "maxLength" | "children" | keyof DateRules>;
+export interface DatePickerProps extends NativeInputProps, DateRules, Pick<CalendarProps, "weekStart" | "weekendDays" | "isDateDisabled" | "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 button is always at the end. */
+    icon?: ReactNode;
+    /** Text before the value inside the box. */
+    prefix?: ReactNode;
+    /** The calendar the box shows and picks in: `ad` or `bs`. Default: the user's setting. The value is an ISO date either way. */
+    calendar?: CalendarType;
+    /** How the date is written in the box: `YYYY-MM-DD`, `DD/MM/YYYY`, `MMM D, YYYY`, ... Default: the user's setting. */
+    format?: string;
+    /** Digits and names of Nepali dates. Default: the user's setting. */
+    script?: DateScript;
+    /** Shows a clear button while there is a value. Default true. */
+    clearable?: boolean;
+    /** Closes the calendar once a day is chosen. Default true. */
+    closeOnSelect?: boolean;
+    /** What a read-only field says when someone tries to change it. Default "Read-only: this date cannot be changed." */
+    readOnlyMessage?: string;
+    /** Name used in messages, e.g. "Check-in 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 date as an ISO string, or `null` for empty. A `Date` or an ISO date-time is accepted and read as a day. */
+    value?: DateInput;
+    defaultValue?: DateInput;
+    /** After each change: the ISO date, or `null` when the box is empty or holds text that is not a date. */
+    onValueChange?: (value: string | null, event: ChangeEvent<HTMLInputElement>) => void;
+    /** Class of the outer field. `inputClassName` goes on the input. */
+    className?: string;
+    inputClassName?: string;
+}
+/**
+ * A date input: type a date in the user's format, or pick one from the calendar that opens under the box. Shows the
+ * English (AD) or Nepali (BS) calendar from the user's settings, and always holds a Gregorian ISO date, which a form
+ * sends through a hidden input with the field's `name`. Uncontrolled by default, so typing re-renders nothing.
+ *
+ * @example <DatePicker name="checkIn" label="Check-in" required min={todayIsoDate()} />
+ */
+export declare function DatePicker(props: DatePickerProps): import("react").JSX.Element;
+export {};

package/dist/Components/Inputs/DatePicker.js

@@ -0,0 +1,246 @@
+"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 { formatDate, parseDateText, toIsoDate, usesDevanagari } from "../../Helpers/DateHelpers.js";
+import { useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { DEFAULT_FIELD_NAME, validateDate } 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;
+/**
+ * A date input: type a date in the user's format, or pick one from the calendar that opens under the box. Shows the
+ * English (AD) or Nepali (BS) calendar from the user's settings, and always holds a Gregorian ISO date, which a form
+ * sends through a hidden input with the field's `name`. Uncontrolled by default, so typing re-renders nothing.
+ *
+ * @example <DatePicker name="checkIn" label="Check-in" required min={todayIsoDate()} />
+ */
+export function DatePicker(props) {
+    const { label, hint, error, design = "standard", size = "md", icon, prefix, clearable = true, closeOnSelect = true, fieldName, readOnlyMessage = "Read-only: this date cannot be changed.", validateOn, value, defaultValue, onValueChange, weekStart, weekendDays, isDateDisabled, showOutsideDays, className, inputClassName, style, required, min, max, 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 = toIsoDate(value !== undefined ? value : defaultValue);
+    const text = (iso) => formatDate(iso, settings);
+    const valueRef = useRef(initial);
+    const editedRef = useRef(false);
+    const hiddenRef = 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 [panelValue, setPanelValue] = useState(initial);
+    const rules = {
+        required,
+        min,
+        max,
+        validate: iso => (iso && isDateDisabled?.(iso) ? unavailableMessage(text(iso)) : validate?.(iso)),
+    };
+    const field = useInputField({
+        ...props,
+        onChange: event => {
+            const input = event.currentTarget;
+            const iso = input.value.trim() ? parseDateText(input.value, settings) : null;
+            const changed = iso !== valueRef.current;
+            editedRef.current = true;
+            valueRef.current = iso;
+            sync(iso);
+            if (open)
+                setPanelValue(iso);
+            onChange?.(event);
+            if (changed)
+                onValueChange?.(iso, event);
+        },
+    }, {
+        // Text that is not a date is checked as itself, so the message says what to type.
+        check: (input, messageName) => validateDate(valueRef.current ?? (input.value.trim() ? input.value : null), rules, messageName, text),
+        checkKeys: [value, required, min, max, validate, isDateDisabled, settings.calendar, settings.format, settings.script],
+        onReset: input => {
+            // Back to the date the field started with, written in the current format. (A hidden input cannot be read
+            // for it: setting its value also sets its default, so a reset leaves it as it was.)
+            editedRef.current = false;
+            valueRef.current = initial;
+            input.value = text(initial);
+            sync(initial);
+        },
+    });
+    const messageName = fieldName ?? (typeof label === "string" ? label : DEFAULT_FIELD_NAME);
+    // 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"] });
+    function unavailableMessage(day) {
+        return `${messageName} cannot be ${day}.`;
+    }
+    /** Writes what depends on the value straight to the DOM: the hidden input a form sends. */
+    function sync(iso) {
+        if (hiddenRef.current)
+            hiddenRef.current.value = iso ?? "";
+    }
+    // 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) || initial === valueRef.current)
+            return;
+        valueRef.current = initial;
+        input.value = text(initial);
+        sync(initial);
+        setPanelValue(initial);
+    }, [initial]);
+    // New settings (another calendar, format, or script) rewrite the same date.
+    useLayoutEffect(() => {
+        const input = field.elementRef.current;
+        if (input && valueRef.current)
+            input.value = text(valueRef.current);
+        // 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 input takes the box's date 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);
+        };
+        window.addEventListener("scroll", reposition, { capture: true, passive: true });
+        window.addEventListener("resize", reposition);
+        return () => {
+            cancelAnimationFrame(frame);
+            window.removeEventListener("scroll", reposition, { capture: true });
+            window.removeEventListener("resize", reposition);
+        };
+    }, [open]);
+    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`;
+    }
+    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;
+        setPanelValue(valueRef.current);
+        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();
+        }
+    }
+    function select(iso) {
+        const input = field.elementRef.current;
+        if (!input)
+            return;
+        setInputValue(input, text(iso));
+        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 date.
+        const input = event.currentTarget;
+        if (valueRef.current && input.value !== text(valueRef.current))
+            input.value = text(valueRef.current);
+        // 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;
+    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", 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 }), name && _jsx("input", { ref: hiddenRef, type: "hidden", name: name, form: form, disabled: disabled, defaultValue: initial ?? "" })] }), 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", calendar: settings.calendar, script: settings.script, value: panelValue, onSelect: select, onValueChange: iso => iso === null && clear(), min: min, max: max, isDateDisabled: isDateDisabled, weekStart: weekStart, weekendDays: weekendDays, showOutsideDays: showOutsideDays, "aria-label": "Calendar" })) }))] }));
+}

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

@@ -0,0 +1,62 @@
+import { type ChangeEvent, type ComponentPropsWithRef, type ReactNode } from "react";
+import type { CalendarType, DateRange, DateRangeInput, DateRangeRules, DateScript } 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";
+type NativeInputProps = Omit<ComponentPropsWithRef<"input">, "type" | "size" | "value" | "defaultValue" | "min" | "max" | "step" | "prefix" | "pattern" | "minLength" | "maxLength" | "children" | keyof DateRangeRules>;
+export interface DateRangePickerProps extends NativeInputProps, DateRangeRules, Pick<CalendarProps, "weekStart" | "weekendDays" | "isDateDisabled" | "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 button is always at the end. */
+    icon?: ReactNode;
+    /** Text before the value inside the box. */
+    prefix?: ReactNode;
+    /** The calendar the box shows and picks in: `ad` or `bs`. Default: the user's setting. The values are ISO dates either way. */
+    calendar?: CalendarType;
+    /** How each date is written in the box: `YYYY-MM-DD`, `DD/MM/YYYY`, `MMM D, YYYY`, ... Default: the user's setting. */
+    format?: string;
+    /** Digits and names of Nepali dates. Default: the user's setting. */
+    script?: DateScript;
+    /** Months shown side by side in the calendar, 1 or 2. Default 2, or 1 when the window is too narrow for two. */
+    months?: 1 | 2;
+    /** Shows a clear button while there is a value. Default true. */
+    clearable?: boolean;
+    /** Closes the calendar once the end is chosen. Default true. */
+    closeOnSelect?: boolean;
+    /** What a read-only field says when someone tries to change it. Default "Read-only: these dates cannot be changed." */
+    readOnlyMessage?: string;
+    /** Name used in messages, e.g. "Stay 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 range as a pair of ISO dates, either `null` while not chosen, or `null` for empty. `Date`s and ISO date-times are read as days. */
+    value?: DateRangeInput;
+    defaultValue?: DateRangeInput;
+    /** After each change: the start and the end as ISO dates, `null` for an end not chosen yet; both `null` when the box is empty or holds text that is not a range. */
+    onValueChange?: (value: DateRange, event: ChangeEvent<HTMLInputElement>) => void;
+    /** Form field name of the start, e.g. `checkIn`, sent as its own field. Without it, `name` sends both dates under one name: the start, then the end. */
+    startName?: string;
+    /** Form field name of the end, e.g. `checkOut`. */
+    endName?: string;
+    /** Class of the outer field. `inputClassName` goes on the input. */
+    className?: string;
+    inputClassName?: string;
+}
+/**
+ * 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 declare function DateRangePicker(props: DateRangePickerProps): import("react").JSX.Element;
+export {};