nexus-shared 1.1.20 → 2.0.0

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

@@ -0,0 +1,84 @@
+import { type ReactNode } from "react";
+import type { DropdownColumn, DropdownItem } from "../../Interfaces/InputInterfaces.ts";
+/**
+ * Why a current value cannot be picked again:
+ * - `inactive`: its item is marked inactive, such as a deactivated user.
+ * - `unavailable`: its item is no longer among the options.
+ * - `unknown`: nothing is known about the value but the value itself.
+ */
+export type DropdownValueState = "inactive" | "unavailable" | "unknown";
+export declare const DROPDOWN_STATE_LABELS: Record<DropdownValueState, string>;
+/** The tooltip of a current value that cannot be picked again. */
+export declare const DROPDOWN_STATE_NOTES: Record<DropdownValueState, string>;
+type AnyColumn = DropdownColumn<never>;
+/** A round photo, or the initials of the name on a soft tone when there is no photo or it fails to load. */
+export declare function DropdownAvatar({ src, name }: {
+    src: unknown;
+    name: string;
+}): import("react").JSX.Element;
+/** A small 4:3 picture, such as a flag or a logo; an empty frame when there is none or it fails to load. */
+export declare function DropdownImage({ src }: {
+    src: unknown;
+}): import("react").JSX.Element;
+/** An icon field: a Tabler icon name, or an element such as `<Icon name="wifi" />`. */
+export declare function iconNode(icon: unknown): ReactNode;
+/** Whether an icon field has something to draw. */
+export declare function hasIcon(icon: unknown): boolean;
+/** One cell of a row with columns. `label` names the avatar's initials; `tag` follows the text. */
+export declare function DropdownCell({ column, item, label, tag }: {
+    column: AnyColumn;
+    item: DropdownItem;
+    label: string;
+    tag?: ReactNode;
+}): import("react").JSX.Element;
+/** The picture that leads a value in the box or a chip: the first avatar, image, or icon column, or the icon field. */
+export declare function DropdownMedia({ item, label, columns, iconKey }: {
+    item: DropdownItem;
+    label: string;
+    columns?: readonly AnyColumn[];
+    iconKey: string;
+}): import("react").JSX.Element | null;
+/** The tag of a value that cannot be picked again. */
+export declare function DropdownTag({ state }: {
+    state: DropdownValueState | null;
+}): import("react").JSX.Element | null;
+export interface DropdownOptionProps {
+    id: string;
+    index: number;
+    /** `null` for a value known only by itself. */
+    item: DropdownItem | null;
+    /** Text of the item's label, or the bare value. */
+    label: string;
+    /** The label field when it is an element rather than text. */
+    labelNode?: ReactNode;
+    description?: ReactNode;
+    columns?: readonly AnyColumn[];
+    /** The column that holds the tag: the label's column, or the last text column. */
+    tagColumn: number;
+    iconKey: string;
+    /** Rows without columns keep an icon slot when any row has an icon, so labels line up. */
+    iconSlot: boolean;
+    multiple: boolean;
+    selected: boolean;
+    active: boolean;
+    disabled: boolean;
+    /** Resolving the item of a bare value: the label shows a placeholder bar. */
+    pending: boolean;
+    state: DropdownValueState | null;
+}
+/**
+ * One row of the list. Memoized, and its events are handled by the list, so moving the highlight or picking re-renders
+ * only the rows whose state changed.
+ */
+export declare const DropdownOption: import("react").MemoExoticComponent<(props: DropdownOptionProps) => import("react").JSX.Element>;
+export interface DropdownChipProps {
+    label: string;
+    media?: ReactNode;
+    state: DropdownValueState | null;
+    pending: boolean;
+    /** Without it, the chip has no remove button (read-only, disabled). */
+    onRemove?: () => void;
+}
+/** A chosen value in a multiple dropdown's box. */
+export declare function DropdownChip({ label, media, state, pending, onRemove }: DropdownChipProps): import("react").JSX.Element;
+export {};

package/dist/Components/Inputs/DropdownParts.js

@@ -0,0 +1,102 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Icon, iconCheck, iconX, InlineIcon } from "nexus-icons";
+import { isValidElement, memo, useState } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { avatarTone, initials, isMediaColumn, readField } from "../../Helpers/DropdownHelpers.js";
+export const DROPDOWN_STATE_LABELS = {
+    inactive: "Inactive",
+    unavailable: "Unavailable",
+    unknown: "Not found",
+};
+/** The tooltip of a current value that cannot be picked again. */
+export const DROPDOWN_STATE_NOTES = {
+    inactive: "Inactive: kept as the current value. Once removed, it cannot be chosen again.",
+    unavailable: "No longer in the list: kept as the current value. Once removed, it cannot be chosen again.",
+    unknown: "Not found in the list: kept as the current value. Once removed, it cannot be chosen again.",
+};
+/** A round photo, or the initials of the name on a soft tone when there is no photo or it fails to load. */
+export function DropdownAvatar({ src, name }) {
+    const url = typeof src === "string" ? src.trim() : "";
+    const [failed, setFailed] = useState(null);
+    const photo = url !== "" && failed !== url;
+    return (_jsx("span", { className: "nx-dropdown-avatar", "data-tone": photo ? undefined : avatarTone(name), "aria-hidden": "true", children: photo ? _jsx("img", { src: url, alt: "", loading: "lazy", decoding: "async", onError: () => setFailed(url) }) : initials(name) }));
+}
+/** A small 4:3 picture, such as a flag or a logo; an empty frame when there is none or it fails to load. */
+export function DropdownImage({ src }) {
+    const url = typeof src === "string" ? src.trim() : "";
+    const [failed, setFailed] = useState(null);
+    if (url === "" || failed === url)
+        return _jsx("span", { className: "nx-dropdown-image nx-dropdown-image--empty", "aria-hidden": "true" });
+    return _jsx("img", { className: "nx-dropdown-image", src: url, alt: "", loading: "lazy", decoding: "async", onError: () => setFailed(url) });
+}
+/** An icon field: a Tabler icon name, or an element such as `<Icon name="wifi" />`. */
+export function iconNode(icon) {
+    if (typeof icon === "string" && icon)
+        return _jsx(Icon, { name: icon });
+    return isValidElement(icon) ? icon : null;
+}
+/** Whether an icon field has something to draw. */
+export function hasIcon(icon) {
+    return (typeof icon === "string" && icon !== "") || isValidElement(icon);
+}
+const alignStyle = (align) => align && align !== "start" ? { justifySelf: align, textAlign: align } : undefined;
+/** One cell of a row with columns. `label` names the avatar's initials; `tag` follows the text. */
+export function DropdownCell({ column, item, label, tag }) {
+    const type = column.type ?? "text";
+    const style = alignStyle(column.align);
+    if (column.render) {
+        return (_jsxs("span", { className: cx("nx-dropdown-cell", `nx-dropdown-cell--${type}`), style: style, children: [column.render(item), tag] }));
+    }
+    const value = readField(item, column.key);
+    if (isMediaColumn(column)) {
+        return (_jsx("span", { className: "nx-dropdown-cell nx-dropdown-cell--media", style: style, "aria-hidden": "true", children: type === "avatar" ? _jsx(DropdownAvatar, { src: value, name: label }) : type === "image" ? _jsx(DropdownImage, { src: value }) : _jsx("span", { className: "nx-dropdown-icon", children: iconNode(value) }) }));
+    }
+    const text = value === null || value === undefined ? "" : String(value);
+    return (_jsxs("span", { className: cx("nx-dropdown-cell", `nx-dropdown-cell--${type}`), style: style, children: [_jsx("span", { className: "nx-dropdown-cell__text", children: text }), tag] }));
+}
+/** The picture that leads a value in the box or a chip: the first avatar, image, or icon column, or the icon field. */
+export function DropdownMedia({ item, label, columns, iconKey }) {
+    if (columns) {
+        const column = columns.find(isMediaColumn);
+        if (!column)
+            return null;
+        const value = readField(item, column.key);
+        if (column.type === "avatar")
+            return _jsx(DropdownAvatar, { src: value, name: label });
+        if (column.type === "image")
+            return _jsx(DropdownImage, { src: value });
+        return hasIcon(value) ? _jsx("span", { className: "nx-dropdown-icon", children: iconNode(value) }) : null;
+    }
+    const icon = readField(item, iconKey);
+    return hasIcon(icon) ? (_jsx("span", { className: "nx-dropdown-icon", "aria-hidden": "true", children: iconNode(icon) })) : null;
+}
+/** The tag of a value that cannot be picked again. */
+export function DropdownTag({ state }) {
+    return state ? _jsx("span", { className: "nx-dropdown-tag", children: DROPDOWN_STATE_LABELS[state] }) : null;
+}
+/**
+ * One row of the list. Memoized, and its events are handled by the list, so moving the highlight or picking re-renders
+ * only the rows whose state changed.
+ */
+export const DropdownOption = memo(function DropdownOption(props) {
+    const { id, index, item, label, labelNode, description, columns, tagColumn, iconKey, iconSlot, multiple, selected, active, disabled, pending, state } = props;
+    const tag = _jsx(DropdownTag, { state: state });
+    const text = pending ? _jsx("span", { className: "nx-dropdown-skeleton" }) : (labelNode ?? label);
+    let body;
+    if (columns && item) {
+        body = columns.map((column, columnIndex) => _jsx(DropdownCell, { column: column, item: item, label: label, tag: columnIndex === tagColumn ? tag : null }, columnIndex));
+    }
+    else if (columns) {
+        // A bare value has no fields to fill the columns: its text and tag span them all.
+        body = (_jsxs("span", { className: "nx-dropdown-cell nx-dropdown-cell--span", children: [_jsx("span", { className: "nx-dropdown-cell__text", children: text }), tag] }));
+    }
+    else {
+        body = (_jsxs(_Fragment, { children: [iconSlot && (_jsx("span", { className: "nx-dropdown-option__icon", "aria-hidden": "true", children: item && iconNode(readField(item, iconKey)) })), _jsxs("span", { className: "nx-dropdown-option__body", children: [_jsxs("span", { className: "nx-dropdown-option__label", children: [_jsx("span", { className: "nx-dropdown-option__text", children: text }), tag] }), description !== undefined && description !== null && description !== "" && _jsx("span", { className: "nx-dropdown-option__description", children: description })] })] }));
+    }
+    return (_jsxs("div", { role: "option", id: id, "data-index": index, "data-active": active || undefined, "data-state": state ?? undefined, "aria-selected": selected, "aria-disabled": disabled || undefined, title: state ? DROPDOWN_STATE_NOTES[state] : undefined, className: "nx-dropdown-option", children: [_jsx("span", { className: "nx-dropdown-option__check", "aria-hidden": "true", children: multiple ? _jsx("span", { className: "nx-dropdown-checkbox" }) : selected && _jsx(InlineIcon, { icon: iconCheck }) }), body] }));
+});
+/** A chosen value in a multiple dropdown's box. */
+export function DropdownChip({ label, media, state, pending, onRemove }) {
+    return (_jsxs("span", { className: "nx-dropdown-chip", "data-state": state ?? undefined, title: state ? `${label}. ${DROPDOWN_STATE_NOTES[state]}` : label, children: [media, _jsx("span", { className: "nx-dropdown-chip__label", children: pending ? _jsx("span", { className: "nx-dropdown-skeleton" }) : label }), onRemove && (_jsx("button", { type: "button", className: "nx-dropdown-chip__remove", tabIndex: -1, "aria-label": `Remove ${label}`, onMouseDown: event => event.preventDefault(), onClick: onRemove, children: _jsx(InlineIcon, { icon: iconX }) }))] }));
+}

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

@@ -0,0 +1,45 @@
+import { type CSSProperties, type KeyboardEvent, type ReactNode, type Ref } from "react";
+export interface EditorShellOptions {
+    /** Height of the body, in pixels. A double-click on the handle goes back to it. */
+    height: number;
+    minHeight: number;
+    maxHeight: number;
+    /** The status bar drags the height. */
+    resizable: boolean;
+    /** Local storage key that remembers the height the user picks. */
+    storageKey?: string;
+    /** A button that opens the editor over the whole window. */
+    fullscreen: boolean;
+    disabled?: boolean;
+    /** What takes focus when the editor opens over the window, unless focus is inside it already. */
+    focusTarget: (box: HTMLElement) => HTMLElement | null;
+}
+type BodyStyle = CSSProperties & {
+    "--nx-editor-height": string;
+};
+/**
+ * State and handlers of the editor frame. The height changes by writing a CSS variable, so dragging re-renders
+ * nothing; full screen moves the field's box into the top layer as a popover without moving it in the page, so the
+ * control inside keeps its undo history and its form.
+ */
+export declare function useEditorShell(options: EditorShellOptions): {
+    fullscreen: boolean;
+    setFullscreen: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    frameRef: import("react").RefObject<HTMLDivElement | null>;
+    bodyRef: import("react").RefObject<HTMLDivElement | null>;
+    bodyStyle: BodyStyle;
+    onFrameKeyDown: (event: KeyboardEvent<HTMLDivElement>) => void;
+    moveTool: (event: KeyboardEvent<HTMLDivElement>) => void;
+    fullscreenButton: import("react").JSX.Element | null;
+    footer: (hint: ReactNode, count: ReactNode) => import("react").JSX.Element;
+};
+/** Word and character counts for the status bar. Editors update them straight in the DOM with `writeEditorCount`. */
+export declare function EditorCount({ ref, text, maxLength }: {
+    ref: Ref<HTMLSpanElement>;
+    text: string;
+    maxLength?: number;
+}): import("react").JSX.Element;
+export declare function writeEditorCount(element: HTMLElement | null, text: string, maxLength?: number): void;
+export declare function readStorage(key: string): string | null;
+export declare function writeStorage(key: string, value: string | null): void;
+export {};

package/dist/Components/Inputs/EditorShell.js

@@ -0,0 +1,214 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconArrowsMaximize, iconArrowsMinimize, InlineIcon } from "nexus-icons";
+import { useEffect, useEffectEvent, useLayoutEffect, useRef, useState } from "react";
+/*
+ * The frame shared by the Markdown and rich text editors: a bar for views and formatting buttons, a body with a
+ * height, a status bar that is also the height handle, and a full-screen view. Class names start with `nx-editor__`
+ * (Nexus.Editor.css); each editor adds its own class to the field (`nx-md`, `nx-rte`).
+ */
+/** Letters and digits, with the marks of scripts such as Devanagari; an apostrophe inside a word keeps it one word. */
+const WORDS = /[\p{L}\p{N}\p{M}]+(?:['\p{Pf}][\p{L}\p{N}\p{M}]+)*/gu;
+/** How long the height shows after a key moves the handle, in milliseconds. */
+const SIZE_MS = 900;
+/**
+ * State and handlers of the editor frame. The height changes by writing a CSS variable, so dragging re-renders
+ * nothing; full screen moves the field's box into the top layer as a popover without moving it in the page, so the
+ * control inside keeps its undo history and its form.
+ */
+export function useEditorShell(options) {
+    const { height, minHeight, maxHeight, resizable, storageKey, fullscreen: canFullscreen, disabled } = options;
+    const [fullscreen, setFullscreen] = useState(false);
+    const frameRef = useRef(null);
+    const bodyRef = useRef(null);
+    const handleRef = useRef(null);
+    const footerRef = useRef(null);
+    const heightRef = useRef(height);
+    const dragRef = useRef(null);
+    const sizeTimerRef = useRef(0);
+    const focusInside = useEffectEvent((box) => options.focusTarget(box)?.focus());
+    const canResize = resizable && !fullscreen;
+    // ---- Height ----
+    function setHeight(next, save = false) {
+        const value = Math.round(Math.min(Math.max(next, minHeight), Math.max(minHeight, maxHeight)));
+        heightRef.current = value;
+        bodyRef.current?.style.setProperty("--nx-editor-height", `${value}px`);
+        handleRef.current?.setAttribute("aria-valuenow", String(value));
+        handleRef.current?.setAttribute("aria-valuetext", `${value} pixels`);
+        const size = footerRef.current?.querySelector(".nx-editor__size");
+        if (size)
+            size.textContent = `${value} px`;
+        if (save && storageKey)
+            writeStorage(storageKey, String(value));
+    }
+    // A remembered height applies before the first paint in the browser; the server renders the default.
+    useLayoutEffect(() => {
+        const stored = storageKey ? Number(readStorage(storageKey)) : 0;
+        setHeight(stored > 0 ? stored : height);
+    }, [storageKey, height, minHeight, maxHeight]);
+    useEffect(() => () => window.clearTimeout(sizeTimerRef.current), []);
+    function startResize(event) {
+        if (event.button !== 0 || !canResize || disabled)
+            return;
+        // No text selection and no focus change while dragging.
+        event.preventDefault();
+        event.currentTarget.setPointerCapture(event.pointerId);
+        dragRef.current = { pointer: event.pointerId, y: event.clientY, height: heightRef.current };
+        event.currentTarget.setAttribute("data-resizing", "");
+    }
+    function moveResize(event) {
+        const drag = dragRef.current;
+        if (drag?.pointer === event.pointerId)
+            setHeight(drag.height + event.clientY - drag.y);
+    }
+    function endResize(event) {
+        if (dragRef.current?.pointer !== event.pointerId)
+            return;
+        dragRef.current = null;
+        event.currentTarget.removeAttribute("data-resizing");
+        setHeight(heightRef.current, true);
+    }
+    function resetHeight() {
+        if (!canResize || disabled)
+            return;
+        setHeight(height);
+        if (storageKey)
+            writeStorage(storageKey, null);
+    }
+    function resizeWithKeys(event) {
+        const step = event.shiftKey ? 100 : 20;
+        const current = heightRef.current;
+        const next = event.key === "ArrowUp" ? current - step
+            : event.key === "ArrowDown" ? current + step
+                : event.key === "PageUp" ? current - 200
+                    : event.key === "PageDown" ? current + 200
+                        : event.key === "Home" ? minHeight
+                            : event.key === "End" ? maxHeight
+                                : null;
+        if (next === null)
+            return;
+        event.preventDefault();
+        setHeight(next, true);
+        // Shows the height for a moment, as a drag does.
+        const footer = footerRef.current;
+        footer?.setAttribute("data-resizing", "");
+        window.clearTimeout(sizeTimerRef.current);
+        sizeTimerRef.current = window.setTimeout(() => {
+            if (!dragRef.current)
+                footer?.removeAttribute("data-resizing");
+        }, SIZE_MS);
+    }
+    // ---- Full screen ----
+    useLayoutEffect(() => {
+        const box = frameRef.current?.closest(".nx-field__box");
+        if (!fullscreen || !box)
+            return;
+        box.setAttribute("popover", "manual");
+        box.showPopover();
+        // Focus goes inside, so Esc closes it even after a click, which leaves focus where it was.
+        if (!box.contains(document.activeElement))
+            focusInside(box);
+        const root = document.documentElement;
+        const overflow = root.style.overflow;
+        root.style.overflow = "hidden";
+        return () => {
+            root.style.overflow = overflow;
+            if (box.matches(":popover-open"))
+                box.hidePopover();
+            box.removeAttribute("popover");
+        };
+    }, [fullscreen]);
+    function handleFrameKeyDown(event) {
+        // Keys inside a menu or a panel of the bar belong to it.
+        if (!fullscreen || event.defaultPrevented || event.target.closest(".nx-popover"))
+            return;
+        if (event.key === "Escape") {
+            event.preventDefault();
+            setFullscreen(false);
+        }
+        else if (event.key === "Tab") {
+            // Over the whole window, Tab stays inside the editor instead of moving to the page hidden behind it.
+            const stops = [...event.currentTarget.querySelectorAll('button, textarea, [tabindex], [contenteditable="true"]')].filter(element => element.tabIndex >= 0 && !element.disabled && element.getClientRects().length > 0 && !element.closest(".nx-popover"));
+            const edge = event.shiftKey ? stops[0] : stops[stops.length - 1];
+            if (edge && document.activeElement === edge) {
+                event.preventDefault();
+                (event.shiftKey ? stops[stops.length - 1] : stops[0])?.focus();
+            }
+        }
+    }
+    // ---- Keyboard in the toolbar ----
+    /** Arrow keys, Home, and End move between toolbar buttons, which are one tab stop. */
+    function moveTool(event) {
+        if (event.target.closest(".nx-popover"))
+            return;
+        const buttons = [...event.currentTarget.querySelectorAll("button:not(:disabled)")].filter(button => !button.closest(".nx-popover"));
+        const index = buttons.indexOf(document.activeElement);
+        const next = event.key === "ArrowRight" ? index + 1
+            : event.key === "ArrowLeft" ? index - 1
+                : event.key === "Home" ? 0
+                    : event.key === "End" ? buttons.length - 1
+                        : null;
+        if (next === null || index < 0)
+            return;
+        event.preventDefault();
+        const target = buttons[(next + buttons.length) % buttons.length];
+        for (const button of buttons)
+            button.tabIndex = button === target ? 0 : -1;
+        target.focus();
+    }
+    const bodyStyle = { "--nx-editor-height": `${height}px` };
+    const fullscreenButton = canFullscreen ? (_jsx("button", { type: "button", className: "nx-editor__tool", "aria-pressed": fullscreen, "aria-label": "Full screen", title: fullscreen ? "Exit full screen (Esc)" : "Full screen", disabled: disabled, onMouseDown: event => event.preventDefault(), onClick: () => setFullscreen(!fullscreen), children: _jsx(InlineIcon, { icon: fullscreen ? iconArrowsMinimize : iconArrowsMaximize }) })) : null;
+    /** The status bar: `hint` on the left, the height handle in the middle, `count` on the right. */
+    function footer(hint, count) {
+        return (_jsxs("div", { ref: footerRef, className: "nx-editor__footer", "data-resizable": canResize || undefined, title: canResize ? "Drag to change the height. Double-click to reset it." : undefined, onPointerDown: startResize, onPointerMove: moveResize, onPointerUp: endResize, onPointerCancel: endResize, onDoubleClick: resetHeight, children: [_jsx("span", { className: "nx-editor__hint", children: hint }), canResize && (_jsxs("div", { ref: handleRef, role: "separator", "aria-orientation": "horizontal", "aria-label": "Editor height", "aria-valuemin": minHeight, "aria-valuemax": Math.max(minHeight, maxHeight), "aria-valuenow": height, "aria-valuetext": `${height} pixels`, tabIndex: disabled ? -1 : 0, className: "nx-editor__handle", onKeyDown: resizeWithKeys, children: [_jsx("span", { className: "nx-editor__grip", "aria-hidden": "true" }), _jsx("span", { className: "nx-editor__size", "aria-hidden": "true", children: `${height} px` })] })), count] }));
+    }
+    return {
+        fullscreen,
+        setFullscreen,
+        frameRef,
+        bodyRef,
+        bodyStyle,
+        onFrameKeyDown: handleFrameKeyDown,
+        moveTool,
+        fullscreenButton,
+        footer,
+    };
+}
+/** Word and character counts for the status bar. Editors update them straight in the DOM with `writeEditorCount`. */
+export function EditorCount({ ref, text, maxLength }) {
+    return (_jsxs("span", { ref: ref, className: "nx-editor__count", children: [_jsx("span", { className: "nx-editor__words", children: countWords(text) }), " ", _jsx("span", { children: countCharacters(text, maxLength) })] }));
+}
+export function writeEditorCount(element, text, maxLength) {
+    const [words, characters] = element?.children ?? [];
+    if (words)
+        words.textContent = countWords(text);
+    if (characters)
+        characters.textContent = countCharacters(text, maxLength);
+}
+function countWords(text) {
+    const words = text.match(WORDS)?.length ?? 0;
+    return `${words.toLocaleString("en-US")} ${words === 1 ? "word" : "words"},`;
+}
+function countCharacters(text, maxLength) {
+    const limit = maxLength ? `/${maxLength.toLocaleString("en-US")}` : "";
+    return `${text.length.toLocaleString("en-US")}${limit} ${text.length === 1 && !limit ? "character" : "characters"}`;
+}
+export function readStorage(key) {
+    try {
+        return localStorage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+export function writeStorage(key, value) {
+    try {
+        if (value === null)
+            localStorage.removeItem(key);
+        else
+            localStorage.setItem(key, value);
+    }
+    catch {
+        // Storage can be blocked; the value then lasts until the page reloads.
+    }
+}

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

@@ -0,0 +1,53 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { InputDesign } from "../../Interfaces/InputInterfaces.ts";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+export interface FieldProps {
+    /** Id of the control inside, so the label points at it. */
+    controlId: string;
+    label?: ReactNode;
+    /** Id of the label, for a control that is not an input and names itself with `aria-labelledby`. */
+    labelId?: string;
+    /** Adds a required mark after the label. The control itself carries `aria-required`. */
+    required?: boolean;
+    /** Default `standard`. */
+    design?: InputDesign;
+    /** Default `md`. */
+    size?: Size;
+    /** Help text under the box. An error takes its place. */
+    hint?: ReactNode;
+    /** Error message. Marks the field invalid and replaces the hint. */
+    error?: ReactNode;
+    /** Id of the hint or error line, for the control's `aria-describedby`. */
+    messageId?: string;
+    /** Decorative icon at the start of the box. */
+    icon?: ReactNode;
+    /** Decorative icon at the end of the box. */
+    iconEnd?: ReactNode;
+    /** Text before the control, such as a currency ("Rs") or "https://". Its id is `<controlId>-prefix`, for `aria-describedby`. */
+    prefix?: ReactNode;
+    /** Text after the control, such as a unit ("kg", "%") or a domain. Its id is `<controlId>-suffix`. */
+    suffix?: ReactNode;
+    /** Buttons inside the box before the control, such as a minus button. */
+    actionsStart?: ReactNode;
+    /** Buttons inside the box after the control, such as clear or show password. */
+    actions?: ReactNode;
+    /** Right side of the line under the box, such as a character count. */
+    aside?: ReactNode;
+    disabled?: boolean;
+    readOnly?: boolean;
+    /** Keeps an `outlined` or `inbox` label raised, for a control that shows a placeholder. */
+    raiseLabel?: boolean;
+    /** For controls taller than one line, such as a text area. */
+    multiline?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    /** The control: an input, a text area, or a custom element with the `nx-field__control` class. */
+    children: ReactNode;
+}
+/**
+ * The frame around every input: label, box, icons, and the hint or error line. It has no state, so it renders
+ * anywhere; inputs such as `TextBox` build on it, and so can custom controls.
+ */
+export declare function Field({ controlId, label, labelId, required, design, size, hint, error, messageId, icon, iconEnd, prefix, suffix, actionsStart, actions, aside, disabled, readOnly, raiseLabel, multiline, className, style, children, }: FieldProps): import("react").JSX.Element;
+/** Whether a node renders something: not `undefined`, `null`, `false`, or "". */
+export declare const hasContent: (node: ReactNode) => boolean;

package/dist/Components/Inputs/Field.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { InlineIcon, iconAlertCircle } from "nexus-icons";
+import { cx } from "../../Helpers/ClassHelpers.js";
+/**
+ * The frame around every input: label, box, icons, and the hint or error line. It has no state, so it renders
+ * anywhere; inputs such as `TextBox` build on it, and so can custom controls.
+ */
+export function Field({ controlId, label, labelId, required = false, design = "standard", size = "md", hint, error, messageId, icon, iconEnd, prefix, suffix, actionsStart, actions, aside, disabled = false, readOnly = false, raiseLabel = false, multiline = false, className, style, children, }) {
+    const hasLabel = hasContent(label);
+    const hasError = hasContent(error);
+    const message = hasError ? error : hint;
+    const labelElement = hasLabel && (_jsxs("label", { id: labelId, className: "nx-field__label", htmlFor: controlId, children: [label, required && (_jsx("span", { className: "nx-field__required", "aria-hidden": "true", children: "*" }))] }));
+    return (_jsxs("div", { className: cx("nx-field", `nx-field--${design}`, `nx-field--${size}`, multiline && "nx-field--multiline", className), "data-invalid": hasError || undefined, "data-disabled": disabled || undefined, "data-readonly": readOnly || undefined, "data-raised": raiseLabel || undefined, style: style, children: [design === "standard" && labelElement, _jsxs("div", { className: "nx-field__box", children: [actionsStart && _jsx("span", { className: "nx-field__actions nx-field__actions--start", children: actionsStart }), icon && (_jsx("span", { className: "nx-field__icon", "aria-hidden": "true", children: icon })), hasContent(prefix) && (_jsx("span", { id: `${controlId}-prefix`, className: "nx-field__affix", children: prefix })), children, design !== "standard" && labelElement, hasContent(suffix) && (_jsx("span", { id: `${controlId}-suffix`, className: "nx-field__affix nx-field__affix--end", children: suffix })), actions && _jsx("span", { className: "nx-field__actions", children: actions }), iconEnd && (_jsx("span", { className: "nx-field__icon nx-field__icon--end", "aria-hidden": "true", children: iconEnd }))] }), (message || aside) && (_jsxs("div", { className: "nx-field__footer", children: [message && (_jsxs("p", { id: messageId, className: cx("nx-field__message", hasError && "nx-field__message--error"), children: [hasError && _jsx(InlineIcon, { icon: iconAlertCircle }), _jsx("span", { children: message })] })), aside && _jsx("span", { className: "nx-field__aside", children: aside })] }))] }));
+}
+/** Whether a node renders something: not `undefined`, `null`, `false`, or "". */
+export const hasContent = (node) => node !== undefined && node !== null && node !== false && node !== "";

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

@@ -0,0 +1,20 @@
+import type { GroupFormProps, RowValue } from "../../Interfaces/FormInterfaces.ts";
+/**
+ * The rows of a `TabularForm` as sections: each row's inputs with their own labels, on a 12-column grid (`span` in
+ * each input's params). The same params, value, rules, and form behavior as `TabularForm`; only the layout differs. It
+ * suits rows with more or wider inputs than a table row holds, such as addresses, guardians, or work history, when there
+ * are a few of them. For hundreds of rows, use `TabularForm`, which renders only the rows in view.
+ *
+ * A section collapses to one line that lists its first values, and tags the radios it has on ("Primary"). Sections can
+ * move, be copied, and be removed (with Undo). A check that finds problems opens their sections and says how many.
+ *
+ * @example
+ * <GroupForm name="addresses" label="Addresses" itemLabel="Address" max={5} inputs={[
+ *   { type: "dropdown", name: "country", label: "Country", required: true, options: countries, span: 6 },
+ *   { type: "text", name: "city", label: "City", required: true, span: 6 },
+ *   { type: "text", name: "zipCode", label: "Zip code", span: 4 },
+ *   { type: "dropdown", name: "type", label: "Type", options: ADDRESS_TYPES, span: 4 },
+ *   { type: "radio", name: "isPrimary", label: "Primary address", span: 4, required: true },
+ * ]} />
+ */
+export declare function GroupForm<TRow extends RowValue = RowValue>(props: GroupFormProps<TRow>): import("react").JSX.Element;