nexus-shared 1.1.21 → 3.0.0

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] }));
+}

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

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