nexus-shared 1.1.20 → 2.0.0

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

@@ -0,0 +1,36 @@
+import { type KeyboardEvent, type MouseEvent, type ReactNode, type RefObject } from "react";
+import { type PopoverAlign } from "../../Helpers/PopoverHelpers.ts";
+export interface ReadOnlyNoticeOptions {
+    /** The element the note goes under, for the element the user acted on. Default: the field's box (`.nx-field__box`). */
+    anchor?: (target: Element) => Element | null;
+    /** Lines the note up with the anchor's `start` (default) or `end` edge, e.g. `end` under a switch at the end of its row. */
+    align?: PopoverAlign;
+    /** Typed text, Backspace, Delete, Ctrl+V, and Ctrl+X count as attempts. Default true; off for a slider. */
+    typing?: boolean;
+    /** Other keys that would change the value: `["ArrowDown"]` opens a date picker's calendar. */
+    keys?: readonly string[];
+    /** `box` (default): a lock the size of a field's buttons, for the end of its box. `label`: a small lock after a label. */
+    lock?: "box" | "label";
+}
+export interface ReadOnlyNotice {
+    /** The lock: in the field's `actions` for `box`, or after the label text for `label`. `null` unless read-only. */
+    lock: ReactNode;
+    /** The note. Render it after the field; it shows nothing until an attempt. `null` unless read-only. */
+    notice: ReactNode;
+    /** Call from `onKeyDown`: a key that would change the value shows the note, and Esc hides it. */
+    onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+    /** Call from `onClick`: a click shows the note under the anchor of its target, unless it selected text to copy. */
+    onClick: (event: MouseEvent<HTMLElement>) => void;
+    /** Shows the note under the anchor of this element, e.g. on a slider's pointer press. */
+    show: (target: Element | null) => void;
+    /** Hides the note, e.g. when focus leaves the field. */
+    hide: () => void;
+}
+/**
+ * Feedback for a read-only field, so a click or a key that does nothing does not look like a bug: a lock, and a
+ * short note under the field when the user tries to change it anyway. Nothing renders until an attempt, and an
+ * attempt re-renders only the note, so a large form or a group of many options costs nothing extra.
+ *
+ * @example const readOnlyNotice = useReadOnlyNotice(Boolean(readOnly) && !disabled, field.elementRef, "Read-only: this date cannot be changed.", { keys: ["ArrowDown"] });
+ */
+export declare function useReadOnlyNotice(enabled: boolean, controlRef: RefObject<HTMLElement | null>, message: ReactNode, options?: ReadOnlyNoticeOptions): ReadOnlyNotice;

package/dist/Components/Inputs/ReadOnlyNotice.js

@@ -0,0 +1,116 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconLock, InlineIcon } from "nexus-icons";
+import { useEffect, useImperativeHandle, useLayoutEffect, useRef, useState, } from "react";
+import { followAnchor, isPopoverOpen, placeUnderAnchor } from "../../Helpers/PopoverHelpers.js";
+/** How long the note stays up after the last attempt, in milliseconds. */
+const NOTICE_MS = 2500;
+/**
+ * Feedback for a read-only field, so a click or a key that does nothing does not look like a bug: a lock, and a
+ * short note under the field when the user tries to change it anyway. Nothing renders until an attempt, and an
+ * attempt re-renders only the note, so a large form or a group of many options costs nothing extra.
+ *
+ * @example const readOnlyNotice = useReadOnlyNotice(Boolean(readOnly) && !disabled, field.elementRef, "Read-only: this date cannot be changed.", { keys: ["ArrowDown"] });
+ */
+export function useReadOnlyNotice(enabled, controlRef, message, options = {}) {
+    const { anchor = fieldBox, align = "start", typing = true, keys, lock: lockDesign = "box" } = options;
+    const noteRef = useRef(null);
+    const lockRef = useRef(null);
+    const timerRef = useRef(0);
+    const shownRef = useRef(false);
+    function show(target) {
+        const element = enabled && target ? anchor(target) : null;
+        if (!element)
+            return;
+        window.clearTimeout(timerRef.current);
+        timerRef.current = window.setTimeout(hide, NOTICE_MS);
+        shownRef.current = true;
+        noteRef.current?.show(element, align);
+        // Each attempt restarts the lock's nudge.
+        const lock = lockRef.current;
+        if (lock) {
+            lock.removeAttribute("data-nudge");
+            void lock.offsetWidth;
+            lock.setAttribute("data-nudge", "");
+        }
+    }
+    function hide() {
+        window.clearTimeout(timerRef.current);
+        if (!shownRef.current)
+            return;
+        shownRef.current = false;
+        noteRef.current?.hide();
+        lockRef.current?.removeAttribute("data-nudge");
+    }
+    useEffect(() => {
+        if (!enabled)
+            hide();
+    }, [enabled]);
+    useEffect(() => () => window.clearTimeout(timerRef.current), []);
+    function onKeyDown(event) {
+        if (!enabled)
+            return;
+        if (event.key === "Escape") {
+            if (!shownRef.current)
+                return;
+            event.stopPropagation();
+            hide();
+        }
+        else if (isChangeKey(event, typing, keys)) {
+            show(event.target);
+        }
+    }
+    function onClick(event) {
+        const target = event.target;
+        if (enabled && target instanceof Element && !hasSelection(target))
+            show(target);
+    }
+    const lock = !enabled ? null : lockDesign === "box" ? (_jsx("span", { ref: lockRef, className: "nx-field__lock", title: "Read-only", "aria-hidden": "true", 
+        // The box keeps focus and any selected text.
+        onMouseDown: event => {
+            event.preventDefault();
+            controlRef.current?.focus();
+            show(controlRef.current);
+        }, children: _jsx(InlineIcon, { icon: iconLock }) })) : (_jsx("span", { ref: lockRef, className: "nx-field__lock nx-field__lock--label", title: "Read-only", "aria-hidden": "true", children: _jsx(InlineIcon, { icon: iconLock }) }));
+    return { lock, notice: enabled ? _jsx(ReadOnlyNote, { ref: noteRef, message: message }) : null, onKeyDown, onClick, show, hide };
+}
+/**
+ * The note itself, with its own state, so showing it re-renders only the note. It is a manual popover in the top
+ * layer, so a table cell or a dialog does not clip it, and it follows its anchor while the page scrolls.
+ */
+function ReadOnlyNote({ ref, message }) {
+    const [shown, setShown] = useState(null);
+    const noteRef = useRef(null);
+    useImperativeHandle(ref, () => ({ show: (anchor, align) => setShown({ anchor, align }), hide: () => setShown(null) }), []);
+    useLayoutEffect(() => {
+        const note = noteRef.current;
+        if (!shown || !note)
+            return;
+        if (!isPopoverOpen(note))
+            note.showPopover?.();
+        const place = () => placeUnderAnchor(note, shown.anchor.getBoundingClientRect(), { align: shown.align });
+        place();
+        return followAnchor(place);
+    }, [shown]);
+    if (!shown)
+        return null;
+    return (_jsxs("div", { ref: noteRef, popover: "manual", role: "status", className: "nx-field-notice", children: [_jsx(InlineIcon, { icon: iconLock }), _jsx("span", { children: message })] }));
+}
+const fieldBox = (target) => target.closest(".nx-field__box");
+/** Whether a text box has selected text, as after dragging across it to copy. */
+function hasSelection(target) {
+    return (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) && target.selectionStart !== target.selectionEnd;
+}
+/** Keys that would change the value. Copying, selecting, and moving the caret are not. */
+function isChangeKey(event, typing, keys = []) {
+    const { key, ctrlKey, metaKey } = event;
+    if (keys.includes(key))
+        return true;
+    if (!typing)
+        return false;
+    if (key === "Backspace" || key === "Delete")
+        return true;
+    if (ctrlKey || metaKey)
+        return key === "v" || key === "V" || key === "x" || key === "X";
+    return key.length === 1;
+}

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

@@ -0,0 +1,103 @@
+import { type CSSProperties, type FocusEvent, type ReactNode, type Ref } from "react";
+import { type RichTextRules, type RichTextToken, type RichTextTokenFormat } from "../../Helpers/RichTextHelpers.ts";
+import type { ValidateOn } from "../../Interfaces/InputInterfaces.ts";
+/** `edit`: the formatted text, edited in place. `html`: its HTML source, one block per line. */
+export type RichTextEditorMode = "edit" | "html";
+export type RichTextTool = "undo" | "redo" | "block" | "bold" | "italic" | "underline" | "strikethrough" | "code" | "subscript" | "superscript" | "color" | "link" | "bulletList" | "numberedList" | "quote" | "align" | "table" | "rule" | "clear" | "token";
+/** A toolbar button, or `"|"` for a divider between groups. */
+export type RichTextToolbarItem = RichTextTool | "|";
+/** The default toolbar. `token` shows only when the editor has `tokens`. */
+export declare const RICH_TEXT_TOOLBAR: readonly RichTextToolbarItem[];
+export interface RichTextEditorProps extends RichTextRules {
+    id?: string;
+    /** Form field name: the form's data gets the sanitized HTML under it. */
+    name?: string;
+    /** Id of the form the editor belongs to, when it sits outside it. */
+    form?: string;
+    label?: ReactNode;
+    /** Help text under the editor. */
+    hint?: ReactNode;
+    /** An error from outside, such as a server message. Shown before the field's own message. */
+    error?: string | null;
+    /** Shown while the editor is empty. */
+    placeholder?: string;
+    /** The HTML it starts with. It is sanitized first. */
+    defaultValue?: string;
+    /** The HTML, when the page controls it; pair it with `onValueChange`. Passing back the value it gave does nothing. */
+    value?: string;
+    /** The sanitized HTML after each change: typed, pasted, from the toolbar, or from the HTML view. */
+    onValueChange?: (html: string) => void;
+    /** The view it opens in. Default `edit`. */
+    defaultMode?: RichTextEditorMode;
+    /** The view, when the page controls it; use with `onModeChange`. */
+    mode?: RichTextEditorMode;
+    onModeChange?: (mode: RichTextEditorMode) => void;
+    /** The views to switch between. Default both; `["edit"]` hides the switch and the HTML. */
+    modes?: readonly RichTextEditorMode[];
+    /** Toolbar buttons in order, `"|"` for a divider. Default `RICH_TEXT_TOOLBAR`; `[]` hides them. Shortcuts work for the tools listed. */
+    toolbar?: readonly RichTextToolbarItem[];
+    /** Values a template fills in, such as the guest's name: a menu inserts them as chips, and the HTML holds them as `tokenFormat` text. */
+    tokens?: readonly RichTextToken[];
+    /** How tokens are written in the HTML: `{{key}}` (default, messages) or `|key|` (reports). */
+    tokenFormat?: RichTextTokenFormat;
+    /** Height of the text, in pixels. Default 280. A double-click on the handle goes back to it. */
+    height?: number;
+    /** Smallest height the handle allows. Default 120. */
+    minHeight?: number;
+    /** Largest height the handle allows. Default 960. */
+    maxHeight?: number;
+    /** The handle under the editor that drags its height. Default true. */
+    resizable?: boolean;
+    /** Remembers the height the user picks, in local storage under `nx-rte-height:<heightKey>`. */
+    heightKey?: string;
+    /** A button that opens the editor over the whole window. Default true. */
+    fullscreen?: boolean;
+    /** Word and character counts in the status bar. Default true. */
+    showCount?: boolean;
+    /** Spelling check while typing. Default true. */
+    spellCheck?: boolean;
+    autoFocus?: boolean;
+    readOnly?: boolean;
+    disabled?: boolean;
+    /** What a read-only editor says when someone tries to change it. Default "Read-only: this text 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;
+    /** Name of the editor for screen readers, when there is no `label`. */
+    "aria-label"?: string;
+    "aria-describedby"?: string;
+    onFocus?: (event: FocusEvent<HTMLDivElement>) => void;
+    onBlur?: (event: FocusEvent<HTMLDivElement>) => void;
+    /** Class of the outer field. */
+    className?: string;
+    style?: CSSProperties;
+    ref?: Ref<RichTextEditorHandle>;
+}
+/** What `ref` gives on a rich text editor. */
+export interface RichTextEditorHandle {
+    /** The sanitized HTML. */
+    getValue: () => string;
+    /** Replaces the content, e.g. with a template loaded from a server. It becomes what a form reset returns to. */
+    setValue: (html: string) => void;
+    /** Inserts text at the caret, replacing the selection. */
+    insertText: (text: string) => void;
+    /** Inserts HTML at the caret, sanitized first. */
+    insertHtml: (html: string) => void;
+    /** Inserts a token (a value the template fills in) at the caret, as a chip. */
+    insertToken: (key: string) => void;
+    focus: () => void;
+    /** The editable element. */
+    element: HTMLDivElement | null;
+}
+/**
+ * A rich text editor: formatted text edited in place, with a toolbar and shortcuts, text colors and highlights, links,
+ * lists, alignment, tables, template tokens as chips, an HTML view, a height handle, and full screen. The value is
+ * HTML, sanitized on every change (`sanitizeRichText`), so a page can store it and show it with `RichTextView`.
+ * Editing goes through the browser, so Ctrl+Z undoes typing and toolbar changes alike, and typing re-renders nothing.
+ * Pastes from Word, Google Docs, and web pages keep their formatting and lose everything else.
+ *
+ * @example <RichTextEditor name="description" label="Room description" heightKey="room-description" maxLength={5000} />
+ */
+export declare function RichTextEditor(props: RichTextEditorProps): import("react").JSX.Element;