nexus-shared 1.1.20 → 2.0.0

package/dist/Components/Inputs/TimePicker.js

@@ -0,0 +1,239 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconClock, iconX, InlineIcon } from "nexus-icons";
+import { useLayoutEffect, useRef, useState } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { usesDevanagari } from "../../Helpers/DateHelpers.js";
+import { useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { followAnchor, isPopoverOpen, placeUnderAnchor } from "../../Helpers/PopoverHelpers.js";
+import { formatTime, normalizeTimeStep, parseTimeText, timeFormatWithSeconds, toIsoTime } from "../../Helpers/TimeHelpers.js";
+import { DEFAULT_FIELD_NAME, validateTime } from "../../Helpers/ValidationHelpers.js";
+import { Field, hasContent } from "./Field.js";
+import { setInputValue, useInputField } from "./InputField.js";
+import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
+import { TimePanel } from "./TimePanel.js";
+/**
+ * A time input: type a time on either clock ("2:30 pm", "1430"), or pick one from the panel that opens under the box.
+ * Written in the user's time format, 12- or 24-hour, and always held as an ISO time with no date and no zone, which a
+ * form sends through a hidden input with the field's `name`. Uncontrolled by default, so typing re-renders nothing.
+ *
+ * @example <TimePicker name="arrival" label="Arrival" min="12:00" max="22:00" step={1800} view="list" />
+ */
+export function TimePicker(props) {
+    const { label, hint, error, design = "standard", size = "md", icon, prefix, view = "columns", clearable = true, fieldName, readOnlyMessage = "Read-only: this time cannot be changed.", validateOn, value, defaultValue, onValueChange, isTimeDisabled, className, inputClassName, style, required, min, max, step, validate, name, form, placeholder, disabled, readOnly, ref, onChange, onBlur, onFocus, onInvalid, onKeyDown, onClick, ...inputProps } = props;
+    const preferences = useDatePreferences();
+    const script = props.script ?? (usesDevanagari(preferences.calendar, preferences.script) ? "devanagari" : "latin");
+    const seconds = normalizeTimeStep(step) % 60 !== 0;
+    const format = timeFormatWithSeconds(props.format ?? preferences.timeFormat, seconds);
+    const editable = !disabled && !readOnly;
+    const initial = toIsoTime(value !== undefined ? value : defaultValue, seconds);
+    const text = (iso) => formatTime(iso, { format, script });
+    const messageName = fieldName ?? (typeof label === "string" ? label : DEFAULT_FIELD_NAME);
+    const valueRef = useRef(initial);
+    const editedRef = useRef(false);
+    const hiddenRef = useRef(null);
+    const panelRef = useRef(null);
+    const focusPanelRef = useRef(false);
+    const [open, setOpen] = useState(false);
+    // Re-renders the panel's selection while it is open; typing with it closed re-renders nothing.
+    const [panelValue, setPanelValue] = useState(initial);
+    const rules = {
+        required,
+        min,
+        max,
+        step,
+        validate: iso => (iso && isTimeDisabled?.(iso) ? `${messageName} cannot be ${text(iso)}.` : validate?.(iso)),
+    };
+    const field = useInputField({
+        ...props,
+        onChange: event => {
+            const input = event.currentTarget;
+            const iso = input.value.trim() ? parseTimeText(input.value, { seconds }) : null;
+            const changed = iso !== valueRef.current;
+            editedRef.current = true;
+            valueRef.current = iso;
+            sync(iso);
+            if (open)
+                setPanelValue(iso);
+            onChange?.(event);
+            if (changed)
+                onValueChange?.(iso, event);
+        },
+    }, {
+        // Text that is not a time is checked as itself, so the message says what to type.
+        check: (input, messageName) => validateTime(valueRef.current ?? (input.value.trim() ? input.value : null), rules, messageName, text),
+        checkKeys: [value, required, min, max, step, validate, isTimeDisabled, format, script],
+        onReset: input => {
+            // Back to the time the field started with, written in the current format.
+            editedRef.current = false;
+            valueRef.current = initial;
+            input.value = text(initial);
+            sync(initial);
+        },
+    });
+    // A read-only box has no panel: a lock, and a note when someone tries to open or change it, say why.
+    const readOnlyNotice = useReadOnlyNotice(Boolean(readOnly) && !disabled, field.elementRef, readOnlyMessage, { keys: ["ArrowDown"] });
+    /** Writes what depends on the value straight to the DOM: the hidden input a form sends. */
+    function sync(iso) {
+        if (hiddenRef.current)
+            hiddenRef.current.value = iso ?? "";
+    }
+    // A controlled value that differs from the box replaces its text. So does a default value that arrives after
+    // mount (from an API, say), as long as the user has not typed anything yet.
+    useLayoutEffect(() => {
+        const input = field.elementRef.current;
+        if (!input || (value === undefined && editedRef.current) || initial === valueRef.current)
+            return;
+        valueRef.current = initial;
+        input.value = text(initial);
+        sync(initial);
+        setPanelValue(initial);
+    }, [initial]);
+    // A new format or script rewrites the same time.
+    useLayoutEffect(() => {
+        const input = field.elementRef.current;
+        if (input && valueRef.current)
+            input.value = text(valueRef.current);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [format, script]);
+    // React sets a hidden input's default value again on every render, and for a hidden input that is its value.
+    // After each render, before paint, the hidden input takes the box's time back.
+    useLayoutEffect(() => {
+        sync(valueRef.current);
+    });
+    // The panel is a manual popover under the box (above it when there is no room), shown once its content has rendered.
+    // It closes only through this component (Esc, Enter, Done, a pick in the list, focus or a press elsewhere), so the
+    // state always matches the screen: a click right after Esc opens it again, and a click on the box keeps it open.
+    useLayoutEffect(() => {
+        const panel = panelRef.current;
+        const box = field.elementRef.current?.closest(".nx-field__box");
+        if (!open || !panel || !box)
+            return;
+        if (!isPopoverOpen(panel))
+            panel.showPopover();
+        const place = () => placeUnderAnchor(panel, box.getBoundingClientRect());
+        place();
+        const stopFollowing = followAnchor(place);
+        const onPointerDown = (event) => {
+            const target = event.target;
+            if (!panel.contains(target) && !box.contains(target))
+                closePanel();
+        };
+        document.addEventListener("pointerdown", onPointerDown, true);
+        return () => {
+            stopFollowing();
+            document.removeEventListener("pointerdown", onPointerDown, true);
+            if (isPopoverOpen(panel))
+                panel.hidePopover();
+        };
+    }, [open]);
+    function openPanel(focusPanel) {
+        if (!editable)
+            return;
+        // The box is the control: it keeps focus while the panel is open, so Esc and Enter reach it.
+        field.elementRef.current?.focus();
+        focusPanelRef.current = focusPanel;
+        // Shown before its content renders, so the panel can scroll its columns and take focus as it mounts. Nothing is
+        // painted in between: the render that fills it runs before the frame.
+        const panel = panelRef.current;
+        if (panel && !isPopoverOpen(panel))
+            panel.showPopover();
+        setPanelValue(valueRef.current);
+        setOpen(true);
+    }
+    /** Closes the panel. With `returnFocus`, focus that was inside the panel goes back to the box (Esc, Enter, Done). */
+    function closePanel(returnFocus = false) {
+        const panel = panelRef.current;
+        const focusInPanel = Boolean(panel?.contains(document.activeElement));
+        // Blur, a press elsewhere, and Done may all close it; hiding happens once.
+        if (isPopoverOpen(panel))
+            panel.hidePopover();
+        setOpen(false);
+        if (returnFocus && focusInPanel)
+            field.elementRef.current?.focus();
+    }
+    function select(iso) {
+        const input = field.elementRef.current;
+        if (!input)
+            return;
+        setInputValue(input, text(iso));
+        field.touch();
+    }
+    function clear() {
+        const input = field.elementRef.current;
+        if (!input)
+            return;
+        setInputValue(input, "");
+        input.focus();
+    }
+    function handleKeyDown(event) {
+        const { key } = event;
+        readOnlyNotice.onKeyDown(event);
+        if (editable && key === "ArrowDown") {
+            event.preventDefault();
+            if (open)
+                panelRef.current?.querySelector('[role="option"][tabindex="0"]')?.focus({ preventScroll: true });
+            else
+                openPanel(true);
+        }
+        else if (key === "Escape" && open) {
+            // Closes the panel only: the page (a dialog, say) does not see this Esc.
+            event.preventDefault();
+            event.stopPropagation();
+            closePanel();
+        }
+        else if (clearable && editable && key === "Escape" && event.currentTarget.value) {
+            event.preventDefault();
+            event.stopPropagation();
+            clear();
+        }
+        else if (key === "Enter" && open) {
+            event.preventDefault();
+            closePanel();
+        }
+        else if (key === "Tab" && open) {
+            // Tab moves on to the next field, not into the panel; ↓ is the way in.
+            closePanel();
+        }
+        onKeyDown?.(event);
+    }
+    function handleClick(event) {
+        if (!open)
+            openPanel(false);
+        readOnlyNotice.onClick(event);
+        onClick?.(event);
+    }
+    function handleBlur(event) {
+        // Typed text takes the canonical form once it is a time.
+        const input = event.currentTarget;
+        if (valueRef.current && input.value !== text(valueRef.current))
+            input.value = text(valueRef.current);
+        // Focus moving anywhere but the panel closes it.
+        if (open && !(event.relatedTarget instanceof Node && panelRef.current?.contains(event.relatedTarget)))
+            closePanel();
+        readOnlyNotice.hide();
+        field.controlProps.onBlur(event);
+    }
+    // Focus leaving the panel for anything but the box (Tab past Done, a click elsewhere) closes it.
+    function handlePanelBlur(event) {
+        const next = event.relatedTarget;
+        if (next instanceof Node && (event.currentTarget.contains(next) || next === field.elementRef.current))
+            return;
+        closePanel();
+    }
+    function handlePanelKeyDown(event) {
+        if (event.key !== "Escape")
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        closePanel(true);
+    }
+    const showClear = clearable && editable;
+    return (_jsxs(_Fragment, { children: [_jsxs(Field, { controlId: field.controlId, messageId: field.messageId, label: label, required: required, design: design, size: size, hint: hint, error: field.error, icon: icon, prefix: prefix, actions: _jsxs(_Fragment, { children: [showClear && (_jsx("button", { type: "button", className: "nx-field__action nx-field__action--clear", tabIndex: -1, "aria-label": "Clear", title: "Clear", onMouseDown: event => event.preventDefault(), onClick: clear, children: _jsx(InlineIcon, { icon: iconX }) })), readOnlyNotice.lock, !readOnly && (_jsx("button", { type: "button", className: "nx-field__action nx-field__action--clock", tabIndex: -1, "aria-label": "Choose a time", "aria-haspopup": "dialog", "aria-expanded": open, "aria-controls": open ? `${field.controlId}-times` : undefined, title: "Choose a time", disabled: disabled, onMouseDown: event => event.preventDefault(), onClick: () => (open ? closePanel() : openPanel(false)), children: _jsx(InlineIcon, { icon: iconClock }) }))] }), disabled: disabled, readOnly: readOnly, raiseLabel: Boolean(placeholder) || hasContent(prefix), className: cx("nx-field--time", className), style: style, children: [_jsx("input", { autoComplete: "off", spellCheck: false, ...inputProps, ...field.controlProps, type: "text", name: undefined, form: form, lang: script === "devanagari" ? "ne" : undefined, defaultValue: text(initial), className: cx("nx-field__control", "nx-field__control--time", inputClassName), placeholder: placeholder || " ", disabled: disabled, readOnly: readOnly, onBlur: handleBlur, onFocus: onFocus, onKeyDown: handleKeyDown, onClick: handleClick }), name && _jsx("input", { ref: hiddenRef, type: "hidden", name: name, form: form, disabled: disabled, defaultValue: initial ?? "" })] }), readOnlyNotice.notice, !readOnly && (_jsx("div", { ref: panelRef, id: `${field.controlId}-times`, popover: "manual", role: "dialog", "aria-label": "Choose a time", className: cx("nx-popover", "nx-time-popover"), onKeyDown: handlePanelKeyDown, onBlur: handlePanelBlur, 
+                // The box keeps focus while items, buttons, and the space between them are clicked. A press on a column
+                // itself is left alone, so its scroll bar can be dragged; the column takes focus, inside the panel.
+                onMouseDown: event => {
+                    if (!event.target.matches("[data-column]"))
+                        event.preventDefault();
+                }, children: open && (_jsx(TimePanel, { view: view, value: panelValue, onValueChange: select, onDone: () => closePanel(true), format: format, script: script, seconds: seconds, step: step, min: min, max: max, isTimeDisabled: isTimeDisabled, autoFocus: focusPanelRef.current })) }))] }));
+}

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

@@ -0,0 +1,160 @@
+import { type CSSProperties, type ReactNode, type Ref } from "react";
+import { type TreeItem, type TreeValue, type TreeValueMode } from "../../Helpers/TreeStore.ts";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+export type TreeAction = "create" | "update" | "delete";
+export interface TreeCreateRequest<TItem extends TreeItem = TreeItem> {
+    /** The item the new one goes under, or `null` at the top level. */
+    parent: TItem | null;
+    parentValue: TreeValue | null;
+    /** The name typed, trimmed. */
+    label: string;
+    /** What the tree adds when `onCreate` returns nothing: a generated value, the parent's value, and the label. */
+    item: TItem;
+}
+export interface TreeUpdateRequest<TItem extends TreeItem = TreeItem> {
+    item: TItem;
+    value: TreeValue;
+    /** The new name, trimmed. */
+    label: string;
+}
+export interface TreeDeleteRequest<TItem extends TreeItem = TreeItem> {
+    item: TItem;
+    value: TreeValue;
+    /** The item and everything under it, in tree order. */
+    items: TItem[];
+}
+/** What a `ref` on `TreeView` can do. */
+export interface TreeViewHandle<TItem extends TreeItem = TreeItem> {
+    /** Expands every item, or the first `levels` levels. */
+    expandAll: (levels?: number) => void;
+    collapseAll: () => void;
+    /** Expands an item and its parents. */
+    expand: (value: TreeValue) => void;
+    collapse: (value: TreeValue) => void;
+    /** Expands the parents of an item, scrolls to it, and focuses it unless `focus` is false. */
+    reveal: (value: TreeValue, focus?: boolean) => void;
+    getValue: () => TreeValue[];
+    /** Checks exactly these values, locked items included. For a tree without `value`. */
+    setValue: (values: readonly TreeValue[]) => void;
+    /** Checks or unchecks every item that is not locked. */
+    checkAll: (checked: boolean) => void;
+    /** Every item in tree order, with the changes made in the tree. */
+    getItems: () => TItem[];
+    /** Opens the editor for a new item under `parentValue`, or at the top level for `null`. */
+    startCreate: (parentValue: TreeValue | null) => void;
+    startRename: (value: TreeValue) => void;
+    /** Asks (unless `confirmDelete` is off), then deletes an item. Resolves with whether it was deleted. */
+    remove: (value: TreeValue) => Promise<boolean>;
+    /** Focuses the focused row, or the first. */
+    focus: () => void;
+}
+export interface TreeViewProps<TItem extends TreeItem = TreeItem> {
+    /**
+     * The items, flat: each names its parent through `parentKey`, and siblings keep this order. Keep the array stable
+     * (state, a constant, or `useMemo`): a different array, or one with different items, builds the tree again.
+     */
+    items: readonly TItem[];
+    /** The item field that holds its value. Default `id`. */
+    valueKey?: string;
+    /** The item field that holds its parent's value; empty for a top-level item. Default `parentId`. */
+    parentKey?: string;
+    /** The item field shown as its name. Default `label`. */
+    labelKey?: string;
+    /** Muted text after the label. Default `description`. */
+    descriptionKey?: string;
+    /** A Tabler icon name, or an element, before the label. Default `icon`. */
+    iconKey?: string;
+    /**
+     * Items the user has no permission to change: they cannot be checked, unchecked, renamed, or deleted, and everything
+     * under them is locked too. A lock shows at the end of the row, and a try shows `lockedMessage`. Default:
+     * `disabled: true` or `isDisabled: true`.
+     */
+    isItemDisabled?: (item: TItem) => boolean;
+    /** What a locked item says when someone tries to change it. Default "You do not have permission to change this item." */
+    lockedMessage?: string;
+    label?: ReactNode;
+    /** Help text under the tree. */
+    hint?: ReactNode;
+    /** An error from outside, such as a server message. */
+    error?: string | null;
+    /** Default `md`. */
+    size?: Size;
+    /** A checkbox on every row. */
+    checkable?: boolean;
+    /** With `checkable`: checking a parent checks everything under it, and a parent shows the state of its items. Default true. */
+    cascade?: boolean;
+    /** Which checked items the value holds. Default `leaves`, such as the action ids of a permission tree. See `TreeValueMode`. */
+    valueMode?: TreeValueMode;
+    /** The checked values. With `value`, the tree is controlled; pair it with `onValueChange`. */
+    value?: readonly TreeValue[];
+    /** The checked values at the start. Without it, items with `checked: true` or `isChecked: true` start checked. */
+    defaultValue?: readonly TreeValue[];
+    /** After each check or uncheck: the values and their items, in tree order. */
+    onValueChange?: (values: TreeValue[], items: TItem[]) => void;
+    /** A form gets the value as hidden inputs named `name`, one per value. Leave it out for very large values and read them from `onValueChange`. */
+    name?: string;
+    form?: string;
+    /** With `checkable` and `cascade`: a parent shows how many of its items are checked, as "3/5". Default true. */
+    counts?: boolean;
+    /** What is expanded at the start: `"all"`, a number of levels, or the values of items to open. */
+    defaultExpanded?: "all" | number | readonly TreeValue[];
+    /** Items can be added: a + on each row adds under it, and Add in the toolbar adds at the top level. */
+    creatable?: boolean;
+    /** Items can be renamed: a pencil on each row, F2, or the context menu. */
+    editable?: boolean;
+    /** Items can be deleted, with everything under them: a bin on each row, Delete, or the context menu. */
+    deletable?: boolean;
+    /** Narrows the actions per item, e.g. from the user's permissions. `item` is `null` for adding at the top level. */
+    canChange?: (action: TreeAction, item: TItem | null) => boolean;
+    /**
+     * Saves a new item, e.g. through an API. Return the saved item (with the server's id), or nothing to keep
+     * `request.item`. A thrown error keeps the editor open with the name typed and shows the message under the tree.
+     */
+    onCreate?: (request: TreeCreateRequest<TItem>) => TItem | void | Promise<TItem | void>;
+    /** Saves a new name. Return the saved item, or nothing to keep the item with the new label. A thrown error keeps the editor open. */
+    onUpdate?: (request: TreeUpdateRequest<TItem>) => TItem | void | Promise<TItem | void>;
+    /** Deletes an item and everything under it. A thrown error keeps the items and shows the message. */
+    onDelete?: (request: TreeDeleteRequest<TItem>) => void | Promise<void>;
+    /** After an item is added, renamed, or deleted: every item in tree order. Passing this array back as `items` does not rebuild the tree. */
+    onItemsChange?: (items: TItem[]) => void;
+    /** Asks before deleting. Default true; needs `<PopupHost />` on the page. */
+    confirmDelete?: boolean;
+    /** The longest name the editor takes. Default 100. */
+    maxLabelLength?: number;
+    /** A click on a row without a checkbox, or Enter on it. Without it, a click expands or collapses a parent. */
+    onItemClick?: (item: TItem) => void;
+    /** Items are on their way: placeholder rows while the tree is empty, and a spinner in the toolbar. */
+    loading?: boolean;
+    /** Shown when there are no items. Default "No items". */
+    emptyMessage?: ReactNode;
+    /** The bar above the rows: select all, counts, expand all, collapse all, and Add. Default true. */
+    toolbar?: boolean;
+    /** A fixed height for the rows' area, e.g. 480 or "60vh". */
+    height?: number | string;
+    /** The tallest the rows' area grows before it scrolls. Default 420. */
+    maxHeight?: number | string;
+    /** Can be browsed, expanded, and focused, but not changed. A lock follows the label, and a try shows a note. */
+    readOnly?: boolean;
+    /** What a read-only tree says when someone tries to change it. Default "Read-only: this tree cannot be changed." */
+    readOnlyMessage?: string;
+    disabled?: boolean;
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+    /** Name for screen readers when there is no `label`. */
+    "aria-label"?: string;
+    ref?: Ref<TreeViewHandle<TItem>>;
+}
+/**
+ * A tree of items from a flat list: a permission tree (controller > menu > action) with checkboxes that cascade and
+ * items the user may not change, or a tree of categories to add, rename, and delete. Only the rows in view are
+ * rendered, so collapsed items never reach the page, and 100,000 expanded items scroll like 40. Expanding and
+ * collapsing slide open and closed (at once with reduced motion).
+ *
+ * Keys: arrows move and expand, Home and End jump, letters find a row, Space checks, Enter opens, `*` expands the
+ * siblings, F2 renames, Delete deletes, Insert adds under the focused row, and Shift+F10 opens the actions menu.
+ *
+ * @example
+ * <TreeView label="Permissions" items={permissions} checkable name="actionIds" defaultExpanded={1} isItemDisabled={item => !item.canAssign} />
+ */
+export declare function TreeView<TItem extends TreeItem = TreeItem>(props: TreeViewProps<TItem>): import("react").JSX.Element;