nexus-shared 1.1.20 → 2.0.0

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

@@ -0,0 +1,69 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { CalendarDay, CalendarType, DateInput, DateRange, DateScript } from "../../Interfaces/DateInterfaces.ts";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+export type { DateRange } from "../../Interfaces/DateInterfaces.ts";
+export interface CalendarProps {
+    /** Picks one day (default) or a start and an end. */
+    mode?: "single" | "range";
+    /** The chosen day, as an ISO date. With `value`, the calendar is controlled. */
+    value?: DateInput;
+    defaultValue?: DateInput;
+    /** After a day is chosen or cleared, with the ISO date or `null`. */
+    onValueChange?: (value: string | null) => void;
+    /** Range mode: the chosen range. With `range`, the calendar is controlled. */
+    range?: DateRange;
+    defaultRange?: DateRange;
+    /** Range mode: after the start is chosen (end `null`), after the end is chosen, and after a clear. */
+    onRangeChange?: (range: [string | null, string | null]) => void;
+    /** After a pick is complete: a day, or the end of a range. A popover closes on this. */
+    onSelect?: (value: string) => void;
+    /** The calendar shown: `ad` or `bs`. Default: the user's setting. Values are ISO dates in either case. */
+    calendar?: CalendarType;
+    /** Digits and names of Nepali dates. Default: the user's setting. */
+    script?: DateScript;
+    /** Earliest day that can be picked. */
+    min?: DateInput;
+    /** Latest day that can be picked. */
+    max?: DateInput;
+    /** Days that cannot be picked, such as booked nights. */
+    isDateDisabled?: (iso: string) => boolean;
+    /** The month shown, as any day in it. With `month`, moving between months goes through `onMonthChange`. */
+    month?: DateInput;
+    defaultMonth?: DateInput;
+    /** After the shown month changes, with its first day. */
+    onMonthChange?: (firstDay: string) => void;
+    /** Months shown side by side, from the one in `month`: 1 (default) or 2, for ranges. With more than one, outside days are not drawn. */
+    months?: number;
+    /** First column of the week: 0 Sunday (default), 1 Monday, 6 Saturday. */
+    weekStart?: number;
+    /** Weekdays drawn as holidays (0 Sunday to 6 Saturday). Default: Saturday in the Nepali calendar, none otherwise. */
+    weekendDays?: readonly number[];
+    /** Shows the days of the months before and after that fill the first and last rows. Default true. */
+    showOutsideDays?: boolean;
+    /** Draws the inside of a day, e.g. the number with event markers under it. Default: the day number. */
+    renderDay?: (day: CalendarDay) => ReactNode;
+    /** Today and Clear buttons under the grid. Default true. */
+    footer?: boolean;
+    /** The day marked and picked as today, as an ISO date. Default: today where the browser is; a date and time picker showing another time zone passes that zone's day. */
+    today?: DateInput;
+    /** Default `md`. */
+    size?: Size;
+    readOnly?: boolean;
+    disabled?: boolean;
+    /** Focuses the calendar's current day when it mounts. */
+    autoFocus?: boolean;
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+}
+/**
+ * A month of days to pick from, in the English (AD) or Nepali (BS) calendar, with month and year menus, arrow-key
+ * navigation, a range mode with a live preview, two months side by side with `months`, and a `renderDay` slot for
+ * event markers. Values are ISO dates in the Gregorian calendar whatever calendar is shown. It is the panel of
+ * `DatePicker` and `DateRangePicker`, and works on its own in a page.
+ *
+ * @example <Calendar value={date} onValueChange={setDate} min={todayIsoDate()} />
+ */
+export declare function Calendar(props: CalendarProps): import("react").JSX.Element;

package/dist/Components/Inputs/Calendar.js

@@ -0,0 +1,258 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { InlineIcon, iconChevronLeft, iconChevronRight } from "nexus-icons";
+import { useEffect, useId, useRef, useState } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { addDays, addMonths, CALENDAR_RANGE, daysInMonth, formatDateParts, fromCalendar, getMonthNames, getWeekdayNames, toCalendar, toDevanagariDigits, todayIsoDate, toIsoDate, usesDevanagari, weekdayOf, } from "../../Helpers/DateHelpers.js";
+import { useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { BS_FIRST_YEAR, BS_LAST_YEAR } from "../../Helpers/NepaliCalendar.js";
+import { Button } from "../Documents/Button.js";
+const ROWS = 6;
+const LABEL_FORMAT = "dddd, MMMM D, YYYY";
+const yearsWindow = (calendar, today, min, max) => {
+    const first = calendar === "bs" ? BS_FIRST_YEAR : today.year - 100;
+    const last = calendar === "bs" ? BS_LAST_YEAR : today.year + 50;
+    return { first: min ? Math.max(min.year, first) : first, last: max ? Math.min(max.year, last) : last };
+};
+/**
+ * A month of days to pick from, in the English (AD) or Nepali (BS) calendar, with month and year menus, arrow-key
+ * navigation, a range mode with a live preview, two months side by side with `months`, and a `renderDay` slot for
+ * event markers. Values are ISO dates in the Gregorian calendar whatever calendar is shown. It is the panel of
+ * `DatePicker` and `DateRangePicker`, and works on its own in a page.
+ *
+ * @example <Calendar value={date} onValueChange={setDate} min={todayIsoDate()} />
+ */
+export function Calendar(props) {
+    const { mode = "single", value, defaultValue, onValueChange, range, defaultRange, onRangeChange, onSelect, min, max, isDateDisabled, month, defaultMonth, onMonthChange, months = 1, weekStart = 0, weekendDays, showOutsideDays = true, renderDay, footer = true, size = "md", readOnly = false, disabled = false, autoFocus = false, id, className, style, } = props;
+    const preferences = useDatePreferences();
+    const calendar = props.calendar ?? preferences.calendar;
+    const script = props.script ?? preferences.script;
+    const devanagari = usesDevanagari(calendar, script);
+    const lang = devanagari ? "ne" : undefined;
+    const isRange = mode === "range";
+    const inert = readOnly || disabled;
+    const monthCount = Math.max(1, Math.floor(months));
+    // Two months share their edges, so the days of a neighbour are drawn once, in their own month.
+    const outsideDays = showOutsideDays && monthCount === 1;
+    const generatedId = useId();
+    const rootId = id ?? generatedId;
+    const gridRef = useRef(null);
+    const focusPendingRef = useRef(false);
+    // The value: one day, or a start and an end.
+    const [ownValue, setOwnValue] = useState(() => toIsoDate(defaultValue));
+    const [ownRange, setOwnRange] = useState(() => [toIsoDate(defaultRange?.[0]), toIsoDate(defaultRange?.[1])]);
+    const selected = value !== undefined ? toIsoDate(value) : ownValue;
+    const [rangeStart, rangeEnd] = range !== undefined ? [toIsoDate(range[0]), toIsoDate(range[1])] : ownRange;
+    const picking = isRange && rangeStart !== null && rangeEnd === null;
+    const [hoverEnd, setHoverEnd] = useState(null);
+    // Limits, as ISO dates, kept inside the days the calendar covers.
+    const today = toIsoDate(props.today) ?? todayIsoDate();
+    const minIso = toIsoDate(min) ?? CALENDAR_RANGE[calendar].min;
+    const maxIso = toIsoDate(max) ?? CALENDAR_RANGE[calendar].max;
+    const clampView = (iso) => (iso < CALENDAR_RANGE[calendar].min ? CALENDAR_RANGE[calendar].min : iso > CALENDAR_RANGE[calendar].max ? CALENDAR_RANGE[calendar].max : iso);
+    // The month shown is remembered as a day in it, so a change of calendar keeps showing the month of that day.
+    const [ownView, setOwnView] = useState(() => toIsoDate(defaultMonth) ?? (isRange ? rangeStart : selected) ?? today);
+    const viewIso = clampView((month !== undefined ? toIsoDate(month) : null) ?? ownView);
+    const view = toCalendar(viewIso, calendar) ?? toCalendar(CALENDAR_RANGE[calendar].min, calendar);
+    const viewStart = { year: view.year, month: view.month, day: 1 };
+    const firstOfMonth = fromCalendar(viewStart, calendar);
+    // The first day after the last month shown. At the end of the Nepali table, the day after its last day.
+    const afterShown = fromCalendar(addMonths(viewStart, monthCount, calendar), calendar);
+    const shownEnd = afterShown && afterShown > firstOfMonth ? afterShown : addDays(CALENDAR_RANGE[calendar].max, 1);
+    // The day that takes focus, in the roving tab order of the grid: the chosen day when it is on screen, else today,
+    // else the first day of the month shown.
+    const inShown = (iso) => iso !== null && iso >= firstOfMonth && iso < shownEnd;
+    const [focused, setFocused] = useState(() => {
+        const chosen = isRange ? rangeStart : selected;
+        return inShown(chosen) ? chosen : inShown(today) ? today : firstOfMonth;
+    });
+    const isDisabled = (iso) => iso < minIso || iso > maxIso || (isDateDisabled?.(iso) ?? false);
+    function showMonth(iso) {
+        const next = clampView(iso);
+        if (month === undefined)
+            setOwnView(next);
+        const parts = toCalendar(next, calendar);
+        if (parts && (parts.year !== view.year || parts.month !== view.month))
+            onMonthChange?.(fromCalendar({ year: parts.year, month: parts.month, day: 1 }, calendar));
+    }
+    /** Shows a month picked in the menus of the month at `index`, so that month keeps its place. */
+    function showMonthAt(parts, index) {
+        showMonth(fromCalendar(addMonths({ year: parts.year, month: parts.month, day: 1 }, -index, calendar), calendar) ?? firstOfMonth);
+    }
+    function moveFocus(iso) {
+        if (iso < CALENDAR_RANGE[calendar].min || iso > CALENDAR_RANGE[calendar].max)
+            return;
+        setFocused(iso);
+        focusPendingRef.current = true;
+        if (iso < firstOfMonth) {
+            showMonth(iso);
+        }
+        else if (iso >= shownEnd) {
+            // Moving forward, the day lands in the last month shown.
+            const parts = toCalendar(iso, calendar);
+            if (parts)
+                showMonth(fromCalendar(addMonths({ year: parts.year, month: parts.month, day: 1 }, 1 - monthCount, calendar), calendar) ?? iso);
+        }
+        if (picking)
+            setHoverEnd(iso);
+    }
+    function pick(iso) {
+        if (inert || isDisabled(iso))
+            return;
+        setFocused(iso);
+        if (!isRange) {
+            if (value === undefined)
+                setOwnValue(iso);
+            onValueChange?.(iso);
+            onSelect?.(iso);
+            return;
+        }
+        if (!picking) {
+            if (range === undefined)
+                setOwnRange([iso, null]);
+            setHoverEnd(null);
+            onRangeChange?.([iso, null]);
+            return;
+        }
+        const next = iso < rangeStart ? [iso, rangeStart] : [rangeStart, iso];
+        if (range === undefined)
+            setOwnRange(next);
+        setHoverEnd(null);
+        onRangeChange?.(next);
+        onSelect?.(next[1]);
+    }
+    function clear() {
+        if (inert)
+            return;
+        if (isRange) {
+            if (range === undefined)
+                setOwnRange([null, null]);
+            setHoverEnd(null);
+            onRangeChange?.([null, null]);
+        }
+        else {
+            if (value === undefined)
+                setOwnValue(null);
+            onValueChange?.(null);
+        }
+    }
+    function goToday() {
+        showMonth(today);
+        moveFocus(today);
+        if (!isRange)
+            pick(today);
+    }
+    // Focus follows the roving day after the grid renders it, e.g. after an arrow key moved to another month.
+    useEffect(() => {
+        if (!focusPendingRef.current || !focused)
+            return;
+        focusPendingRef.current = false;
+        gridRef.current?.querySelector(`[data-iso="${focused}"]`)?.focus();
+    });
+    useEffect(() => {
+        if (autoFocus)
+            gridRef.current?.querySelector('[role="gridcell"][tabindex="0"]')?.focus();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    function onKeyDown(event) {
+        const target = event.target;
+        const current = target.dataset.iso;
+        if (!current)
+            return;
+        const { key } = event;
+        let next = null;
+        if (key === "ArrowLeft")
+            next = addDays(current, -1);
+        else if (key === "ArrowRight")
+            next = addDays(current, 1);
+        else if (key === "ArrowUp")
+            next = addDays(current, -7);
+        else if (key === "ArrowDown")
+            next = addDays(current, 7);
+        else if (key === "Home")
+            next = addDays(current, -((weekdayOf(current) - weekStart + 7) % 7));
+        else if (key === "End")
+            next = addDays(current, 6 - ((weekdayOf(current) - weekStart + 7) % 7));
+        else if (key === "PageUp" || key === "PageDown") {
+            const parts = toCalendar(current, calendar);
+            if (parts)
+                next = fromCalendar(addMonths(parts, (key === "PageUp" ? -1 : 1) * (event.shiftKey ? 12 : 1), calendar), calendar);
+        }
+        else if (key === "Enter" || key === " ") {
+            event.preventDefault();
+            pick(current);
+            return;
+        }
+        if (next) {
+            event.preventDefault();
+            moveFocus(next);
+        }
+    }
+    function onPointerOver(event) {
+        if (!picking)
+            return;
+        const iso = event.target.closest("[data-iso]")?.dataset.iso ?? null;
+        if (iso !== hoverEnd)
+            setHoverEnd(iso);
+    }
+    // The range band: between the two ends, or between the start and the day under the pointer while picking.
+    const bandEnd = rangeEnd ?? (picking ? hoverEnd : null);
+    const [bandStart, bandStop] = rangeStart && bandEnd ? (bandEnd < rangeStart ? [bandEnd, rangeStart] : [rangeStart, bandEnd]) : [null, null];
+    const holidays = weekendDays ?? (calendar === "bs" ? [6] : []);
+    const monthNames = getMonthNames(calendar, script);
+    const digits = (n) => (devanagari ? toDevanagariDigits(String(n)) : String(n));
+    const monthLabel = (m) => monthNames[m - 1] ?? "";
+    // The grids: always six rows each, so the panel keeps its height from month to month.
+    const monthViews = [];
+    for (let index = 0; index < monthCount; index++) {
+        const parts = addMonths(viewStart, index, calendar);
+        const first = fromCalendar(parts, calendar);
+        if (!first || (index > 0 && first <= monthViews[index - 1].first))
+            break;
+        const monthLength = daysInMonth(parts.year, parts.month, calendar);
+        const lead = (weekdayOf(first) - weekStart + 7) % 7;
+        const cells = [];
+        for (let cell = 0; cell < ROWS * 7; cell++) {
+            const iso = addDays(first, cell - lead);
+            const outside = cell < lead || cell >= lead + monthLength;
+            const dayParts = toCalendar(iso, calendar);
+            if (!dayParts || (outside && !outsideDays)) {
+                cells.push(null);
+                continue;
+            }
+            const weekday = weekdayOf(iso);
+            cells.push({
+                iso,
+                parts: dayParts,
+                weekday,
+                outside,
+                today: iso === today,
+                selected: isRange ? iso === rangeStart || iso === rangeEnd : iso === selected,
+                inRange: bandStart !== null && iso > bandStart && iso < bandStop,
+                disabled: inert || isDisabled(iso),
+                rangeStart: isRange && iso === bandStart && bandStop !== bandStart,
+                rangeEnd: isRange && iso === bandStop && bandStop !== bandStart,
+            });
+        }
+        monthViews.push({ first, parts, title: `${monthLabel(parts.month)} ${digits(parts.year)}`, cells });
+    }
+    const focusIso = focused && monthViews.some(view => view.cells.some(cell => cell?.iso === focused)) ? focused : (monthViews[0]?.cells.find(cell => cell && !cell.outside)?.iso ?? null);
+    // Header menus and arrows
+    const todayParts = toCalendar(today, calendar) ?? view;
+    const years = yearsWindow(calendar, todayParts, toIsoDate(min) ? toCalendar(minIso, calendar) : null, toIsoDate(max) ? toCalendar(maxIso, calendar) : null);
+    const lastShownYear = monthViews[monthViews.length - 1]?.parts.year ?? view.year;
+    const yearOptions = [];
+    for (let year = Math.min(years.first, view.year); year <= Math.max(years.last, lastShownYear); year++)
+        yearOptions.push(year);
+    const prevMonth = fromCalendar(addMonths(viewStart, -1, calendar), calendar) ?? firstOfMonth;
+    const nextMonth = fromCalendar(addMonths(viewStart, 1, calendar), calendar) ?? firstOfMonth;
+    const canGoPrev = prevMonth < firstOfMonth && addDays(firstOfMonth, -1) >= minIso;
+    const canGoNext = nextMonth > firstOfMonth && shownEnd <= maxIso;
+    const title = monthViews.map(view => view.title).join(" – ");
+    const weekdayNames = getWeekdayNames(calendar, script);
+    const weekdayMinNames = getWeekdayNames(calendar, script, "min");
+    return (_jsxs("div", { id: rootId, className: cx("nx-cal", `nx-cal--${size}`, isRange && "nx-cal--range", monthViews.length > 1 && "nx-cal--months", className), style: style, "data-disabled": disabled || undefined, "data-readonly": readOnly || undefined, "aria-label": props["aria-label"], "aria-labelledby": props["aria-labelledby"], children: [_jsx("div", { ref: gridRef, className: "nx-cal__months", children: monthViews.map((monthView, index) => (_jsxs("div", { className: "nx-cal__month", children: [_jsxs("div", { className: "nx-cal__head", children: [index === 0 ? (_jsx("button", { type: "button", className: "nx-cal__nav", "aria-label": "Previous month", disabled: disabled || !canGoPrev, onClick: () => showMonth(prevMonth), children: _jsx(InlineIcon, { icon: iconChevronLeft }) })) : (_jsx("span", { className: "nx-cal__nav nx-cal__nav--space", "aria-hidden": "true" })), _jsxs("div", { className: "nx-cal__menus", children: [_jsx("select", { className: "nx-cal__select", "aria-label": "Month", lang: lang, value: monthView.parts.month, disabled: disabled, onChange: event => showMonthAt({ year: monthView.parts.year, month: Number(event.target.value), day: 1 }, index), children: monthNames.map((name, monthIndex) => (_jsx("option", { value: monthIndex + 1, children: name }, name))) }), _jsx("select", { className: "nx-cal__select", "aria-label": "Year", lang: lang, value: monthView.parts.year, disabled: disabled, onChange: event => showMonthAt({ year: Number(event.target.value), month: monthView.parts.month, day: 1 }, index), children: yearOptions.map(year => (_jsx("option", { value: year, children: digits(year) }, year))) })] }), index === monthViews.length - 1 ? (_jsx("button", { type: "button", className: "nx-cal__nav", "aria-label": "Next month", disabled: disabled || !canGoNext, onClick: () => showMonth(nextMonth), children: _jsx(InlineIcon, { icon: iconChevronRight }) })) : (_jsx("span", { className: "nx-cal__nav nx-cal__nav--space", "aria-hidden": "true" }))] }), _jsxs("div", { className: "nx-cal__grid", role: "grid", "aria-label": monthView.title, "aria-multiselectable": isRange || undefined, onKeyDown: onKeyDown, onPointerOver: onPointerOver, onPointerLeave: () => picking && setHoverEnd(null), children: [_jsx("div", { className: "nx-cal__row", role: "row", children: Array.from({ length: 7 }, (_, column) => {
+                                        const weekday = (weekStart + column) % 7;
+                                        return (_jsx("div", { className: "nx-cal__weekday", role: "columnheader", lang: lang, "data-weekend": holidays.includes(weekday) || undefined, "aria-label": weekdayNames[weekday], title: weekdayNames[weekday], children: weekdayMinNames[weekday] }, weekday));
+                                    }) }), Array.from({ length: ROWS }, (_, row) => (_jsx("div", { className: "nx-cal__row", role: "row", children: monthView.cells.slice(row * 7, row * 7 + 7).map((cell, column) => cell ? (_jsx("button", { type: "button", role: "gridcell", className: "nx-cal__day", lang: lang, "data-iso": cell.iso, "data-outside": cell.outside || undefined, "data-today": cell.today || undefined, "data-weekend": holidays.includes(cell.weekday) || undefined, "data-in-range": cell.inRange || undefined, "data-range-start": cell.rangeStart || undefined, "data-range-end": cell.rangeEnd || undefined, "aria-selected": cell.selected, "aria-disabled": cell.disabled || undefined, "aria-current": cell.today ? "date" : undefined, "aria-label": formatDateParts(cell.parts, calendar, LABEL_FORMAT, script, cell.weekday), tabIndex: cell.iso === focusIso ? 0 : -1, onClick: () => pick(cell.iso), onFocus: () => setFocused(cell.iso), children: renderDay ? renderDay(cell) : _jsx("span", { className: "nx-cal__num", children: digits(cell.parts.day) }) }, cell.iso)) : (_jsx("div", { className: "nx-cal__day nx-cal__day--empty", role: "gridcell", "aria-hidden": "true" }, `empty-${row}-${column}`))) }, row)))] })] }, monthView.first))) }), _jsx("p", { className: "nx-visually-hidden", "aria-live": "polite", lang: lang, children: title }), footer && (_jsxs("div", { className: "nx-cal__foot", children: [_jsx(Button, { size: "sm", variant: "ghost", hoverTone: "primary", disabled: inert || isDisabled(today), onClick: goToday, children: "Today" }), _jsx(Button, { size: "sm", variant: "ghost", disabled: inert || (isRange ? rangeStart === null : selected === null), onClick: clear, children: "Clear" })] }))] }));
+}

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

@@ -0,0 +1,53 @@
+import { type ChangeEvent, type ComponentPropsWithRef, type ReactNode } from "react";
+import type { CheckRules, ValidateOn } from "../../Interfaces/InputInterfaces.ts";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+type NativeInputProps = Omit<ComponentPropsWithRef<"input">, "type" | "size" | "children" | keyof CheckRules>;
+export interface CheckBoxProps extends NativeInputProps, CheckRules {
+    label?: ReactNode;
+    /** A second, muted line under the label. */
+    description?: ReactNode;
+    /** An error from outside, such as a server message. */
+    error?: string | null;
+    /** Default `md`. */
+    size?: Size;
+    /** `end` (default) puts the label after the box. `start` puts it first and fills the width, as in a settings list. */
+    labelPosition?: "end" | "start";
+    /** Can be clicked and focused but not changed; still sent with a form when checked. A lock follows the label, and a click shows a note. */
+    readOnly?: boolean;
+    /** What a read-only box says when someone tries to change it. Default "Read-only: this option cannot be changed." ("this setting" for a switch). */
+    readOnlyMessage?: string;
+    /** Name used in messages: "Terms must be checked." Without it: "Check this box to continue." */
+    fieldName?: string;
+    /** When the message shows. Default `blur`; submitting a form always shows it. */
+    validateOn?: ValidateOn;
+    /** The new state after each change. */
+    onValueChange?: (checked: boolean, event: ChangeEvent<HTMLInputElement>) => void;
+    /** Class of the outer field. `inputClassName` goes on the input. */
+    className?: string;
+    inputClassName?: string;
+}
+export interface CheckBoxOnlyProps {
+    /** Shows a dash for "some chosen", e.g. a select-all box. A click clears it. */
+    indeterminate?: boolean;
+}
+/**
+ * A checkbox with a label. Uncontrolled by default (`defaultChecked`); `checked` with `onValueChange` also works.
+ * `required` means it must be checked. Drawn from the native input, so it stays one element and works in any form.
+ *
+ * @example <CheckBox name="terms" label="I accept the booking terms" required />
+ */
+export declare function CheckBox({ indeterminate, ...props }: CheckBoxProps & CheckBoxOnlyProps): import("react").JSX.Element;
+/**
+ * An on/off switch for a setting that takes effect at once. The same props as `CheckBox`, announced as a switch.
+ *
+ * @example <Switch name="breakfast" label="Breakfast included" labelPosition="start" defaultChecked />
+ */
+export declare function Switch(props: CheckBoxProps): import("react").JSX.Element;
+/**
+ * One radio button that is on or off, with the same props as `CheckBox`. A click only turns it on. Tabular and group
+ * forms use it for a value one row has at a time, such as the primary address; for a choice from a list, use `RadioGroup`.
+ *
+ * @example <RadioButton label="Primary" defaultChecked onValueChange={on => on && makePrimary(row)} />
+ */
+export declare function RadioButton(props: CheckBoxProps): import("react").JSX.Element;
+export {};

package/dist/Components/Inputs/CheckBox.js

@@ -0,0 +1,87 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useLayoutEffect, useRef } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { validateCheck } from "../../Helpers/ValidationHelpers.js";
+import { assignRef, GroupFooter, leavesField, OPTION_ATTRIBUTE, optionAnchor, preventChange, useChoiceField } from "./ChoiceField.js";
+import { hasContent } from "./Field.js";
+import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
+/**
+ * A checkbox with a label. Uncontrolled by default (`defaultChecked`); `checked` with `onValueChange` also works.
+ * `required` means it must be checked. Drawn from the native input, so it stays one element and works in any form.
+ *
+ * @example <CheckBox name="terms" label="I accept the booking terms" required />
+ */
+export function CheckBox({ indeterminate, ...props }) {
+    return _jsx(Toggle, { ...props, kind: "checkbox", indeterminate: indeterminate });
+}
+/**
+ * An on/off switch for a setting that takes effect at once. The same props as `CheckBox`, announced as a switch.
+ *
+ * @example <Switch name="breakfast" label="Breakfast included" labelPosition="start" defaultChecked />
+ */
+export function Switch(props) {
+    return _jsx(Toggle, { ...props, kind: "switch" });
+}
+/**
+ * One radio button that is on or off, with the same props as `CheckBox`. A click only turns it on. Tabular and group
+ * forms use it for a value one row has at a time, such as the primary address; for a choice from a list, use `RadioGroup`.
+ *
+ * @example <RadioButton label="Primary" defaultChecked onValueChange={on => on && makePrimary(row)} />
+ */
+export function RadioButton(props) {
+    return _jsx(Toggle, { ...props, kind: "radio" });
+}
+function Toggle(props) {
+    const { kind, label, description, error, size = "md", labelPosition = "end", indeterminate, readOnly = false, readOnlyMessage = kind === "switch" ? "Read-only: this setting cannot be changed." : kind === "radio" ? "Read-only: this choice cannot be changed." : "Read-only: this option cannot be changed.", required, validate, fieldName, validateOn, onValueChange, className, inputClassName, style, id, checked, disabled, ref, onChange, onClick, onKeyDown, ...inputProps } = props;
+    const inputRef = useRef(null);
+    const field = useChoiceField({ id, label, fieldName, error, validateOn, nameFromLabel: false }, {
+        check: ([input], name) => (input ? validateCheck(input.checked, { required, validate }, name) : null),
+        checkKeys: [checked, required, validate],
+    });
+    const setRef = useCallback((node) => {
+        inputRef.current = node;
+        assignRef(ref, node);
+    }, [ref]);
+    useLayoutEffect(() => {
+        if (inputRef.current && kind === "checkbox")
+            inputRef.current.indeterminate = Boolean(indeterminate);
+    }, [indeterminate, kind]);
+    // A lock after the label, and a note under the row when someone tries to change it. With the label first, the
+    // control sits at the end of the row, so the note lines up with that end.
+    const readOnlyNotice = useReadOnlyNotice(readOnly && !disabled, inputRef, readOnlyMessage, {
+        anchor: optionAnchor,
+        align: labelPosition === "start" ? "end" : "start",
+        typing: false,
+        lock: "label",
+    });
+    function handleClick(event) {
+        if (!readOnly) {
+            onClick?.(event);
+            return;
+        }
+        preventChange(event);
+        readOnlyNotice.onClick(event);
+    }
+    function handleKeyDown(event) {
+        readOnlyNotice.onKeyDown(event);
+        onKeyDown?.(event);
+    }
+    function handleBlur(event) {
+        if (leavesField(event))
+            readOnlyNotice.hide();
+        field.onBlur(event);
+    }
+    function handleChange(event) {
+        if (readOnly)
+            return;
+        field.onChange();
+        onChange?.(event);
+        onValueChange?.(event.currentTarget.checked, event);
+    }
+    const descriptionId = hasContent(description) ? `${field.fieldId}-description` : undefined;
+    // With a description, the name comes from the label text alone; the description is read as a description.
+    const labelId = descriptionId && hasContent(label) && !inputProps["aria-label"] ? `${field.fieldId}-label` : undefined;
+    const describedBy = [inputProps["aria-describedby"], descriptionId, field.error && field.messageId].filter(Boolean).join(" ") || undefined;
+    return (_jsxs("div", { ref: field.containerRef, className: cx("nx-choice-field", className), style: style, "data-invalid": field.error ? true : undefined, "data-readonly": readOnly || undefined, onBlur: handleBlur, children: [_jsxs("label", { className: cx("nx-choice", `nx-choice--${size}`, labelPosition === "start" && "nx-choice--start"), children: [_jsx("input", { ...inputProps, [OPTION_ATTRIBUTE]: 0, ref: setRef, id: field.fieldId, type: kind === "radio" ? "radio" : "checkbox", role: kind === "switch" ? "switch" : undefined, className: cx("nx-choice__control", `nx-choice__control--${kind}`, inputClassName), checked: checked, disabled: disabled, "aria-invalid": field.error ? true : undefined, "aria-required": required || undefined, "aria-readonly": readOnly || undefined, "aria-labelledby": inputProps["aria-labelledby"] ?? labelId, "aria-describedby": describedBy, onClick: handleClick, onKeyDown: handleKeyDown, onChange: handleChange, onInvalid: field.onInvalid }), (hasContent(label) || descriptionId) && (_jsxs("span", { className: "nx-choice__text", children: [hasContent(label) && (_jsxs("span", { id: labelId, className: "nx-choice__label", children: [label, readOnlyNotice.lock] })), descriptionId && (_jsx("span", { id: descriptionId, className: "nx-choice__description", children: description }))] }))] }), _jsx(GroupFooter, { id: field.messageId, error: field.error }), readOnlyNotice.notice] }));
+}

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

@@ -0,0 +1,20 @@
+import { type ChangeEvent, type ReactNode } from "react";
+import type { OptionValue, SelectionRules } from "../../Interfaces/InputInterfaces.ts";
+import { type ChoiceGroupProps } from "./ChoiceField.tsx";
+export interface CheckBoxGroupProps<T extends OptionValue = string> extends ChoiceGroupProps<T>, Omit<SelectionRules<T>, "required"> {
+    /** The chosen values. With `value`, the group is controlled; pair it with `onValueChange`. */
+    value?: readonly T[];
+    defaultValue?: readonly T[];
+    /** Adds a "Select all" box above the options (`true`), or one with this label. Not shown with `max`. */
+    selectAll?: boolean | ReactNode;
+    /** The chosen values, in option order, after each change. */
+    onValueChange?: (values: T[], event: ChangeEvent<HTMLElement>) => void;
+}
+/**
+ * Several choices from a list of options, such as amenities or permissions. `min` and `max` limit the count; at `max`,
+ * the other options are disabled and a count shows under the group. Clicking an option re-renders nothing. Read-only
+ * (default note "Read-only: these options cannot be changed.") shows a lock after the label and a note under a clicked option.
+ *
+ * @example <CheckBoxGroup name="amenities" label="Amenities" columns={3} options={[{ value: "wifi", label: "Wi-Fi" }]} />
+ */
+export declare function CheckBoxGroup<T extends OptionValue = string>(props: CheckBoxGroupProps<T>): import("react").JSX.Element;

package/dist/Components/Inputs/CheckBoxGroup.js

@@ -0,0 +1,80 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useRef } from "react";
+import { validateSelection } from "../../Helpers/ValidationHelpers.js";
+import { ChoiceItem, ChoiceLegend, GroupFooter, groupLayout, leavesField, OPTION_ATTRIBUTE, optionAnchor, useChoiceField } from "./ChoiceField.js";
+import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
+/**
+ * Several choices from a list of options, such as amenities or permissions. `min` and `max` limit the count; at `max`,
+ * the other options are disabled and a count shows under the group. Clicking an option re-renders nothing. Read-only
+ * (default note "Read-only: these options cannot be changed.") shows a lock after the label and a note under a clicked option.
+ *
+ * @example <CheckBoxGroup name="amenities" label="Amenities" columns={3} options={[{ value: "wifi", label: "Wi-Fi" }]} />
+ */
+export function CheckBoxGroup(props) {
+    const { options, name, label, hint, required, min, max, validate, value, defaultValue, selectAll, readOnly = false, disabled, onValueChange } = props;
+    const { readOnlyMessage = "Read-only: these options cannot be changed." } = props;
+    const { size = "md" } = props;
+    const allRef = useRef(null);
+    const countRef = useRef(null);
+    const chosen = (inputs) => inputs.filter(input => input.checked).map(input => options[Number(input.getAttribute(OPTION_ATTRIBUTE))].value);
+    const field = useChoiceField(props, {
+        check: (inputs, fieldName) => validateSelection(chosen(inputs), { required, min, max, validate }, fieldName),
+        checkKeys: [value, required, min, max, validate, options],
+        sync,
+    });
+    /** Writes the count, the select-all state, and the limit straight to the DOM. */
+    function sync(inputs) {
+        const count = inputs.filter(input => input.checked).length;
+        if (countRef.current)
+            countRef.current.textContent = String(count);
+        if (max !== undefined) {
+            for (const input of inputs) {
+                const limited = count >= max && !input.checked;
+                if (limited && !input.disabled) {
+                    input.disabled = true;
+                    input.dataset.nxLimit = "";
+                }
+                else if (!limited && input.dataset.nxLimit !== undefined) {
+                    input.disabled = false;
+                    delete input.dataset.nxLimit;
+                }
+            }
+        }
+        const all = allRef.current;
+        if (all) {
+            const available = inputs.filter(input => !input.disabled);
+            const availableChosen = available.filter(input => input.checked).length;
+            all.checked = available.length > 0 && availableChosen === available.length;
+            all.indeterminate = availableChosen > 0 && availableChosen < available.length;
+            all.disabled = available.length === 0;
+        }
+    }
+    function toggleAll(event) {
+        if (readOnly)
+            return;
+        const checked = event.currentTarget.checked;
+        for (const input of field.inputs())
+            if (!input.disabled)
+                input.checked = checked;
+    }
+    function handleChange(event) {
+        if (readOnly)
+            return;
+        field.onChange();
+        onValueChange?.(chosen(field.inputs()), event);
+    }
+    // Clicks and focus bubble to the fieldset, so one handler covers every option.
+    const readOnlyNotice = useReadOnlyNotice(readOnly && !disabled, field.containerRef, readOnlyMessage, { anchor: optionAnchor, typing: false, lock: "label" });
+    function handleBlur(event) {
+        if (leavesField(event))
+            readOnlyNotice.hide();
+        field.onBlur(event);
+    }
+    const invalid = Boolean(field.error);
+    const layout = groupLayout(props);
+    const groupName = name ?? field.fieldId;
+    const selected = value ?? defaultValue ?? [];
+    const showAll = Boolean(selectAll) && max === undefined;
+    return (_jsxs("fieldset", { ref: field.containerRef, id: field.fieldId, className: layout.className, style: props.style, disabled: disabled, "data-invalid": invalid || undefined, "data-readonly": readOnly || undefined, "aria-label": props["aria-label"], "aria-labelledby": props["aria-labelledby"], "aria-describedby": field.error || hint ? field.messageId : undefined, onChange: handleChange, onClick: readOnlyNotice.onClick, onKeyDown: readOnlyNotice.onKeyDown, onBlur: handleBlur, children: [_jsx(ChoiceLegend, { label: label, required: required, lock: readOnlyNotice.lock }), showAll && (_jsxs("label", { className: `nx-choice nx-choice--${size} nx-choices__all`, children: [_jsx("input", { ref: allRef, type: "checkbox", className: "nx-choice__control nx-choice__control--checkbox", "aria-controls": options.map((_, index) => `${field.fieldId}-${index}`).join(" "), onClick: readOnly ? event => event.preventDefault() : undefined, onChange: toggleAll }), _jsx("span", { className: "nx-choice__text", children: _jsx("span", { className: "nx-choice__label", children: selectAll === true ? "Select all" : selectAll }) })] })), _jsx("div", { className: "nx-choices__options", style: layout.optionsStyle, children: options.map((option, index) => (_jsx(ChoiceItem, { type: "checkbox", groupId: field.fieldId, name: groupName, option: option, index: index, size: size, checked: value ? value.includes(option.value) : undefined, defaultChecked: defaultValue?.includes(option.value), invalid: invalid, readOnly: readOnly, onInvalid: field.onInvalid }, String(option.value)))) }), _jsx(GroupFooter, { id: field.messageId, hint: hint, error: field.error, aside: max !== undefined && (_jsxs(_Fragment, { children: [_jsx("span", { ref: countRef, children: options.filter(option => selected.includes(option.value)).length }), "/", max] })) }), readOnlyNotice.notice] }));
+}