nexus-shared 1.1.21 → 3.0.0

package/dist/Components/Inputs/TabularForm.js

@@ -0,0 +1,348 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconArrowDown, iconArrowUp, iconCopy, iconDotsVertical, iconLock, iconRowInsertBottom, iconRowInsertTop, iconTrash, InlineIcon } from "nexus-icons";
+import { memo, useCallback, useLayoutEffect, useMemo, useRef, useState, } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { Menu } from "../Documents/Menu.js";
+import { firstFocusable, labelText, RowCell, RowsFooter, RowsLegend, useRowsFrame, useRowsInput, useRowVersion } from "./RowsInput.js";
+/** Height of a row: the input's box and the line under it. Measured from the first row once it renders. */
+const ROW_HEIGHT = { sm: 29, md: 35, lg: 41 };
+/** Rows rendered above and below the ones in view, so Tab and Enter always find the next row on the page. */
+const OVERSCAN = 8;
+const DEFAULT_MAX_HEIGHT = 440;
+/** A column's width by input type, when its params give none. */
+const COLUMN_WIDTH = {
+    text: "10rem",
+    email: "13rem",
+    password: "10rem",
+    search: "10rem",
+    tel: "9rem",
+    url: "13rem",
+    textarea: "14rem",
+    number: "7.5rem",
+    checkbox: "6rem",
+    switch: "6rem",
+    radio: "6rem",
+    "checkbox-group": "16rem",
+    "radio-group": "16rem",
+    dropdown: "10rem",
+    date: "10rem",
+    "date-range": "15rem",
+    time: "8rem",
+    "date-time": "14rem",
+    slider: "10rem",
+    "range-slider": "12rem",
+};
+/** Columns that keep their width instead of sharing the spare room. */
+const FIXED_TYPES = new Set(["checkbox", "switch", "radio"]);
+const ENTER_MOVES = new Set(["text", "email", "tel", "url", "search", "password", "number"]);
+const cssLength = (value) => (typeof value === "number" ? `${value}px` : value);
+/** How a cell lines up: numbers at the end, checkboxes and radios in the middle, the rest at the start. */
+function cellKind(params) {
+    if (params.type === "number")
+        return "number";
+    if (FIXED_TYPES.has(params.type))
+        return "check";
+    return "text";
+}
+function columnWidth(params) {
+    return cssLength(params.width ?? COLUMN_WIDTH[params.type] ?? "12rem");
+}
+/** One row of inputs. It renders again only when its position, its messages, or a value set from code change. */
+const TabularRow = memo(function TabularRow({ store, rowKey, index, count, columns, context, onAction }) {
+    useRowVersion(store, rowKey);
+    const title = `${store.names.title} ${index + 1}`;
+    const invalid = context.showAll && store.rowProblems(rowKey) > 0;
+    const items = [];
+    // A row nobody may change (an inherited field) has nothing to offer: no copy of it, no move, no removal.
+    const fixed = Boolean(context.rowLock(rowKey, index));
+    if (context.canAdd && !fixed) {
+        items.push({ value: "insert-above", label: "Insert above", icon: _jsx(InlineIcon, { icon: iconRowInsertTop }) }, { value: "insert-below", label: "Insert below", icon: _jsx(InlineIcon, { icon: iconRowInsertBottom }) }, { value: "duplicate", label: "Duplicate", icon: _jsx(InlineIcon, { icon: iconCopy }) });
+    }
+    if (context.sortable && !fixed) {
+        if (items.length)
+            items.push({ separator: true });
+        items.push({ value: "move-up", label: "Move up", icon: _jsx(InlineIcon, { icon: iconArrowUp }), disabled: index === 0 || Boolean(context.rowLock(store.keyAt(index - 1), index - 1)) }, { value: "move-down", label: "Move down", icon: _jsx(InlineIcon, { icon: iconArrowDown }), disabled: index === count - 1 });
+    }
+    if (context.removable && !fixed) {
+        if (items.length)
+            items.push({ separator: true });
+        items.push({ value: "remove", label: "Remove", icon: _jsx(InlineIcon, { icon: iconTrash }), tone: "danger" });
+    }
+    // Leaving an input counts as using it: a repeated value shows its message from then on.
+    function onBlur(event) {
+        const cell = event.target.closest("[data-nx-cell]");
+        if (!cell || (event.relatedTarget instanceof Node && cell.contains(event.relatedTarget)))
+            return;
+        store.touch(rowKey, cell.dataset.nxCell ?? "");
+    }
+    return (_jsxs("div", { role: "row", className: "nx-tabular__row", "aria-rowindex": index + 2, "data-nx-row": rowKey, "data-problem": invalid || undefined, onBlur: onBlur, children: [context.numbered && (_jsxs("div", { role: "cell", className: "nx-tabular__num", children: [_jsx("span", { className: "nx-tabular__num-text", children: index + 1 }), items.length > 0 && (_jsx(Menu, { items: items, onSelect: value => onAction(value, rowKey), "aria-label": `${title} actions`, children: _jsx("button", { type: "button", className: "nx-tabular__num-button", "aria-label": `${title} actions`, title: `${title} actions`, "data-nx-row-actions": "", children: _jsx(InlineIcon, { icon: iconDotsVertical }) }) }))] })), columns.map(params => (_jsx("div", { role: "cell", className: cx("nx-tabular__cell", `nx-tabular__cell--${cellKind(params)}`), "data-nx-cell": params.name, children: _jsx(RowCell, { store: store, rowKey: rowKey, params: context.cellParams(rowKey, params, index), index: index, error: store.shownError(rowKey, params.name), layout: "tabular", idPrefix: context.idPrefix, size: context.size, readOnly: context.readOnly, disabled: context.disabled, lock: context.cellLock(rowKey, params.name, index) }, store.revision(rowKey, params.name)) }, params.name)))] }));
+});
+/**
+ * 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 function TabularForm(props) {
+    const { inputs, label, hint, error, size = "md", maxHeight = DEFAULT_MAX_HEIGHT, numbered = true, readOnly = false, disabled = false, required, max, className, style } = props;
+    const addable = props.addable !== false && !readOnly;
+    const removable = props.removable !== false && !readOnly && !disabled;
+    const sortable = Boolean(props.sortable) && !readOnly && !disabled;
+    const layoutRef = useRef(null);
+    const rows = useRowsInput(props, "Row", layoutRef);
+    const store = rows.store;
+    const { snapshot } = rows;
+    const frame = useRowsFrame(props, store);
+    const columns = useMemo(() => inputs.filter(params => !params.hidden), [inputs]);
+    const count = snapshot.keys.length;
+    const viewportRef = useRef(null);
+    const headRef = useRef(null);
+    const bodyRef = useRef(null);
+    const [rowHeight, setRowHeight] = useState(ROW_HEIGHT[size]);
+    const [viewportMax, setViewportMax] = useState(null);
+    const pageRows = Math.ceil((typeof maxHeight === "number" ? maxHeight : 600) / rowHeight);
+    const [range, setRange] = useState({ start: 0, end: pageRows + OVERSCAN });
+    const [status, setStatus] = useState(null);
+    const pendingRef = useRef(null);
+    const start = Math.min(range.start, count);
+    const end = Math.min(count, Math.max(range.end, start + 1));
+    const shownKeys = snapshot.keys.slice(start, end);
+    /** The rows in view, from the scroll position, and a margin around them. */
+    const updateRange = useCallback(() => {
+        const viewport = viewportRef.current;
+        if (!viewport)
+            return;
+        const head = headRef.current?.offsetHeight ?? 0;
+        const top = Math.max(0, viewport.scrollTop - head);
+        const first = Math.max(0, Math.floor(top / rowHeight) - OVERSCAN);
+        const last = Math.ceil((top + Math.max(viewport.clientHeight - head, rowHeight)) / rowHeight) + OVERSCAN;
+        // Focus in a row that is about to leave the page moves to the table, so the keyboard keeps its place.
+        const active = document.activeElement;
+        const activeRow = active instanceof Element ? active.closest("[data-nx-row]") : null;
+        if (activeRow && bodyRef.current?.contains(activeRow)) {
+            const index = store.indexOf(activeRow.dataset.nxRow ?? "");
+            if (index >= 0 && (index < first || index >= last))
+                viewport.focus({ preventScroll: true });
+        }
+        setRange(current => (current.start === first && current.end === last ? current : { start: first, end: last }));
+    }, [rowHeight, store]);
+    // The real row height, once a row is on the page (custom styles may change it).
+    useLayoutEffect(() => {
+        const row = bodyRef.current?.querySelector(":scope > .nx-tabular__row");
+        const height = row?.offsetHeight;
+        if (height && height !== rowHeight)
+            setRowHeight(height);
+    });
+    /**
+     * `maxHeight`, brought down to whole rows. A scroller that cuts the last row in half reads as broken rather than as
+     * scrollable, and the header is not a row, so the arithmetic has to leave it out — as it does the frame and the
+     * horizontal scroll bar, neither of which is a row either.
+     */
+    useLayoutEffect(() => {
+        const viewport = viewportRef.current;
+        const wanted = typeof maxHeight === "number" ? maxHeight : null;
+        if (!viewport || wanted === null || count === 0) {
+            if (viewportMax !== null)
+                setViewportMax(null);
+            return;
+        }
+        const head = headRef.current?.offsetHeight ?? 0;
+        const chrome = viewport.offsetHeight - viewport.clientHeight;
+        const room = wanted - chrome - head;
+        // Not even one row fits: leave what was asked for rather than showing a header and a sliver.
+        const next = room < rowHeight ? null : chrome + head + Math.floor(room / rowHeight) * rowHeight;
+        if (next !== viewportMax)
+            setViewportMax(next);
+    });
+    // A resize, a new row height, or fewer rows change which rows are in view.
+    useLayoutEffect(() => {
+        const viewport = viewportRef.current;
+        if (!viewport)
+            return;
+        updateRange();
+        const observer = new ResizeObserver(updateRange);
+        observer.observe(viewport);
+        return () => observer.disconnect();
+    }, [updateRange, count]);
+    function tryFocus() {
+        const pending = pendingRef.current;
+        const body = bodyRef.current;
+        if (!pending || !body)
+            return;
+        const row = body.querySelector(`:scope > [data-nx-row="${CSS.escape(pending.key)}"]`);
+        if (!row)
+            return;
+        pendingRef.current = null;
+        const { target } = pending;
+        let element;
+        if (typeof target === "string")
+            element = firstFocusable(row.querySelector(`[data-nx-cell="${CSS.escape(target)}"]`));
+        else if ("actions" in target)
+            element = row.querySelector("[data-nx-row-actions]") ?? firstFocusable(row);
+        else
+            element = firstFocusable(row.querySelector("[data-nx-cell]")) ?? firstFocusable(row);
+        element?.focus();
+    }
+    layoutRef.current = {
+        focusRow(key, target) {
+            const index = store.indexOf(key);
+            const viewport = viewportRef.current;
+            if (index < 0 || !viewport)
+                return;
+            pendingRef.current = { key, target };
+            // Scroll the row into view below the header, and render the rows around it before the scroll event comes.
+            const head = headRef.current?.offsetHeight ?? 0;
+            const top = index * rowHeight;
+            if (top < viewport.scrollTop)
+                viewport.scrollTop = top;
+            else if (head + top + rowHeight > viewport.scrollTop + viewport.clientHeight)
+                viewport.scrollTop = head + top + rowHeight - viewport.clientHeight;
+            setRange(current => (index >= current.start && index < current.end ? current : { start: Math.max(0, index - OVERSCAN), end: index + pageRows + OVERSCAN }));
+            // After the render that brings the row (a layout effect), or in the next frame when nothing renders.
+            requestAnimationFrame(tryFocus);
+        },
+    };
+    useLayoutEffect(tryFocus);
+    const actionsRef = useRef(rows.actions);
+    actionsRef.current = rows.actions;
+    const onAction = useCallback((action, key) => {
+        const index = store.indexOf(key);
+        const run = actionsRef.current;
+        if (action === "insert-above")
+            run.add(undefined, index);
+        else if (action === "insert-below")
+            run.add(undefined, index + 1);
+        else if (action === "duplicate")
+            run.duplicate(key);
+        else if (action === "move-up")
+            run.move(key, -1);
+        else if (action === "move-down")
+            run.move(key, 1);
+        else
+            run.remove(key);
+    }, [store]);
+    /** The message or hint of the input with focus, shown under the table: cells have no room for their own. */
+    function readStatus() {
+        const active = document.activeElement;
+        const cell = active instanceof Element ? active.closest("[data-nx-cell]") : null;
+        const row = cell?.closest("[data-nx-row]");
+        let next = null;
+        if (cell && row && bodyRef.current?.contains(cell)) {
+            const message = cell.querySelector(".nx-field__message");
+            const text = message?.textContent?.trim() ?? "";
+            const isError = Boolean(message?.classList.contains("nx-field__message--error"));
+            const params = columns.find(item => item.name === cell.dataset.nxCell);
+            if (text)
+                next = { text: isError ? `${store.names.title} ${store.indexOf(row.dataset.nxRow ?? "") + 1}: ${text}` : `${params ? labelText(params) : ""}: ${text}`, error: isError };
+        }
+        setStatus(current => (current?.text === next?.text && current?.error === next?.error ? current : next));
+    }
+    const readStatusSoon = () => requestAnimationFrame(readStatus);
+    useLayoutEffect(() => {
+        if (status)
+            readStatus();
+    });
+    /** Enter moves down the column, Shift+Enter up; on the last row Enter adds a row. */
+    function onBodyKeyDown(event) {
+        if (event.key !== "Enter" || event.altKey || event.ctrlKey || event.metaKey || event.nativeEvent.isComposing)
+            return;
+        const target = event.target;
+        if (!(target instanceof HTMLInputElement) || !ENTER_MOVES.has(target.type) || target.hasAttribute("aria-haspopup") || target.getAttribute("role") === "combobox")
+            return;
+        const cell = target.closest("[data-nx-cell]");
+        const row = target.closest("[data-nx-row]");
+        if (!cell || !row)
+            return;
+        event.preventDefault();
+        const name = cell.dataset.nxCell ?? "";
+        const index = store.indexOf(row.dataset.nxRow ?? "") + (event.shiftKey ? -1 : 1);
+        if (index < 0)
+            return;
+        const next = store.keyAt(index);
+        if (next)
+            layoutRef.current?.focusRow(next, name);
+        else if (!event.shiftKey && rows.canAdd) {
+            const key = store.add();
+            layoutRef.current?.focusRow(key, name);
+        }
+    }
+    const context = useMemo(() => ({ idPrefix: frame.id, size, readOnly, disabled, numbered, removable, sortable, canAdd: rows.canAdd, showAll: snapshot.showAll, cellLock: rows.cellLock, cellParams: rows.cellParams, rowLock: rows.rowLock }), [frame.id, size, readOnly, disabled, numbered, removable, sortable, rows.canAdd, snapshot.showAll, rows.cellLock, rows.cellParams, rows.rowLock]);
+    /**
+     * Which columns are generated for **every** row on the page. The lock is then said once, on the column header,
+     * instead of on each of its cells: eighteen locks down one column is eighteen times the ink for one fact. The cells
+     * keep their read-only tint and their reason, which shows under the table when one is used.
+     *
+     * Only the rows in view are asked, which is what a column-wide rule (`cellReadOnly` on a name) answers the same way
+     * however the table is scrolled. A lock that really is per row leaves the column unlocked, which is what it means.
+     */
+    const lockedColumns = useMemo(() => {
+        const locked = new Map();
+        for (const params of columns) {
+            if (readOnly || params.readOnly === true) {
+                locked.set(params.name, true);
+                continue;
+            }
+            if (!shownKeys.length)
+                continue;
+            let reason;
+            for (const [offset, key] of shownKeys.entries()) {
+                // A locked row says nothing about its columns: the rows around it decide whether a column is generated.
+                if (rows.rowLock(key, start + offset))
+                    continue;
+                const lock = rows.cellLock(key, params.name, start + offset);
+                if (!lock) {
+                    reason = undefined;
+                    break;
+                }
+                if (reason === undefined)
+                    reason = typeof lock === "string" ? lock : true;
+            }
+            if (reason !== undefined)
+                locked.set(params.name, reason);
+        }
+        return locked;
+        // `shownKeys` is a fresh array on every render; the work is a call per visible cell, and nothing memoised is
+        // handed to the rows, so recomputing it costs a map and never a re-render of a row.
+    }, [columns, readOnly, rows.cellLock, rows.rowLock, shownKeys, start]);
+    // The number and the row's menu, side by side, plus the frame around them. Both are always there, so nothing moves.
+    const numberWidth = `calc(${Math.max(2, String(count).length)}ch + 18px + var(--nx-tabular-menu))`;
+    const widths = columns.map(columnWidth);
+    const template = [
+        numbered ? numberWidth : null,
+        ...columns.map((params, index) => {
+            const grow = params.grow ?? (FIXED_TYPES.has(params.type) ? 0 : 1);
+            return grow > 0 ? `minmax(${widths[index]}, ${grow}fr)` : widths[index];
+        }),
+    ]
+        .filter(Boolean)
+        .join(" ");
+    const minWidth = `calc(${[numbered ? numberWidth : "0px", ...widths].join(" + ")})`;
+    const tableStyle = { "--nx-tabular-columns": template, "--nx-tabular-num": numbered ? numberWidth : "0px", minWidth };
+    const invalid = Boolean(error || snapshot.message || snapshot.invalidRows);
+    return (_jsxs("fieldset", { id: frame.id, className: cx("nx-rows", "nx-tabular", `nx-tabular--${size}`, className), style: style, disabled: disabled, "data-problem": invalid || undefined, "data-readonly": readOnly || undefined, "aria-label": props["aria-label"], "aria-describedby": frame.messageId, children: [_jsx(RowsLegend, { id: frame.legendId, label: label, required: required || (props.min ?? 0) > 0, lock: frame.lock }), _jsx("input", { ref: rows.proxyRef, className: "nx-visually-hidden", tabIndex: -1, "aria-hidden": "true", form: props.form, onInvalid: rows.onInvalid }), _jsx("div", { ref: viewportRef, className: "nx-tabular__viewport", tabIndex: -1, style: { maxHeight: viewportMax ?? cssLength(maxHeight) }, onScroll: updateRange, children: _jsxs("div", { role: "table", className: "nx-tabular__table", style: tableStyle, "aria-labelledby": label ? frame.legendId : undefined, "aria-label": label ? undefined : props["aria-label"], "aria-rowcount": count + 1, children: [_jsx("div", { ref: headRef, role: "rowgroup", className: "nx-tabular__head", children: _jsxs("div", { role: "row", className: "nx-tabular__row", "aria-rowindex": 1, children: [numbered && (_jsxs("div", { role: "columnheader", className: "nx-tabular__num", children: [_jsx("span", { "aria-hidden": "true", children: "#" }), _jsx("span", { className: "nx-visually-hidden", children: store.names.title })] })), columns.map(params => {
+                                        const columnHint = params.hint;
+                                        const locked = lockedColumns.get(params.name);
+                                        const reason = typeof locked === "string" ? locked : locked ? "Read-only" : undefined;
+                                        return (_jsxs("div", { role: "columnheader", className: cx("nx-tabular__head-cell", `nx-tabular__cell--${cellKind(params)}`), title: reason ?? (typeof columnHint === "string" ? columnHint : undefined), "data-nx-locked": locked ? "" : undefined, children: [_jsx("span", { className: "nx-tabular__head-label", children: params.label ?? params.name }), params.required && !locked && (_jsx("span", { className: "nx-field__required", "aria-hidden": "true", children: "*" })), locked && _jsx(InlineIcon, { icon: iconLock, className: "nx-tabular__head-lock", "aria-hidden": "true" })] }, params.name));
+                                    })] }) }), _jsx("div", { ref: bodyRef, role: "rowgroup", className: "nx-tabular__body", style: { paddingTop: start * rowHeight, paddingBottom: Math.max(0, count - end) * rowHeight }, onKeyDown: onBodyKeyDown, onFocus: readStatus, onBlur: readStatusSoon, onInput: readStatusSoon, children: count === 0 ? (_jsx("div", { role: "row", className: "nx-tabular__row nx-tabular__row--empty", children: _jsx("div", { role: "cell", className: "nx-tabular__empty", children: frame.emptyMessage }) })) : (shownKeys.map((key, offset) => (_jsx(TabularRow, { store: store, rowKey: key, index: start + offset, count: count, columns: columns, context: context, onAction: onAction }, `${snapshot.generation}:${key}`)))) })] }) }), _jsx(RowsFooter, { messageId: frame.messageId, store: store, snapshot: snapshot, error: error, hint: hint, status: status, addLabel: frame.addLabel, addable: addable, canAdd: rows.canAdd, max: max, maxMessage: frame.maxMessage, size: size, onAdd: () => rows.actions.add(), onUndo: () => rows.actions.undo() })] }));
+}

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

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

package/dist/Components/Inputs/TextArea.js

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

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

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

package/dist/Components/Inputs/TextBox.js

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

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

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

package/dist/Components/Inputs/TextField.js

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

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

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