@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/components/notification-center.js

@@ -0,0 +1,399 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { Popover as PopoverPrimitive } from "radix-ui";
+import { Bell, Check, CheckCheck, Settings } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useLabels } from "../lib/labels.js";
+import { useLocale } from "../lib/locale.js";
+import { SmartLink } from "../lib/provider.js";
+import { usePortalContainer } from "../lib/theme-scope.js";
+import { Layer } from "../lib/layer.js";
+import { useLatest } from "../lib/use-controllable-state.js";
+import { useMediaQuery } from "../lib/use-media-query.js";
+import { Button, IconButton } from "./button.js";
+import { Avatar } from "./avatar.js";
+import { Badge } from "./badge.js";
+import { Skeleton } from "./skeleton.js";
+import { Alert } from "./alert.js";
+import { EmptyState } from "./empty-state.js";
+import { Spinner } from "./spinner.js";
+import { Sheet, SheetContent } from "./sheet.js";
+import { DialogTitle } from "./dialog.js";
+import { toast } from "./toast.js";
+const notificationLabels = {
+    label: "Notifications",
+    trigger: "Notifications",
+    triggerUnread: "Notifications, {count, plural, one {# unread} other {# unread}}",
+    unreadCount: "{count, plural, one {# unread} other {# unread}}",
+    markAllRead: "Mark all as read",
+    markRead: "Mark as read",
+    empty: "You're all caught up",
+    emptyDescription: "New mentions, approvals and updates will show up here.",
+    error: "Couldn't load notifications.",
+    retry: "Try again",
+    loadMore: "Load more",
+    settings: "Notification settings",
+    today: "Today",
+    yesterday: "Yesterday",
+    earlier: "Earlier",
+    all: "All",
+    unread: "Unread",
+    mentions: "Mentions",
+    filter: "Filter notifications",
+    newItem: "New notification: {title}",
+    unreadDot: "Unread",
+};
+/**
+ * An in-memory adapter: `filter` "unread" keeps unread items, any other value matches `category`
+ * or `app`. Pages of `pageSize` (default 20), with optional `latency` in ms.
+ */
+export function createMemoryNotificationAdapter(initial, options = {}) {
+    let items = [...initial].sort((a, b) => +new Date(b.createdAt) - +new Date(a.createdAt));
+    const subs = new Set();
+    const pageSize = options.pageSize ?? 20;
+    const wait = (signal) => new Promise((resolve, reject) => {
+        if (!options.latency)
+            return resolve();
+        const t = setTimeout(resolve, options.latency);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(t);
+            reject(new DOMException("Aborted", "AbortError"));
+        });
+    });
+    return {
+        async list({ cursor, filter, signal }) {
+            await wait(signal);
+            const pool = items.filter((n) => (!filter ? true : filter === "unread" ? !n.readAt : n.category === filter || n.app === filter));
+            const start = cursor ? Number(cursor) : 0;
+            const page = pool.slice(start, start + pageSize);
+            return { items: page, nextCursor: start + pageSize < pool.length ? String(start + pageSize) : undefined };
+        },
+        async unreadCount() {
+            return items.filter((n) => !n.readAt).length;
+        },
+        async markRead(ids) {
+            const now = new Date().toISOString();
+            items = items.map((n) => (ids === "all" || ids.includes(n.id) ? { ...n, readAt: n.readAt ?? now } : n));
+        },
+        async onAction(id, actionId) {
+            await wait();
+            await options.onAction?.(id, actionId);
+            items = items.map((n) => (n.id === id ? { ...n, actions: undefined, readAt: n.readAt ?? new Date().toISOString() } : n));
+        },
+        subscribe(cb) {
+            subs.add(cb);
+            return () => subs.delete(cb);
+        },
+        push(n) {
+            items = [n, ...items];
+            subs.forEach((cb) => cb(n));
+        },
+    };
+}
+const emptyList = { items: [], status: "idle", loadingMore: false };
+const NotificationContext = React.createContext(null);
+const useNC = () => {
+    const ctx = React.useContext(NotificationContext);
+    if (!ctx)
+        throw new Error("Notification parts must be used inside <NotificationCenter>.");
+    return ctx;
+};
+const isUnread = (n) => !n.readAt;
+/**
+ * An in-app inbox: the bell in the top bar, a panel (popover ≥768px, sheet below) with filter tabs,
+ * a grouped feed (Today / Yesterday / Earlier), read/unread, inline actions and "Mark all as read".
+ * Data comes through an adapter, so the app chooses REST, SSE or websockets.
+ *
+ * ```tsx
+ * <NotificationCenter adapter={inbox} settingsHref="/settings/notifications" toastOnNew />
+ * ```
+ */
+export function NotificationCenter({ adapter, tabs: tabsProp, toastOnNew, pollInterval, size = "md", settingsHref, open: openProp, defaultOpen = false, onOpenChange, children, labels, }) {
+    const t = useLabels("notifications", notificationLabels, labels);
+    const tabs = React.useMemo(() => tabsProp ?? [{ id: "all", label: t("all") }, { id: "unread", label: t("unread"), filter: "unread" }, { id: "mentions", label: t("mentions"), filter: "mention" }], [tabsProp, t]);
+    const [openState, setOpenState] = React.useState(defaultOpen);
+    const open = openProp ?? openState;
+    const onOpenChangeRef = useLatest(onOpenChange);
+    const setOpen = React.useCallback((o) => {
+        if (openProp === undefined)
+            setOpenState(o);
+        onOpenChangeRef.current?.(o);
+    }, [openProp, onOpenChangeRef]);
+    const [tab, setTab] = React.useState(tabs[0]?.id ?? "all");
+    const [lists, setLists] = React.useState({});
+    const [unread, setUnread] = React.useState(0);
+    const [pending, setPending] = React.useState({});
+    const triggerRef = React.useRef(null);
+    const adapterRef = useLatest(adapter);
+    const filterOf = React.useCallback((id) => tabs.find((x) => x.id === id)?.filter, [tabs]);
+    const refreshCount = React.useCallback(() => {
+        adapterRef.current.unreadCount().then(setUnread, () => { });
+    }, [adapterRef]);
+    React.useEffect(refreshCount, [refreshCount, adapter]);
+    const load = React.useCallback((tabId, signal, cursor) => {
+        setLists((prev) => {
+            const cur = prev[tabId] ?? emptyList;
+            return { ...prev, [tabId]: cursor ? { ...cur, loadingMore: true } : { ...cur, status: "loading" } };
+        });
+        adapterRef.current.list({ cursor, filter: filterOf(tabId), signal }).then((res) => {
+            if (signal.aborted)
+                return;
+            setLists((prev) => {
+                const cur = prev[tabId] ?? emptyList;
+                const items = cursor ? [...cur.items, ...res.items.filter((n) => !cur.items.some((c) => c.id === n.id))] : res.items;
+                return { ...prev, [tabId]: { items, nextCursor: res.nextCursor, status: "ready", loadingMore: false } };
+            });
+        }, () => {
+            if (signal.aborted)
+                return;
+            setLists((prev) => ({ ...prev, [tabId]: { ...(prev[tabId] ?? emptyList), status: cursor ? "ready" : "error", loadingMore: false } }));
+        });
+    }, [adapterRef, filterOf]);
+    // Load the active tab when the panel opens or the tab changes.
+    const [reloadKey, setReloadKey] = React.useState(0);
+    React.useEffect(() => {
+        if (!open)
+            return;
+        const ac = new AbortController();
+        load(tab, ac.signal);
+        refreshCount();
+        return () => ac.abort();
+    }, [open, tab, load, reloadKey, refreshCount]);
+    const loadMore = React.useCallback(() => {
+        const cur = lists[tab];
+        if (!cur?.nextCursor || cur.loadingMore)
+            return;
+        load(tab, new AbortController().signal, cur.nextCursor);
+    }, [lists, tab, load]);
+    // Live items + toasts + a throttled polite announcement.
+    const [announcement, setAnnouncement] = React.useState("");
+    const lastAnnounce = React.useRef(0);
+    const toastRef = useLatest(toastOnNew);
+    React.useEffect(() => {
+        if (!adapter.subscribe)
+            return;
+        return adapter.subscribe((n) => {
+            setLists((prev) => {
+                const next = {};
+                for (const [id, l] of Object.entries(prev)) {
+                    const f = filterOf(id);
+                    const fits = !f || (f === "unread" && isUnread(n)) || n.category === f || n.app === f;
+                    next[id] = fits ? { ...l, items: [n, ...l.items.filter((x) => x.id !== n.id)] } : l;
+                }
+                return next;
+            });
+            if (isUnread(n))
+                setUnread((u) => u + 1);
+            const shouldToast = typeof toastRef.current === "function" ? toastRef.current(n) : toastRef.current;
+            if (shouldToast)
+                toast(n.title, { description: n.body });
+            const now = Date.now();
+            if (now - lastAnnounce.current > 10_000) {
+                lastAnnounce.current = now;
+                setAnnouncement(t("newItem", { title: typeof n.title === "string" ? n.title : "" }));
+            }
+        });
+    }, [adapter, filterOf, toastRef, t]);
+    React.useEffect(() => {
+        if (adapter.subscribe || !pollInterval)
+            return;
+        const id = setInterval(refreshCount, pollInterval);
+        return () => clearInterval(id);
+    }, [adapter, pollInterval, refreshCount]);
+    const markRead = React.useCallback((ids) => {
+        const now = new Date().toISOString();
+        let changed = 0;
+        const seen = new Set();
+        setLists((prev) => {
+            const next = {};
+            for (const [id, l] of Object.entries(prev)) {
+                next[id] = {
+                    ...l,
+                    items: l.items.map((n) => {
+                        if (isUnread(n) && (ids === "all" || ids.includes(n.id))) {
+                            if (!seen.has(n.id)) {
+                                seen.add(n.id);
+                                changed++;
+                            }
+                            return { ...n, readAt: now };
+                        }
+                        return n;
+                    }),
+                };
+            }
+            return next;
+        });
+        setUnread((u) => (ids === "all" ? 0 : Math.max(0, u - (changed || ids.length))));
+        adapterRef.current.markRead(ids).then(refreshCount, refreshCount);
+    }, [adapterRef, refreshCount]);
+    const runAction = React.useCallback(async (id, actionId) => {
+        setPending((p) => ({ ...p, [id]: actionId }));
+        try {
+            await adapterRef.current.onAction?.(id, actionId);
+            setLists((prev) => {
+                const next = {};
+                for (const [k, l] of Object.entries(prev))
+                    next[k] = { ...l, items: l.items.map((n) => (n.id === id ? { ...n, actions: undefined, readAt: n.readAt ?? new Date().toISOString() } : n)) };
+                return next;
+            });
+            refreshCount();
+        }
+        finally {
+            setPending((p) => ({ ...p, [id]: undefined }));
+        }
+    }, [adapterRef, refreshCount]);
+    const list = lists[tab] ?? emptyList;
+    const important = Object.values(lists).some((l) => l.items.some((n) => n.important && isUnread(n)));
+    const value = {
+        open,
+        setOpen,
+        unread,
+        important,
+        tabs,
+        tab,
+        setTab,
+        list,
+        reload: () => setReloadKey((k) => k + 1),
+        loadMore,
+        markRead,
+        runAction,
+        pending,
+        triggerRef,
+        settingsHref,
+        size,
+        t,
+    };
+    return (_jsxs(NotificationContext.Provider, { value: value, children: [children ?? (_jsxs(_Fragment, { children: [_jsx(NotificationTrigger, {}), _jsxs(NotificationPanel, { children: [_jsx(NotificationTabs, {}), _jsx(NotificationList, {}), _jsx(NotificationFooter, {})] })] })), _jsx("div", { "aria-live": "polite", className: "sr-only", children: announcement })] }));
+}
+/* ------------------------------------------------------------------ */
+/* Trigger                                                             */
+/* ------------------------------------------------------------------ */
+/** The bell with the unread badge (99+). `aria-label` includes the count. */
+export const NotificationTrigger = React.forwardRef(function NotificationTrigger({ className, size = "sm", onClick, ...props }, ref) {
+    const { open, setOpen, unread, important, triggerRef, t } = useNC();
+    const { format } = useLocale();
+    const label = unread > 0 ? t("triggerUnread", { count: unread }) : t("trigger");
+    return (_jsxs("span", { className: "relative inline-flex", children: [_jsx(IconButton, { ref: (node) => {
+                    triggerRef.current = node;
+                    if (typeof ref === "function")
+                        ref(node);
+                    else if (ref)
+                        ref.current = node;
+                }, label: label, tooltip: false, size: size, "aria-haspopup": "dialog", "aria-expanded": open, "data-state": open ? "open" : "closed", onClick: (e) => {
+                    onClick?.(e);
+                    if (!e.defaultPrevented)
+                        setOpen(!open);
+                }, className: cn(open && "bg-hover", className), ...props, children: _jsx(Bell, {}) }), unread > 0 ? (_jsx("span", { "aria-hidden": true, "data-slot": "notification-badge", className: cn("pointer-events-none absolute -end-0.5 -top-0.5 min-w-4 rounded-full px-1 text-center text-[10px] font-semibold leading-4 tabular ring-2 ring-(--scene)", important ? "bg-danger-solid text-white" : "bg-accent text-accent-fg"), children: unread > 99 ? `${format.number(99)}+` : format.number(unread) })) : null] }));
+});
+/* ------------------------------------------------------------------ */
+/* Panel                                                               */
+/* ------------------------------------------------------------------ */
+/** Popover anchored to the bell on ≥768px, an end Sheet below. Titled "Notifications". */
+export function NotificationPanel({ className, children }) {
+    const { open, setOpen, triggerRef, size, t } = useNC();
+    const container = usePortalContainer();
+    const desktop = useMediaQuery("(min-width: 768px)") ?? true;
+    const titleId = React.useId();
+    const closedByPointer = React.useRef(false);
+    const header = (_jsxs("div", { className: "flex items-center gap-2 px-4 pt-3.5 pb-2", children: [_jsx("h2", { id: titleId, className: "text-[15px] font-semibold tracking-[-0.01em] text-fg", children: t("label") }), _jsx(NotificationUnreadBadge, {})] }));
+    if (!desktop) {
+        return (_jsx(Sheet, { open: open, onOpenChange: setOpen, children: _jsxs(SheetContent, { side: "end", size: "sm", className: cn("p-0", className), children: [_jsx(DialogTitle, { className: "sr-only", children: t("label") }), header, _jsx("div", { className: "flex min-h-0 flex-1 flex-col", children: children })] }) }));
+    }
+    return (_jsxs(PopoverPrimitive.Root, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverPrimitive.Anchor, { virtualRef: triggerRef }), _jsx(PopoverPrimitive.Portal, { container: container, children: _jsx(Layer, { asChild: true, children: _jsxs(PopoverPrimitive.Content, { align: "end", sideOffset: 8, collisionPadding: 12, "aria-labelledby": titleId, "data-slot": "notification-panel", "data-size": size, onInteractOutside: (e) => {
+                            // The bell toggles itself.
+                            if (triggerRef.current?.contains(e.target))
+                                e.preventDefault();
+                            else if (e.type === "dismissableLayer.pointerDownOutside")
+                                closedByPointer.current = true;
+                        }, onOpenAutoFocus: () => {
+                            closedByPointer.current = false;
+                        }, onCloseAutoFocus: (e) => {
+                            e.preventDefault();
+                            // Return focus to the bell — unless the user clicked elsewhere (don't steal that focus).
+                            if (!closedByPointer.current)
+                                triggerRef.current?.focus();
+                            closedByPointer.current = false;
+                        }, className: cn("surface-popover ui-pop z-(--z-popover) flex max-h-[min(36rem,calc(var(--radix-popover-content-available-height)-8px))] flex-col overflow-hidden rounded-ui-lg outline-none", size === "lg" ? "w-[27.5rem]" : "w-[23.75rem]", "max-w-[calc(100vw-1.5rem)]", className), children: [header, children] }) }) })] }));
+}
+function NotificationUnreadBadge() {
+    const { unread, t } = useNC();
+    if (!unread)
+        return null;
+    return (_jsx(Badge, { tone: "accent", size: "sm", children: t("unreadCount", { count: unread }) }));
+}
+/** Filter tabs (All · Unread · Mentions by default). Toggle buttons with `aria-pressed`. */
+export function NotificationTabs({ className }) {
+    const { tabs, tab, setTab, t } = useNC();
+    if (tabs.length < 2)
+        return null;
+    return (_jsx("div", { role: "group", "aria-label": t("filter"), className: cn("flex items-center gap-1 border-b border-line px-3 pb-2", className), children: tabs.map((x) => (_jsx("button", { type: "button", "aria-pressed": x.id === tab, onClick: () => setTab(x.id), className: cn("h-7 rounded-full px-3 text-[12.5px] font-medium transition-colors focus-ring", x.id === tab ? "bg-fg text-scene" : "text-fg-muted hover:bg-hover hover:text-fg"), children: x.label }, x.id))) }));
+}
+/* ------------------------------------------------------------------ */
+/* List + item                                                         */
+/* ------------------------------------------------------------------ */
+function dayKey(d, timeZone) {
+    return new Intl.DateTimeFormat("en-CA", { timeZone, year: "numeric", month: "2-digit", day: "2-digit" }).format(d);
+}
+/** Splits notifications into Today / Yesterday / Earlier in the provider's time zone. */
+export function groupNotifications(items, timeZone = "UTC", now = new Date()) {
+    const today = dayKey(now, timeZone);
+    const yesterday = dayKey(new Date(now.getTime() - 86_400_000), timeZone);
+    const groups = { today: [], yesterday: [], earlier: [] };
+    for (const n of items) {
+        const k = dayKey(new Date(n.createdAt), timeZone);
+        (k === today ? groups.today : k === yesterday ? groups.yesterday : groups.earlier).push(n);
+    }
+    return ["today", "yesterday", "earlier"].filter((g) => groups[g].length).map((g) => ({ id: g, items: groups[g] }));
+}
+/** The grouped feed with loading, empty, error and "Load more" states. */
+export function NotificationList({ className, grouped = true }) {
+    const { list, reload, loadMore, markRead, runAction, pending, setOpen, t } = useNC();
+    const { timeZone } = useLocale();
+    const groupIds = React.useId();
+    let body;
+    if (list.status === "loading" || list.status === "idle") {
+        body = (_jsx("div", { role: "status", "aria-label": t("label"), className: "grid gap-1 p-2", children: [0, 1, 2].map((i) => (_jsxs("div", { className: "flex gap-3 rounded-ui p-2.5", children: [_jsx(Skeleton, { shape: "circle", className: "size-9 shrink-0" }), _jsxs("div", { className: "grid flex-1 gap-2 pt-1", children: [_jsx(Skeleton, { className: "h-3 w-4/5 rounded-full" }), _jsx(Skeleton, { className: "h-2.5 w-1/2 rounded-full" })] })] }, i))) }));
+    }
+    else if (list.status === "error") {
+        body = (_jsx("div", { className: "p-3", children: _jsx(Alert, { tone: "danger", title: t("error"), actions: _jsx(Button, { size: "sm", onClick: reload, children: t("retry") }) }) }));
+    }
+    else if (!list.items.length) {
+        body = _jsx(EmptyState, { kind: "done", size: "sm", title: t("empty"), description: t("emptyDescription"), className: "py-10" });
+    }
+    else {
+        const groups = grouped ? groupNotifications(list.items, timeZone) : [{ id: "earlier", items: list.items }];
+        body = (_jsxs("div", { className: "grid gap-1 px-1.5 py-1.5", children: [groups.map((g) => (_jsxs("section", { "aria-labelledby": grouped ? `${groupIds}-${g.id}` : undefined, children: [grouped ? (_jsx("h3", { id: `${groupIds}-${g.id}`, className: "px-2.5 pt-2 pb-1 text-[11px] font-medium tracking-[0.06em] text-fg-subtle", children: t(g.id) })) : null, _jsx("div", { role: "feed", "aria-busy": list.loadingMore, "aria-labelledby": grouped ? `${groupIds}-${g.id}` : undefined, "aria-label": grouped ? undefined : t("label"), className: "grid gap-px", children: g.items.map((n, i) => (_jsx(NotificationItem, { notification: n, posinset: i + 1, setsize: g.items.length, pendingAction: pending[n.id], onOpen: () => {
+                                    if (isUnread(n))
+                                        markRead([n.id]);
+                                    setOpen(false);
+                                }, onMarkRead: () => markRead([n.id]), onAction: (actionId) => runAction(n.id, actionId) }, n.id))) })] }, g.id))), list.nextCursor ? (_jsx("div", { className: "flex justify-center py-2", children: _jsx(Button, { size: "sm", variant: "ghost", loading: list.loadingMore, onClick: loadMore, children: t("loadMore") }) })) : null] }));
+    }
+    return _jsx("div", { className: cn("min-h-0 flex-1 overflow-y-auto overscroll-contain", className), children: body });
+}
+const toneWell = {
+    neutral: "tone-neutral",
+    info: "tone-info",
+    success: "tone-success",
+    warning: "tone-warning",
+    danger: "tone-danger",
+};
+/** One notification. Usable on its own — e.g. a full "/notifications" page. */
+export const NotificationItem = React.forwardRef(function NotificationItem({ notification: n, onOpen, onMarkRead, onAction, pendingAction, posinset, setsize, labels, className, ...props }, ref) {
+    const t = useLabels("notifications", notificationLabels, labels);
+    const { format } = useLocale();
+    const titleId = React.useId();
+    const bodyId = React.useId();
+    const unread = isUnread(n);
+    const created = new Date(n.createdAt);
+    return (_jsxs("article", { ref: ref, "aria-labelledby": titleId, "aria-describedby": n.body ? bodyId : undefined, "aria-posinset": posinset, "aria-setsize": setsize, "data-slot": "notification-item", "data-unread": unread ? "" : undefined, className: cn("group/n relative flex gap-3 rounded-ui p-2.5 transition-colors focus-within:bg-hover hover:bg-hover", unread && "bg-[color-mix(in_srgb,var(--accent-soft)_45%,transparent)]", className), ...props, children: [_jsx("div", { className: "relative shrink-0", children: n.actor ? (_jsx(Avatar, { name: n.actor.name, src: n.actor.avatar, size: "md", "aria-hidden": true })) : (_jsx("span", { "aria-hidden": true, className: cn("tone-soft grid size-9 place-items-center rounded-full [&_svg]:size-4", toneWell[n.tone ?? "neutral"]), children: n.icon ?? _jsx(Bell, {}) })) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("p", { id: titleId, className: cn("text-[13.5px] leading-snug text-fg", unread ? "font-medium" : "text-fg-muted"), children: n.href ? (_jsx(SmartLink, { href: n.href, onClick: onOpen, className: "rounded-[3px] outline-none after:absolute after:inset-0 after:rounded-ui after:content-[''] focus-visible:after:outline-2 focus-visible:after:outline-ring", children: n.title })) : (n.title) }), n.body ? (_jsx("p", { id: bodyId, className: "mt-0.5 line-clamp-2 text-[13px] leading-snug text-fg-muted", children: n.body })) : null, _jsxs("p", { className: "mt-1 flex flex-wrap items-center gap-1.5 text-[12px] text-fg-subtle", children: [_jsx("time", { dateTime: created.toISOString(), suppressHydrationWarning: true, children: format.relative(created, { style: "short" }) }), n.app ? (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": true, children: "\u00B7" }), _jsx(Badge, { size: "sm", tone: "outline", shape: "square", children: n.app })] })) : null] }), n.actions?.length ? (_jsx("div", { className: "relative z-10 mt-2 flex flex-wrap gap-1.5", children: n.actions.map((a) => (_jsx(Button, { size: "xs", variant: a.variant === "primary" ? "primary" : "secondary", loading: pendingAction === a.id, disabled: Boolean(pendingAction) && pendingAction !== a.id, onClick: () => void onAction?.(a.id), children: a.label }, a.id))) })) : null] }), unread ? (_jsxs("div", { className: "relative z-10 flex shrink-0 flex-col items-center gap-1", children: [_jsx("span", { className: "mt-1.5 size-2 rounded-full bg-accent ring-2 ring-[color-mix(in_srgb,var(--accent)_25%,transparent)]", children: _jsx("span", { className: "sr-only", children: t("unreadDot") }) }), onMarkRead ? (_jsx(IconButton, { label: t("markRead"), size: "xs", tooltip: false, className: "opacity-0 transition-opacity group-hover/n:opacity-100 group-focus-within/n:opacity-100 focus-visible:opacity-100", onClick: onMarkRead, children: _jsx(Check, {}) })) : null] })) : null] }));
+});
+/** Footer: "Mark all as read" and a settings link. */
+export function NotificationFooter({ className }) {
+    const { unread, markRead, settingsHref, setOpen, t } = useNC();
+    return (_jsxs("div", { className: cn("flex items-center justify-between gap-2 border-t border-line px-2 py-1.5", className), children: [_jsxs(Button, { size: "sm", variant: "ghost", disabled: !unread, onClick: () => markRead("all"), children: [_jsx(CheckCheck, { "aria-hidden": true }), " ", t("markAllRead")] }), settingsHref ? (_jsx(Button, { size: "sm", variant: "ghost", asChild: true, children: _jsxs(SmartLink, { href: settingsHref, onClick: () => setOpen(false), children: [_jsx(Settings, { "aria-hidden": true }), " ", t("settings")] }) })) : null] }));
+}
+/** Spinner row while paginating (for custom lists). */
+export function NotificationLoadingRow() {
+    return (_jsx("div", { className: "flex justify-center py-3 text-fg-subtle", children: _jsx(Spinner, { size: "sm" }) }));
+}

package/dist/components/page-header.d.ts

@@ -0,0 +1,60 @@
+import * as React from "react";
+import type { MenuEntry } from "../lib/variants.js";
+export { filterNav, resolveActive, flattenNav, matchPath, navItems, findNavItem, navTrailItems, normaliseBadge, isNavGroup, isNavItem, isNavSeparator, SIDEBAR_COOKIE, parseSidebarCookie, } from "../lib/nav.js";
+export declare const pageHeaderTitleVariants: (props?: ({
+    size?: "sm" | "md" | "lg" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export interface PageHeaderProps extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
+    /** The page's one `<h1>`. `<em>` inside follows the font preset (italic in serif headings). */
+    title: React.ReactNode;
+    /** Small line above the title ("Monday, November 10", "Content"). */
+    eyebrow?: React.ReactNode;
+    /** A Breadcrumb, or `"auto"` to build it from the App shell's active nav trail. */
+    breadcrumb?: React.ReactNode | "auto";
+    /** "← Contacts" link above the title. */
+    back?: {
+        href: string;
+        label: string;
+    };
+    description?: React.ReactNode;
+    /** Status badges, "Updated 2h ago" — next to the title. */
+    meta?: React.ReactNode;
+    /** Buttons at the end; they wrap under the title on narrow screens. */
+    actions?: React.ReactNode;
+    /** Secondary actions in a "⋯" menu after `actions`. */
+    menu?: MenuEntry[];
+    /** Sub-navigation (`TabsLinkList` / `TabsList`) attached to the bottom edge. */
+    tabs?: React.ReactNode;
+    /** `lg` 40px (dashboards), `md` 30px (lists, default), `sm` 22px (records) — scaled by the font preset. */
+    size?: "sm" | "md" | "lg";
+    /** Sticks under the top bar on the bar surface. */
+    sticky?: boolean;
+    align?: "start" | "center";
+    /** Title still loading: a skeleton line in the `<h1>`. */
+    loading?: boolean;
+}
+/**
+ * The title block of a page: breadcrumb or eyebrow, title in the display font, description, meta,
+ * actions and sub-tabs. Server-compatible; `breadcrumb="auto"` is a small client island that reads
+ * the App shell's active trail.
+ *
+ * ```tsx
+ * <PageHeader
+ *   eyebrow="Content"
+ *   title="Posts"
+ *   description="128 posts · 6 scheduled"
+ *   actions={<Button variant="primary">New post</Button>}
+ * />
+ * ```
+ */
+export declare const PageHeader: React.ForwardRefExoticComponent<PageHeaderProps & React.RefAttributes<HTMLElement>>;
+/** The `<h1>`. */
+export declare const PageHeaderTitle: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLHeadingElement> & {
+    size?: "sm" | "md" | "lg";
+} & React.RefAttributes<HTMLHeadingElement>>;
+/** The small line above the title. Not uppercased with CSS: `text-transform` breaks Turkish i/İ without the right `lang`. */
+export declare function PageHeaderEyebrow({ className, ...props }: React.HTMLAttributes<HTMLParagraphElement>): React.JSX.Element;
+export declare function PageHeaderDescription({ className, ...props }: React.HTMLAttributes<HTMLParagraphElement>): React.JSX.Element;
+export declare function PageHeaderActions({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+/** Tabs row; pulls itself onto the header's bottom hairline. */
+export declare function PageHeaderTabs({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;

package/dist/components/page-header.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cva } from "class-variance-authority";
+import { ArrowLeft } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { SmartLink } from "../lib/provider.js";
+import { Skeleton } from "./skeleton.js";
+import { ActionMenu } from "./dropdown-menu.js";
+import { AppShellBreadcrumb } from "./app-shell.js";
+// Server-safe nav helpers (this module has no "use client"), so server layouts can call them.
+export { filterNav, resolveActive, flattenNav, matchPath, navItems, findNavItem, navTrailItems, normaliseBadge, isNavGroup, isNavItem, isNavSeparator, SIDEBAR_COOKIE, parseSidebarCookie, } from "../lib/nav.js";
+export const pageHeaderTitleVariants = cva("font-display min-w-0 text-fg [text-wrap:balance]", {
+    variants: {
+        size: {
+            /** Record pages. */
+            sm: "text-[length:calc(22px*var(--display-scale))] leading-[1.15]",
+            /** Lists and settings. */
+            md: "text-[length:calc(30px*var(--display-scale))] leading-[1.1]",
+            /** Dashboards. */
+            lg: "text-[length:calc(40px*var(--display-scale))] leading-[1.05]",
+        },
+    },
+    defaultVariants: { size: "md" },
+});
+/**
+ * The title block of a page: breadcrumb or eyebrow, title in the display font, description, meta,
+ * actions and sub-tabs. Server-compatible; `breadcrumb="auto"` is a small client island that reads
+ * the App shell's active trail.
+ *
+ * ```tsx
+ * <PageHeader
+ *   eyebrow="Content"
+ *   title="Posts"
+ *   description="128 posts · 6 scheduled"
+ *   actions={<Button variant="primary">New post</Button>}
+ * />
+ * ```
+ */
+export const PageHeader = React.forwardRef(function PageHeader({ title, eyebrow, breadcrumb, back, description, meta, actions, menu, tabs, size = "md", sticky, align = "start", loading, className, children, ...props }, ref) {
+    const centered = align === "center";
+    return (_jsxs("header", { ref: ref, "data-slot": "page-header", "data-size": size, className: cn("grid gap-3", tabs ? "mb-6" : size === "lg" ? "mb-8" : "mb-6", sticky && "surface-bar sticky top-(--topbar-h) z-(--z-sticky) -mx-[var(--page-px,1.5rem)] px-[var(--page-px,1.5rem)] pt-3", sticky && !tabs && "pb-3", centered && "justify-items-center text-center", className), ...props, children: [breadcrumb === "auto" ? _jsx(AppShellBreadcrumb, {}) : breadcrumb ? breadcrumb : null, back ? (_jsxs(SmartLink, { href: back.href, className: "-ms-0.5 inline-flex w-fit items-center gap-1.5 rounded-ui-sm text-[13px] text-fg-muted transition-colors hover:text-fg focus-ring", children: [_jsx(ArrowLeft, { "aria-hidden": true, className: "size-3.5 rtl:-scale-x-100" }), back.label] })) : null, _jsxs("div", { className: cn("flex flex-wrap items-end gap-x-6 gap-y-4", centered ? "justify-center" : "justify-between"), children: [_jsxs("div", { className: cn("min-w-0", centered ? "max-w-2xl" : "max-w-3xl flex-[1_1_22rem]"), children: [eyebrow ? _jsx(PageHeaderEyebrow, { className: "mb-1.5", children: eyebrow }) : null, _jsxs("div", { className: cn("flex flex-wrap items-center gap-x-3 gap-y-1.5", centered && "justify-center"), children: [_jsx(PageHeaderTitle, { size: size, "aria-busy": loading || undefined, children: loading ? _jsx(Skeleton, { className: "inline-block h-[0.8em] w-[min(18rem,60vw)] rounded-ui-sm align-middle" }) : title }), meta ? _jsx("div", { className: "flex flex-wrap items-center gap-2 text-[13px] text-fg-subtle", children: meta }) : null] }), description ? _jsx(PageHeaderDescription, { className: cn(size === "lg" ? "mt-2.5" : "mt-1.5", centered && "mx-auto"), children: description }) : null] }), actions || menu?.length ? (_jsxs(PageHeaderActions, { children: [actions, menu?.length ? _jsx(ActionMenu, { items: menu, triggerSize: "md" }) : null] })) : null] }), children, tabs ? _jsx(PageHeaderTabs, { children: tabs }) : null] }));
+});
+/** The `<h1>`. */
+export const PageHeaderTitle = React.forwardRef(function PageHeaderTitle({ size, className, ...props }, ref) {
+    return _jsx("h1", { ref: ref, "data-slot": "page-header-title", className: cn(pageHeaderTitleVariants({ size }), className), ...props });
+});
+/** The small line above the title. Not uppercased with CSS: `text-transform` breaks Turkish i/İ without the right `lang`. */
+export function PageHeaderEyebrow({ className, ...props }) {
+    return _jsx("p", { "data-slot": "page-header-eyebrow", className: cn("text-[12px] font-medium tracking-[0.08em] text-fg-subtle", className), ...props });
+}
+export function PageHeaderDescription({ className, ...props }) {
+    return _jsx("p", { "data-slot": "page-header-description", className: cn("max-w-[62ch] text-[14.5px] leading-relaxed text-fg-muted", className), ...props });
+}
+export function PageHeaderActions({ className, ...props }) {
+    return _jsx("div", { "data-slot": "page-header-actions", className: cn("flex flex-wrap items-center gap-2", className), ...props });
+}
+/** Tabs row; pulls itself onto the header's bottom hairline. */
+export function PageHeaderTabs({ className, ...props }) {
+    return _jsx("div", { "data-slot": "page-header-tabs", className: cn("-mb-px mt-1 border-b border-line", className), ...props });
+}

package/dist/components/pagination.d.ts

@@ -0,0 +1,121 @@
+import * as React from "react";
+declare const paginationLabels: {
+    label: string;
+    previous: string;
+    next: string;
+    previousPage: string;
+    nextPage: string;
+    goTo: string;
+    page: string;
+    range: string;
+    empty: string;
+    pageSize: string;
+    morePages: string;
+};
+type PaginationLabels = Partial<typeof paginationLabels>;
+export type PaginationRangeItem = number | "ellipsis-start" | "ellipsis-end";
+export interface PaginationRangeOptions {
+    /** Current page, 1-based. */
+    page: number;
+    pageCount: number;
+    /** Pages shown on each side of the current one. Default 1. */
+    siblingCount?: number;
+    /** Pages always shown at the start and end. Default 1. */
+    boundaryCount?: number;
+}
+/**
+ * The page numbers to render, with ellipsis markers. The length stays constant while paging
+ * (no jumping buttons): `paginationRange({ page: 6, pageCount: 20 })` → `[1, "ellipsis-start", 5, 6, 7, "ellipsis-end", 20]`.
+ * A gap of exactly one page shows the page instead of "…".
+ */
+export declare function paginationRange({ page, pageCount, siblingCount, boundaryCount }: PaginationRangeOptions): PaginationRangeItem[];
+/** Memoised `paginationRange` for components. */
+export declare function usePaginationRange(options: PaginationRangeOptions): PaginationRangeItem[];
+type PaginationSize = "sm" | "md";
+/** The `<ul>` of page items. */
+export declare const PaginationList: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLUListElement> & React.RefAttributes<HTMLUListElement>>;
+/** One `<li>`. */
+export declare const PaginationItem: React.ForwardRefExoticComponent<React.LiHTMLAttributes<HTMLLIElement> & React.RefAttributes<HTMLLIElement>>;
+export interface PaginationLinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement> & React.ButtonHTMLAttributes<HTMLButtonElement>, "href" | "type"> {
+    /** Real link (SEO, blog archives). Without it the item is a `<button>`. */
+    href?: string;
+    /** The current page (`aria-current="page"`). */
+    isActive?: boolean;
+    disabled?: boolean;
+    /** Spinner in place of the label (current page while the next page loads). */
+    loading?: boolean;
+}
+/** A page number, or the shell for Previous / Next. Router `Link` when `href` is set, else a button. */
+export declare const PaginationLink: React.ForwardRefExoticComponent<PaginationLinkProps & React.RefAttributes<HTMLElement>>;
+export interface PaginationStepProps extends PaginationLinkProps {
+    /** Show the word next to the arrow ("Previous"). Default: only the arrow; the name is always "Previous page". */
+    showLabel?: boolean;
+    labels?: PaginationLabels;
+}
+/** Previous-page control. The arrow flips in RTL. */
+export declare const PaginationPrevious: React.ForwardRefExoticComponent<PaginationStepProps & React.RefAttributes<HTMLElement>>;
+/** Next-page control. The arrow flips in RTL. */
+export declare const PaginationNext: React.ForwardRefExoticComponent<PaginationStepProps & React.RefAttributes<HTMLElement>>;
+/** "…" between page numbers. */
+export declare function PaginationEllipsis({ className, labels, ...props }: React.HTMLAttributes<HTMLSpanElement> & {
+    labels?: PaginationLabels;
+}): React.JSX.Element;
+export interface PaginationProps extends Omit<React.HTMLAttributes<HTMLElement>, "onChange"> {
+    /** Current page, 1-based. */
+    page: number;
+    pageCount: number;
+    onPageChange?: (page: number) => void;
+    /** Web / SEO: real `<a href>` links through the app's router `Link`. */
+    getHref?: (page: number) => string;
+    /** Default 1. */
+    siblingCount?: number;
+    /** Default 1. */
+    boundaryCount?: number;
+    /** `numbers` (default), `compact` ("3 / 52" + arrows) or `simple` (Previous / Next). Below 640px `numbers` shows as `compact`. */
+    variant?: "numbers" | "compact" | "simple";
+    size?: PaginationSize;
+    /** Render nothing when there is only one page. Default `true`. */
+    hideOnSinglePage?: boolean;
+    /** Spinner on the current page and arrows locked while the next page loads. */
+    loading?: boolean;
+    labels?: PaginationLabels;
+}
+/**
+ * Page through a long list. 1-based `page`, props line up with TanStack Table state.
+ *
+ * ```tsx
+ * <Pagination page={page} pageCount={52} onPageChange={setPage} />
+ * <Pagination page={3} pageCount={12} getHref={(p) => `/blog?page=${p}`} />   // SEO links
+ * ```
+ *
+ * Moving focus to the top of the list after a page change is the consumer's job.
+ */
+export declare const Pagination: React.ForwardRefExoticComponent<PaginationProps & React.RefAttributes<HTMLElement>>;
+export interface PaginationBarProps extends Omit<PaginationProps, "pageCount"> {
+    /** Total number of rows. */
+    total: number;
+    pageSize: number;
+    /** Default `[10, 20, 50, 100]`. Pass `[]` to hide the page-size picker. */
+    pageSizeOptions?: number[];
+    onPageSizeChange?: (pageSize: number) => void;
+}
+/**
+ * The table footer: "1–20 of 312" + rows per page + page numbers. Changing the page size keeps the
+ * first visible row on screen (the page is recomputed) — the consumer receives both callbacks.
+ */
+export declare const PaginationBar: React.ForwardRefExoticComponent<PaginationBarProps & React.RefAttributes<HTMLDivElement>>;
+export interface CursorPaginationProps extends React.HTMLAttributes<HTMLElement> {
+    hasPrev: boolean;
+    hasNext: boolean;
+    onPrev?: () => void;
+    onNext?: () => void;
+    /** Locks both buttons and shows a spinner on the one that was pressed. */
+    loading?: boolean;
+    /** Optional status in the middle, e.g. "Showing 50 contacts". */
+    status?: React.ReactNode;
+    size?: PaginationSize;
+    labels?: PaginationLabels;
+}
+/** Previous / Next for cursor APIs where the total is unknown. */
+export declare const CursorPagination: React.ForwardRefExoticComponent<CursorPaginationProps & React.RefAttributes<HTMLElement>>;
+export {};