basalt-ui 1.26.0 → 1.28.0

package/dist/nav/types.d.ts

@@ -67,11 +67,14 @@ export type SidebarSection = {
     mobile?: false | NavSectionMobile;
 };
 /**
- * Status tone on a sidebar-block item — the same three-member vocabulary as `StatCardTone`, whose
- * members are `VX.status` keys by construction. Declared here rather than imported from
- * `../dashboard/stat-card`: this module is the one `./router-tanstack` reads, and even a
- * type-only edge into the Mantine layer would make `nav/types.d.ts` unresolvable without
- * `@mantine/core` installed.
+ * Status tone on a sidebar-block item — byte-identical to the common `Tone` vocabulary
+ * (`common/props.ts`, audit A13) and to `StatCardTone`, whose members are `VX.status` keys by
+ * construction. Declared here rather than aliased to `common`'s `Tone`: this module is the one
+ * `./router-tanstack` reads, and `common/props.ts` re-exports `Tier` (type-only) from
+ * `../widget-header/widget-header`, a Mantine-coupled file — importing anything from `common/props`
+ * here would pull that whole module's declaration graph into `nav/types.d.ts`, making it
+ * unresolvable without `@mantine/core` installed. Kept in step with `Tone` by convention, not by
+ * import.
  */
 export type SidebarBlockTone = 'good' | 'warn' | 'bad';
 /** One row inside a `kind: 'list'` block. Same router seam as `SidebarItem` — `Anchor`, then href. */
@@ -180,7 +183,13 @@ export type MobileNavConfig = {
     menuMax?: number;
     /** @default 'More' */
     moreLabel?: string;
-    /** Scroll container for active-slot re-tap. @default document.scrollingElement */
+    /**
+     * Scroll container for active-slot re-tap. Only needed when the page scrolls somewhere basalt
+     * cannot see — inside a shell the default already resolves `AppShell.Main`
+     * (`[data-basalt-scrollport]`), and outside one it falls back to the document.
+     *
+     * @default the `[data-basalt-scrollport]` element, else `document.scrollingElement`
+     */
     getScrollElement?: () => HTMLElement | null;
 };
 //# sourceMappingURL=types.d.ts.map

package/dist/nav/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/nav/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/nav/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAElD,6FAA6F;AAC7F,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAA;AAE1D;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAA;IAC9C,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AACD,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,SAAS,CAAA;AAE5D,gCAAgC;AAChC,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,gFAAgF;IAChF,MAAM,CAAC,EAAE,OAAO,GAAG,kBAAkB,CAAA;IACrC,IAAI,EAAE,SAAS,CAAA;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,gGAAgG;IAChG,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAA;IACjC,+DAA+D;IAC/D,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;4DACwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAA;CACzB,CAAA;AAED,qFAAqF;AACrF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,0FAA0F;IAC1F,GAAG,CAAC,EAAE,IAAI,CAAA;IACV,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,+DAA+D;IAC/D,IAAI,CAAC,EAAE,SAAS,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,WAAW,EAAE,CAAA;IACpB,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,wFAAwF;IACxF,MAAM,CAAC,EAAE,KAAK,GAAG,gBAAgB,CAAA;CAClC,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAA;AAEtD,sGAAsG;AACtG,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,6FAA6F;IAC7F,IAAI,CAAC,EAAE,gBAAgB,CAAA;IACvB,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;CACrB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,wEAAwE;IACxE,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,gBAAgB,EAAE,CAAA;IACzB,qBAAqB;IACrB,SAAS,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAA;IAC5B,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,0FAA0F;IAC1F,IAAI,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAA;IACvB,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;CAC3B,CAAA;AAED,mGAAmG;AACnG,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,UAAU,CAAA;IAChB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,iEAAiE;IACjE,SAAS,CAAC,EAAE,QAAQ,CAAA;IACpB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;IACxB,wBAAwB;IACxB,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;CAC3B,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,QAAQ,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,SAAS,CAAA;IACf,qBAAqB;IACrB,SAAS,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAA;CAC7B,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,gBAAgB,GAAG,oBAAoB,GAAG,kBAAkB,CAAA;AAEvF,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAExD,8EAA8E;AAC9E,MAAM,MAAM,cAAc,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,WAAW,EAAE,CAAA;CAAE,CAAA;AAElF,MAAM,MAAM,aAAa,GACrB;IACE,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,SAAS,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;IACf,IAAI,EAAE,WAAW,CAAA;CAClB,GACD;IACE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IACtB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,SAAS,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,cAAc,EAAE,CAAA;IACxB,MAAM,EAAE,OAAO,CAAA;CAChB,CAAA;AAEL,6EAA6E;AAC7E,MAAM,MAAM,cAAc,GAAG;IAAE,KAAK,EAAE,aAAa,EAAE,CAAA;CAAE,CAAA;AAEvD,MAAM,MAAM,eAAe,GAAG;IAC5B,wFAAwF;IACxF,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACxB,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sBAAsB;IACtB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAA;CAC5C,CAAA"}

package/dist/notifications/bell.d.ts

@@ -1,4 +1,5 @@
-export type NotificationBellProps = {
+import type { BasaltProps } from '../common/props.js';
+export type NotificationBellProps = BasaltProps & {
     /** Tooltip label. Default: 'Notifications'. */
     label?: string;
 };
@@ -11,5 +12,5 @@ export type NotificationBellProps = {
  *   {...rest}
  * />
  */
-export declare function NotificationBell({ label }: NotificationBellProps): import("react").JSX.Element;
+export declare function NotificationBell({ label, className, style, }: NotificationBellProps): import("react").JSX.Element;
 //# sourceMappingURL=bell.d.ts.map

package/dist/notifications/bell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bell.d.ts","sourceRoot":"","sources":["../../src/notifications/bell.tsx"],"names":[],"mappings":"AA0BA,MAAM,MAAM,qBAAqB,GAAG;IAClC,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,KAAuB,EAAE,EAAE,qBAAqB,+BAsElF"}
+{"version":3,"file":"bell.d.ts","sourceRoot":"","sources":["../../src/notifications/bell.tsx"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAOlD,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG;IAChD,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,KAAuB,EACvB,SAAS,EACT,KAAK,GACN,EAAE,qBAAqB,+BA+EvB"}

package/dist/notifications/bell.js

@@ -3,10 +3,14 @@ import { ActionIcon, Indicator, Popover } from "@mantine/core";
 import { useDisclosure } from "@mantine/hooks";
 import { useRef } from "react";
 import { useNotificationHistory } from "./store.js";
-import { NotificationCenter } from "./center.js";
+import { NOTIFICATION_POPOVER_WIDTH, NotificationCenter } from "./center.js";
 const HOVER_OPEN_DELAY = 150;
 const HOVER_CLOSE_DELAY = 200;
-function NotificationBell({ label = "Notifications" }) {
+function NotificationBell({
+  label = "Notifications",
+  className,
+  style
+}) {
   const [opened, { open, toggle, close }] = useDisclosure(false);
   const { unreadCount } = useNotificationHistory();
   const timer = useRef(void 0);
@@ -18,66 +22,79 @@ function NotificationBell({ label = "Notifications" }) {
     clearTimeout(timer.current);
     timer.current = setTimeout(() => close(), HOVER_CLOSE_DELAY);
   };
-  return /* @__PURE__ */ jsxs(Popover, { opened, onClose: close, position: "bottom-end", withArrow: true, withinPortal: true, children: [
-    /* @__PURE__ */ jsx(Popover.Target, { children: /* @__PURE__ */ jsx(
-      Indicator,
-      {
-        color: "color-mix(in srgb, var(--vx-ink) 8%, transparent)",
-        size: 16,
-        label: unreadCount > 9 ? "9+" : String(unreadCount),
-        disabled: unreadCount === 0,
-        processing: false,
-        styles: {
-          indicator: {
-            color: "var(--vx-ink)",
-            fontFamily: "var(--basalt-font-mono)",
-            fontWeight: 500
-          }
-        },
-        children: /* @__PURE__ */ jsx(
-          ActionIcon,
+  return /* @__PURE__ */ jsxs(
+    Popover,
+    {
+      opened,
+      onClose: close,
+      position: "bottom-end",
+      width: NOTIFICATION_POPOVER_WIDTH,
+      withArrow: true,
+      withinPortal: true,
+      children: [
+        /* @__PURE__ */ jsx(Popover.Target, { children: /* @__PURE__ */ jsx(
+          Indicator,
           {
-            variant: "transparent",
-            color: "gray",
-            onClick: toggle,
-            onMouseEnter: scheduleOpen,
-            onMouseLeave: scheduleClose,
-            "aria-label": label,
-            "aria-expanded": opened,
-            "aria-haspopup": "dialog",
-            children: /* @__PURE__ */ jsxs(
-              "svg",
+            color: "color-mix(in srgb, var(--vx-ink) 8%, transparent)",
+            size: 16,
+            label: unreadCount > 9 ? "9+" : String(unreadCount),
+            disabled: unreadCount === 0,
+            processing: false,
+            styles: {
+              indicator: {
+                color: "var(--vx-ink)",
+                fontFamily: "var(--basalt-font-mono)",
+                fontWeight: 500
+              }
+            },
+            children: /* @__PURE__ */ jsx(
+              ActionIcon,
               {
-                width: 18,
-                height: 18,
-                viewBox: "0 0 24 24",
-                fill: "none",
-                stroke: "var(--mantine-color-dimmed)",
-                strokeWidth: 2,
-                strokeLinecap: "round",
-                strokeLinejoin: "round",
-                "aria-hidden": true,
-                children: [
-                  /* @__PURE__ */ jsx("path", { d: "M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9" }),
-                  /* @__PURE__ */ jsx("path", { d: "M13.73 21a2 2 0 0 1-3.46 0" })
-                ]
+                variant: "transparent",
+                color: "gray",
+                onClick: toggle,
+                onMouseEnter: scheduleOpen,
+                onMouseLeave: scheduleClose,
+                "aria-label": label,
+                "aria-expanded": opened,
+                "aria-haspopup": "dialog",
+                ...className !== void 0 && { className },
+                ...style !== void 0 && { style },
+                children: /* @__PURE__ */ jsxs(
+                  "svg",
+                  {
+                    width: 18,
+                    height: 18,
+                    viewBox: "0 0 24 24",
+                    fill: "none",
+                    stroke: "var(--mantine-color-dimmed)",
+                    strokeWidth: 2,
+                    strokeLinecap: "round",
+                    strokeLinejoin: "round",
+                    "aria-hidden": true,
+                    children: [
+                      /* @__PURE__ */ jsx("path", { d: "M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9" }),
+                      /* @__PURE__ */ jsx("path", { d: "M13.73 21a2 2 0 0 1-3.46 0" })
+                    ]
+                  }
+                )
               }
             )
           }
+        ) }),
+        /* @__PURE__ */ jsx(
+          Popover.Dropdown,
+          {
+            p: "md",
+            "aria-label": "Notification center",
+            onMouseEnter: scheduleOpen,
+            onMouseLeave: scheduleClose,
+            children: /* @__PURE__ */ jsx(NotificationCenter, {})
+          }
         )
-      }
-    ) }),
-    /* @__PURE__ */ jsx(
-      Popover.Dropdown,
-      {
-        p: "md",
-        "aria-label": "Notification center",
-        onMouseEnter: scheduleOpen,
-        onMouseLeave: scheduleClose,
-        children: /* @__PURE__ */ jsx(NotificationCenter, {})
-      }
-    )
-  ] });
+      ]
+    }
+  );
 }
 export {
   NotificationBell

package/dist/notifications/center.d.ts

@@ -1,4 +1,9 @@
-export type NotificationCenterProps = {
+import type { BasaltProps } from '../common/props.js';
+/** The popover width `NotificationBell` fixes at the `Popover` level (see `NotificationCenter`'s
+ *  own doc for why WIDTH lives there and not on this component). Shared so the two call sites and
+ *  this doc's example never drift apart. */
+export declare const NOTIFICATION_POPOVER_WIDTH = 320;
+export type NotificationCenterProps = BasaltProps & {
     /** Maximum height of the scrollable list. Default: 320px. */
     maxHeight?: number | string;
 };
@@ -7,14 +12,20 @@ export type NotificationCenterProps = {
  * registry-resolved action buttons. Designed to be mounted inside a Popover or Drawer (e.g.
  * NotificationBell).
  *
+ * Sizes to its host's full width (`width: 100%`) rather than a fixed px — a popover default that
+ * overflowed any inline mount. `NotificationBell` fixes the WIDTH at the Popover level instead
+ * (`<Popover width={NOTIFICATION_POPOVER_WIDTH}>`), which is the correct home for a
+ * popover-specific dimension; a consumer mounting this directly controls the same thing through
+ * its own container.
+ *
  * @example
- * import { NotificationCenter } from 'basalt-ui/notifications'
+ * import { NOTIFICATION_POPOVER_WIDTH, NotificationCenter } from 'basalt-ui/notifications'
  *
- * <Popover>
+ * <Popover width={NOTIFICATION_POPOVER_WIDTH}>
  *   <Popover.Dropdown>
  *     <NotificationCenter />
  *   </Popover.Dropdown>
  * </Popover>
  */
-export declare function NotificationCenter({ maxHeight }: NotificationCenterProps): import("react").JSX.Element;
+export declare function NotificationCenter({ maxHeight, className, style }: NotificationCenterProps): import("react").JSX.Element;
 //# sourceMappingURL=center.d.ts.map

package/dist/notifications/center.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"center.d.ts","sourceRoot":"","sources":["../../src/notifications/center.tsx"],"names":[],"mappings":"AAwJA,MAAM,MAAM,uBAAuB,GAAG;IACpC,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,SAAe,EAAE,EAAE,uBAAuB,+BAyE9E"}
+{"version":3,"file":"center.d.ts","sourceRoot":"","sources":["../../src/notifications/center.tsx"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAyClD;;4CAE4C;AAC5C,eAAO,MAAM,0BAA0B,MAAM,CAAA;AAwF7C,MAAM,MAAM,uBAAuB,GAAG,WAAW,GAAG;IAClD,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,SAAe,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,uBAAuB,+BAyEhG"}

package/dist/notifications/center.js

@@ -10,6 +10,7 @@ import {
   Stack,
   Text
 } from "@mantine/core";
+import { cx } from "../common/props.js";
 import { VX } from "../tokens/index.js";
 import { resolveAction } from "./define-notifications.js";
 import { useNotificationHistory } from "./store.js";
@@ -35,6 +36,7 @@ const INTENT_STATUS = {
   warning: VX.status.warn,
   info: VX.accent
 };
+const NOTIFICATION_POPOVER_WIDTH = 320;
 function NotificationItem({
   item,
   view,
@@ -101,12 +103,12 @@ function NotificationItem({
     }
   );
 }
-function NotificationCenter({ maxHeight = 320 }) {
+function NotificationCenter({ maxHeight = 320, className, style }) {
   const { items, inbox, unreadCount, markRead, markAllRead, dismiss, dismissAll, remove, clear } = useNotificationHistory();
   const [view, setView] = useState("inbox");
   const list = view === "inbox" ? inbox : items;
   const emptyLabel = view === "inbox" ? "You're all caught up" : "No notifications yet";
-  return /* @__PURE__ */ jsxs(Stack, { gap: "xs", style: { width: 320 }, children: [
+  return /* @__PURE__ */ jsxs(Stack, { className: cx(className), gap: "xs", style: { width: "100%", ...style }, children: [
     /* @__PURE__ */ jsxs(Group, { justify: "space-between", align: "center", wrap: "nowrap", children: [
       /* @__PURE__ */ jsx(Text, { size: "sm", fw: 600, children: "Notifications" }),
       unreadCount > 0 && /* @__PURE__ */ jsx(Button, { variant: "subtle", size: "compact-xs", onClick: markAllRead, children: "Mark all read" })
@@ -140,5 +142,6 @@ function NotificationCenter({ maxHeight = 320 }) {
   ] });
 }
 export {
+  NOTIFICATION_POPOVER_WIDTH,
   NotificationCenter
 };

package/dist/notifications/define-notifications.d.ts

@@ -5,6 +5,11 @@
  * Consumer augments BasaltRegister.notifications with the spec map type, then uses the typed
  * `emit` helper which resolves the registered kind at compile-time. An unknown kind is a tsc error.
  *
+ * A kind's payload type is INFERRED, the same way `defineOverlays` infers an overlay's props from
+ * `render` — annotate `toMessage` (or `action.run`) with the payload shape and `emit` picks it up:
+ * `emit('saved', { id })` then requires that shape and a wrong one is a tsc error. A kind that never
+ * annotates either function keeps today's `payload?: unknown` — additive, no existing call breaks.
+ *
  * @example
  * // notifications.ts (app-side)
  * import { defineNotifications } from 'basalt-ui/notifications'
@@ -18,8 +23,9 @@
  *
  * // usage.ts
  * import { emit } from 'basalt-ui/notifications'
- * emit('upload:success', { name: 'photo.jpg' })  // ✓ typed
- * emit('nonexistent', {})                         // ✗ tsc error
+ * emit('upload:success', { name: 'photo.jpg' })  // ✓ typed, and the payload shape is checked
+ * emit('upload:success', 'nope')                  // ✗ tsc error — wrong payload shape
+ * emit('nonexistent', {})                         // ✗ tsc error — unregistered kind
  */
 import type { ReactNode } from 'react';
 import type { Slot } from '../register.js';
@@ -31,19 +37,28 @@ export type { NotificationIntent };
  * registry (code, app-scoped) — only a serializable `{ kind, payload }` ref is persisted — so an
  * actionable notification keeps working after a reload. The handler can do anything (navigate, open
  * a modal, retry a request); it receives the same payload that was passed to `emit`.
+ *
+ * The payload type P is the consumer's own payload — same generic shape as `Overlay<P>` in
+ * ./define-overlays, inferred from `run`'s parameter, not a separate declared field.
  */
-export type NotificationAction = {
+export type NotificationAction<P = unknown> = {
     label: string;
-    run: (payload: unknown) => void;
+    run: (payload: P) => void;
 };
-/** A single notification kind spec — intent + optional payload→message renderer + optional action. */
-export type NotificationSpec = {
+/**
+ * A single notification kind spec — intent + optional payload→message renderer + optional action.
+ *
+ * The payload type P is INFERRED from `toMessage`/`action.run`'s parameter, the same mechanism
+ * `defineOverlays`' `Overlay<P>` uses for `render`. Default `unknown` — a kind that annotates
+ * neither function keeps taking any payload, unchanged.
+ */
+export type NotificationSpec<P = unknown> = {
     intent?: NotificationIntent;
-    toMessage?: (payload: unknown) => ReactNode;
-    action?: NotificationAction;
+    toMessage?: (payload: P) => ReactNode;
+    action?: NotificationAction<P>;
 };
 /** The map of kind → spec that a consumer registers. */
-export type NotificationSpecMap = Record<string, NotificationSpec>;
+export type NotificationSpecMap = Record<string, NotificationSpec<any>>;
 /** The consumer's registered notification spec map, or `{}` when un-augmented. */
 type Notifications = Slot<'notifications', NotificationSpecMap>;
 /**
@@ -53,8 +68,27 @@ type Notifications = Slot<'notifications', NotificationSpecMap>;
  */
 export type NotificationKind = Extract<keyof Notifications, string>;
 /**
- * Type a single notification spec without registering it.
- * Identity passthrough — preserves the exact literal shape for local type-checking.
+ * Extract the inferred payload type for a registered notification kind — mirrors `OverlayProps` in
+ * ./define-overlays (same `infer` over the generic spec type, not a separate declared field).
+ *
+ * Resolves to `unknown` for a kind whose spec never annotates `toMessage`/`action.run` with a
+ * payload shape — that is the additive fallback, not a failure to infer.
+ */
+type NotificationPayload<K extends NotificationKind> = Notifications extends {
+    [_K in K]: NotificationSpec<infer V>;
+} ? V : unknown;
+/**
+ * Type a single notification spec without registering it. Identity passthrough — the payload type
+ * `P` is INFERRED from `toMessage`/`action.run`'s parameter, exactly as it is inside
+ * `defineNotifications`, so a spec typed here and a spec written inline behave identically.
+ *
+ * **It is `NotificationSpec<P>`, NOT `<const T extends NotificationSpec>(spec: T): T`** — the
+ * const-generic shape every other `defineX` factory takes. Under `strictFunctionTypes` that
+ * constraint rejects the example below outright: `T` must extend `NotificationSpec<unknown>`, and a
+ * `toMessage: (p: { name: string }) => …` is not assignable to `(payload: unknown) => …`
+ * (parameters are contravariant). The factory's own documented usage did not compile. Inferring `P`
+ * instead is what makes an annotated payload the point of this file rather than a type error.
+ * `.type-guard.test.ts` pins both halves.
  *
  * **WARNING:** this does NOT register the spec in the runtime registry and does NOT
  * augment BasaltRegister. Use `defineNotifications` (plural) to register a full spec
@@ -69,8 +103,15 @@ export type NotificationKind = Extract<keyof Notifications, string>;
  * // Merge into the full registry before passing to defineNotifications:
  * const NOTIFICATIONS = defineNotifications({ 'upload:success': uploadSuccess })
  */
-export declare function defineNotification<const T extends NotificationSpec>(spec: T): T;
+export declare function defineNotification<P = unknown>(spec: NotificationSpec<P>): NotificationSpec<P>;
 export declare function defineNotifications<const T extends NotificationSpecMap>(spec: T): T;
+/**
+ * The rest-args tuple for `emit`'s payload + opts. A kind whose spec declared a payload shape
+ * (`NotificationPayload<K>` is narrower than `unknown`) requires that shape as a real argument; a
+ * kind that never declared one keeps `payload?: unknown` — the pre-existing, backward-compatible
+ * shape.
+ */
+type EmitArgs<K extends NotificationKind> = [unknown] extends [NotificationPayload<K>] ? [payload?: unknown, opts?: Omit<NotifyOptions, 'intent' | 'message'>] : [payload: NotificationPayload<K>, opts?: Omit<NotifyOptions, 'intent' | 'message'>];
 /**
  * Emit a registered notification kind. The kind must be a key of the consumer's registered
  * `BasaltRegister.notifications` map — any other string is a tsc error.
@@ -78,13 +119,14 @@ export declare function defineNotifications<const T extends NotificationSpecMap>
  * Resolves the spec's intent + toMessage, then calls notify(). Extra opts override spec defaults.
  *
  * Un-augmented (Notifications = {}): NotificationKind = never → `emit` is effectively uncallable.
- * Augmented: only the registered keys are accepted.
+ * Augmented: only the registered keys are accepted, and a kind whose spec annotated
+ * `toMessage`/`action.run` with a payload shape requires that shape — see {@link NotificationPayload}.
  *
  * @example
  * emit('upload:success', { name: 'photo.jpg' })
  * emit('upload:error', null, { title: 'Storage full' })
  */
-export declare function emit(kind: NotificationKind, payload?: unknown, opts?: Omit<NotifyOptions, 'intent' | 'message'>): string;
+export declare function emit<K extends NotificationKind>(kind: K, ...args: EmitArgs<K>): string;
 /**
  * Resolve a persisted action ref against the active registry — returns the button label and a
  * bound handler, or undefined if the kind is unregistered (e.g. the registry changed since the

package/dist/notifications/define-notifications.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-notifications.d.ts","sourceRoot":"","sources":["../../src/notifications/define-notifications.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAEvC,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AACjE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAEpD,YAAY,EAAE,kBAAkB,EAAE,CAAA;AAIlC;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CAChC,CAAA;AAID,sGAAsG;AACtG,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,SAAS,CAAA;IAC3C,MAAM,CAAC,EAAE,kBAAkB,CAAA;CAC5B,CAAA;AAED,wDAAwD;AACxD,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;AAIlE,kFAAkF;AAClF,KAAK,aAAa,GAAG,IAAI,CAAC,eAAe,EAAE,mBAAmB,CAAC,CAAA;AAE/D;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,MAAM,aAAa,EAAE,MAAM,CAAC,CAAA;AAInE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,CAAC,SAAS,gBAAgB,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAE/E;AAsBD,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,CAAC,SAAS,mBAAmB,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAGnF;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI,CAClB,IAAI,EAAE,gBAAgB,EACtB,OAAO,CAAC,EAAE,OAAO,EACjB,IAAI,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,SAAS,CAAC,GAC/C,MAAM,CAWR;AAID;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,qBAAqB,GACzB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,IAAI,CAAA;CAAE,GAAG,SAAS,CAIhD"}
+{"version":3,"file":"define-notifications.d.ts","sourceRoot":"","sources":["../../src/notifications/define-notifications.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAEvC,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AACjE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAEpD,YAAY,EAAE,kBAAkB,EAAE,CAAA;AAIlC;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,GAAG,OAAO,IAAI;IAC5C,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAAA;CAC1B,CAAA;AAID;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,GAAG,OAAO,IAAI;IAC1C,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,SAAS,CAAA;IACrC,MAAM,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAA;CAC/B,CAAA;AAED,wDAAwD;AAExD,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAA;AAIvE,kFAAkF;AAClF,KAAK,aAAa,GAAG,IAAI,CAAC,eAAe,EAAE,mBAAmB,CAAC,CAAA;AAE/D;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,MAAM,aAAa,EAAE,MAAM,CAAC,CAAA;AAEnE;;;;;;GAMG;AACH,KAAK,mBAAmB,CAAC,CAAC,SAAS,gBAAgB,IAAI,aAAa,SAAS;KAC1E,EAAE,IAAI,CAAC,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;CACrC,GACG,CAAC,GACD,OAAO,CAAA;AAIX;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAE9F;AAsBD,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,CAAC,SAAS,mBAAmB,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAGnF;AAID;;;;;GAKG;AACH,KAAK,QAAQ,CAAC,CAAC,SAAS,gBAAgB,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,GAClF,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,SAAS,CAAC,CAAC,GACrE,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAA;AAEvF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,gBAAgB,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,MAAM,CAYtF;AAID;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,qBAAqB,GACzB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,IAAI,CAAA;CAAE,GAAG,SAAS,CAIhD"}

package/dist/notifications/define-notifications.js

@@ -7,7 +7,8 @@ function defineNotifications(spec) {
   activeRegistry = spec;
   return spec;
 }
-function emit(kind, payload, opts) {
+function emit(kind, ...args) {
+  const [payload, opts] = args;
   const spec = activeRegistry[kind];
   const intent = spec?.intent ?? "info";
   const message = spec?.toMessage !== void 0 ? spec.toMessage(payload) : kind;

package/dist/notifications/index.d.ts

@@ -19,11 +19,15 @@
  * notifyError('Failed', { title: 'Upload error' })
  * notifyPromise(save(), { loading: 'Saving…', success: 'Saved', error: 'Failed' })
  *
+ * // Optimistic mutation with an undo window (the toast's autoClose IS the window):
+ * import { notifyUndo } from 'basalt-ui/notifications'
+ * notifyUndo({ message: 'Item deleted', onUndo: () => restore(), onExpire: () => api.delete(id) })
+ *
  * // Shell bell (globalActions slot):
  * <BasaltShell globalActions={[{ key: 'notifications', node: <NotificationBell />, mobile: 'bar' }]} ... />
  */
-export { notify, notifySuccess, notifyError, notifyWarning, notifyInfo, notifyPromise, } from './notify.js';
-export type { NotifyOptions, NotifyPromiseMessages } from './notify.js';
+export { notify, notifySuccess, notifyError, notifyWarning, notifyInfo, notifyPromise, notifyUndo, notifyUndoable, } from './notify.js';
+export type { NotifyOptions, NotifyPromiseMessages, NotifyUndoOptions, NotifyUndoHandle, } from './notify.js';
 export { defineNotification, defineNotifications, emit, resolveAction, type NotificationAction, type NotificationKind, type NotificationSpec, type NotificationSpecMap, type NotificationIntent, } from './define-notifications.js';
 export { add, markRead, markAllRead, dismiss, dismissAll, remove, clear, needsAttention, useNotificationHistory, } from './store.js';
 export type { NotificationActionRef, NotificationHistoryItem, NotificationHistoryState, UseNotificationHistoryReturn, } from './store.js';

package/dist/notifications/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/notifications/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EACL,MAAM,EACN,aAAa,EACb,WAAW,EACX,aAAa,EACb,UAAU,EACV,aAAa,GACd,MAAM,UAAU,CAAA;AACjB,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAA;AAGpE,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,IAAI,EACJ,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,wBAAwB,CAAA;AAG/B,OAAO,EACL,GAAG,EACH,QAAQ,EACR,WAAW,EACX,OAAO,EACP,UAAU,EACV,MAAM,EACN,KAAK,EACL,cAAc,EACd,sBAAsB,GACvB,MAAM,SAAS,CAAA;AAChB,YAAY,EACV,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAA;AACzC,YAAY,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAA;AAGnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAC7C,YAAY,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAA;AAGvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAC/C,YAAY,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/notifications/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EACL,MAAM,EACN,aAAa,EACb,WAAW,EACX,aAAa,EACb,UAAU,EACV,aAAa,EACb,UAAU,EACV,cAAc,GACf,MAAM,UAAU,CAAA;AACjB,YAAY,EACV,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,UAAU,CAAA;AAGjB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,IAAI,EACJ,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,wBAAwB,CAAA;AAG/B,OAAO,EACL,GAAG,EACH,QAAQ,EACR,WAAW,EACX,OAAO,EACP,UAAU,EACV,MAAM,EACN,KAAK,EACL,cAAc,EACd,sBAAsB,GACvB,MAAM,SAAS,CAAA;AAChB,YAAY,EACV,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAA;AACzC,YAAY,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAA;AAGnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAC7C,YAAY,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAA;AAGvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAC/C,YAAY,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAA"}

package/dist/notifications/index.js

@@ -4,7 +4,9 @@ import {
   notifyError,
   notifyWarning,
   notifyInfo,
-  notifyPromise
+  notifyPromise,
+  notifyUndo,
+  notifyUndoable
 } from "./notify.js";
 import {
   defineNotification,
@@ -45,6 +47,8 @@ export {
   notifyInfo,
   notifyPromise,
   notifySuccess,
+  notifyUndo,
+  notifyUndoable,
   notifyWarning,
   remove,
   resolveAction,

package/dist/notifications/mount-guard.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Call from any component that renders a `<Notifications />` overlay. Warns in dev when a second
+ * caller is mounted at the same time. Not a false positive under React 18 StrictMode's double-invoke
+ * (that mounts/unmounts the SAME instance in sequence, so the count returns to 0 before a genuine
+ * second instance could exist).
+ */
+export declare function useNotificationsMountGuard(): void;
+//# sourceMappingURL=mount-guard.d.ts.map

package/dist/notifications/mount-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-guard.d.ts","sourceRoot":"","sources":["../../src/notifications/mount-guard.ts"],"names":[],"mappings":"AAoBA;;;;;GAKG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAcjD"}

package/dist/notifications/mount-guard.js

@@ -0,0 +1,19 @@
+import { useEffect } from "react";
+import { isDev } from "../utils/is-dev.js";
+let mountedNotificationsCount = 0;
+function useNotificationsMountGuard() {
+  useEffect(() => {
+    mountedNotificationsCount++;
+    if (mountedNotificationsCount > 1 && isDev()) {
+      console.warn(
+        "[basalt] more than one Notifications overlay is mounted at once \u2014 mount ONE of <BasaltOverlays notifications /> or <BasaltNotifications />, never both (they both render Mantine's <Notifications />, so toasts would double-fire)."
+      );
+    }
+    return () => {
+      mountedNotificationsCount--;
+    };
+  }, []);
+}
+export {
+  useNotificationsMountGuard
+};

package/dist/notifications/notify.d.ts

@@ -7,7 +7,8 @@
  *   2. dedupKey window — module-level Map prevents duplicate keys within 1500ms
  *
  * For loading→success/error transitions use notifyPromise — it calls notifications.update
- * (never show()) so the loading state is replaced correctly.
+ * (never show()) so the loading state is replaced correctly. For an optimistic mutation with a
+ * grace period use notifyUndo — one number is both the Undo affordance and the commit delay.
  *
  * @example
  * notify({ intent: 'success', message: 'Saved' })
@@ -31,6 +32,12 @@ export type NotifyOptions = {
      * only when calling `notify()` for an action registered in the notifications registry.
      */
     action?: NotificationActionRef;
+    /**
+     * What the persisted history records instead of `String(message)`. Only needed when `message` is
+     * a composed ReactNode the store cannot stringify — `String(<Group/>)` is `[object Object]`.
+     * `notifyUndo` passes its plain text here because its toast body carries the Undo button.
+     */
+    historyMessage?: string;
 };
 /**
  * Show a toast and record it to the notification history.
@@ -70,6 +77,56 @@ export declare function notifyWarning(message: ReactNode, opts?: Omit<NotifyOpti
  * notifyInfo('New version available')
  */
 export declare function notifyInfo(message: ReactNode, opts?: Omit<NotifyOptions, 'intent' | 'message'>): string;
+export type NotifyUndoOptions = {
+    /** The toast text, left of the Undo button. Also what the history records. */
+    message: ReactNode;
+    /** Revert the optimistic change. Runs once, on click; `onExpire` then never runs. */
+    onUndo: () => void;
+    /** How long the Undo button stays offered, in ms. Also the toast's autoClose. Default: 6000. */
+    window?: number;
+    /**
+     * The window elapsed with no undo — the place to COMMIT the optimistic mutation. Runs at most
+     * once, and never after `onUndo`.
+     */
+    onExpire?: () => void;
+};
+export type NotifyUndoHandle = {
+    /** The toast id — the same id in Mantine and in the notification history. */
+    id: string;
+    /**
+     * Close the toast early and settle the window NOW: `onExpire` runs (unless undo already did), so
+     * a dismissed toast can never strand an uncommitted mutation. Idempotent.
+     */
+    dismiss: () => void;
+};
+/**
+ * Show a toast offering an Undo for `window` ms, then commit.
+ *
+ * The affordance and the grace period are ONE number: `autoClose === window`, so the button is on
+ * screen for exactly as long as undoing still does something. Exactly one of `onUndo` / `onExpire`
+ * runs, exactly once — clicking Undo cancels the timer, and letting it elapse (or calling
+ * `dismiss()`) commits.
+ *
+ * Built on `notify`, so the toast is recorded to the notification history like any other.
+ *
+ * @example
+ * // Optimistic delete: the row is already gone from the UI; commit when the window closes.
+ * setRows((rows) => rows.filter((r) => r.id !== id))
+ * notifyUndo({
+ *   message: 'Item deleted',
+ *   onUndo: () => setRows(before),
+ *   onExpire: () => api.delete(id),
+ * })
+ */
+export declare function notifyUndo(opts: NotifyUndoOptions): NotifyUndoHandle;
+/**
+ * `notifyUndo` for the common optimistic shape: the UI already changed, `undo` puts it back, and
+ * `mutate` is what actually commits when the window closes.
+ *
+ * @example
+ * notifyUndoable(() => api.delete(id), () => setRows(before), { message: 'Item deleted' })
+ */
+export declare function notifyUndoable(mutate: () => void, undo: () => void, opts: Omit<NotifyUndoOptions, 'onUndo' | 'onExpire'>): NotifyUndoHandle;
 export type NotifyPromiseMessages = {
     loading: ReactNode;
     success: ReactNode;

package/dist/notifications/notify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../../src/notifications/notify.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAExE,YAAY,EAAE,kBAAkB,EAAE,CAAA;AAoDlC,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,OAAO,EAAE,SAAS,CAAA;IAClB,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,qBAAqB,CAAA;CAC/B,CAAA;AAID;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAgClD;AAID;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,SAAS,EAClB,IAAI,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,SAAS,CAAC,GAC/C,MAAM,CAER;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,SAAS,EAClB,IAAI,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,SAAS,CAAC,GAC/C,MAAM,CAER;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,SAAS,EAClB,IAAI,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,SAAS,CAAC,GAC/C,MAAM,CAER;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,SAAS,EAClB,IAAI,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,SAAS,CAAC,GAC/C,MAAM,CAER;AAID,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,SAAS,CAAA;IAClB,OAAO,EAAE,SAAS,CAAA;IAClB,KAAK,EAAE,SAAS,CAAA;CACjB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,qBAAqB,GAAG,OAAO,CAAC,CAAC,CAAC,CAkDjG"}
+{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../../src/notifications/notify.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAExE,YAAY,EAAE,kBAAkB,EAAE,CAAA;AAoDlC,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,OAAO,EAAE,SAAS,CAAA;IAClB,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,qBAAqB,CAAA;IAC9B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAID;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CA0ClD;AAID;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,SAAS,EAClB,IAAI,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,SAAS,CAAC,GAC/C,MAAM,CAER;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,SAAS,EAClB,IAAI,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,SAAS,CAAC,GAC/C,MAAM,CAER;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,SAAS,EAClB,IAAI,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,SAAS,CAAC,GAC/C,MAAM,CAER;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,SAAS,EAClB,IAAI,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,SAAS,CAAC,GAC/C,MAAM,CAER;AAOD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,8EAA8E;IAC9E,OAAO,EAAE,SAAS,CAAA;IAClB,qFAAqF;IACrF,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,gGAAgG;IAChG,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,6EAA6E;IAC7E,EAAE,EAAE,MAAM,CAAA;IACV;;;OAGG;IACH,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,gBAAgB,CAoCpE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,IAAI,EAClB,IAAI,EAAE,MAAM,IAAI,EAChB,IAAI,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,UAAU,CAAC,GACnD,gBAAgB,CAElB;AAID,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,SAAS,CAAA;IAClB,OAAO,EAAE,SAAS,CAAA;IAClB,KAAK,EAAE,SAAS,CAAA;CACjB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,qBAAqB,GAAG,OAAO,CAAC,CAAC,CAAC,CAkDjG"}