nexus-shared 1.1.20 → 2.0.0

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

@@ -0,0 +1,43 @@
+import type { ChangeEvent, ComponentPropsWithRef, ReactNode } from "react";
+import type { InputDesign, TextRules, ValidateOn } from "../../Interfaces/InputInterfaces.ts";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+type NativeTextAreaProps = Omit<ComponentPropsWithRef<"textarea">, "children" | keyof TextRules>;
+export interface TextAreaProps extends NativeTextAreaProps, TextRules {
+    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 top left. */
+    icon?: ReactNode;
+    /** Visible lines. Default 3. */
+    rows?: number;
+    /** Grows with its text, from `rows` up to `maxRows`, then scrolls. Where the browser cannot, it keeps `rows` and a resize handle. */
+    autoResize?: boolean;
+    /** Tallest size with `autoResize`, in lines. Default 12. */
+    maxRows?: number;
+    /** Shows the character count, and the limit when `maxLength` is set. */
+    showCount?: boolean;
+    /** What a read-only field says when someone tries to change it. Default "Read-only: this field cannot be changed." */
+    readOnlyMessage?: string;
+    /** Name used in messages. 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 new text after each change. */
+    onValueChange?: (value: string, event: ChangeEvent<HTMLTextAreaElement>) => void;
+    /** Class of the outer field. `textAreaClassName` goes on the text area. */
+    className?: string;
+    textAreaClassName?: string;
+}
+/**
+ * A multi-line text input with the same label, hint, validation, and designs as `TextBox`.
+ *
+ * @example <TextArea label="Description" maxLength={500} showCount autoResize />
+ */
+export declare function TextArea(props: TextAreaProps): import("react").JSX.Element;
+export {};

package/dist/Components/Inputs/TextArea.js

@@ -0,0 +1,31 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { Field } from "./Field.js";
+import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
+import { useTextField } from "./TextField.js";
+/**
+ * A multi-line text input with the same label, hint, validation, and designs as `TextBox`.
+ *
+ * @example <TextArea label="Description" maxLength={500} showCount autoResize />
+ */
+export function TextArea(props) {
+    const { label, hint, error, design = "standard", size = "md", icon, rows = 3, autoResize = false, maxRows = 12, showCount = false, readOnlyMessage = "Read-only: this field cannot be changed.", fieldName, validateOn, onValueChange, className, textAreaClassName, style, required, minLength, maxLength, pattern, patternMessage, validate, placeholder, disabled, readOnly, ref, onChange, onBlur, onInvalid, onKeyDown, onClick, ...textAreaProps } = props;
+    const field = useTextField(props);
+    const rowsStyle = { "--nx-field-rows": rows, "--nx-field-max-rows": Math.max(rows, maxRows) };
+    // A lock at the top end of the box, and a note under it when someone tries to change the text, say why nothing happens.
+    const readOnlyNotice = useReadOnlyNotice(Boolean(readOnly) && !disabled, field.elementRef, readOnlyMessage, { keys: ["Enter"] });
+    function handleKeyDown(event) {
+        readOnlyNotice.onKeyDown(event);
+        onKeyDown?.(event);
+    }
+    function handleClick(event) {
+        readOnlyNotice.onClick(event);
+        onClick?.(event);
+    }
+    function handleBlur(event) {
+        readOnlyNotice.hide();
+        field.controlProps.onBlur(event);
+    }
+    return (_jsxs(_Fragment, { children: [_jsx(Field, { controlId: field.controlId, messageId: field.messageId, label: label, required: required, design: design, size: size, hint: hint, error: field.error, icon: icon, actions: readOnlyNotice.lock, aside: field.count, disabled: disabled, readOnly: readOnly, raiseLabel: Boolean(placeholder), multiline: true, className: className, style: { ...rowsStyle, ...style }, children: _jsx("textarea", { ...textAreaProps, ...field.controlProps, className: cx("nx-field__control", autoResize && "nx-field__control--auto", textAreaClassName), rows: rows, placeholder: placeholder || " ", disabled: disabled, readOnly: readOnly, onClick: handleClick, onBlur: handleBlur, onKeyDown: handleKeyDown }) }), readOnlyNotice.notice] }));
+}

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

@@ -0,0 +1,52 @@
+import { type ChangeEvent, type ComponentPropsWithRef, type ReactNode } from "react";
+import type { InputDesign, TextRules, ValidateOn } from "../../Interfaces/InputInterfaces.ts";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+export type TextBoxType = "text" | "email" | "password" | "search" | "tel" | "url";
+type NativeInputProps = Omit<ComponentPropsWithRef<"input">, "type" | "size" | "pattern" | "prefix" | "children" | keyof TextRules>;
+export interface TextBoxProps extends NativeInputProps, TextRules {
+    /** Default `text`. `password` adds a show-password button. */
+    type?: TextBoxType;
+    label?: ReactNode;
+    /** Help text under the box. */
+    hint?: ReactNode;
+    /** An error from outside, such as the server's "Email is already registered". Shown before the field's own message. */
+    error?: string | null;
+    /** Default `standard`. */
+    design?: InputDesign;
+    /** Default `md`. */
+    size?: Size;
+    /** Decorative icon at the start, e.g. `<InlineIcon icon={iconMail} />`. */
+    icon?: ReactNode;
+    /** Decorative icon at the end. */
+    iconEnd?: ReactNode;
+    /** Text before the value inside the box, e.g. "https://". Read after the label by screen readers. */
+    prefix?: ReactNode;
+    /** Text after the value inside the box, e.g. "@nexus.com". */
+    suffix?: ReactNode;
+    /** Buttons inside the box before the value, such as the rows per page in a table search box. */
+    actionsStart?: ReactNode;
+    /** Shows a clear button while there is text. Esc clears too. */
+    clearable?: boolean;
+    /** Shows the character count, and the limit when `maxLength` is set. */
+    showCount?: boolean;
+    /** What a read-only field says when someone tries to change it. Default "Read-only: this field cannot be changed." */
+    readOnlyMessage?: string;
+    /** Name used in messages, e.g. "Email 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 new text after each change. */
+    onValueChange?: (value: string, event: ChangeEvent<HTMLInputElement>) => void;
+    /** Class of the outer field. `inputClassName` goes on the input. */
+    className?: string;
+    inputClassName?: string;
+}
+/**
+ * A single-line text input with a label, hint, validation message, icons, and optional clear and show-password buttons.
+ * Uncontrolled by default (`defaultValue`), so typing does not re-render it; `value` with `onValueChange` also works.
+ * Inside a `<form>`, invalid fields block submit and show their messages.
+ *
+ * @example <TextBox label="Email" type="email" required pattern={TEXT_PATTERNS.email} icon={<InlineIcon icon={iconMail} />} />
+ */
+export declare function TextBox(props: TextBoxProps): import("react").JSX.Element;
+export {};

package/dist/Components/Inputs/TextBox.js

@@ -0,0 +1,58 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { InlineIcon, iconEye, iconEyeOff, iconX } from "nexus-icons";
+import { useState } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { Field, hasContent } from "./Field.js";
+import { setInputValue } from "./InputField.js";
+import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
+import { useTextField } from "./TextField.js";
+// Values that are not prose: no red spell-check underline, no capital first letter on phones.
+const PLAIN_TYPES = new Set(["email", "password", "tel", "url"]);
+/**
+ * A single-line text input with a label, hint, validation message, icons, and optional clear and show-password buttons.
+ * Uncontrolled by default (`defaultValue`), so typing does not re-render it; `value` with `onValueChange` also works.
+ * Inside a `<form>`, invalid fields block submit and show their messages.
+ *
+ * @example <TextBox label="Email" type="email" required pattern={TEXT_PATTERNS.email} icon={<InlineIcon icon={iconMail} />} />
+ */
+export function TextBox(props) {
+    const { type = "text", label, hint, error, design = "standard", size = "md", icon, iconEnd, prefix, suffix, actionsStart, clearable = false, showCount = false, readOnlyMessage = "Read-only: this field cannot be changed.", fieldName, validateOn, onValueChange, className, inputClassName, style, required, minLength, maxLength, pattern, patternMessage, validate, placeholder, disabled, readOnly, ref, onChange, onBlur, onInvalid, onKeyDown, onClick, ...inputProps } = props;
+    const field = useTextField(props);
+    const [revealed, setRevealed] = useState(false);
+    const editable = !disabled && !readOnly;
+    const plain = PLAIN_TYPES.has(type);
+    // A lock at the end of the box, and a note under it when someone tries to change the text, say why nothing happens.
+    const readOnlyNotice = useReadOnlyNotice(Boolean(readOnly) && !disabled, field.elementRef, readOnlyMessage);
+    function clear() {
+        const input = field.elementRef.current;
+        if (!input)
+            return;
+        setInputValue(input, "");
+        input.focus();
+    }
+    function handleKeyDown(event) {
+        readOnlyNotice.onKeyDown(event);
+        // Esc clears first; a second Esc reaches the page, e.g. to close a dialog.
+        if (clearable && editable && event.key === "Escape" && event.currentTarget.value) {
+            event.preventDefault();
+            event.stopPropagation();
+            clear();
+        }
+        onKeyDown?.(event);
+    }
+    function handleClick(event) {
+        readOnlyNotice.onClick(event);
+        onClick?.(event);
+    }
+    function handleBlur(event) {
+        readOnlyNotice.hide();
+        field.controlProps.onBlur(event);
+    }
+    const actions = (clearable && editable) || type === "password" || readOnlyNotice.lock ? (_jsxs(_Fragment, { children: [clearable && editable && (_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 }) })), type === "password" && (_jsx("button", { type: "button", className: "nx-field__action", "aria-label": "Show password", "aria-controls": field.controlId, "aria-pressed": revealed, title: revealed ? "Hide password" : "Show password", disabled: disabled, onMouseDown: event => event.preventDefault(), onClick: () => setRevealed(current => !current), children: _jsx(InlineIcon, { icon: revealed ? iconEyeOff : iconEye }) })), readOnlyNotice.lock] })) : null;
+    return (_jsxs(_Fragment, { children: [_jsx(Field, { controlId: field.controlId, messageId: field.messageId, label: label, required: required, design: design, size: size, hint: hint, error: field.error, icon: icon, iconEnd: iconEnd, prefix: prefix, suffix: suffix, actionsStart: actionsStart, actions: actions, aside: field.count, disabled: disabled, readOnly: readOnly, 
+                // A prefix sits where the resting label would, so the label stays raised.
+                raiseLabel: Boolean(placeholder) || hasContent(prefix), className: className, style: style, children: _jsx("input", { spellCheck: plain ? false : undefined, autoCapitalize: plain ? "none" : undefined, ...inputProps, ...field.controlProps, type: type === "password" && revealed ? "text" : type, className: cx("nx-field__control", inputClassName), 
+                    // Never empty, so CSS :placeholder-shown can tell an empty field (hides the clear button, lowers the label).
+                    placeholder: placeholder || " ", disabled: disabled, readOnly: readOnly, onClick: handleClick, onBlur: handleBlur, onKeyDown: handleKeyDown }) }), readOnlyNotice.notice] }));
+}

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

@@ -0,0 +1,31 @@
+import { type ChangeEvent } from "react";
+import type { TextRules } from "../../Interfaces/InputInterfaces.ts";
+import { type InputFieldOptions, type TextElement } from "./InputField.tsx";
+export interface TextFieldOptions<E extends TextElement> extends InputFieldOptions<E>, TextRules {
+    value?: string | number | readonly string[];
+    defaultValue?: string | number | readonly string[];
+    showCount?: boolean;
+    onValueChange?: (value: string, event: ChangeEvent<E>) => void;
+}
+/** Behavior shared by TextBox and TextArea: text rules, and a character count written straight to the DOM. */
+export declare function useTextField<E extends TextElement>(options: TextFieldOptions<E>): {
+    controlProps: {
+        maxLength: number | undefined;
+        id: string;
+        ref: (node: E | null) => void;
+        "aria-invalid": boolean | undefined;
+        "aria-required": true | undefined;
+        "aria-describedby": string | undefined;
+        onChange: (event: ChangeEvent<E, Element>) => void;
+        onBlur: (event: import("react").FocusEvent<E, Element>) => void;
+        onInvalid: (event: import("react").FormEvent<E>) => void;
+    };
+    /** Character count for the field's `aside`, when `showCount` is on. */
+    count: import("react").JSX.Element | null;
+    controlId: string;
+    messageId: string;
+    elementRef: import("react").RefObject<E | null>;
+    error: string | null;
+    touch: () => void;
+    change: () => void;
+};

package/dist/Components/Inputs/TextField.js

@@ -0,0 +1,35 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef } from "react";
+import { validateText } from "../../Helpers/ValidationHelpers.js";
+import { useInputField } from "./InputField.js";
+/** Behavior shared by TextBox and TextArea: text rules, and a character count written straight to the DOM. */
+export function useTextField(options) {
+    const { value, defaultValue, showCount = false, required, minLength, maxLength, pattern, patternMessage, validate } = options;
+    const countRef = useRef(null);
+    const rules = { required, minLength, maxLength, pattern, patternMessage, validate };
+    const patternKey = pattern instanceof RegExp ? pattern.toString() : typeof pattern === "object" ? pattern.source : pattern;
+    function updateCount(element) {
+        if (countRef.current)
+            countRef.current.textContent = String(element.value.length);
+    }
+    const field = useInputField({
+        ...options,
+        onChange: event => {
+            updateCount(event.currentTarget);
+            options.onChange?.(event);
+            options.onValueChange?.(event.currentTarget.value, event);
+        },
+    }, {
+        check: (element, name) => validateText(element.value, rules, name),
+        checkKeys: [value, required, minLength, maxLength, patternKey, patternMessage, validate],
+        onReset: updateCount,
+    });
+    const initialLength = String(value ?? defaultValue ?? "").length;
+    return {
+        ...field,
+        controlProps: { ...field.controlProps, maxLength },
+        /** Character count for the field's `aside`, when `showCount` is on. */
+        count: showCount ? (_jsxs("span", { className: "nx-field__count", children: [_jsx("span", { ref: countRef, children: initialLength }), maxLength ? `/${maxLength}` : null] })) : null,
+    };
+}

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

@@ -0,0 +1,34 @@
+import type { DateScript, TimeInput } from "../../Interfaces/DateInterfaces.ts";
+/** `columns`: hours, minutes (seconds), and AM/PM side by side, for any time. `list`: one list of slots, for bookings. */
+export type TimePanelView = "columns" | "list";
+export interface TimePanelProps {
+    /** The chosen time, as an ISO time, or `null` for none. */
+    value: string | null;
+    /** Columns: after each pick in a column, with the whole new time. List: when a slot is picked, before `onDone`. */
+    onValueChange: (value: string) => void;
+    /** The pick is finished: Enter, Done, Now, or a slot of the list. A popover closes on this. */
+    onDone: () => void;
+    /** Default `columns`. */
+    view?: TimePanelView;
+    /** The field's time format, with seconds already added or removed. Decides a 12- or 24-hour clock. */
+    format: string;
+    script?: DateScript;
+    /** Whether values have seconds ("HH:mm:ss"). */
+    seconds?: boolean;
+    /** Seconds between allowed times, from midnight. A list offers a slot per step, or one every 30 minutes for steps under 5 minutes. */
+    step?: number;
+    min?: TimeInput;
+    max?: TimeInput;
+    isTimeDisabled?: (iso: string) => boolean;
+    /** Moves focus into the panel when it mounts, as after ↓ in the box. */
+    autoFocus?: boolean;
+    /** Now and Done buttons under the columns. Default true; a panel that has its own buttons, as in the date and time picker, turns them off. */
+    footer?: boolean;
+    className?: string;
+}
+/**
+ * The panel of a time picker: columns of hours, minutes, seconds, and AM/PM whose chosen items line up on the middle row, or
+ * a list of slots. Items outside `min` and `max`, off the `step`, or refused by `isTimeDisabled` are dimmed and cannot
+ * be picked. It holds no value of its own: the picker passes the value in and writes each pick to its box.
+ */
+export declare function TimePanel(props: TimePanelProps): import("react").JSX.Element;

package/dist/Components/Inputs/TimePanel.js

@@ -0,0 +1,288 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useLayoutEffect, useMemo, useRef } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { toDevanagariDigits } from "../../Helpers/DateHelpers.js";
+import { formatTime, getMeridiemNames, isSecondsInRange, isTwelveHourFormat, listTimeSlots, normalizeTimeStep, nowIsoTime, SECONDS_PER_DAY, secondsToIsoTime, timeToSeconds, toIsoTime, } from "../../Helpers/TimeHelpers.js";
+import { Button } from "../Documents/Button.js";
+const PAGE = 5;
+const gcd = (a, b) => (b === 0 ? a : gcd(b, a % b));
+const COLUMN_LABELS = { hour: "Hours", minute: "Minutes", second: "Seconds", meridiem: "AM or PM" };
+/**
+ * The panel of a time picker: columns of hours, minutes, seconds, and AM/PM whose chosen items line up on the middle row, or
+ * a list of slots. Items outside `min` and `max`, off the `step`, or refused by `isTimeDisabled` are dimmed and cannot
+ * be picked. It holds no value of its own: the picker passes the value in and writes each pick to its box.
+ */
+export function TimePanel(props) {
+    const { value, onValueChange, onDone, view = "columns", format, script = "latin", seconds = false, min, max, isTimeDisabled, autoFocus = false, footer = true, className } = props;
+    const step = normalizeTimeStep(props.step);
+    const rootRef = useRef(null);
+    const scrolledRef = useRef(false);
+    const focusedRef = useRef(false);
+    const minIso = toIsoTime(min, true);
+    const maxIso = toIsoTime(max, true);
+    const from = minIso === null ? null : timeToSeconds(minIso);
+    const to = maxIso === null ? null : timeToSeconds(maxIso);
+    const devanagari = script === "devanagari";
+    const digits = (number) => (devanagari ? toDevanagariDigits(String(number).padStart(2, "0")) : String(number).padStart(2, "0"));
+    const allowed = (time) => isSecondsInRange(time, from, to) && time % step === 0 && !isTimeDisabled?.(secondsToIsoTime(time, seconds));
+    /** Whether any allowed time lies in a span of seconds, e.g. an hour. Stops at the first one. */
+    const anyAllowed = (start, end) => {
+        for (let time = Math.ceil(start / step) * step; time <= end; time += step)
+            if (allowed(time))
+                return true;
+        return false;
+    };
+    /** The first allowed time from a point, going forward through the day, or `null` when none is. */
+    const firstAllowedFrom = (start, end = start + SECONDS_PER_DAY - 1) => {
+        for (let time = Math.ceil(start / step) * step; time <= end; time += step) {
+            const inDay = time % SECONDS_PER_DAY;
+            if (allowed(inDay))
+                return inDay;
+        }
+        return null;
+    };
+    const selected = value === null ? null : timeToSeconds(value);
+    // An empty field shows the columns around the first time it allows, with nothing chosen.
+    const base = useMemo(() => selected ?? firstAllowedFrom(from ?? 0) ?? 0, [selected, from, to, step, isTimeDisabled, seconds]);
+    function pick(kind, itemValue) {
+        let hour = Math.floor(base / 3600);
+        let minute = Math.floor(base / 60) % 60;
+        let second = seconds ? base % 60 : 0;
+        let start;
+        let end;
+        if (kind === "hour") {
+            hour = itemValue;
+            [start, end] = [hour * 3600, hour * 3600 + 3599];
+        }
+        else if (kind === "minute") {
+            minute = itemValue;
+            [start, end] = [hour * 3600 + minute * 60, hour * 3600 + minute * 60 + 59];
+        }
+        else if (kind === "second") {
+            second = itemValue;
+            start = end = hour * 3600 + minute * 60 + second;
+        }
+        else {
+            hour = (hour % 12) + itemValue * 12;
+            [start, end] = [itemValue * 43200, itemValue * 43200 + 43199];
+        }
+        let time = hour * 3600 + minute * 60 + second;
+        // The part just picked stays; smaller parts move to the first time it allows, e.g. 09:45 → 10 o'clock → 10:00 when 10:45 is past `max`.
+        if (!allowed(time))
+            time = firstAllowedFrom(start, end) ?? time;
+        if (time !== selected)
+            onValueChange(secondsToIsoTime(time, seconds));
+    }
+    // Columns
+    const twelveHour = isTwelveHourFormat(format);
+    const half = Math.floor(base / 43200);
+    const baseHour = Math.floor(base / 3600);
+    const baseMinute = Math.floor(base / 60) % 60;
+    const hourInterval = step % 3600 === 0 ? gcd(step / 3600, 24) : 1;
+    const minuteInterval = step % 60 === 0 ? gcd(step / 60, 60) : 1;
+    const secondInterval = gcd(step, 60);
+    const isChosen = selected !== null;
+    const columns = useMemo(() => {
+        if (view !== "columns")
+            return [];
+        const hours = [];
+        const hourStart = twelveHour ? half * 12 : 0;
+        for (let hour = hourStart; hour < hourStart + (twelveHour ? 12 : 24); hour++) {
+            if (hour % hourInterval !== 0)
+                continue;
+            hours.push({
+                value: hour,
+                label: digits(twelveHour ? hour % 12 || 12 : hour),
+                selected: isChosen && hour === baseHour,
+                disabled: !anyAllowed(hour * 3600, hour * 3600 + 3599),
+            });
+        }
+        const minutes = [];
+        for (let minute = 0; minute < 60; minute += minuteInterval) {
+            const start = baseHour * 3600 + minute * 60;
+            minutes.push({
+                value: minute,
+                label: digits(minute),
+                selected: isChosen && minute === baseMinute,
+                disabled: seconds ? !anyAllowed(start, start + 59) : !allowed(start),
+            });
+        }
+        const result = [
+            { kind: "hour", items: hours },
+            { kind: "minute", items: minutes },
+        ];
+        if (seconds) {
+            const items = [];
+            for (let second = 0; second < 60; second += secondInterval) {
+                items.push({ value: second, label: digits(second), selected: isChosen && second === base % 60, disabled: !allowed(baseHour * 3600 + baseMinute * 60 + second) });
+            }
+            result.push({ kind: "second", items });
+        }
+        if (twelveHour) {
+            result.push({
+                kind: "meridiem",
+                items: getMeridiemNames(script).map((label, index) => ({
+                    value: index,
+                    label,
+                    selected: isChosen && index === half,
+                    disabled: !anyAllowed(index * 43200, index * 43200 + 43199),
+                })),
+            });
+        }
+        return result;
+    }, [view, base, isChosen, twelveHour, seconds, script, step, from, to, isTimeDisabled]);
+    // List
+    const slotStep = step >= 300 ? step : 1800;
+    const slots = useMemo(() => {
+        if (view !== "list")
+            return [];
+        return listTimeSlots(slotStep, minIso, maxIso).map(iso => {
+            const time = timeToSeconds(iso);
+            return { value: time, iso, label: formatTime(iso, { format, script }), disabled: !(time % step === 0 && !isTimeDisabled?.(secondsToIsoTime(time, seconds))) };
+        });
+    }, [view, slotStep, minIso, maxIso, format, script, step, isTimeDisabled, seconds]);
+    // The list's slot to scroll to and focus first: the chosen one, the one just before the chosen time, or the first free one.
+    const listAnchor = useMemo(() => {
+        if (view !== "list" || slots.length === 0)
+            return null;
+        if (selected !== null) {
+            const exact = slots.find(slot => slot.value === selected);
+            if (exact)
+                return exact.value;
+            const before = slots.filter(slot => slot.value <= selected).at(-1);
+            if (before)
+                return before.value;
+        }
+        return (slots.find(slot => !slot.disabled) ?? slots[0]).value;
+    }, [view, slots, selected]);
+    // Chosen items scroll to the middle row of their column, so they line up across columns with their neighbours above
+    // and below; the list centers its slot the same way. At once when the panel opens, smoothly after that, unless the
+    // user asked for reduced motion. (Columns are positioned, so an item's offsetTop is measured from the column.)
+    // With `autoFocus`, focus then moves in once.
+    useLayoutEffect(() => {
+        const root = rootRef.current;
+        if (!root)
+            return;
+        const align = () => {
+            const smooth = scrolledRef.current && !window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+            for (const column of root.querySelectorAll("[data-column]")) {
+                const target = column.querySelector(view === "list" ? "[data-anchor]" : '[aria-selected="true"]');
+                if (!target)
+                    continue;
+                const top = target.offsetTop - (column.clientHeight - target.offsetHeight) / 2;
+                if (Math.abs(column.scrollTop - top) > 1)
+                    column.scrollTo({ top, behavior: smooth ? "smooth" : "instant" });
+            }
+            scrolledRef.current = true;
+            if (autoFocus && !focusedRef.current) {
+                focusedRef.current = true;
+                root.querySelector('[role="option"][tabindex="0"]')?.focus({ preventScroll: true });
+            }
+        };
+        if (root.getClientRects().length > 0) {
+            align();
+            return;
+        }
+        // On the first render the popover around the panel is still hidden (the picker shows it after this effect), and a
+        // hidden element can neither scroll nor take focus. The next frame comes before the first paint.
+        const frame = requestAnimationFrame(align);
+        return () => cancelAnimationFrame(frame);
+    });
+    function onColumnKeyDown(event, kind, items) {
+        const target = event.target.closest("[data-value]");
+        if (!target)
+            return;
+        const index = items.findIndex(item => String(item.value) === target.dataset.value);
+        const enabled = (from, direction) => {
+            for (let i = from; i >= 0 && i < items.length; i += direction)
+                if (!items[i].disabled)
+                    return i;
+            return -1;
+        };
+        let next = -1;
+        switch (event.key) {
+            case "ArrowDown":
+                next = enabled(index + 1, 1);
+                break;
+            case "ArrowUp":
+                next = enabled(index - 1, -1);
+                break;
+            case "PageDown":
+                next = enabled(Math.min(index + PAGE, items.length - 1), 1);
+                if (next < 0)
+                    next = enabled(items.length - 1, -1);
+                break;
+            case "PageUp":
+                next = enabled(Math.max(index - PAGE, 0), -1);
+                if (next < 0)
+                    next = enabled(0, 1);
+                break;
+            case "Home":
+                next = enabled(0, 1);
+                break;
+            case "End":
+                next = enabled(items.length - 1, -1);
+                break;
+            case "ArrowLeft":
+            case "ArrowRight": {
+                if (kind === "slot")
+                    return;
+                event.preventDefault();
+                const all = [...(rootRef.current?.querySelectorAll("[data-column]") ?? [])];
+                const column = all[all.indexOf(target.closest("[data-column]")) + (event.key === "ArrowRight" ? 1 : -1)];
+                column?.querySelector('[tabindex="0"]')?.focus({ preventScroll: true });
+                return;
+            }
+            case "Enter":
+            case " ":
+                event.preventDefault();
+                if (kind === "slot") {
+                    const slot = items[index];
+                    if (slot && !slot.disabled)
+                        choose(slot.value);
+                }
+                else {
+                    if (event.key === " " && index >= 0 && !items[index].disabled)
+                        pick(kind, items[index].value);
+                    else
+                        onDone();
+                }
+                return;
+            default:
+                return;
+        }
+        event.preventDefault();
+        if (next < 0 || next === index)
+            return;
+        const item = items[next];
+        // Moving within a column keeps its items, so the element to focus is already there.
+        const element = target.parentElement?.querySelector(`[data-value="${item.value}"]`);
+        element?.focus({ preventScroll: true });
+        if (kind === "slot") {
+            // The list moves focus only; Enter or a click picks.
+            element?.scrollIntoView({ block: "nearest" });
+        }
+        else {
+            // A column is a spin button: the value follows focus, and the column scrolls it to the chosen row.
+            pick(kind, item.value);
+        }
+    }
+    function choose(time) {
+        if (time !== selected)
+            onValueChange(secondsToIsoTime(time, seconds));
+        onDone();
+    }
+    const now = useMemo(() => {
+        const time = Math.floor(timeToSeconds(nowIsoTime(true)) / step) * step;
+        return allowed(time) ? time : null;
+        // Read when the panel renders; a panel stays open for seconds, not hours.
+    }, [step, from, to, isTimeDisabled, seconds]);
+    if (view === "list") {
+        return (_jsx("div", { ref: rootRef, className: cx("nx-time", "nx-time--list", className), lang: devanagari ? "ne" : undefined, children: _jsxs("div", { role: "listbox", "aria-label": "Times", "data-column": "slot", className: "nx-time__list", tabIndex: -1, onKeyDown: event => onColumnKeyDown(event, "slot", slots), children: [slots.map(slot => (_jsx("div", { role: "option", "data-value": slot.value, "data-anchor": slot.value === listAnchor || undefined, "aria-selected": slot.value === selected, "aria-disabled": slot.disabled || undefined, tabIndex: slot.value === listAnchor ? 0 : -1, className: "nx-time__item nx-time__slot", onClick: () => !slot.disabled && choose(slot.value), children: slot.label }, slot.value))), slots.length === 0 && _jsx("div", { className: "nx-time__empty", children: "No times available" })] }) }));
+    }
+    return (_jsxs("div", { ref: rootRef, className: cx("nx-time", className), lang: devanagari ? "ne" : undefined, children: [_jsx("div", { className: "nx-time__columns", children: columns.map(({ kind, items }) => {
+                    const reachable = items.find(item => item.selected && !item.disabled) ?? items.find(item => !item.disabled) ?? items[0];
+                    return (_jsx("div", { role: "listbox", "aria-label": COLUMN_LABELS[kind], "data-column": kind, className: cx("nx-time__column", kind === "meridiem" && "nx-time__column--meridiem"), tabIndex: -1, onKeyDown: event => onColumnKeyDown(event, kind, items), children: items.map((item, index) => (_jsx("div", { role: "option", "data-value": item.value, "aria-selected": item.selected, "aria-disabled": item.disabled || undefined, tabIndex: item === reachable ? 0 : -1, className: "nx-time__item", onClick: () => !item.disabled && pick(kind, item.value), children: item.label }, kind === "hour" ? index : item.value))) }, kind));
+                }) }), footer && (_jsxs("div", { className: "nx-time__foot", children: [_jsx(Button, { size: "sm", variant: "ghost", disabled: now === null, onClick: () => now !== null && choose(now), children: "Now" }), _jsx(Button, { size: "sm", variant: "primary", onClick: onDone, children: "Done" })] }))] }));
+}

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

@@ -0,0 +1,54 @@
+import { type ChangeEvent, type ComponentPropsWithRef, type ReactNode } from "react";
+import type { DateScript, TimeInput, TimeRules } from "../../Interfaces/DateInterfaces.ts";
+import type { InputDesign, ValidateOn } from "../../Interfaces/InputInterfaces.ts";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+import { type TimePanelView } from "./TimePanel.tsx";
+type NativeInputProps = Omit<ComponentPropsWithRef<"input">, "type" | "size" | "value" | "defaultValue" | "min" | "max" | "step" | "prefix" | "pattern" | "minLength" | "maxLength" | "children" | keyof TimeRules>;
+export interface TimePickerProps extends NativeInputProps, TimeRules {
+    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 clock button is always at the end. */
+    icon?: ReactNode;
+    /** Text before the value inside the box. */
+    prefix?: ReactNode;
+    /** 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. */
+    format?: string;
+    /** `devanagari` writes Nepali digits and पूर्वाह्न/अपराह्न. Default: Devanagari when the user's settings show Nepali dates in Devanagari. */
+    script?: DateScript;
+    /** `columns` (default): hours, minutes, and AM/PM, for any time. `list`: a slot every `step` (30 minutes for steps under 5), for bookings. */
+    view?: TimePanelView;
+    /** Times that cannot be picked, such as booked slots. Receives the ISO time. */
+    isTimeDisabled?: (iso: 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 time cannot be changed." */
+    readOnlyMessage?: string;
+    /** Name used in messages, e.g. "Arrival 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 time as an ISO string ("14:30"), or `null` for empty. A `Date` or an ISO date-time is accepted and read as its local time. */
+    value?: TimeInput;
+    defaultValue?: TimeInput;
+    /** After each change: the ISO time ("HH:mm", or "HH:mm:ss" when `step` has seconds), or `null` when the box is empty or holds text that is not a time. */
+    onValueChange?: (value: string | null, event: ChangeEvent<HTMLInputElement>) => void;
+    /** Class of the outer field. `inputClassName` goes on the input. */
+    className?: string;
+    inputClassName?: string;
+}
+/**
+ * A time input: type a time on either clock ("2:30 pm", "1430"), or pick one from the panel that opens under the box.
+ * Written in the user's time format, 12- or 24-hour, and always held as an ISO time with no date and no zone, which a
+ * form sends through a hidden input with the field's `name`. Uncontrolled by default, so typing re-renders nothing.
+ *
+ * @example <TimePicker name="arrival" label="Arrival" min="12:00" max="22:00" step={1800} view="list" />
+ */
+export declare function TimePicker(props: TimePickerProps): import("react").JSX.Element;
+export {};