nexus-shared 1.1.21 → 3.0.0

package/dist/Components/Layouts/Toaster.d.ts

@@ -0,0 +1,76 @@
+import { type ReactNode } from "react";
+export type ToastTone = "neutral" | "info" | "success" | "warning" | "danger";
+export type ToastPosition = "top-right" | "top-center" | "top-left" | "bottom-right" | "bottom-center" | "bottom-left";
+export interface ToastAction {
+    label: ReactNode;
+    onClick: () => void;
+}
+export interface ToastOptions {
+    /** Pass the id of a toast that is showing to update it in place. */
+    id?: string;
+    /** Text under the title. */
+    message?: ReactNode;
+    /** Default `neutral`. */
+    tone?: ToastTone;
+    /** Replaces the tone's icon; `null` shows none. */
+    icon?: ReactNode | null;
+    /** Milliseconds until the toast closes itself. Default 5000; 0 keeps it until it is closed. Pauses while hovered. */
+    duration?: number;
+    /** A button at the end, such as Undo. Clicking it closes the toast. */
+    action?: ToastAction;
+    /** Shows the close button. Default true. */
+    closable?: boolean;
+    /** Where this toast stacks. Default: the Toaster's position. */
+    position?: ToastPosition;
+    /** After the toast has left. */
+    onClose?: () => void;
+}
+export interface ToastData extends ToastOptions {
+    id: string;
+    title: ReactNode;
+    tone: ToastTone;
+    duration: number;
+    /** The toast is playing its exit animation. */
+    closing: boolean;
+    /** Grows on every update, so the timer starts again. */
+    version: number;
+}
+/** Shows a toast, or updates the one with the same `id`. Returns the id. */
+declare function show(title: ReactNode, options?: ToastOptions | string): string;
+/** Closes one toast, or every toast without an id. */
+export declare function dismissToast(id?: string): void;
+type ToastText<T> = ReactNode | ((value: T) => ReactNode);
+declare function loading(title: ReactNode, options?: ToastOptions | string): string;
+export interface ToastPromiseTexts<T> {
+    loading: ReactNode;
+    success: ToastText<T>;
+    error: ToastText<unknown>;
+}
+/** A loading toast that turns into a success or an error toast when the promise settles. Returns the promise. */
+declare function promise<T>(work: Promise<T>, texts: ToastPromiseTexts<T>, options?: ToastOptions): Promise<T>;
+/**
+ * Shows a toast: `toast("Saved")`, `toast.success("Booking confirmed", "Room 204, 3 nights")`,
+ * `toast.error("Could not save", { action: { label: "Retry", onClick: save } })`, `toast.promise(save(), { ... })`.
+ * Needs one `<Toaster />` on the page.
+ */
+export declare const toast: typeof show & {
+    info: (title: ReactNode, options?: ToastOptions | string) => string;
+    success: (title: ReactNode, options?: ToastOptions | string) => string;
+    warning: (title: ReactNode, options?: ToastOptions | string) => string;
+    error: (title: ReactNode, options?: ToastOptions | string) => string;
+    loading: typeof loading;
+    promise: typeof promise;
+    dismiss: typeof dismissToast;
+};
+export interface ToasterProps {
+    /** Corner or edge where toasts stack. Default `top-right`. */
+    position?: ToastPosition;
+    /** Most toasts shown at once per position; the oldest close to make room. Default 5. */
+    max?: number;
+}
+/**
+ * Shows the toasts. Put one in the root layout. Toasts stack from the chosen edge, newest nearest to it,
+ * and the rest of the page stays clickable around them.
+ */
+export declare function Toaster({ position, max }: ToasterProps): import("react").JSX.Element;
+export {};

package/dist/Components/Layouts/Toaster.js

@@ -0,0 +1,172 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconAlertCircle, iconAlertTriangle, iconCircleCheck, iconInfoCircle, iconLoader2, iconX, InlineIcon } from "nexus-icons";
+import { useEffect, useLayoutEffect, useRef, useSyncExternalStore } from "react";
+import { afterAnimation } from "../../Helpers/AnimationHelpers.js";
+import { cx } from "../../Helpers/ClassHelpers.js";
+const DEFAULT_DURATION = 5000;
+const GAP = 8;
+const EMPTY = [];
+let toasts = [];
+let counter = 0;
+let hosts = 0;
+let warned = false;
+const listeners = new Set();
+function emit() {
+    for (const listener of listeners)
+        listener();
+}
+function subscribe(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+const getSnapshot = () => toasts;
+const getServerSnapshot = () => EMPTY;
+function normalize(options) {
+    return typeof options === "string" ? { message: options } : (options ?? {});
+}
+/** Shows a toast, or updates the one with the same `id`. Returns the id. */
+function show(title, options) {
+    const next = normalize(options);
+    const id = next.id ?? `nx-toast-${++counter}`;
+    const existing = toasts.find(item => item.id === id);
+    const data = {
+        ...existing,
+        ...next,
+        id,
+        title,
+        tone: next.tone ?? existing?.tone ?? "neutral",
+        duration: next.duration ?? existing?.duration ?? DEFAULT_DURATION,
+        closing: false,
+        version: (existing?.version ?? 0) + 1,
+    };
+    toasts = existing ? toasts.map(item => (item.id === id ? data : item)) : [data, ...toasts];
+    if (hosts === 0 && !warned && typeof window !== "undefined") {
+        warned = true;
+        console.warn("toast(): no <Toaster /> is mounted, so toasts cannot show. Add one to the root layout.");
+    }
+    emit();
+    return id;
+}
+/** Closes one toast, or every toast without an id. */
+export function dismissToast(id) {
+    let changed = false;
+    toasts = toasts.map(item => {
+        if ((id === undefined || item.id === id) && !item.closing) {
+            changed = true;
+            return { ...item, closing: true };
+        }
+        return item;
+    });
+    if (changed)
+        emit();
+}
+function removeToast(id) {
+    const item = toasts.find(candidate => candidate.id === id);
+    if (!item)
+        return;
+    toasts = toasts.filter(candidate => candidate.id !== id);
+    emit();
+    item.onClose?.();
+}
+const withTone = (options, tone) => ({ ...normalize(options), tone });
+const resolveText = (text, value) => (typeof text === "function" ? text(value) : text);
+function loading(title, options) {
+    return show(title, { ...normalize(options), tone: "neutral", icon: _jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin" }), duration: 0, closable: false });
+}
+/** A loading toast that turns into a success or an error toast when the promise settles. Returns the promise. */
+function promise(work, texts, options) {
+    const id = loading(texts.loading, options);
+    const settle = (tone, title) => show(title, { ...options, id, tone, icon: undefined, duration: options?.duration ?? DEFAULT_DURATION, closable: options?.closable ?? true });
+    work.then(value => settle("success", resolveText(texts.success, value)), error => settle("danger", resolveText(texts.error, error)));
+    return work;
+}
+/**
+ * Shows a toast: `toast("Saved")`, `toast.success("Booking confirmed", "Room 204, 3 nights")`,
+ * `toast.error("Could not save", { action: { label: "Retry", onClick: save } })`, `toast.promise(save(), { ... })`.
+ * Needs one `<Toaster />` on the page.
+ */
+export const toast = Object.assign(show, {
+    info: (title, options) => show(title, withTone(options, "info")),
+    success: (title, options) => show(title, withTone(options, "success")),
+    warning: (title, options) => show(title, withTone(options, "warning")),
+    error: (title, options) => show(title, withTone(options, "danger")),
+    loading,
+    promise,
+    dismiss: dismissToast,
+});
+const TONE_ICONS = {
+    neutral: null,
+    info: iconInfoCircle,
+    success: iconCircleCheck,
+    warning: iconAlertTriangle,
+    danger: iconAlertCircle,
+};
+/**
+ * Shows the toasts. Put one in the root layout. Toasts stack from the chosen edge, newest nearest to it,
+ * and the rest of the page stays clickable around them.
+ */
+export function Toaster({ position = "top-right", max = 5 }) {
+    const items = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+    const rootRef = useRef(null);
+    useEffect(() => {
+        hosts++;
+        return () => {
+            hosts--;
+        };
+    }, []);
+    // Over the limit, the oldest toasts of that position close.
+    useEffect(() => {
+        const perPosition = new Map();
+        for (const item of items) {
+            if (item.closing)
+                continue;
+            const key = item.position ?? position;
+            const count = (perPosition.get(key) ?? 0) + 1;
+            perPosition.set(key, count);
+            if (count > max)
+                dismissToast(item.id);
+        }
+    }, [items, max, position]);
+    // Every toast is shown as a popover and stacked from its edge; a closing toast keeps no room, so the others slide up.
+    useLayoutEffect(() => {
+        const root = rootRef.current;
+        if (!root)
+            return;
+        const offsets = new Map();
+        for (const node of Array.from(root.querySelectorAll(".nx-toast"))) {
+            if (typeof node.showPopover === "function" && !node.matches(":popover-open"))
+                node.showPopover();
+            const key = node.dataset.position ?? position;
+            const offset = offsets.get(key) ?? 0;
+            node.style.setProperty("--nx-toast-offset", `${offset}px`);
+            if (!node.classList.contains("nx-toast--closing"))
+                offsets.set(key, offset + node.offsetHeight + GAP);
+        }
+    });
+    return (_jsx("div", { ref: rootRef, className: "nx-toaster", children: items.map(item => (_jsx(ToastView, { item: item, position: item.position ?? position }, item.id))) }));
+}
+function ToastView({ item, position }) {
+    const { id, title, message, tone, icon, duration, action, closable = true, closing, version } = item;
+    const nodeRef = useRef(null);
+    // The toast leaves once its exit animation has played, or in the same frame with reduced motion.
+    useLayoutEffect(() => {
+        const node = nodeRef.current;
+        if (!closing || !node)
+            return;
+        return afterAnimation(node, "nx-toast-out", () => removeToast(id));
+    }, [closing, id]);
+    const toneIcon = TONE_ICONS[tone];
+    const shownIcon = icon === undefined ? (toneIcon && _jsx(InlineIcon, { icon: toneIcon })) : icon;
+    function onProgressEnd(event) {
+        event.stopPropagation();
+        if (event.animationName === "nx-toast-progress")
+            dismissToast(id);
+    }
+    return (_jsxs("div", { ref: nodeRef, popover: "manual", role: tone === "danger" || tone === "warning" ? "alert" : "status", "data-position": position, className: cx("nx-toast", `nx-toast--${tone}`, `nx-toast--${position}`, closing && "nx-toast--closing"), children: [shownIcon && _jsx("span", { className: "nx-toast__icon", children: shownIcon }), _jsxs("div", { className: "nx-toast__body", children: [_jsx("div", { className: "nx-toast__title", children: title }), message && _jsx("div", { className: "nx-toast__message", children: message })] }), action && (_jsx("button", { type: "button", className: "nx-toast__action", onClick: () => {
+                    action.onClick();
+                    dismissToast(id);
+                }, children: action.label })), closable && (_jsx("button", { type: "button", className: "nx-toast__close", "aria-label": "Close", title: "Close", onClick: () => dismissToast(id), children: _jsx(InlineIcon, { icon: iconX }) })), duration > 0 && !closing && _jsx("span", { className: "nx-toast__progress", style: { animationDuration: `${duration}ms` }, onAnimationEnd: onProgressEnd }, version)] }));
+}

package/dist/Components/Viewers/DataTable.d.ts

@@ -0,0 +1,25 @@
+import { TableStore } from "../../Helpers/TableStore.ts";
+import type { DataTableProps, TableRow } from "../../Interfaces/TableInterfaces.ts";
+/**
+ * The store of a table, for the page: pass it as `table`, then call `table.reload()`, `table.upsert(row)`, or
+ * `table.getSelected()` from anywhere.
+ */
+export declare function useTable<TRow extends TableRow = TableRow>(): TableStore<TRow>;
+/**
+ * A data table. Columns are params (`{ key, label, format, ... }`); rows are given (`rows`), loaded once (`load`), or
+ * loaded a page at a time (`load` with `paging="server"`, which sends the search, the sort, and the page). The user
+ * arranges the columns: the Columns menu shows and hides them, a heading drags into another place, its edge changes its
+ * width, and its menu pins it left or right; with a `stateKey` the table remembers all of it on the device.
+ *
+ * @example
+ * <DataTable
+ *   aria-label="Guests"
+ *   columns={[{ key: "name", label: "Name" }, { key: "visits", label: "Visits", format: "number" }]}
+ *   load={(query, signal) => fetchGuests(query, signal)}
+ *   paging="server"
+ *   selectable
+ *   massActions={[{ id: "email", label: "Email", onSelect: rows => email(rows) }]}
+ *   rowActions={row => [{ id: "edit", label: "Edit", icon: <InlineIcon icon={iconPencil} />, inline: true, onSelect: edit }]}
+ * />
+ */
+export declare function DataTable<TRow extends TableRow = TableRow>(props: DataTableProps<TRow>): import("react").JSX.Element;