nexus-shared 1.1.21 → 3.0.0

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

@@ -0,0 +1,87 @@
+import { type ChangeEvent, type ComponentPropsWithRef, type CSSProperties, type ReactNode } from "react";
+import type { NumberFormatOptions, SliderMark, ValidateOn } from "../../Interfaces/InputInterfaces.ts";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+interface SliderBaseProps extends NumberFormatOptions {
+    label?: ReactNode;
+    /** Help text under the slider. An error takes its place. */
+    hint?: ReactNode;
+    /** An error from outside, such as a server message. */
+    error?: string | null;
+    /** Default `md`. */
+    size?: Size;
+    /** Default 0. */
+    min?: number;
+    /** Default 100. */
+    max?: number;
+    /** Default 1. */
+    step?: number;
+    /** Text before the shown value, e.g. "Rs ". Include a space if one is wanted. */
+    prefix?: string;
+    /** Text after the shown value, e.g. "%" or " nights". */
+    suffix?: string;
+    /** Writes the shown value; replaces the number format, `prefix`, and `suffix`. For example, hours as "14:30". */
+    format?: (value: number) => string;
+    /** Shows the value beside the label. Default true. */
+    showValue?: boolean;
+    /** Shows the value above the thumb while it is hovered, focused, or dragged. Best with `showValue={false}`. */
+    tooltip?: boolean;
+    /** Labelled points under the track. */
+    marks?: readonly SliderMark[];
+    disabled?: boolean;
+    /** Can be focused but not moved; the value is still sent with a form. A lock follows the label, and a try to move it shows a note. */
+    readOnly?: boolean;
+    /** What a read-only slider says when someone tries to move it. Default "Read-only: this value cannot be changed." ("this range" for a range slider). */
+    readOnlyMessage?: string;
+    /** Form field name. A range slider sends two values under it: start, then end. */
+    name?: string;
+    id?: string;
+    /** Name used in messages. Default: the label, when it is text. */
+    fieldName?: string;
+    /** When a `validate` message shows. Default `blur`; submitting a form always shows it. */
+    validateOn?: ValidateOn;
+    className?: string;
+    style?: CSSProperties;
+}
+type NativeInputProps = Omit<ComponentPropsWithRef<"input">, keyof SliderBaseProps | "type" | "value" | "defaultValue" | "onChange" | "children">;
+export interface SliderProps extends SliderBaseProps, NativeInputProps {
+    value?: number;
+    /** Default: `min`. */
+    defaultValue?: number;
+    /** Returns a message to fail, e.g. a deposit below a minimum. */
+    validate?: (value: number) => string | null | undefined;
+    /** Every change while dragging or stepping. */
+    onValueChange?: (value: number, event: ChangeEvent<HTMLElement>) => void;
+    /** Once the thumb is released or a key step ends: the moment to call an API. */
+    onValueCommit?: (value: number) => void;
+    inputClassName?: string;
+}
+export interface RangeSliderProps extends SliderBaseProps {
+    /** `[start, end]`. With `value`, the slider is controlled. */
+    value?: readonly [number, number];
+    /** Default: `[min, max]`. */
+    defaultValue?: readonly [number, number];
+    /** Smallest gap between start and end. Default 0. */
+    minDistance?: number;
+    /** Names of the two thumbs for screen readers, after the label. Default `["minimum", "maximum"]`. */
+    thumbLabels?: readonly [string, string];
+    validate?: (value: [number, number]) => string | null | undefined;
+    onValueChange?: (value: [number, number], event: ChangeEvent<HTMLElement>) => void;
+    onValueCommit?: (value: [number, number]) => void;
+    "aria-label"?: string;
+}
+/**
+ * Pick a number by dragging, with the arrow keys (Page Up and Page Down for bigger steps, Home and End for the
+ * limits), or by clicking a mark. A native range input, so touch and screen readers work as usual. Dragging writes
+ * the fill and the shown value straight to the DOM: nothing re-renders.
+ *
+ * @example <Slider name="discount" label="Discount" max={50} suffix="%" defaultValue={10} />
+ */
+export declare function Slider({ value, defaultValue, validate, onValueChange, onValueCommit, inputClassName, ...props }: SliderProps): import("react").JSX.Element;
+/**
+ * Pick a range with two thumbs, such as a price filter. Clicking the track moves the nearer thumb, and the thumbs
+ * keep `minDistance` apart.
+ *
+ * @example <RangeSlider name="price" label="Price per night" min={1000} max={30000} step={500} prefix="Rs " grouping />
+ */
+export declare function RangeSlider({ value, defaultValue, minDistance, thumbLabels, validate, onValueChange, onValueCommit, ...props }: RangeSliderProps): import("react").JSX.Element;
+export {};

package/dist/Components/Inputs/Slider.js

@@ -0,0 +1,216 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment, useEffect, useEffectEvent, useRef, } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { clampNumber, countDecimals, formatNumber, roundDecimal } from "../../Helpers/NumberHelpers.js";
+import { GroupFooter, leavesField, OPTION_ATTRIBUTE, useChoiceField } from "./ChoiceField.js";
+import { hasContent } from "./Field.js";
+import { setInputValue } from "./InputField.js";
+import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
+/**
+ * Pick a number by dragging, with the arrow keys (Page Up and Page Down for bigger steps, Home and End for the
+ * limits), or by clicking a mark. A native range input, so touch and screen readers work as usual. Dragging writes
+ * the fill and the shown value straight to the DOM: nothing re-renders.
+ *
+ * @example <Slider name="discount" label="Discount" max={50} suffix="%" defaultValue={10} />
+ */
+export function Slider({ value, defaultValue, validate, onValueChange, onValueCommit, inputClassName, ...props }) {
+    const base = pickBase(props);
+    const inputProps = omitBase(props);
+    return (_jsx(SliderField, { ...base, values: value === undefined ? undefined : [value], defaultValues: [defaultValue ?? base.min ?? 0], validate: validate && (values => validate(values[0])), onValues: onValueChange && ((values, event) => onValueChange(values[0], event)), onCommit: onValueCommit && (values => onValueCommit(values[0])), inputProps: inputProps, inputClassName: inputClassName }));
+}
+/**
+ * Pick a range with two thumbs, such as a price filter. Clicking the track moves the nearer thumb, and the thumbs
+ * keep `minDistance` apart.
+ *
+ * @example <RangeSlider name="price" label="Price per night" min={1000} max={30000} step={500} prefix="Rs " grouping />
+ */
+export function RangeSlider({ value, defaultValue, minDistance = 0, thumbLabels = ["minimum", "maximum"], validate, onValueChange, onValueCommit, ...props }) {
+    const base = pickBase(props);
+    const min = base.min ?? 0;
+    const max = base.max ?? 100;
+    const start = defaultValue ?? [min, max];
+    return (_jsx(SliderField, { ...base, range: true, values: value, defaultValues: [Math.min(start[0], start[1]), Math.max(start[0], start[1])], minDistance: minDistance, thumbLabels: thumbLabels, validate: validate && (values => validate([values[0], values[1]])), onValues: onValueChange && ((values, event) => onValueChange([values[0], values[1]], event)), onCommit: onValueCommit && (values => onValueCommit([values[0], values[1]])), inputProps: { "aria-label": props["aria-label"] } }));
+}
+const BASE_KEYS = [
+    "label", "hint", "error", "size", "min", "max", "step", "prefix", "suffix", "format", "showValue", "tooltip", "marks", "disabled", "readOnly", "readOnlyMessage",
+    "name", "id", "fieldName", "validateOn", "className", "style", "decimals", "fixedDecimals", "grouping", "locale",
+];
+function pickBase(props) {
+    const base = {};
+    for (const key of BASE_KEYS)
+        if (key in props)
+            base[key] = props[key];
+    return base;
+}
+function omitBase(props) {
+    const rest = { ...props };
+    for (const key of BASE_KEYS)
+        delete rest[key];
+    return rest;
+}
+function SliderField(props) {
+    const { label, hint, size = "md", min = 0, max = 100, step = 1, prefix, suffix, format, showValue = true, tooltip = false, marks, disabled = false, readOnly = false, name, fieldName, className, style, decimals, fixedDecimals, grouping, locale, range = false, values, defaultValues, minDistance = 0, thumbLabels = [], validate, onValues, onCommit, inputProps, inputClassName, } = props;
+    const { readOnlyMessage = range ? "Read-only: this range cannot be changed." : "Read-only: this value cannot be changed." } = props;
+    const span = max - min || 1;
+    const initial = (values ?? defaultValues).map(value => clampNumber(value, min, max));
+    const text = (value) => (format ? format(value) : `${prefix ?? ""}${formatNumber(value, { decimals, fixedDecimals, grouping, locale })}${suffix ?? ""}`);
+    const fraction = (value) => (clampNumber(value, min, max) - min) / span;
+    const controlRef = useRef(null);
+    const valueRef = useRef(null);
+    const tooltipRefs = useRef([]);
+    // The last values, so a read-only slider can put a moved thumb straight back.
+    const lastRef = useRef(initial);
+    const field = useChoiceField(props, {
+        check: inputs => validate?.(read(inputs)) || null,
+        checkKeys: [values?.join(), validate, min, max],
+        sync,
+    });
+    const read = (inputs) => inputs.map(input => Number(input.value));
+    // A read-only slider puts a moved thumb straight back: a lock after the label, and a note under the track, say why.
+    const readOnlyNotice = useReadOnlyNotice(readOnly && !disabled, field.containerRef, readOnlyMessage, {
+        anchor: target => target.closest(".nx-slider__control"),
+        typing: false,
+        keys: ["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown", "PageUp", "PageDown", "Home", "End"],
+        lock: "label",
+    });
+    /** Writes the fill, the shown value, the tooltips, and each thumb's spoken value straight to the DOM. */
+    function sync(inputs) {
+        const current = read(inputs);
+        const control = controlRef.current;
+        if (!control || current.length === 0)
+            return;
+        control.style.setProperty("--nx-slider-start", String(range ? fraction(current[0]) : 0));
+        control.style.setProperty("--nx-slider-end", String(fraction(current[current.length - 1])));
+        inputs.forEach((input, index) => {
+            const valueText = text(current[index]);
+            input.setAttribute("aria-valuetext", valueText);
+            const bubble = tooltipRefs.current[index];
+            if (bubble) {
+                bubble.textContent = valueText;
+                bubble.style.setProperty("--nx-slider-at", String(fraction(current[index])));
+            }
+        });
+        if (valueRef.current)
+            valueRef.current.textContent = current.map(text).join(" – ");
+        lastRef.current = current;
+    }
+    function handleChange(event) {
+        const input = event.target;
+        if (!(input instanceof HTMLInputElement) || !input.hasAttribute(OPTION_ATTRIBUTE))
+            return;
+        const index = Number(input.getAttribute(OPTION_ATTRIBUTE));
+        if (readOnly) {
+            input.value = String(lastRef.current[index]);
+            return;
+        }
+        const inputs = field.inputs();
+        if (range && inputs.length === 2) {
+            // The thumbs never cross, and keep minDistance apart.
+            const [start, end] = inputs;
+            if (index === 0 && Number(start.value) > Number(end.value) - minDistance)
+                start.value = String(Math.max(min, Number(end.value) - minDistance));
+            if (index === 1 && Number(end.value) < Number(start.value) + minDistance)
+                end.value = String(Math.min(max, Number(start.value) + minDistance));
+            controlRef.current?.setAttribute("data-active", String(index));
+        }
+        field.onChange();
+        onValues?.(read(inputs), event);
+    }
+    // A released thumb, or a finished key step, fires the native change event.
+    const commit = useEffectEvent(() => onCommit?.(read(field.inputs())));
+    useEffect(() => {
+        const control = controlRef.current;
+        if (!control)
+            return;
+        const onNativeChange = () => commit();
+        control.addEventListener("change", onNativeChange);
+        return () => control.removeEventListener("change", onNativeChange);
+    }, []);
+    /** The value under a pointer's x position, on the step grid. */
+    function valueAt(clientX) {
+        const control = controlRef.current;
+        const rect = control.getBoundingClientRect();
+        const thumb = parseFloat(getComputedStyle(control).getPropertyValue("--nx-slider-thumb")) || 16;
+        const position = clampNumber((clientX - rect.left - thumb / 2) / Math.max(1, rect.width - thumb), 0, 1);
+        const stepped = min + Math.round((position * span) / step) * step;
+        return clampNumber(roundDecimal(stepped, Math.max(countDecimals(step), countDecimals(min))), min, max);
+    }
+    /** Moves the thumb nearest to a value there, as a click on the track or on a mark does. */
+    function moveTo(value, focus = true) {
+        const input = nearestInput(value);
+        if (disabled || readOnly || !input)
+            return null;
+        if (focus)
+            input.focus();
+        setInputValue(input, String(value));
+        return input;
+    }
+    /** The thumb a press at a value would move: the only one, or the nearer of two. */
+    function nearestInput(value) {
+        const inputs = field.inputs();
+        if (inputs.length < 2)
+            return inputs[0];
+        const [start, end] = read(inputs);
+        return inputs[value <= start ? 0 : value >= end ? 1 : value - start <= end - value ? 0 : 1];
+    }
+    function commitInput(input) {
+        input.dispatchEvent(new Event("change", { bubbles: true }));
+    }
+    function handleControlPointerDown(event) {
+        if (!readOnly) {
+            if (range)
+                handleTrackPointerDown(event);
+            return;
+        }
+        // A press on a range slider's track focuses the nearer thumb, as when editable, so focus stays in the slider
+        // and the note stays up.
+        if (range && event.button === 0 && !(event.target instanceof HTMLInputElement)) {
+            event.preventDefault();
+            nearestInput(valueAt(event.clientX))?.focus();
+        }
+        readOnlyNotice.show(event.currentTarget);
+    }
+    function handleBlur(event) {
+        if (leavesField(event))
+            readOnlyNotice.hide();
+        field.onBlur(event);
+    }
+    // A range slider's inputs only take pointer events on their thumbs, so a press on the track lands here.
+    function handleTrackPointerDown(event) {
+        if (event.button !== 0 || event.target instanceof HTMLInputElement)
+            return;
+        const input = moveTo(valueAt(event.clientX));
+        if (!input)
+            return;
+        event.preventDefault();
+        const control = event.currentTarget;
+        control.setPointerCapture(event.pointerId);
+        const move = (moveEvent) => setInputValue(input, String(valueAt(moveEvent.clientX)));
+        const end = () => {
+            control.removeEventListener("pointermove", move);
+            control.removeEventListener("lostpointercapture", end);
+            commitInput(input);
+        };
+        control.addEventListener("pointermove", move);
+        control.addEventListener("lostpointercapture", end);
+    }
+    const labelId = `${field.fieldId}-label`;
+    const inputId = (index) => (index === 0 ? field.fieldId : `${field.fieldId}-${index}`);
+    const describedBy = field.error || hint ? field.messageId : undefined;
+    const nameText = fieldName ?? (typeof label === "string" ? label : undefined);
+    const controlStyle = { "--nx-slider-start": range ? fraction(initial[0]) : 0, "--nx-slider-end": fraction(initial[initial.length - 1]) };
+    return (_jsxs("div", { ref: field.containerRef, role: range ? "group" : undefined, "aria-labelledby": range && hasContent(label) ? labelId : undefined, className: cx("nx-slider", `nx-slider--${size}`, range && "nx-slider--range", className), style: style, "data-invalid": field.error ? true : undefined, "data-disabled": disabled || undefined, "data-readonly": readOnly || undefined, onChange: handleChange, onKeyDown: readOnlyNotice.onKeyDown, onBlur: handleBlur, children: [(hasContent(label) || showValue) && (_jsxs("div", { className: "nx-slider__head", children: [hasContent(label) &&
+                        (range ? (_jsxs("span", { id: labelId, className: "nx-field__label", children: [label, readOnlyNotice.lock] })) : (_jsxs("label", { id: labelId, htmlFor: field.fieldId, className: "nx-field__label", children: [label, readOnlyNotice.lock] }))), showValue && (_jsx("output", { ref: valueRef, className: "nx-slider__value", htmlFor: initial.map((_, index) => inputId(index)).join(" "), "aria-hidden": "true", children: initial.map(text).join(" – ") }))] })), _jsxs("div", { ref: controlRef, className: "nx-slider__control", style: controlStyle, onPointerDown: range || readOnly ? handleControlPointerDown : undefined, children: [_jsx("span", { className: "nx-slider__track", "aria-hidden": "true", children: _jsx("span", { className: "nx-slider__fill" }) }), initial.map((value, index) => (_jsxs(Fragment, { children: [_jsx("input", { ...(index === 0 ? inputProps : undefined), [OPTION_ATTRIBUTE]: index, id: inputId(index), type: "range", className: cx("nx-slider__input", inputClassName), name: name, min: min, max: max, step: step, value: values ? value : undefined, defaultValue: values ? undefined : value, disabled: disabled, "aria-label": range ? [nameText, thumbLabels[index]].filter(Boolean).join(" ") || undefined : inputProps["aria-label"], "aria-readonly": readOnly || undefined, "aria-invalid": field.error ? true : undefined, "aria-describedby": describedBy, "aria-valuetext": text(value), onInvalid: field.onInvalid, 
+                                // A controlled value changes through onValueChange; this silences React's missing-onChange warning.
+                                onChange: values ? noop : undefined }), tooltip && (_jsx("span", { ref: node => {
+                                    tooltipRefs.current[index] = node;
+                                }, className: "nx-slider__tooltip", style: { "--nx-slider-at": fraction(value) }, "aria-hidden": "true", children: text(value) }))] }, index)))] }), marks && marks.length > 0 && (_jsx("div", { className: "nx-slider__marks", "aria-hidden": "true", children: marks.map(mark => (_jsx("button", { type: "button", tabIndex: -1, className: "nx-slider__mark", style: { "--nx-slider-at": fraction(mark.value) }, "data-edge": mark.value <= min ? "start" : mark.value >= max ? "end" : undefined, disabled: disabled, onClick: () => {
+                        const input = moveTo(mark.value);
+                        if (input)
+                            commitInput(input);
+                        else
+                            readOnlyNotice.show(controlRef.current);
+                    }, children: mark.label ?? text(mark.value) }, mark.value))) })), _jsx(GroupFooter, { id: field.messageId, hint: hint, error: field.error }), readOnlyNotice.notice] }));
+}
+function noop() { }

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

@@ -0,0 +1,27 @@
+import type { RowValue, TabularFormProps } from "../../Interfaces/FormInterfaces.ts";
+/**
+ * Rows of inputs in a table, one column per input: a person's emails or addresses, invoice lines, a salary sheet. The
+ * value is an array of row objects, one value per input, with any other fields the rows came with (such as ids). Inputs
+ * come as params, the same objects a form takes, so the same list can show as sections in a `GroupForm`.
+ *
+ * Only the rows in view are on the page, so a sheet of thousands of rows opens and types as fast as a short one; the
+ * values live in a store outside React, and typing renders nothing. The header and the numbered column stay in place
+ * while the table scrolls. Each row has one control, beside its number and never in its place: a menu of insert,
+ * duplicate, move and remove. Enter in a text or number cell moves down the column, and on the last row adds a row.
+ *
+ * Every row is one line high, whatever it holds, so nothing shifts as the table is used; a column generated for every
+ * row (`cellReadOnly`) says so once on its header rather than on each of its cells; and `maxHeight` is brought down
+ * to whole rows, because a scroller that cuts the last one in half reads as broken rather than as scrollable.
+ *
+ * Inside a `<form>`, the rows are sent as JSON under `name`; a row with a problem blocks submit, and the first one
+ * scrolls into view with focus.
+ *
+ * @example
+ * <TabularForm name="emails" label="Emails" itemLabel="Email" max={5} unique={["email"]} inputs={[
+ *   { type: "email", name: "email", label: "Email", required: true, pattern: TEXT_PATTERNS.email },
+ *   { type: "dropdown", name: "type", label: "Type", options: EMAIL_TYPES },
+ *   { type: "checkbox", name: "isVerified", label: "Verified" },
+ *   { type: "radio", name: "isPrimary", label: "Primary", required: true },
+ * ]} />
+ */
+export declare function TabularForm<TRow extends RowValue = RowValue>(props: TabularFormProps<TRow>): import("react").JSX.Element;