nexus-shared 1.1.20 → 2.0.0

package/dist/Components/Inputs/DateTimePicker.js

@@ -0,0 +1,399 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { iconCalendarTime, iconX, InlineIcon } from "nexus-icons";
+import { useLayoutEffect, useRef, useState } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { clampIsoDate } from "../../Helpers/DateHelpers.js";
+import { useBrowserTimeZone, useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { describeTimeZone, formatDateTime, fromLocalDateTime, parseLocalDateTimeText, timeScriptOf, toLocalDateTime, toTimeZone, toUtcDateTime } from "../../Helpers/DateTimeHelpers.js";
+import { followAnchor, isPopoverOpen, placeUnderAnchor } from "../../Helpers/PopoverHelpers.js";
+import { isSecondsInRange, normalizeTimeStep, SECONDS_PER_DAY, secondsToIsoTime, timeFormatWithSeconds, timeToSeconds, toIsoTime } from "../../Helpers/TimeHelpers.js";
+import { DEFAULT_FIELD_NAME, validateDateTime } from "../../Helpers/ValidationHelpers.js";
+import { Button } from "../Documents/Button.js";
+import { Calendar } from "./Calendar.js";
+import { Field, hasContent } from "./Field.js";
+import { setInputValue, useInputField } from "./InputField.js";
+import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
+import { TimePanel } from "./TimePanel.js";
+const PANEL_GAP = 4;
+const PANEL_MARGIN = 8;
+/**
+ * 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 function DateTimePicker(props) {
+    const { label, hint, error, design = "standard", size = "md", icon, prefix, calendar: calendarProp, format: formatProp, timeFormat: timeFormatProp, script: scriptProp, timeZone: timeZoneProp, showTimeZone = Boolean(timeZoneProp), view = "columns", defaultTime, clearable = true, fieldName, readOnlyMessage = "Read-only: this date and time cannot be changed.", validateOn, value, defaultValue, onValueChange, isDateDisabled, isTimeDisabled, weekStart, weekendDays, showOutsideDays, className, inputClassName, style, required, min, max, minTime, maxTime, step, validate, name, form, placeholder, disabled, readOnly, ref, onChange, onBlur, onFocus, onInvalid, onKeyDown, onClick, ...inputProps } = props;
+    const preferences = useDatePreferences();
+    const browserZone = useBrowserTimeZone();
+    // Unknown on the server and while the page hydrates: the box stays empty until then rather than show another zone's time.
+    const zone = toTimeZone(timeZoneProp) ?? browserZone;
+    const stepSize = normalizeTimeStep(step);
+    const seconds = stepSize % 60 !== 0;
+    const options = {
+        calendar: calendarProp ?? preferences.calendar,
+        format: formatProp ?? preferences.format,
+        script: scriptProp ?? preferences.script,
+        timeFormat: timeFormatWithSeconds(timeFormatProp ?? preferences.timeFormat, seconds),
+        timeZone: zone ?? undefined,
+        seconds,
+    };
+    const editable = !disabled && !readOnly;
+    const initial = toUtcDateTime(value !== undefined ? value : defaultValue, zone ?? "UTC");
+    const text = (iso) => (zone ? formatDateTime(iso, options) : "");
+    /** A time of day at the precision the box shows: "14:30", or "14:30:15" when the step has seconds. */
+    const shownTime = (time) => (seconds ? time : time.slice(0, 5));
+    const messageName = fieldName ?? (typeof label === "string" ? label : DEFAULT_FIELD_NAME);
+    const startTime = shownTime(toIsoTime(defaultTime, true) ?? toIsoTime(minTime, true) ?? "00:00:00");
+    const zoneCity = zone && showTimeZone ? zone.slice(zone.lastIndexOf("/") + 1).replaceAll("_", " ") : null;
+    const valueRef = useRef(initial);
+    // The moment the box held before the text being typed: set by a pick, leaving the box, or a reset, and kept while
+    // the text is cleared or retyped, so every keystroke is read against it.
+    const committedRef = useRef(initial);
+    const editedRef = useRef(false);
+    // A value being picked: the text written for it reads back as this very moment.
+    const pendingRef = useRef(null);
+    const hiddenRef = useRef(null);
+    const panelRef = useRef(null);
+    const focusPanelRef = useRef(false);
+    const focusTimeRef = useRef(false);
+    const revealTimeRef = useRef(false);
+    const [open, setOpen] = useState(false);
+    // Re-renders the panel's selection while it is open; typing with it closed re-renders nothing.
+    const [panelValue, setPanelValue] = useState(initial);
+    const rules = {
+        required,
+        min,
+        max,
+        minTime,
+        maxTime,
+        step,
+        validate: iso => {
+            const local = iso && zone ? toLocalDateTime(iso, zone) : null;
+            if (local && (isDateDisabled?.(local.date) || isTimeDisabled?.(shownTime(local.time), local.date)))
+                return `${messageName} cannot be ${text(iso)}.`;
+            return validate?.(iso);
+        },
+    };
+    const field = useInputField({
+        ...props,
+        suffix: zoneCity,
+        onChange: event => {
+            const input = event.currentTarget;
+            const iso = input.value.trim() ? read(input.value) : 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 and time is checked as itself, so the message says what to type.
+        check: (input, messageName) => validateDateTime(valueRef.current ?? (input.value.trim() ? input.value : null), rules, messageName, options),
+        checkKeys: [value, required, min, max, minTime, maxTime, step, validate, isDateDisabled, isTimeDisabled, zone, options.calendar, options.format, options.script, options.timeFormat],
+        onReset: input => {
+            // Back to the moment the field started with, written in the current settings.
+            editedRef.current = false;
+            valueRef.current = initial;
+            committedRef.current = initial;
+            input.value = text(initial);
+            sync(initial);
+        },
+    });
+    // A read-only box has no panel: 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"] });
+    /**
+     * The moment typed text names in the zone. A date without a time takes the start time. Text that names what a pick
+     * being written, the value, or the committed value shows keeps that moment, with its hidden seconds and milliseconds,
+     * and the second of two equal times when clocks go back; other text in a repeated hour keeps the committed offset.
+     */
+    function read(typed) {
+        const local = zone ? parseLocalDateTimeText(typed, options) : null;
+        if (!zone || !local)
+            return null;
+        const time = local.time ? shownTime(local.time) : startTime;
+        for (const candidate of [pendingRef.current, valueRef.current, committedRef.current]) {
+            const shown = candidate ? toLocalDateTime(candidate, zone) : null;
+            if (shown && shown.date === local.date && shownTime(shown.time) === time)
+                return candidate;
+        }
+        return fromLocalDateTime(local.date, time, zone, pendingRef.current ?? committedRef.current);
+    }
+    /** 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;
+        if (initial)
+            committedRef.current = initial;
+        input.value = text(initial);
+        sync(initial);
+        setPanelValue(initial);
+    }, [initial]);
+    // The zone becoming known after hydration, another zone, or new settings rewrite the same moment.
+    useLayoutEffect(() => {
+        const input = field.elementRef.current;
+        if (input && valueRef.current)
+            input.value = text(valueRef.current);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [zone, options.calendar, options.format, options.script, options.timeFormat]);
+    // 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 value back.
+    useLayoutEffect(() => {
+        sync(valueRef.current);
+        // A day picked by keyboard moves focus on to the time, once the panel shows the new day. In a panel too tall for
+        // the window, which scrolls, a picked day scrolls up to the time, and on to Done when there is room.
+        const panel = panelRef.current;
+        if (panel && revealTimeRef.current) {
+            revealTimeRef.current = false;
+            const time = panel.querySelector(".nx-datetime__time");
+            if (time && panel.scrollHeight > panel.clientHeight)
+                panel.scrollTop = Math.min(time.offsetTop, panel.scrollHeight - panel.clientHeight);
+        }
+        if (panel && focusTimeRef.current) {
+            focusTimeRef.current = false;
+            panel.querySelector('[data-column] [role="option"][tabindex="0"]')?.focus({ preventScroll: true });
+        }
+    });
+    // The panel is a manual popover under the box (above it when there is no room). It closes only through this
+    // component (Esc, Enter, Done, a slot of a list, focus or a press elsewhere), so the state always matches the screen.
+    useLayoutEffect(() => {
+        const panel = panelRef.current;
+        const box = field.elementRef.current?.closest(".nx-field__box");
+        if (!open || !panel || !box)
+            return;
+        if (!isPopoverOpen(panel))
+            panel.showPopover();
+        const place = () => {
+            const anchor = box.getBoundingClientRect();
+            // Too tall for either side, as on a phone: it takes the side with more room, and scrolls. The cap changes only
+            // when the room does, so scrolling inside the panel (which runs this again) keeps its place.
+            const natural = panel.scrollHeight + panel.offsetHeight - panel.clientHeight;
+            const room = Math.floor(Math.max(window.innerHeight - anchor.bottom, anchor.top) - PANEL_GAP - PANEL_MARGIN);
+            const cap = natural > room ? `${Math.max(0, room)}px` : "";
+            if (panel.style.maxHeight !== cap)
+                panel.style.maxHeight = cap;
+            placeUnderAnchor(panel, anchor, { gap: PANEL_GAP, margin: PANEL_MARGIN });
+        };
+        place();
+        if (focusPanelRef.current) {
+            focusPanelRef.current = false;
+            panel.querySelector('[role="gridcell"][tabindex="0"]')?.focus();
+        }
+        const stopFollowing = followAnchor(place);
+        const onPointerDown = (event) => {
+            const target = event.target;
+            if (!panel.contains(target) && !box.contains(target))
+                closePanel();
+        };
+        document.addEventListener("pointerdown", onPointerDown, true);
+        return () => {
+            stopFollowing();
+            document.removeEventListener("pointerdown", onPointerDown, true);
+            if (isPopoverOpen(panel))
+                panel.hidePopover();
+        };
+    }, [open]);
+    function openPanel(focusCalendar) {
+        if (!editable || !zone)
+            return;
+        // The box is the control: it keeps focus while the panel is open, so Esc and Enter reach it.
+        field.elementRef.current?.focus();
+        focusPanelRef.current = focusCalendar;
+        // Shown before its content renders, so the time columns can scroll as they mount. Nothing is painted in between.
+        const panel = panelRef.current;
+        if (panel && !isPopoverOpen(panel))
+            panel.showPopover();
+        setPanelValue(valueRef.current);
+        setOpen(true);
+    }
+    /** Closes the panel. With `returnFocus`, focus that was inside the panel goes back to the box (Esc, Enter, Done). */
+    function closePanel(returnFocus = false) {
+        const panel = panelRef.current;
+        const focusInPanel = Boolean(panel?.contains(document.activeElement));
+        if (isPopoverOpen(panel))
+            panel.hidePopover();
+        setOpen(false);
+        if (returnFocus && focusInPanel)
+            field.elementRef.current?.focus();
+    }
+    function select(iso) {
+        const input = field.elementRef.current;
+        if (!input || !iso)
+            return;
+        pendingRef.current = iso;
+        setInputValue(input, text(iso));
+        pendingRef.current = null;
+        committedRef.current = valueRef.current;
+        field.touch();
+    }
+    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();
+            if (open)
+                panelRef.current?.querySelector('[role="gridcell"][tabindex="0"]')?.focus();
+            else
+                openPanel(true);
+        }
+        else if (key === "Escape" && open) {
+            // Closes the panel only: the page (a dialog, say) does not see this Esc.
+            event.preventDefault();
+            event.stopPropagation();
+            closePanel();
+        }
+        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 panel; ↓ 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 and time.
+        const input = event.currentTarget;
+        if (valueRef.current && input.value !== text(valueRef.current))
+            input.value = text(valueRef.current);
+        if (valueRef.current)
+            committedRef.current = valueRef.current;
+        // Focus moving anywhere but the panel closes it.
+        if (open && !(event.relatedTarget instanceof Node && panelRef.current?.contains(event.relatedTarget)))
+            closePanel();
+        readOnlyNotice.hide();
+        field.controlProps.onBlur(event);
+    }
+    // Focus leaving the panel for anything but the box (Tab past Done, a click elsewhere) closes it.
+    function handlePanelBlur(event) {
+        const next = event.relatedTarget;
+        if (next instanceof Node && (event.currentTarget.contains(next) || next === field.elementRef.current))
+            return;
+        closePanel();
+    }
+    function handlePanelKeyDown(event) {
+        if (event.key !== "Escape")
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        closePanel(true);
+    }
+    /** The panel's content: the calendar, the time on the day shown, and Now, the zone, and Done. Built only while open. */
+    function renderPanel(zone) {
+        const now = Date.now();
+        const today = toLocalDateTime(now, zone).date;
+        const minValue = toUtcDateTime(min, zone);
+        const maxValue = toUtcDateTime(max, zone);
+        const from = minValue ? toLocalDateTime(minValue, zone) : null;
+        const to = maxValue ? toLocalDateTime(maxValue, zone) : null;
+        const chosen = panelValue ? toLocalDateTime(panelValue, zone) : null;
+        const minTimeIso = toIsoTime(minTime, true);
+        const maxTimeIso = toIsoTime(maxTime, true);
+        const dailyFrom = minTimeIso === null ? null : timeToSeconds(minTimeIso);
+        const dailyTo = maxTimeIso === null ? null : timeToSeconds(maxTimeIso);
+        // The day the time columns work on: the chosen one, or today kept inside the limits.
+        const day = chosen?.date ?? clampIsoDate(today, from?.date, to?.date);
+        /** The seconds of a day inside `min` and `max`, or `null` when none are. */
+        const boundsOf = (date) => {
+            let low = 0;
+            let high = SECONDS_PER_DAY - 1;
+            if (from && date < from.date)
+                return null;
+            // A limit with milliseconds starts at the next whole second.
+            if (from && date === from.date)
+                low = timeToSeconds(from.time) + (minValue.endsWith(".000Z") ? 0 : 1);
+            if (to && date > to.date)
+                return null;
+            if (to && date === to.date)
+                high = timeToSeconds(to.time);
+            return low <= high ? [low, high] : null;
+        };
+        const allowedIn = (date, bounds, time) => bounds !== null &&
+            time >= bounds[0] &&
+            time <= bounds[1] &&
+            isSecondsInRange(time, dailyFrom, dailyTo) &&
+            time % stepSize === 0 &&
+            !isTimeDisabled?.(secondsToIsoTime(time, seconds), date);
+        /** The allowed time of a day nearest after a wanted time, or before it when none comes after; `null` when the day has none. */
+        const nearestAllowed = (date, wanted) => {
+            const bounds = boundsOf(date);
+            if (!bounds || isDateDisabled?.(date))
+                return null;
+            for (let time = Math.ceil(wanted / stepSize) * stepSize; time < SECONDS_PER_DAY; time += stepSize)
+                if (allowedIn(date, bounds, time))
+                    return time;
+            for (let time = Math.floor(wanted / stepSize) * stepSize - stepSize; time >= 0; time -= stepSize)
+                if (allowedIn(date, bounds, time))
+                    return time;
+            return null;
+        };
+        function pickDay(date) {
+            const wanted = timeToSeconds(chosen ? shownTime(chosen.time) : startTime);
+            const time = nearestAllowed(date, wanted) ?? wanted;
+            // Picked by keyboard: focus moves on to the time.
+            focusTimeRef.current = Boolean(panelRef.current?.querySelector(".nx-cal")?.contains(document.activeElement));
+            revealTimeRef.current = true;
+            select(fromLocalDateTime(date, secondsToIsoTime(time, seconds), zone, panelValue));
+        }
+        // Now, on the step: the step before it when allowed, else the step after, e.g. with `min` set to the page's now.
+        const nowLocal = toLocalDateTime(now, zone);
+        const nowSeconds = timeToSeconds(nowLocal.time);
+        const nowBounds = isDateDisabled?.(nowLocal.date) ? null : boundsOf(nowLocal.date);
+        const nowTime = [Math.floor(nowSeconds / stepSize) * stepSize, Math.ceil(nowSeconds / stepSize) * stepSize].find(time => time < SECONDS_PER_DAY && allowedIn(nowLocal.date, nowBounds, time));
+        const dayBounds = isDateDisabled?.(day) ? null : boundsOf(day);
+        const info = describeTimeZone(zone, panelValue ?? now);
+        return (_jsxs("div", { className: "nx-datetime", children: [_jsxs("div", { className: "nx-datetime__body", children: [_jsx(Calendar, { size: "sm", footer: false, className: "nx-datetime__calendar", calendar: options.calendar, script: options.script, value: chosen?.date ?? null, defaultMonth: day, today: today, onSelect: pickDay, min: from?.date, max: to?.date, isDateDisabled: isDateDisabled, weekStart: weekStart, weekendDays: weekendDays, showOutsideDays: showOutsideDays, "aria-label": "Calendar" }), _jsx(TimePanel, { className: "nx-datetime__time", view: view, footer: false, value: chosen ? shownTime(chosen.time) : null, onValueChange: time => select(fromLocalDateTime(day, time, zone, panelValue)), onDone: () => closePanel(true), format: options.timeFormat, script: timeScriptOf(options), seconds: seconds, step: step, min: minTime, max: maxTime, isTimeDisabled: time => {
+                                const total = timeToSeconds(time);
+                                return dayBounds === null || total < dayBounds[0] || total > dayBounds[1] || Boolean(isTimeDisabled?.(time, day));
+                            } })] }), _jsxs("div", { className: "nx-datetime__foot", children: [_jsx(Button, { size: "sm", variant: "ghost", hoverTone: "primary", disabled: nowTime === undefined, onClick: () => {
+                                if (nowTime === undefined)
+                                    return;
+                                select(fromLocalDateTime(nowLocal.date, secondsToIsoTime(nowTime, seconds), zone));
+                                closePanel(true);
+                            }, children: "Now" }), _jsx("span", { className: "nx-datetime__zone", title: info.name, children: info.id === "UTC" ? "UTC" : `${info.city} · ${info.offset}` }), _jsx(Button, { size: "sm", variant: "primary", onClick: () => closePanel(true), children: "Done" })] })] }));
+    }
+    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, suffix: zoneCity, 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--datetime", tabIndex: -1, "aria-label": "Choose a date and time", "aria-haspopup": "dialog", "aria-expanded": open, "aria-controls": open ? `${field.controlId}-datetime` : undefined, title: "Choose a date and time", disabled: disabled, onMouseDown: event => event.preventDefault(), onClick: () => (open ? closePanel() : openPanel(false)), children: _jsx(InlineIcon, { icon: iconCalendarTime }) }))] }), disabled: disabled, readOnly: readOnly, raiseLabel: Boolean(placeholder) || hasContent(prefix), className: cx("nx-field--datetime", className), style: style, children: [_jsx("input", { autoComplete: "off", spellCheck: false, ...inputProps, ...field.controlProps, type: "text", name: undefined, form: form, lang: timeScriptOf(options) === "devanagari" ? "ne" : undefined, defaultValue: text(initial), className: cx("nx-field__control", "nx-field__control--datetime", 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}-datetime`, popover: "manual", role: "dialog", "aria-label": "Choose a date and time", className: cx("nx-popover", "nx-datetime-popover"), onKeyDown: handlePanelKeyDown, onBlur: handlePanelBlur, 
+                // The box keeps focus while days, times, and buttons are clicked. The month and year menus need focus to
+                // open, and a press on a time column itself is left alone, so its scroll bar can be dragged.
+                onMouseDown: event => {
+                    const target = event.target;
+                    if (!target.closest("select") && !target.matches("[data-column]"))
+                        event.preventDefault();
+                }, children: open && zone && renderPanel(zone) }))] }));
+}

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

@@ -0,0 +1,117 @@
+import { type ComponentPropsWithRef, type ReactNode } from "react";
+import type { ChoiceOption, DropdownColumn, DropdownItem, DropdownPage, DropdownPageRequest, InputDesign, OptionValue, SelectionRules, ValidateOn } from "../../Interfaces/InputInterfaces.ts";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+type NativeInputProps = Omit<ComponentPropsWithRef<"input">, "type" | "size" | "value" | "defaultValue" | "min" | "max" | "step" | "prefix" | "pattern" | "minLength" | "maxLength" | "children" | "multiple" | "list" | "onChange" | "onInput">;
+interface DropdownBaseProps<TItem extends DropdownItem, TValue extends OptionValue> extends NativeInputProps, Pick<SelectionRules<TValue>, "required" | "validate"> {
+    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 of the box. */
+    icon?: ReactNode;
+    /** The options, for a list the page already has. Searched in the browser. Ignored for picking when `loadOptions` is set. */
+    options?: readonly TItem[];
+    /** Loads the options page by page from a server, for the search typed: the first page when the list opens, the next near its end. */
+    loadOptions?: (request: DropdownPageRequest) => Promise<DropdownPage<TItem>>;
+    /** Change it to drop the loaded pages and load again, e.g. the id of the country whose cities `loadOptions` loads. */
+    loadKey?: unknown;
+    /** Items per page for `loadOptions`. Default 50. */
+    pageSize?: number;
+    /**
+     * The items of the current value, when the list may not hold them: a saved record's country on page 7 of a server list,
+     * or a user who has since become inactive. They show the value, and are never offered for picking unless the list has them.
+     */
+    selectedOptions?: readonly TItem[];
+    /** Loads the items of values that no list or `selectedOptions` has, e.g. by id. Values it does not return show as "Not found". */
+    resolveOptions?: (values: TValue[]) => Promise<readonly TItem[]>;
+    /** The item field that holds the value. Default `value`. */
+    valueKey?: string;
+    /** The item field shown as its name, in the box and in the list. Default `label`. */
+    labelKey?: string;
+    /** A second line under the label, in rows without columns. Default `description`. */
+    descriptionKey?: string;
+    /** A Tabler icon name or an element before the label, in rows without columns. Default `icon`. */
+    iconKey?: string;
+    /** Rows as columns, like a data table: an avatar, a username, and a full name; or a flag, a code, and a country. */
+    columns?: readonly DropdownColumn<TItem>[];
+    /** The fields a typed search looks in. Default: the label, the description, the value, and the text and code columns. */
+    searchKeys?: readonly string[];
+    /** Items shown but not pickable, such as a sold-out room. Default: `disabled: true`. */
+    isOptionDisabled?: (item: TItem) => boolean;
+    /** Items never offered: they show only as a current value, and cannot be picked again once removed. Default: `inactive: true` or `isActive: false`. */
+    isOptionInactive?: (item: TItem) => boolean;
+    /** Typing in the box searches the list. Default: on with `loadOptions` or more than 8 options; off, typed letters jump to an option. */
+    searchable?: boolean;
+    /** A button that clears the value. Default true. */
+    clearable?: boolean;
+    /** Options are on their way (the page loads them itself): a spinner in the box, and placeholder rows in the list. */
+    loading?: boolean;
+    /** Shown in an empty list. Default "No options". */
+    emptyMessage?: string;
+    /** Draws the chosen item in the box instead of its picture and label. */
+    renderValue?: (item: TItem) => ReactNode;
+    /** Width of the list's panel, e.g. 420 or "28rem". Default: the box's width, or wider for its content. */
+    panelWidth?: number | string;
+    /** What a read-only field says when someone tries to change it. Default "Read-only: this choice cannot be changed." */
+    readOnlyMessage?: string;
+    /** Name used in messages, e.g. "Country 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;
+    /** Class of the outer field. `inputClassName` goes on the input. */
+    className?: string;
+    inputClassName?: string;
+}
+export interface SingleDropdownProps<TItem extends DropdownItem, TValue extends OptionValue> extends DropdownBaseProps<TItem, TValue> {
+    multiple?: false;
+    /** The chosen value, or `null` for none. With `value`, the dropdown is controlled; pair it with `onValueChange`. */
+    value?: TValue | null;
+    defaultValue?: TValue | null;
+    /** After each change: the value and its item, or `null` when cleared. The item is `null` for a value nothing is known about. */
+    onValueChange?: (value: TValue | null, item: TItem | null) => void;
+    min?: never;
+    max?: never;
+    selectAll?: never;
+    maxChips?: never;
+}
+export interface MultipleDropdownProps<TItem extends DropdownItem, TValue extends OptionValue> extends DropdownBaseProps<TItem, TValue> {
+    multiple: true;
+    /** The chosen values, in the order they were picked. With `value`, the dropdown is controlled. */
+    value?: readonly TValue[];
+    defaultValue?: readonly TValue[];
+    /** After each change: the values, and their items in the same order (`null` for values nothing is known about). */
+    onValueChange?: (values: TValue[], items: (TItem | null)[]) => void;
+    /** Fewest choices. Not checked when nothing is chosen; use `required` for that. */
+    min?: number;
+    /** Most choices. The other options are disabled at this count. */
+    max?: number;
+    /**
+     * Select all and Clear buttons in the list's footer, beside the count and Done. They act on what the list shows: every option, or the matches of a
+     * typed search. A server list with more pages to load selects the rows loaded ("Select 30 shown"). Default true.
+     */
+    selectAll?: boolean;
+    /** The most chips the box shows: the rest count in one "+12 more" chip, so a long selection keeps the box small. 0 shows "12 selected". Default 10. */
+    maxChips?: number;
+}
+export type DropdownProps<TItem extends DropdownItem = ChoiceOption<OptionValue>, TValue extends OptionValue = OptionValue> = SingleDropdownProps<TItem, TValue> | MultipleDropdownProps<TItem, TValue>;
+/**
+ * Pick one value, or several with `multiple`, from options the page has or pages a server sends while the user
+ * searches and scrolls. Rows can be columns like a data table (avatar, username, full name; flag, code, country).
+ *
+ * The value always shows, even when the list cannot offer it: a saved value on a page not loaded yet (pass
+ * `selectedOptions` or `resolveOptions` for its label), an inactive item, or an item no longer among the options.
+ * Such values sit at the top of the list with a tag, can be removed, and cannot be picked again.
+ *
+ * A form gets the value through hidden inputs named `name` (one per value with `multiple`). The list renders only
+ * while it is open, so a form of many dropdowns mounts light.
+ *
+ * @example <Dropdown name="country" label="Country" options={countries} valueKey="code" labelKey="name" columns={[{ key: "flag", type: "image" }, { key: "code", type: "code" }, { key: "name" }]} />
+ */
+export declare function Dropdown<TItem extends DropdownItem = ChoiceOption<OptionValue>, TValue extends OptionValue = OptionValue>(props: MultipleDropdownProps<TItem, TValue>): ReactNode;
+export declare function Dropdown<TItem extends DropdownItem = ChoiceOption<OptionValue>, TValue extends OptionValue = OptionValue>(props: SingleDropdownProps<TItem, TValue>): ReactNode;
+export {};