nexus-shared 3.2.0 → 4.1.0

package/dist/Components/Dashboards/DashboardWidgets.d.ts

@@ -0,0 +1,155 @@
+import { type ReactNode } from "react";
+import { type CalendarMark } from "../../Helpers/DashboardHelpers.ts";
+import type { CalendarType } from "../../Interfaces/DateInterfaces.ts";
+import type { Tone } from "../../Interfaces/TypeInterfaces.ts";
+export interface StatWidgetItem {
+    /** What the figure counts: "Unread". */
+    label: ReactNode;
+    /** The figure, written as the page wants it: 12, "NPR 4.2M", "92%". */
+    value: ReactNode;
+    /** A line under it: what it is compared with, or made of. */
+    note?: ReactNode;
+    /** The page that lists what it counts: the whole figure is the link. */
+    href?: string;
+    /** A dot of this tone before the label (a second cue beside the words, never the only one). */
+    tone?: Tone;
+}
+export interface StatWidgetProps {
+    items: readonly StatWidgetItem[];
+    className?: string;
+}
+/**
+ * One or several figures in a widget, side by side as they fit and wrapping as the widget narrows; each may link to
+ * the list behind it. Plain on the widget's panel: no card in the card.
+ *
+ * @example <StatWidget items={[{ label: "Unread", value: 4, href: "/admin/message?list=2" }, { label: "Sent", value: 31 }]} />
+ */
+export declare function StatWidget({ items, className }: StatWidgetProps): import("react").JSX.Element;
+export interface ListWidgetRow {
+    id: string | number;
+    /** The row's words: a subject, a person, a request. */
+    title: ReactNode;
+    /** A second line, muted: who, what, from where. */
+    secondary?: ReactNode;
+    /** At the end: a time, a date, already written. */
+    time?: ReactNode;
+    /** A tag at the end: a type, a state. */
+    chip?: {
+        label: ReactNode;
+        tone?: Tone;
+    };
+    /** A person's picture (initials without one). */
+    avatar?: {
+        name: string;
+        src?: string | null;
+    };
+    /** An icon in the picture's place. */
+    icon?: ReactNode;
+    /** The row opens this page. */
+    href?: string;
+    /** Strong title: not read yet. */
+    unread?: boolean;
+}
+export interface ListWidgetProps {
+    rows: readonly ListWidgetRow[];
+    /** How many there are in all, when `rows` are the first of them (a count the server gave). Default: the rows'. */
+    total?: number;
+    /**
+     * A line under the rows linking to the whole list, shown while some are not: its label is "N more" by default, or
+     * the page's words (a function is given N).
+     */
+    more?: {
+        href: string;
+        label?: ReactNode | ((hidden: number) => ReactNode);
+    };
+    /** Shows only the rows that fit whole in the widget's height, never a half row. Default true. */
+    fit?: boolean;
+    className?: string;
+}
+/**
+ * A few rows in a widget: a picture or an icon, the words and a muted second line, a time and a tag at the end. A row
+ * with `href` is a link. Rows are one height, and only those that fit whole show (`fit`), so the widget's size says how
+ * many: the rest are counted on the more line.
+ *
+ * @example <ListWidget rows={mails.map(m => ({ id: m.id, title: m.subject, secondary: m.from, time: m.when, avatar: { name: m.from } }))} />
+ */
+export declare function ListWidget({ rows, total, more, fit, className }: ListWidgetProps): import("react").JSX.Element;
+/** A kind of calendar mark: its name in the legend and its tone. */
+export interface CalendarMarkKind {
+    label: string;
+    tone: Tone;
+}
+/** The kinds a calendar widget knows without being told: holidays, leave, events. */
+export declare const CALENDAR_MARK_KINDS: Readonly<Record<string, CalendarMarkKind>>;
+export interface CalendarWidgetProps {
+    marks: readonly CalendarMark[];
+    /** The kinds of mark and their tones, added to (or replacing) holiday, leave and event. */
+    kinds?: Readonly<Record<string, CalendarMarkKind>>;
+    /** The calendar shown: `ad` or `bs`. Default: the person's setting. */
+    calendar?: CalendarType;
+    /** Today, an ISO date. Default: today where the browser is. */
+    today?: string;
+    /** After the month shown changes, with its first day: read that month's marks. */
+    onMonthChange?: (firstDay: string) => void;
+    /** First column of the week: 0 Sunday (default), 1 Monday. */
+    weekStart?: number;
+    className?: string;
+}
+/**
+ * A month in a widget with typed marks on its days - holidays, leave, events, or the app's own kinds - a dot of each
+ * kind's tone under the day's number, today marked, a legend counting the month's marks by kind, and the picked day's
+ * marks listed beside the month (under it when the widget is narrow). In the English or the Nepali calendar.
+ *
+ * @example <CalendarWidget marks={[{ date: "2026-11-12", kind: "holiday", label: "Tihar" }, { date: "2026-11-16", until: "2026-11-18", kind: "leave", label: "Sita Rai" }]} />
+ */
+export declare function CalendarWidget({ marks, kinds, calendar, today, onMonthChange, weekStart, className }: CalendarWidgetProps): import("react").JSX.Element;
+/** A release note: `released` (out now) or `coming-soon` (announced). */
+export interface NewsItem {
+    id: string | number;
+    title: ReactNode;
+    /** "4.2.0". */
+    version?: string;
+    /** The release day, an ISO date. */
+    date?: string;
+    kind?: "released" | "coming-soon";
+    /** Which application: "Nexus Web". */
+    application?: ReactNode;
+    /** The notes, in Markdown: the first lines show. */
+    notes?: string;
+    /** The whole note's page: "Read more". */
+    href?: string;
+}
+export interface NewsWidgetProps {
+    items: readonly NewsItem[];
+    /** "Read more" without `href`: open the note in a popup of the page's own. */
+    onReadMore?: (item: NewsItem) => void;
+    /** Lines of notes shown. Default 3. */
+    excerptLines?: number;
+    className?: string;
+}
+/**
+ * Release notes in a widget, newest first as given: the title, the version and the kind (Released, Coming soon) as
+ * tags, the day, the first lines of the Markdown notes and "Read more".
+ *
+ * @example <NewsWidget items={releases} onReadMore={item => openNote(item)} />
+ */
+export declare function NewsWidget({ items, onReadMore, excerptLines, className }: NewsWidgetProps): import("react").JSX.Element;
+export interface VersionWidgetProps {
+    /** The application: "Nexus Web". */
+    name: ReactNode;
+    /** "4.2.0". */
+    version: string;
+    /** When it was built, an ISO date or date and time. */
+    build?: string;
+    /** A tag beside the version: "Preview", "Stable". */
+    channel?: ReactNode;
+    /** Its release notes. */
+    href?: string;
+    className?: string;
+}
+/**
+ * The application's name, version and build day in a widget: what a person reads out when they ask for help.
+ *
+ * @example <VersionWidget name="Nexus Web" version={BUILD.version} build={BUILD.time} href="/admin/tenant/releases" />
+ */
+export declare function VersionWidget({ name, version, build, channel, href, className }: VersionWidgetProps): import("react").JSX.Element;

package/dist/Components/Dashboards/DashboardWidgets.js

@@ -0,0 +1,159 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { iconArrowRight, InlineIcon } from "nexus-icons";
+import { useLayoutEffect, useMemo, useRef, useState } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { marksByDay } from "../../Helpers/DashboardHelpers.js";
+import { formatDate, todayIsoDate, toLatinDigits, usesDevanagari, toDevanagariDigits } from "../../Helpers/DateHelpers.js";
+import { useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { Calendar } from "../Inputs/Calendar.js";
+import { MarkdownView } from "../Viewers/MarkdownView.js";
+import { Avatar } from "../Viewers/Avatar.js";
+import { WidgetLink } from "./WidgetFrame.js";
+/**
+ * One or several figures in a widget, side by side as they fit and wrapping as the widget narrows; each may link to
+ * the list behind it. Plain on the widget's panel: no card in the card.
+ *
+ * @example <StatWidget items={[{ label: "Unread", value: 4, href: "/admin/message?list=2" }, { label: "Sent", value: 31 }]} />
+ */
+export function StatWidget({ items, className }) {
+    return (_jsx("ul", { className: cx("nx-wstat", className), children: items.map((item, index) => {
+            const body = (_jsxs(_Fragment, { children: [_jsxs("span", { className: "nx-wstat__label", children: [item.tone && _jsx("span", { className: "nx-wstat__dot", "data-tone": item.tone, "aria-hidden": "true" }), item.label] }), _jsx("span", { className: "nx-wstat__value", children: item.value }), item.note && _jsx("span", { className: "nx-wstat__note", children: item.note })] }));
+            return (_jsx("li", { className: "nx-wstat__item", children: item.href ? (_jsx(WidgetLink, { className: "nx-wstat__figure nx-wstat__figure--link", href: item.href, children: body })) : (_jsx("span", { className: "nx-wstat__figure", children: body })) }, index));
+        }) }));
+}
+// The more line's height before it is drawn: a line of small text and its padding.
+const MORE_LINE = 24;
+/**
+ * A few rows in a widget: a picture or an icon, the words and a muted second line, a time and a tag at the end. A row
+ * with `href` is a link. Rows are one height, and only those that fit whole show (`fit`), so the widget's size says how
+ * many: the rest are counted on the more line.
+ *
+ * @example <ListWidget rows={mails.map(m => ({ id: m.id, title: m.subject, secondary: m.from, time: m.when, avatar: { name: m.from } }))} />
+ */
+export function ListWidget({ rows, total = rows.length, more, fit = true, className }) {
+    const rootRef = useRef(null);
+    const [shown, setShown] = useState(rows.length);
+    // As many rows as fit whole in what holds the list (a widget's body), less the more line when some stay out.
+    useLayoutEffect(() => {
+        const root = rootRef.current;
+        const holder = root?.parentElement;
+        if (!fit || !root || !holder) {
+            setShown(rows.length);
+            return;
+        }
+        const measure = () => {
+            const first = root.querySelector(".nx-wlist__row");
+            if (!first)
+                return;
+            const style = getComputedStyle(holder);
+            const room = holder.clientHeight - parseFloat(style.paddingTop) - parseFloat(style.paddingBottom);
+            const row = first.offsetHeight;
+            if (row <= 0 || room <= 0)
+                return;
+            const line = root.querySelector(".nx-wlist__more")?.offsetHeight || MORE_LINE;
+            const all = rows.length * row <= room - (more && total > rows.length ? line : 0);
+            const next = all ? rows.length : Math.max(1, Math.floor((room - (more ? line : 0)) / row));
+            setShown(previous => (previous === next ? previous : next));
+        };
+        measure();
+        const observer = new ResizeObserver(measure);
+        observer.observe(holder);
+        return () => observer.disconnect();
+    }, [fit, rows.length, total, more]);
+    const count = Math.min(shown, rows.length);
+    const hidden = total - count;
+    const moreLabel = more && (typeof more.label === "function" ? more.label(hidden) : (more.label ?? `${hidden} more`));
+    return (_jsxs("div", { ref: rootRef, className: cx("nx-wlist", className), children: [_jsx("ul", { className: "nx-wlist__rows", children: rows.slice(0, count).map(row => {
+                    const body = (_jsxs(_Fragment, { children: [row.avatar ? _jsx(Avatar, { name: row.avatar.name, src: row.avatar.src, size: "md" }) : row.icon ? _jsx("span", { className: "nx-wlist__icon", children: row.icon }) : null, _jsxs("span", { className: "nx-wlist__text", children: [_jsx("span", { className: "nx-wlist__title", "data-unread": row.unread || undefined, children: row.title }), row.secondary && _jsx("span", { className: "nx-wlist__secondary", children: row.secondary })] }), (row.time || row.chip) && (_jsxs("span", { className: "nx-wlist__end", children: [row.time && _jsx("span", { className: "nx-wlist__time", children: row.time }), row.chip && (_jsx("span", { className: "nx-table__tag nx-wlist__chip", "data-tone": row.chip.tone, children: row.chip.label }))] }))] }));
+                    return (_jsx("li", { className: "nx-wlist__row", "data-lead": row.avatar || row.icon ? "" : undefined, children: row.href ? (_jsx(WidgetLink, { className: "nx-wlist__item nx-wlist__item--link", href: row.href, children: body })) : (_jsx("span", { className: "nx-wlist__item", children: body })) }, row.id));
+                }) }), more && hidden > 0 && (_jsxs(WidgetLink, { className: "nx-wlist__more", href: more.href, children: [moreLabel, _jsx(InlineIcon, { icon: iconArrowRight })] }))] }));
+}
+/** The kinds a calendar widget knows without being told: holidays, leave, events. */
+export const CALENDAR_MARK_KINDS = {
+    holiday: { label: "Holiday", tone: "danger" },
+    leave: { label: "Leave", tone: "warning" },
+    event: { label: "Event", tone: "primary" },
+};
+const MAX_DOTS = 3;
+/**
+ * A month in a widget with typed marks on its days - holidays, leave, events, or the app's own kinds - a dot of each
+ * kind's tone under the day's number, today marked, a legend counting the month's marks by kind, and the picked day's
+ * marks listed beside the month (under it when the widget is narrow). In the English or the Nepali calendar.
+ *
+ * @example <CalendarWidget marks={[{ date: "2026-11-12", kind: "holiday", label: "Tihar" }, { date: "2026-11-16", until: "2026-11-18", kind: "leave", label: "Sita Rai" }]} />
+ */
+export function CalendarWidget({ marks, kinds, calendar, today, onMonthChange, weekStart, className }) {
+    const preferences = useDatePreferences();
+    const shown = calendar ?? preferences.calendar;
+    const day0 = today ?? todayIsoDate();
+    const [picked, setPicked] = useState(day0);
+    const [month, setMonth] = useState(null);
+    const known = useMemo(() => ({ ...CALENDAR_MARK_KINDS, ...kinds }), [kinds]);
+    const byDay = useMemo(() => marksByDay(marks), [marks]);
+    const kindOf = (kind) => known[kind] ?? {
+        label: kind.charAt(0).toUpperCase() + kind.slice(1),
+        tone: "neutral",
+    };
+    const devanagari = usesDevanagari(shown, preferences.script);
+    const digits = (value) => (devanagari ? toDevanagariDigits(String(value)) : String(value));
+    const dateOptions = {
+        ...preferences,
+        calendar: shown,
+        format: "dddd, MMM D",
+    };
+    // The month's marks by kind, for the legend. A mark over several days counts once.
+    const monthMarks = useMemo(() => {
+        const first = month ?? day0;
+        const counts = new Map();
+        const seen = new Set();
+        const prefix = (iso) => formatDate(iso, { calendar: shown, format: "YYYY-MM", script: "latin" });
+        const wanted = prefix(first);
+        for (const [iso, list] of byDay)
+            if (prefix(iso) === wanted)
+                for (const mark of list)
+                    if (!seen.has(mark)) {
+                        seen.add(mark);
+                        counts.set(mark.kind, (counts.get(mark.kind) ?? 0) + 1);
+                    }
+        return counts;
+    }, [byDay, month, day0, shown]);
+    const legendKinds = [...new Set([...Object.keys(CALENDAR_MARK_KINDS), ...Object.keys(kinds ?? {}), ...monthMarks.keys()])];
+    const dayMarks = byDay.get(picked) ?? [];
+    function renderDay(day) {
+        const list = byDay.get(day.iso) ?? [];
+        const kindsOnDay = [...new Set(list.map(mark => mark.kind))];
+        return (_jsxs("span", { className: "nx-wcal__day", "data-holiday": kindsOnDay.includes("holiday") || undefined, children: [_jsx("span", { className: "nx-cal__num", children: digits(day.parts.day) }), kindsOnDay.length > 0 && (_jsx("span", { className: "nx-wcal__dots", "aria-hidden": "true", children: kindsOnDay.slice(0, MAX_DOTS).map(kind => (_jsx("span", { className: "nx-wcal__dot", "data-tone": kindOf(kind).tone }, kind))) }))] }));
+    }
+    return (_jsxs("div", { className: cx("nx-wcal", className), children: [_jsx(Calendar, { size: "sm", className: "nx-wcal__month", calendar: shown, value: picked, onValueChange: value => value && setPicked(value), today: day0, footer: false, weekStart: weekStart, renderDay: renderDay, onMonthChange: first => {
+                    setMonth(first);
+                    onMonthChange?.(first);
+                }, "aria-label": "Calendar" }), _jsxs("div", { className: "nx-wcal__side", children: [_jsx("ul", { className: "nx-wcal__legend", "aria-label": "This month", children: legendKinds.map(kind => (_jsxs("li", { className: "nx-wcal__key", children: [_jsx("span", { className: "nx-wcal__dot", "data-tone": kindOf(kind).tone, "aria-hidden": "true" }), kindOf(kind).label, _jsx("span", { className: "nx-wcal__count", children: digits(monthMarks.get(kind) ?? 0) })] }, kind))) }), _jsxs("section", { "aria-live": "polite", children: [_jsxs("h4", { className: "nx-wcal__date", children: [picked === day0 ? "Today · " : "", formatDate(picked, dateOptions)] }), dayMarks.length > 0 ? (_jsx("ul", { className: "nx-wcal__marks", children: dayMarks.map((mark, index) => (_jsxs("li", { className: "nx-wcal__mark", children: [_jsx("span", { className: "nx-table__tag", "data-tone": kindOf(mark.kind).tone, children: kindOf(mark.kind).label }), _jsx("span", { className: "nx-wcal__label", children: mark.label })] }, index))) })) : (_jsx("p", { className: "nx-wcal__none", children: "Nothing on this day." }))] })] })] }));
+}
+const NEWS_KINDS = {
+    released: { label: "Released", tone: "success" },
+    "coming-soon": { label: "Coming soon", tone: "info" },
+};
+/**
+ * Release notes in a widget, newest first as given: the title, the version and the kind (Released, Coming soon) as
+ * tags, the day, the first lines of the Markdown notes and "Read more".
+ *
+ * @example <NewsWidget items={releases} onReadMore={item => openNote(item)} />
+ */
+export function NewsWidget({ items, onReadMore, excerptLines = 3, className }) {
+    const preferences = useDatePreferences();
+    return (_jsx("ol", { className: cx("nx-wnews", className), children: items.map(item => (_jsxs("li", { className: "nx-wnews__item", children: [_jsxs("div", { className: "nx-wnews__head", children: [_jsx("span", { className: "nx-wnews__title", children: item.title }), item.version && (_jsx("span", { className: "nx-table__tag", "data-tone": "primary", children: item.version })), item.kind && (_jsx("span", { className: "nx-table__tag", "data-tone": NEWS_KINDS[item.kind].tone, children: NEWS_KINDS[item.kind].label }))] }), (item.application || item.date) && (_jsxs("p", { className: "nx-wnews__meta", children: [item.application, item.application && item.date ? " · " : "", item.date && (_jsx("time", { dateTime: item.date, children: formatDate(item.date, {
+                                ...preferences,
+                                format: "MMM D, YYYY",
+                            }) }))] })), item.notes && _jsx(MarkdownView, { className: "nx-wnews__notes", value: item.notes, style: { WebkitLineClamp: excerptLines } }), item.href ? (_jsxs(WidgetLink, { className: "nx-wnews__more", href: item.href, children: ["Read more", _jsx(InlineIcon, { icon: iconArrowRight })] })) : (onReadMore && (_jsxs("button", { type: "button", className: "nx-wnews__more", onClick: () => onReadMore(item), children: ["Read more", _jsx(InlineIcon, { icon: iconArrowRight })] })))] }, item.id))) }));
+}
+/**
+ * The application's name, version and build day in a widget: what a person reads out when they ask for help.
+ *
+ * @example <VersionWidget name="Nexus Web" version={BUILD.version} build={BUILD.time} href="/admin/tenant/releases" />
+ */
+export function VersionWidget({ name, version, build, channel, href, className }) {
+    const preferences = useDatePreferences();
+    const day = build ? toLatinDigits(build).slice(0, 10) : undefined;
+    return (_jsxs("div", { className: cx("nx-wversion", className), children: [_jsxs("span", { className: "nx-wversion__line", children: [_jsx("span", { className: "nx-wversion__version", children: version }), channel && (_jsx("span", { className: "nx-table__tag", "data-tone": "info", children: channel }))] }), _jsxs("span", { className: "nx-wversion__meta", children: [name, day && (_jsxs(_Fragment, { children: [" · Built ", _jsx("time", { dateTime: build, children: formatDate(day, { ...preferences, format: "MMM D, YYYY" }) })] }))] }), href && (_jsxs(WidgetLink, { className: "nx-wversion__link", href: href, children: ["What's new", _jsx(InlineIcon, { icon: iconArrowRight })] }))] }));
+}

package/dist/Components/Dashboards/WidgetFrame.d.ts

@@ -0,0 +1,51 @@
+import { type ComponentPropsWithRef, type ReactNode } from "react";
+import type { WidgetSize } from "../../Interfaces/DashboardInterfaces.ts";
+/**
+ * How a link inside a board moves: the app's router (`router.push`) for a plain click, so a dashboard's links stay in
+ * the app; a click with a modifier key, or no router, is the browser's own. `DashboardBoard` gives it from `onNavigate`.
+ */
+export declare const WidgetNavigateContext: import("react").Context<((href: string) => void) | null>;
+export interface WidgetLinkProps extends Omit<ComponentPropsWithRef<"a">, "href"> {
+    href: string;
+}
+/** A link inside a widget: an `<a>`, moved through the board's `onNavigate` on a plain click. */
+export declare function WidgetLink({ href, onClick, ...rest }: WidgetLinkProps): import("react").JSX.Element;
+/** What a frame shows: bones while it loads, a sentence when empty, the failure with Try again, or its content. */
+export type WidgetFrameState = "loading" | "ready" | "empty" | "failed";
+export interface WidgetFrameProps extends Omit<ComponentPropsWithRef<"article">, "title" | "children"> {
+    title: ReactNode;
+    /** A link in the heading to the page its data comes from: "View all" by default. */
+    link?: {
+        href: string;
+        label?: ReactNode;
+    };
+    /** Its size on a board's grid; it sets the frame's spans. Default `M`. */
+    size?: WidgetSize;
+    /** Default `ready`. */
+    state?: WidgetFrameState;
+    /** `empty`: what it says (default "Nothing to show yet."); `failed`: the failure (default "This could not be read."). */
+    message?: ReactNode;
+    /** `failed`: Try again. */
+    onRetry?: () => void;
+    /** Its own refresh button in the heading. */
+    onRefresh?: () => void;
+    /** Its data is being read again behind what it shows: the refresh button turns. */
+    refreshing?: boolean;
+    /** Controls at the end of the heading (a board's edit tools). */
+    tools?: ReactNode;
+    /** Before the title (a board's move handle). */
+    lead?: ReactNode;
+    /** The body takes no clicks or focus (a board in edit mode). */
+    inertBody?: boolean;
+    children?: ReactNode;
+}
+/**
+ * A widget's frame on a dashboard: the title, an optional link, its own refresh, and its body in one of four states -
+ * bones of its own size while it loads (it is the size it will be, so nothing moves when the data lands), a sentence
+ * when there is nothing to show, the failure with Try again (never more than the frame: the board goes on), or its
+ * content. Its size sets its spans on the board's grid.
+ *
+ * @example
+ * <WidgetFrame title="Mail" size="S" state={loading ? "loading" : "ready"} link={{ href: "/admin/message" }}>…</WidgetFrame>
+ */
+export declare function WidgetFrame({ title, link, size, state, message, onRetry, onRefresh, refreshing, tools, lead, inertBody, className, style, children, ...rest }: WidgetFrameProps): import("react").JSX.Element;

package/dist/Components/Dashboards/WidgetFrame.js

@@ -0,0 +1,45 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconArrowRight, iconRefresh, InlineIcon } from "nexus-icons";
+import { createContext, useContext, useId } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { WIDGET_SPANS } from "../../Helpers/DashboardHelpers.js";
+import { ChatFailure } from "../Chats/ChatParts.js";
+import { Button } from "../Documents/Button.js";
+/**
+ * How a link inside a board moves: the app's router (`router.push`) for a plain click, so a dashboard's links stay in
+ * the app; a click with a modifier key, or no router, is the browser's own. `DashboardBoard` gives it from `onNavigate`.
+ */
+export const WidgetNavigateContext = createContext(null);
+/** A link inside a widget: an `<a>`, moved through the board's `onNavigate` on a plain click. */
+export function WidgetLink({ href, onClick, ...rest }) {
+    const navigate = useContext(WidgetNavigateContext);
+    function click(event) {
+        onClick?.(event);
+        if (event.defaultPrevented || !navigate || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey || rest.target === "_blank")
+            return;
+        event.preventDefault();
+        navigate(href);
+    }
+    return _jsx("a", { ...rest, href: href, onClick: click });
+}
+/** How many lines of bones stand in for a size's content while it loads. */
+const BONE_LINES = { S: 1, M: 3, L: 7, W: 3, T: 7 };
+/**
+ * A widget's frame on a dashboard: the title, an optional link, its own refresh, and its body in one of four states -
+ * bones of its own size while it loads (it is the size it will be, so nothing moves when the data lands), a sentence
+ * when there is nothing to show, the failure with Try again (never more than the frame: the board goes on), or its
+ * content. Its size sets its spans on the board's grid.
+ *
+ * @example
+ * <WidgetFrame title="Mail" size="S" state={loading ? "loading" : "ready"} link={{ href: "/admin/message" }}>…</WidgetFrame>
+ */
+export function WidgetFrame({ title, link, size = "M", state = "ready", message, onRetry, onRefresh, refreshing = false, tools, lead, inertBody = false, className, style, children, ...rest }) {
+    const titleId = `${useId()}-title`;
+    const span = WIDGET_SPANS[size];
+    return (_jsxs("article", { ...rest, className: cx("nx-widget", className), "data-size": size, "data-state": state, "aria-labelledby": rest["aria-label"] ? undefined : titleId, "aria-busy": state === "loading" || refreshing || undefined, style: {
+            "--nx-widget-columns": span.columns,
+            "--nx-widget-rows": span.rows,
+            ...style,
+        }, children: [_jsxs("header", { className: "nx-widget__head", children: [lead, _jsx("h3", { id: titleId, className: "nx-widget__title", children: title }), link && (_jsxs(WidgetLink, { className: "nx-widget__link", href: link.href, tabIndex: inertBody ? -1 : undefined, children: [link.label ?? "View all", _jsx(InlineIcon, { icon: iconArrowRight })] })), onRefresh && !tools && (_jsx(Button, { variant: "ghost", size: "sm", className: "nx-widget__refresh", icon: _jsx(InlineIcon, { icon: iconRefresh, className: refreshing ? "nx-spin" : undefined }), "aria-label": typeof title === "string" ? `Refresh ${title}` : "Refresh", title: "Refresh", disabled: state === "loading" || refreshing, onClick: onRefresh })), tools] }), _jsx("div", { className: "nx-widget__body", inert: inertBody || undefined, children: state === "loading" ? (_jsx("div", { className: "nx-widget__bones", "aria-hidden": "true", children: Array.from({ length: BONE_LINES[size] }, (_, index) => (_jsx("span", { className: "nx-table__bone nx-widget__bone" }, index))) })) : state === "failed" ? (_jsx("div", { className: "nx-widget__failure", children: _jsx(ChatFailure, { message: typeof message === "string" && message ? message : "This could not be read.", onRetry: onRetry, flat: true }) })) : state === "empty" ? (_jsx("p", { className: "nx-widget__empty", children: message ?? "Nothing to show yet." })) : (children) })] }));
+}

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

@@ -26,9 +26,14 @@ export interface ButtonProps extends ComponentPropsWithRef<"button"> {
      * a state that is on, such as filters.
      */
     dot?: boolean | "primary";
+    /**
+     * A count over the corner, in the chat's badge: "3", "99+". The button keeps its size whatever the count, so a bar of
+     * buttons does not move as it arrives. Say the count in `aria-label` too: the badge is not read.
+     */
+    badge?: number | string | null;
 }
 /**
  * A button. Without children it becomes a square icon button, which then needs an `aria-label`.
  * Has no client state, so it renders in server and client components alike.
  */
-export declare function Button({ variant, size, hoverTone, icon, iconEnd, loading, block, dot, type, disabled, className, children, ...rest }: ButtonProps): import("react").JSX.Element;
+export declare function Button({ variant, size, hoverTone, icon, iconEnd, loading, block, dot, badge, type, disabled, className, children, ...rest }: ButtonProps): import("react").JSX.Element;

package/dist/Components/Documents/Button.js

@@ -5,7 +5,7 @@ import { cx } from "../../Helpers/ClassHelpers.js";
  * A button. Without children it becomes a square icon button, which then needs an `aria-label`.
  * Has no client state, so it renders in server and client components alike.
  */
-export function Button({ variant = "secondary", size = "md", hoverTone, icon, iconEnd, loading = false, block = false, dot = false, type = "button", disabled, className, children, ...rest }) {
+export function Button({ variant = "secondary", size = "md", hoverTone, icon, iconEnd, loading = false, block = false, dot = false, badge, type = "button", disabled, className, children, ...rest }) {
     const hasLabel = children !== undefined && children !== null && children !== false;
-    return (_jsxs("button", { type: type, className: cx("nx-btn", `nx-btn--${variant}`, `nx-btn--${size}`, hoverTone && `nx-btn--hover-${hoverTone}`, block && "nx-btn--block", !hasLabel && "nx-btn--icon", className), disabled: disabled || loading, "aria-busy": loading || undefined, ...rest, children: [loading ? _jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin" }) : icon, hasLabel && _jsx("span", { className: "nx-btn__label", children: children }), iconEnd, dot && _jsx("span", { className: "nx-btn__dot", "data-tone": dot === true ? undefined : dot, "aria-hidden": "true" })] }));
+    return (_jsxs("button", { type: type, className: cx("nx-btn", `nx-btn--${variant}`, `nx-btn--${size}`, hoverTone && `nx-btn--hover-${hoverTone}`, block && "nx-btn--block", !hasLabel && "nx-btn--icon", className), disabled: disabled || loading, "aria-busy": loading || undefined, ...rest, children: [loading ? _jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin" }) : icon, hasLabel && _jsx("span", { className: "nx-btn__label", children: children }), iconEnd, dot && _jsx("span", { className: "nx-btn__dot", "data-tone": dot === true ? undefined : dot, "aria-hidden": "true" }), badge !== undefined && badge !== null && badge !== "" && (_jsx("span", { className: "nx-btn__badge", "aria-hidden": "true", children: badge }))] }));
 }

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

@@ -0,0 +1,50 @@
+import { type CSSProperties, type ReactNode, type Ref } from "react";
+/** What a page shown in a `DocumentFrame` can be asked to do. */
+export interface DocumentFrameHandle {
+    /** Opens the print dialog for the page shown; `false` when it cannot (not `printable`, no page yet, frame not loaded). */
+    print: () => boolean;
+}
+export interface DocumentFrameProps {
+    /** The whole page to show, or null/undefined (or "") while there is none yet. */
+    html: string | null | undefined;
+    /** The frame's name for screen readers and its title attribute: "Voucher preview". Required. */
+    title: string;
+    /**
+     * A read is under way: the page shown stays, and a read that lasts dims it and says `loadingMessage` in the bar (a
+     * quick one says nothing, as a form's status line). The page area is `aria-busy` from the start. While loading, or
+     * with an `error`, an `html` of null keeps the last page in view.
+     */
+    loading?: boolean;
+    /** What the bar says while a read lasts. Default "Loading…". */
+    loadingMessage?: ReactNode;
+    /** Why the page could not be shown: a line with `role="alert"` in the bar above the page, which stays in view under it. */
+    error?: ReactNode;
+    /** Shown in the page area before any page arrives. Default "Nothing to show yet." */
+    emptyMessage?: ReactNode;
+    /**
+     * Buttons the page puts in the frame's bar, at its end beside the status line ("Print", "Reset to default"); on a
+     * narrow frame they wrap under the line. The bar shows only when there are actions, or a status to say.
+     */
+    actions?: ReactNode;
+    /**
+     * The page may be printed through the handle's `print()`: only then is the frame sandboxed
+     * "allow-same-origin allow-modals" (same origin so the parent can call the frame's print(); modals so print() opens
+     * the dialog). Never allow-scripts. Without it the sandbox is "" (an opaque origin, nothing allowed).
+     */
+    printable?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    ref?: Ref<DocumentFrameHandle>;
+}
+/**
+ * A whole HTML page from a server, in a frame that fills the height its container gives it (at least 22rem) and
+ * scrolls inside itself: an A4 sheet wider than the frame scrolls sideways there, never the page. Above it, a bar holds
+ * the status line and the page's `actions`. A page read again keeps its place while the title stays the same (a
+ * `printable` frame; the sandbox of another lets nobody look in).
+ *
+ * @example
+ * const frame = useRef<DocumentFrameHandle>(null);
+ * <DocumentFrame ref={frame} title="Voucher preview" html={preview} loading={reading} error={problem} printable
+ *   actions={<Button onClick={() => frame.current?.print()}>Print</Button>} />
+ */
+export declare function DocumentFrame({ html, title, loading, loadingMessage, error, emptyMessage, actions, printable, className, style, ref, }: DocumentFrameProps): import("react").JSX.Element;

package/dist/Components/Documents/DocumentFrame.js

@@ -0,0 +1,83 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { iconAlertCircle, iconFileText, iconLoader2, InlineIcon } from "nexus-icons";
+import { useImperativeHandle, useLayoutEffect, useRef } from "react";
+import { useSlowBusy } from "../../Helpers/BusyHooks.js";
+import { cx } from "../../Helpers/ClassHelpers.js";
+/*
+ * A whole HTML page a server wrote - a print layout's preview, a document to print - shown in a sandboxed frame. The
+ * page is the server's, from `<!DOCTYPE html>` to `</html>`, with its own `@page` sheet and screen style, so it is never
+ * mixed into this page's DOM and styles: it goes into an `<iframe srcdoc>`, and **no script ever runs in it**, whatever
+ * the page holds. The sandbox is "" (an opaque origin: nothing allowed, the parent cannot reach in either), or, for a
+ * page that may be printed, "allow-same-origin allow-modals": the parent may call the frame's print(), and print() may
+ * open its dialog. Never allow-scripts, allow-forms, allow-popups or allow-top-navigation.
+ */
+/** A page that may be printed: the parent reaches the frame's window, and its print() may open the dialog. */
+const PRINTABLE_SANDBOX = "allow-same-origin allow-modals";
+const hasContent = (node) => node !== undefined && node !== null && node !== false && node !== "";
+/**
+ * A whole HTML page from a server, in a frame that fills the height its container gives it (at least 22rem) and
+ * scrolls inside itself: an A4 sheet wider than the frame scrolls sideways there, never the page. Above it, a bar holds
+ * the status line and the page's `actions`. A page read again keeps its place while the title stays the same (a
+ * `printable` frame; the sandbox of another lets nobody look in).
+ *
+ * @example
+ * const frame = useRef<DocumentFrameHandle>(null);
+ * <DocumentFrame ref={frame} title="Voucher preview" html={preview} loading={reading} error={problem} printable
+ *   actions={<Button onClick={() => frame.current?.print()}>Print</Button>} />
+ */
+export function DocumentFrame({ html, title, loading = false, loadingMessage = "Loading…", error, emptyMessage = "Nothing to show yet.", actions, printable = false, className, style, ref, }) {
+    const frameRef = useRef(null);
+    const failed = hasContent(error);
+    // The page shown: the one given, else the last one while a read is under way or has failed.
+    const last = useRef(null);
+    const page = html ? html : loading || failed ? last.current : null;
+    const slow = useSlowBusy(loading);
+    const said = failed || slow;
+    const shownTitle = useRef(title);
+    const place = useRef(null);
+    // A new page replaces the one shown: note where the old one was scrolled to, while it is still there (the frame
+    // loads the new one a task later). Only a printable frame's page can be read; another's throws, and keeps nothing.
+    useLayoutEffect(() => {
+        try {
+            const view = frameRef.current?.contentWindow;
+            place.current = view && view.location.href === "about:srcdoc" ? { title: shownTitle.current, x: view.scrollX, y: view.scrollY } : null;
+        }
+        catch {
+            place.current = null;
+        }
+        last.current = page;
+        shownTitle.current = title;
+    }, [page, title]);
+    function keepPlace() {
+        const kept = place.current;
+        if (!kept || kept.title !== title || (!kept.x && !kept.y))
+            return;
+        try {
+            frameRef.current?.contentWindow?.scrollTo(kept.x, kept.y);
+        }
+        catch {
+            // The frame is not ours to reach (not printable): it opens at the top.
+        }
+    }
+    useImperativeHandle(ref, () => ({
+        print() {
+            const frame = frameRef.current;
+            if (!printable || !frame)
+                return false;
+            try {
+                const view = frame.contentWindow;
+                const document_ = frame.contentDocument;
+                if (!view || !document_ || document_.URL !== "about:srcdoc" || document_.readyState !== "complete")
+                    return false;
+                view.focus();
+                view.print();
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    }), [printable]);
+    return (_jsxs("div", { className: cx("nx-document-frame", className), style: style, children: [_jsxs("div", { className: cx("nx-form-buttons nx-form-buttons--end nx-document-frame__bar", !said && !hasContent(actions) && "nx-visually-hidden"), children: [failed ? (_jsxs("p", { className: "nx-form-status nx-form-status--error", role: "alert", children: [_jsx(InlineIcon, { icon: iconAlertCircle }), _jsx("span", { children: error })] }, "error")) : (_jsx("p", { className: "nx-form-status", role: "status", children: slow && (_jsxs(_Fragment, { children: [_jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin" }), _jsx("span", { children: loadingMessage })] })) }, "status")), hasContent(actions) && _jsx("div", { className: "nx-form-buttons__actions", children: actions })] }), _jsx("div", { className: cx("nx-document-frame__view", slow && "nx-document-frame__view--busy"), "aria-busy": loading || undefined, children: page ? (_jsx("iframe", { ref: frameRef, className: "nx-document-frame__page", title: title, sandbox: printable ? PRINTABLE_SANDBOX : "", srcDoc: page, referrerPolicy: "no-referrer", onLoad: keepPlace }, printable ? "printable" : "sealed")) : (!loading && (_jsxs("p", { className: "nx-form-status nx-document-frame__empty", children: [_jsx(InlineIcon, { icon: iconFileText }), _jsx("span", { children: emptyMessage })] }))) })] }));
+}

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

@@ -12,6 +12,10 @@ export interface MenuItem<T extends string = string> {
     shortcut?: string;
     /** `danger` draws the item in the danger color, for Delete and the like. */
     tone?: "danger";
+    /**
+     * Switched off. With a `description` it is held, saying why: still reached by the arrow keys, and a press shows the
+     * description in a note beside it, as a held Add and a read-only field do.
+     */
     disabled?: boolean;
     /** Renders the item as a link. */
     href?: string;