nexus-shared 1.1.21 → 2.0.0

package/dist/Components/Documents/SplitButton.js

@@ -0,0 +1,127 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconChevronDown, InlineIcon } from "nexus-icons";
+import { useId, useLayoutEffect, useRef, useState } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { followAnchor, isPopoverOpen, placeUnderAnchor } from "../../Helpers/PopoverHelpers.js";
+import { Button } from "./Button.js";
+import { MenuPanel } from "./Menu.js";
+const STORAGE_PREFIX = "nx-split:";
+function readChoice(key) {
+    if (!key)
+        return null;
+    try {
+        return localStorage.getItem(STORAGE_PREFIX + key);
+    }
+    catch {
+        return null;
+    }
+}
+function saveChoice(key, value) {
+    if (!key)
+        return;
+    try {
+        localStorage.setItem(STORAGE_PREFIX + key, value);
+    }
+    catch {
+        // Storage blocked (private mode, for example): the choice lasts until the page reloads.
+    }
+}
+/**
+ * A main action with a menu of alternatives, like "Create pull request" with "Create draft pull request".
+ * Picking an alternative makes it the main button, and with `storageKey` the browser remembers it for next time.
+ *
+ * @example
+ * <SplitButton storageKey="pull-request" onAction={create} options={[
+ *   { value: "create", label: "Create pull request" },
+ *   { value: "draft", label: "Create draft pull request", description: "Cannot be merged until marked ready" },
+ * ]} />
+ */
+export function SplitButton({ options, onAction, defaultValue, value, onValueChange, storageKey, runOnSelect = false, variant = "primary", size = "md", loading = false, disabled = false, block = false, type = "button", form, name, menuLabel = "More actions", align = "end", className, style, }) {
+    const id = useId();
+    const panelId = `${id}-menu`;
+    const toggleRef = useRef(null);
+    const panelRef = useRef(null);
+    const dismissingRef = useRef(false);
+    const [open, setOpen] = useState(false);
+    const [chosen, setChosen] = useState(defaultValue);
+    const usable = (candidate) => options.find(option => option.value === candidate && !option.disabled);
+    // The remembered choice applies before the first paint, so the button never shows the default and then switches.
+    useLayoutEffect(() => {
+        const saved = usable(readChoice(storageKey));
+        if (saved)
+            setChosen(saved.value);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [storageKey]);
+    const current = usable(value ?? chosen) ?? options.find(option => !option.disabled) ?? options[0];
+    if (!current)
+        return null;
+    function place() {
+        const panel = panelRef.current;
+        const anchor = toggleRef.current?.parentElement;
+        if (panel && anchor)
+            placeUnderAnchor(panel, anchor.getBoundingClientRect(), { align });
+    }
+    function show(focusFirst) {
+        const panel = panelRef.current;
+        if (!panel || typeof panel.showPopover !== "function" || isPopoverOpen(panel))
+            return;
+        panel.showPopover();
+        place();
+        if (focusFirst)
+            panel.querySelector('.nx-menu__item:not([aria-disabled="true"])')?.focus();
+        else
+            panel.focus();
+    }
+    function hide() {
+        if (isPopoverOpen(panelRef.current))
+            panelRef.current?.hidePopover();
+    }
+    useLayoutEffect(() => {
+        if (!open)
+            return;
+        return followAnchor(place);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [open, align]);
+    function onToggle(event) {
+        setOpen(event.newState === "open");
+    }
+    function pick(next) {
+        const option = usable(next);
+        if (!option || !current)
+            return;
+        if (value === undefined)
+            setChosen(next);
+        saveChoice(storageKey, next);
+        if (next !== current.value)
+            onValueChange?.(next, option);
+        if (runOnSelect)
+            onAction(next, option);
+    }
+    const items = options.map(option => ({
+        value: option.value,
+        label: option.label,
+        description: option.description,
+        icon: option.icon,
+        disabled: option.disabled,
+        checked: option.value === current.value,
+    }));
+    const blocked = disabled || loading;
+    return (_jsxs("div", { className: cx("nx-split", `nx-split--${variant}`, `nx-split--${size}`, block && "nx-split--block", className), style: style, children: [_jsx(Button, { type: type, form: form, variant: variant, size: size, icon: current.icon, loading: loading, disabled: disabled, className: "nx-split__main", onClick: () => onAction(current.value, current), children: current.label }), name && _jsx("input", { type: "hidden", name: name, form: form, value: current.value }), _jsx(Button, { ref: toggleRef, variant: variant, size: size, disabled: blocked, className: "nx-split__toggle", "aria-label": menuLabel, title: menuLabel, "aria-haspopup": "menu", "aria-expanded": open, "aria-controls": panelId, icon: _jsx(InlineIcon, { icon: iconChevronDown }), onPointerDown: () => {
+                    dismissingRef.current = isPopoverOpen(panelRef.current);
+                }, onClick: event => {
+                    if (dismissingRef.current) {
+                        dismissingRef.current = false;
+                        return;
+                    }
+                    if (isPopoverOpen(panelRef.current))
+                        hide();
+                    else
+                        show(event.detail === 0);
+                }, onKeyDown: event => {
+                    if (event.key === "ArrowDown") {
+                        event.preventDefault();
+                        show(true);
+                    }
+                } }), _jsx(MenuPanel, { ref: panelRef, id: panelId, kind: "radio", size: size, items: items, onSelect: pick, "aria-label": menuLabel, onToggle: onToggle, className: "nx-split__menu" })] }));
+}

package/dist/Components/Documents/TabButtons.d.ts

@@ -0,0 +1,62 @@
+import { type ReactNode } from "react";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+export interface TabButtonOption<T extends string = string> {
+    value: T;
+    label: ReactNode;
+    /** Shown before the label, e.g. `<InlineIcon icon={iconSun} />`. It takes the primary color while selected. */
+    icon?: ReactNode;
+    /** A second line in muted text. Shown by the `list` design only. */
+    description?: ReactNode;
+    /** A count or short tag at the end of the row, e.g. `3`. Shown by the `list` design only. */
+    badge?: ReactNode;
+    disabled?: boolean;
+    /** Tooltip. With `labels="selected"`, a text label is the default tooltip. */
+    title?: string;
+}
+/** `all`: every option shows its label. `selected`: options show only their icon, and the selected one adds its label. */
+export type TabButtonLabels = "all" | "selected";
+/** `nav`: a horizontal track with a sliding indicator. `list`: a vertical list of rows, for settings pages and side panels. */
+export type TabButtonDesign = "nav" | "list";
+interface TabButtonsBaseProps<T extends string> {
+    options: readonly TabButtonOption<T>[];
+    /** The selected option. A value that matches no option leaves every option unselected. */
+    value: T;
+    onChange: (value: T) => void;
+    /** Default `nav`. `list` stacks the options as full-width rows with a bar at the selected one. */
+    design?: TabButtonDesign;
+    /** Default `md`. */
+    size?: Size;
+    /** `neutral` (default): a raised indicator. `primary`: a solid primary indicator, for a choice that matters. */
+    tone?: "neutral" | "primary";
+    /**
+     * Default `all`. `selected` keeps a toolbar compact: icons only, and the selected option grows to show its label.
+     * Every option needs an icon; hidden labels are still read by screen readers and shown as tooltips. `nav` design only.
+     */
+    labels?: TabButtonLabels;
+    /** Fills the width of its container. With `labels="all"`, options share the width equally. A `list` always fills it. */
+    block?: boolean;
+    /** Radio group name, for forms. Default: a unique id. */
+    name?: string;
+    /**
+     * Id of the form the choice belongs to, as the HTML `form` attribute. An id that matches no form keeps the choice out
+     * of every form, for a switch inside a form that is not one of its values, such as an editor's view.
+     */
+    form?: string;
+    className?: string;
+}
+/** A label is required: pass `aria-label`, or `aria-labelledby` pointing at a visible heading. */
+export type TabButtonsProps<T extends string = string> = TabButtonsBaseProps<T> & ({
+    "aria-label": string;
+    "aria-labelledby"?: never;
+} | {
+    "aria-labelledby": string;
+    "aria-label"?: never;
+});
+/**
+ * Tab buttons: pick one option from a small set, such as Light / Dark / System.
+ * The `nav` design slides an indicator to the selection; the `list` design stacks the options as rows, each with an
+ * icon, a label, a description, and a badge, for settings pages and side panels. Built on native radio buttons, so
+ * arrow keys move the selection and screen readers announce it. To switch between page panels, use tabs with panels instead.
+ */
+export declare function TabButtons<T extends string>({ options, value, onChange, design, size, tone, labels, block, name, form, className, ...labelling }: TabButtonsProps<T>): import("react").JSX.Element;
+export {};

package/dist/Components/Documents/TabButtons.js

@@ -0,0 +1,19 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+/**
+ * Tab buttons: pick one option from a small set, such as Light / Dark / System.
+ * The `nav` design slides an indicator to the selection; the `list` design stacks the options as rows, each with an
+ * icon, a label, a description, and a badge, for settings pages and side panels. Built on native radio buttons, so
+ * arrow keys move the selection and screen readers announce it. To switch between page panels, use tabs with panels instead.
+ */
+export function TabButtons({ options, value, onChange, design = "nav", size = "md", tone = "neutral", labels = "all", block = false, name, form, className, ...labelling }) {
+    const generatedName = useId();
+    const groupName = name ?? generatedName;
+    const index = options.findIndex(option => option.value === value);
+    const style = { "--nx-tabs-count": Math.max(options.length, 1), "--nx-tabs-index": Math.max(index, 0) };
+    const list = design === "list";
+    const labelsSelected = !list && labels === "selected";
+    return (_jsxs("div", { role: "radiogroup", "aria-orientation": list ? "vertical" : undefined, ...labelling, className: cx("nx-tabs", `nx-tabs--${size}`, list && "nx-tabs--list", tone === "primary" && "nx-tabs--primary", labelsSelected && "nx-tabs--labels-selected", block && "nx-tabs--block", className), style: list ? undefined : style, children: [index >= 0 && !list && !labelsSelected && _jsx("span", { className: "nx-tabs__indicator", "aria-hidden": "true" }), options.map(option => (_jsxs("label", { className: "nx-tabs__option", title: option.title ?? (labelsSelected && typeof option.label === "string" ? option.label : undefined), children: [_jsx("input", { type: "radio", className: "nx-visually-hidden", name: groupName, form: form, value: option.value, checked: option.value === value, disabled: option.disabled, onChange: () => onChange(option.value) }), option.icon, _jsxs("span", { className: "nx-tabs__label", children: [_jsx("span", { className: "nx-tabs__text", children: option.label }), list && option.description && _jsx("span", { className: "nx-tabs__description", children: option.description })] }), list && option.badge !== undefined && option.badge !== null && _jsx("span", { className: "nx-tabs__badge", children: option.badge })] }, option.value)))] }));
+}

package/dist/Components/Forms/ApiForm.d.ts

@@ -0,0 +1,21 @@
+import type { ApiFormProps, FormValues } from "../../Interfaces/FormInterfaces.ts";
+/**
+ * A `SubmitForm` that sends its values to an API: an endpoint (`ROOMS.update`, or `{ module, path, method }` in place),
+ * a URL outside the app's modules (`{ url, method }`, as JSON), both sent through the app's `api` without its toasts, or
+ * a function that sends them with a client of the app's own. The answer is read as Nexus API responses (`{ isSuccess, message,
+ * inputName, result }`), ASP.NET Core problem details, or any JSON by its status. On success a toast says so and the
+ * values become the form's own; on failure the server's messages show on the inputs they name, the rest under the form,
+ * and the first input with a message takes focus. `loadValue` loads the record to edit, with placeholders and Retry.
+ *
+ * @example
+ * const ROOMS = apiController(NexusModule.Reservation, "Room", "room");
+ *
+ * <ApiForm
+ *   inputs={ROOM_INPUTS}
+ *   loadValue={signal => api.get<Room>(ROOMS.details, { params: { id }, signal, toast: false }).then(unwrapApiResult)}
+ *   api={ROOMS.update}
+ *   onSuccess={room => table.updateRow(room)}
+ *   onCancel={close}
+ * />
+ */
+export declare function ApiForm<TValues extends FormValues = FormValues>(props: ApiFormProps<TValues>): import("react").JSX.Element;

package/dist/Components/Forms/ApiForm.js

@@ -0,0 +1,99 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconAlertCircle, iconRefresh, InlineIcon } from "nexus-icons";
+import { useEffect, useRef, useState } from "react";
+import { abortError, apiRequestOptions, matchFieldErrors, toApiResult } from "../../Helpers/ApiFormHelpers.js";
+import { apiStatusMessage, errorMessage, isAbortError, readApiResponse } from "../../Helpers/ApiResponses.js";
+import { isApiEndpoint } from "../../Helpers/ApiRoutes.js";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { messages } from "../../Helpers/MessageBuilder.js";
+import { api as browserApi } from "../../Services/BrowserApi.js";
+import { Button } from "../Documents/Button.js";
+import { toast } from "../Layouts/Toaster.js";
+import { useFormStore } from "./Form.js";
+import { SubmitForm } from "./SubmitForm.js";
+/**
+ * A `SubmitForm` that sends its values to an API: an endpoint (`ROOMS.update`, or `{ module, path, method }` in place),
+ * a URL outside the app's modules (`{ url, method }`, as JSON), both sent through the app's `api` without its toasts, or
+ * a function that sends them with a client of the app's own. The answer is read as Nexus API responses (`{ isSuccess, message,
+ * inputName, result }`), ASP.NET Core problem details, or any JSON by its status. On success a toast says so and the
+ * values become the form's own; on failure the server's messages show on the inputs they name, the rest under the form,
+ * and the first input with a message takes focus. `loadValue` loads the record to edit, with placeholders and Retry.
+ *
+ * @example
+ * const ROOMS = apiController(NexusModule.Reservation, "Room", "room");
+ *
+ * <ApiForm
+ *   inputs={ROOM_INPUTS}
+ *   loadValue={signal => api.get<Room>(ROOMS.details, { params: { id }, signal, toast: false }).then(unwrapApiResult)}
+ *   api={ROOMS.update}
+ *   onSuccess={room => table.updateRow(room)}
+ *   onCancel={close}
+ * />
+ */
+export function ApiForm(props) {
+    const { api: _api, transform: _transform, readResponse: _readResponse, onSuccess: _onSuccess, onError: _onError, successMessage: _successMessage, loadValue, ...rest } = props;
+    const store = useFormStore(props.form);
+    const latest = useRef(props);
+    latest.current = props;
+    const answerRef = useRef(null);
+    const [load, setLoad] = useState(() => (loadValue ? { state: "loading" } : { state: "done" }));
+    const [attempt, setAttempt] = useState(0);
+    useEffect(() => {
+        const loader = latest.current.loadValue;
+        if (!loader)
+            return;
+        const controller = new AbortController();
+        setLoad(current => (current.state === "loading" ? current : { state: "loading" }));
+        loader(controller.signal).then(values => {
+            if (controller.signal.aborted)
+                return;
+            store.load(values ?? {});
+            setLoad({ state: "done" });
+        }, error => {
+            if (controller.signal.aborted || isAbortError(error))
+                return;
+            setLoad({ state: "failed", message: errorMessage(error, "The server did not answer.") });
+        });
+        return () => controller.abort();
+    }, [store, attempt]);
+    async function send(values, context) {
+        const { api, transform, readResponse = readApiResponse } = latest.current;
+        answerRef.current = null;
+        const body = transform ? await transform(values, context) : values;
+        let answer;
+        if (typeof api === "function")
+            answer = await toApiResult(await api(body, context), readResponse);
+        else {
+            // The form shows its own messages, so the call shows no toasts.
+            const options = isApiEndpoint(api) ? { body, signal: context.signal, read: readResponse } : apiRequestOptions(api, body, { signal: context.signal, read: readResponse });
+            answer = await browserApi.send(isApiEndpoint(api) ? api : api.url, { ...options, toast: false });
+            if (answer.aborted)
+                throw abortError();
+        }
+        if (answer.ok) {
+            answerRef.current = answer;
+            return { ok: true };
+        }
+        latest.current.onError?.(answer, values);
+        const names = store.inputs.filter(params => !params.hidden).map(params => params.name);
+        const { fields, others } = matchFieldErrors(answer.errors, names);
+        // A message the server put on inputs (Nexus `inputName`) shows there, not twice.
+        const onInputs = Boolean(answer.message) && Object.values(fields).includes(answer.message);
+        const message = [onInputs ? undefined : answer.message, ...others].filter(Boolean).join(" ");
+        return { ok: false, errors: fields, message: message || (Object.keys(fields).length ? null : apiStatusMessage(answer.status)) };
+    }
+    function saved(values) {
+        const answer = answerRef.current;
+        const { successMessage, onSuccess } = latest.current;
+        const { api } = latest.current;
+        const endpoint = isApiEndpoint(api) ? api : undefined;
+        if (successMessage !== false)
+            toast.success(successMessage ?? answer?.message ?? messages.success(endpoint?.action ?? "save", endpoint?.subject));
+        onSuccess?.(answer?.result, values, store);
+    }
+    if (load.state === "failed") {
+        return (_jsxs("div", { className: cx("nx-form-load-failed", rest.className), style: rest.style, role: "alert", children: [_jsx(InlineIcon, { icon: iconAlertCircle }), _jsxs("p", { children: [_jsx("strong", { children: "Could not load the values." }), " ", load.message] }), _jsxs("div", { className: "nx-form-load-failed__actions", children: [rest.onCancel && (_jsx(Button, { size: "sm", onClick: rest.onCancel, children: rest.cancelLabel ?? "Cancel" })), _jsx(Button, { size: "sm", icon: _jsx(InlineIcon, { icon: iconRefresh }), onClick: () => setAttempt(count => count + 1), children: "Retry" })] })] }));
+    }
+    return _jsx(SubmitForm, { ...rest, form: store, loading: Boolean(rest.loading) || load.state === "loading", onSubmit: send, onSaved: saved });
+}

package/dist/Components/Forms/Crud.d.ts

@@ -0,0 +1,17 @@
+import type { CrudProps } from "../../Interfaces/CrudInterfaces.ts";
+import type { FormValues } from "../../Interfaces/FormInterfaces.ts";
+/**
+ * A CRUD page in one component: a data table of a controller's records with its lists, Add and Edit popups, details,
+ * and actions on one record or many, each shown only when its endpoint exists and the user may call it.
+ *
+ * @example
+ * const GUESTS = MODULES.controller(NexusModule.Reservation, "Guest", "guest");
+ *
+ * <Crud<Guest>
+ *   api={GUESTS}
+ *   columns={[{ key: "fullName", label: "Name" }, { key: "email", label: "Email" }, { key: "visits", label: "Visits", format: "number" }]}
+ *   inputs={GUEST_INPUTS}
+ *   paging="server"
+ * />
+ */
+export declare function Crud<TRow extends FormValues = FormValues>(props: CrudProps<TRow>): import("react").JSX.Element;