@nucleux/proactive 0.0.0-stage → 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nucleux
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+# @nucleux/proactive
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Proactive Suggestions — invisible AI moments that arrive exactly when needed — Nucleux agentic UI for React.
+
+Part of **[Nucleux](https://github.com/intelligaia-open-labs/nucleux)** — agentic UI components for React. Install a single component, or the full kit via [`@nucleux/react`](https://www.npmjs.com/package/@nucleux/react).
+
+An unsolicited suggestion raised when the agent notices something specific and
+actionable. It leads with the finding, can show the evidence, offers exactly
+one next action plus a one-press dismiss (× or Escape) and an optional snooze,
+and does nothing until the person acts.
+
+## Exports
+
+- **`ProactiveSuggestion`**
+- Types: `ProactiveSuggestionProps`, `ProactiveSuggestionVariant`, `ProactiveSuggestionPersist`
+
+## Variants
+
+| `variant` | Use |
+| --- | --- |
+| `contextual-banner` (default) | At the top of a surface. |
+| `inline-suggestion` | A compact action beside the row or element it is about. |
+| `side-toast` | Fixed to the bottom-right corner (override with `className`). |
+
+## Behaviour
+
+- `title` (the finding), `description` (the recommendation), `reason` (the evidence), `actionLabel` + `onAction`.
+- `onAction` may return a promise: the action shows a spinner and `pendingLabel` meanwhile.
+- `evidenceKey` + `persist` (`"local"` default): a dismissal is remembered so the same facts never bring it back, and only one keyed suggestion shows per session.
+- `resolved` says "Resolved" and drops the actions. It sits in a polite live region, so its arrival is announced without taking focus.
+
+## Usage
+
+```tsx
+import { ProactiveSuggestion } from "@nucleux/proactive";
+
+<ProactiveSuggestion
+  agentName="Aria"
+  evidenceKey="renewals-2026-w17"
+  title="Three renewals expire this week"
+  description="Want Aria to draft outreach for each?"
+  actionLabel="Draft emails"
+  onAction={openReview}
+  onSnooze={remindTomorrow}
+/>
+```
+
+## Install
+
+```bash
+pnpm add @nucleux/proactive @nucleux/tokens
+```
+
+`react` / `react-dom` are peer dependencies.
+
+Requires the theme once in your app: `import "@nucleux/tokens/styles.css";`
+and the Tailwind preset from `@nucleux/tokens/preset`.
+
+## License
+
+MIT © Nucleux

package/dist/index.cjs

@@ -0,0 +1,253 @@
+"use client";
+'use strict';
+
+var React = require('react');
+var lucideReact = require('lucide-react');
+var utils = require('@nucleux/utils');
+var button = require('@nucleux/button');
+var spinner = require('@nucleux/spinner');
+var jsxRuntime = require('react/jsx-runtime');
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var React__namespace = /*#__PURE__*/_interopNamespace(React);
+
+// src/index.tsx
+var KEY = "nucleux:proactive:";
+var SESSION_KEY = "nucleux:proactive:session";
+function getStore(kind) {
+  try {
+    return typeof window === "undefined" ? null : kind === "session" ? window.sessionStorage : window.localStorage;
+  } catch {
+    return null;
+  }
+}
+function read(kind, key) {
+  try {
+    return getStore(kind)?.getItem(key) ?? null;
+  } catch {
+    return null;
+  }
+}
+function write(kind, key, value) {
+  try {
+    getStore(kind)?.setItem(key, value);
+  } catch {
+  }
+}
+var ProactiveSuggestion = React__namespace.forwardRef(
+  ({
+    variant = "contextual-banner",
+    title,
+    description,
+    reason,
+    agentName = "the assistant",
+    actionLabel,
+    onAction,
+    pendingLabel = "Preparing\u2026",
+    onSnooze,
+    snoozeLabel = "Not now",
+    onDismiss,
+    dismissLabel = "Dismiss suggestion",
+    open: openProp,
+    defaultOpen = true,
+    onOpenChange,
+    evidenceKey,
+    persist = "local",
+    resolved = false,
+    onImpression,
+    className,
+    onKeyDown,
+    ...props
+  }, ref) => {
+    const baseId = React__namespace.useId();
+    const titleId = `${baseId}-title`;
+    const [internalOpen, setInternalOpen] = React__namespace.useState(defaultOpen);
+    const open = openProp ?? internalOpen;
+    const remembering = evidenceKey != null && persist !== "none";
+    const [allowed, setAllowed] = React__namespace.useState(!remembering);
+    const [pending, setPending] = React__namespace.useState(false);
+    const mounted = React__namespace.useRef(true);
+    React__namespace.useEffect(
+      () => () => {
+        mounted.current = false;
+      },
+      []
+    );
+    React__namespace.useEffect(() => {
+      if (!remembering) {
+        setAllowed(true);
+        return;
+      }
+      const dismissed = read(persist, KEY + evidenceKey);
+      const shown = read("session", SESSION_KEY);
+      setAllowed(!dismissed && (!shown || shown === evidenceKey));
+    }, [remembering, persist, evidenceKey]);
+    const visible = open && allowed;
+    const impressed = React__namespace.useRef(false);
+    React__namespace.useEffect(() => {
+      if (!visible) {
+        impressed.current = false;
+        return;
+      }
+      if (impressed.current) return;
+      impressed.current = true;
+      if (evidenceKey != null) write("session", SESSION_KEY, evidenceKey);
+      onImpression?.();
+    }, [visible, evidenceKey, onImpression]);
+    const setOpen = (next) => {
+      if (openProp === void 0) setInternalOpen(next);
+      onOpenChange?.(next);
+    };
+    const dismiss = () => {
+      if (remembering) write(persist, KEY + evidenceKey, "dismissed");
+      setOpen(false);
+      onDismiss?.();
+    };
+    const snooze = () => {
+      setOpen(false);
+      onSnooze?.();
+    };
+    const act = () => {
+      if (!onAction || pending) return;
+      const result = onAction();
+      if (result && typeof result.then === "function") {
+        setPending(true);
+        result.finally(() => {
+          if (mounted.current) setPending(false);
+        });
+      }
+    };
+    const handleKeyDown = (e) => {
+      onKeyDown?.(e);
+      if (e.key === "Escape") {
+        e.stopPropagation();
+        dismiss();
+      }
+    };
+    const label = `Suggestion from ${agentName}`;
+    const spinner$1 = /* @__PURE__ */ jsxRuntime.jsx(spinner.Spinner, { "aria-hidden": "true", role: void 0, "aria-label": void 0, className: "size-3.5 motion-reduce:animate-none" });
+    const dismissButton = /* @__PURE__ */ jsxRuntime.jsx(
+      button.Button,
+      {
+        variant: "ghost",
+        size: "icon-sm",
+        "aria-label": dismissLabel,
+        onClick: dismiss,
+        className: "size-6 shrink-0 text-muted-foreground [&_svg]:size-3.5",
+        children: /* @__PURE__ */ jsxRuntime.jsx(lucideReact.X, { "aria-hidden": "true" })
+      }
+    );
+    let body = null;
+    if (visible && variant === "inline-suggestion") {
+      body = /* @__PURE__ */ jsxRuntime.jsxs(
+        "section",
+        {
+          ref,
+          "aria-label": label,
+          onKeyDown: handleKeyDown,
+          className: utils.cn("inline-flex items-center gap-1 animate-nx-fade-in motion-reduce:animate-none", className),
+          ...props,
+          children: [
+            /* @__PURE__ */ jsxRuntime.jsxs("span", { id: titleId, className: "sr-only", children: [
+              title,
+              description ? /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+                " ",
+                description
+              ] }) : null
+            ] }),
+            resolved ? /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "inline-flex items-center gap-1.5 text-xs text-muted-foreground", children: [
+              /* @__PURE__ */ jsxRuntime.jsx(lucideReact.CheckCircle2, { "aria-hidden": "true", className: "size-3.5 text-success" }),
+              "Resolved"
+            ] }) : /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+              /* @__PURE__ */ jsxRuntime.jsx(
+                button.Button,
+                {
+                  size: "sm",
+                  "aria-describedby": titleId,
+                  "aria-busy": pending || void 0,
+                  onClick: act,
+                  className: "h-7 rounded-full px-3 text-xs",
+                  leftIcon: pending ? spinner$1 : /* @__PURE__ */ jsxRuntime.jsx(lucideReact.Sparkles, { "aria-hidden": "true", className: "size-3.5" }),
+                  children: pending ? pendingLabel : actionLabel
+                }
+              ),
+              dismissButton
+            ] })
+          ]
+        }
+      );
+    } else if (visible) {
+      const toast = variant === "side-toast";
+      body = /* @__PURE__ */ jsxRuntime.jsxs(
+        "section",
+        {
+          ref,
+          "aria-labelledby": titleId,
+          onKeyDown: handleKeyDown,
+          className: utils.cn(
+            "flex items-start gap-3 text-sm animate-nx-fade-in motion-reduce:animate-none",
+            toast ? "fixed bottom-4 right-4 z-50 w-80 max-w-[calc(100vw-2rem)] rounded-xl border border-border bg-background p-3.5 shadow-lg" : "rounded-lg border border-brand/30 bg-brand-muted/60 p-3.5",
+            className
+          ),
+          ...props,
+          children: [
+            !toast && /* @__PURE__ */ jsxRuntime.jsx(
+              "span",
+              {
+                "aria-hidden": "true",
+                className: "grid size-6 shrink-0 place-items-center rounded-md bg-brand text-brand-foreground [&_svg]:size-3.5",
+                children: /* @__PURE__ */ jsxRuntime.jsx(lucideReact.Sparkles, {})
+              }
+            ),
+            /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-1", children: [
+              toast && /* @__PURE__ */ jsxRuntime.jsxs("p", { className: "flex items-center gap-1.5 text-xs font-semibold text-brand", children: [
+                /* @__PURE__ */ jsxRuntime.jsx(lucideReact.Sparkles, { "aria-hidden": "true", className: "size-3.5" }),
+                "Worth a look"
+              ] }),
+              /* @__PURE__ */ jsxRuntime.jsxs("p", { id: titleId, className: "font-semibold text-foreground", children: [
+                /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "sr-only", children: [
+                  label,
+                  ": "
+                ] }),
+                title
+              ] }),
+              description && /* @__PURE__ */ jsxRuntime.jsx("p", { className: "text-muted-foreground", children: description }),
+              reason && /* @__PURE__ */ jsxRuntime.jsx("p", { className: "text-xs text-muted-foreground", children: reason }),
+              resolved ? /* @__PURE__ */ jsxRuntime.jsxs("p", { className: "mt-1 inline-flex items-center gap-1.5 text-xs text-muted-foreground", children: [
+                /* @__PURE__ */ jsxRuntime.jsx(lucideReact.CheckCircle2, { "aria-hidden": "true", className: "size-3.5 text-success" }),
+                "Resolved"
+              ] }) : /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "mt-1.5 flex flex-wrap items-center gap-1.5", children: [
+                /* @__PURE__ */ jsxRuntime.jsx(button.Button, { size: "sm", onClick: act, "aria-busy": pending || void 0, leftIcon: pending ? spinner$1 : void 0, children: pending ? pendingLabel : actionLabel }),
+                onSnooze && /* @__PURE__ */ jsxRuntime.jsx(button.Button, { size: "sm", variant: "ghost", onClick: snooze, children: snoozeLabel })
+              ] })
+            ] }),
+            !resolved && dismissButton
+          ]
+        }
+      );
+    }
+    return /* @__PURE__ */ jsxRuntime.jsx("div", { "aria-live": "polite", className: "contents", children: body });
+  }
+);
+ProactiveSuggestion.displayName = "ProactiveSuggestion";
+
+exports.ProactiveSuggestion = ProactiveSuggestion;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.tsx"],"names":["React","spinner","jsx","Spinner","Button","X","jsxs","cn","Fragment","CheckCircle2","Sparkles"],"mappings":"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","file":"index.cjs","sourcesContent":["import * as React from \"react\";\nimport { CheckCircle2, Sparkles, X } from \"lucide-react\";\nimport { cn } from \"@nucleux/utils\";\nimport { Button } from \"@nucleux/button\";\nimport { Spinner } from \"@nucleux/spinner\";\n\n/** Form of the suggestion, from the spec's variants. */\nexport type ProactiveSuggestionVariant = \"contextual-banner\" | \"inline-suggestion\" | \"side-toast\";\n\n/** Where dismissals are remembered when the suggestion has an `evidenceKey`. */\nexport type ProactiveSuggestionPersist = \"none\" | \"session\" | \"local\";\n\nexport interface ProactiveSuggestionProps extends Omit<React.HTMLAttributes<HTMLElement>, \"title\"> {\n  /** \"contextual-banner\" (default), \"inline-suggestion\" or \"side-toast\". */\n  variant?: ProactiveSuggestionVariant;\n  /** The finding, first (\"Three renewals expire this week\"). */\n  title: React.ReactNode;\n  /** The recommendation, phrased as a question (\"Want Aria to draft outreach for each?\"). */\n  description?: React.ReactNode;\n  /** The evidence it is based on (\"Acme, Globex and Initech renew before Friday.\"). */\n  reason?: React.ReactNode;\n  /** The agent's name, used in the accessible label and the provenance line. Defaults to \"the assistant\". */\n  agentName?: string;\n  /** The one next action (\"Draft emails\"). */\n  actionLabel: string;\n  /**\n   * Called by the action. It should open a review the person confirms, not\n   * act on its own. May return a promise: while it is pending the action\n   * shows a spinner and `pendingLabel`.\n   */\n  onAction?: () => void | Promise<unknown>;\n  /** Shown on the action while `onAction` is pending. Defaults to \"Preparing…\". */\n  pendingLabel?: string;\n  /** Shows a snooze action (\"Not now\", \"Remind me tomorrow\"); hides without remembering a dismissal. */\n  onSnooze?: () => void;\n  /** Label of the snooze action. Defaults to \"Not now\". */\n  snoozeLabel?: string;\n  /** Called when dismissed (× or Escape). One press; remembered for `evidenceKey`. */\n  onDismiss?: () => void;\n  /** Accessible name of the dismiss button. Defaults to \"Dismiss suggestion\". */\n  dismissLabel?: string;\n  /** Whether the suggestion is showing (controlled). */\n  open?: boolean;\n  /** Initial visibility when uncontrolled. Defaults to true. */\n  defaultOpen?: boolean;\n  /** Called whenever it shows or hides. */\n  onOpenChange?: (open: boolean) => void;\n  /**\n   * Identifies the facts behind it. With a key, a dismissal is remembered so\n   * the same evidence never brings it back, and only one suggestion with a\n   * key is shown per browser session.\n   */\n  evidenceKey?: string;\n  /** Where to remember dismissals of `evidenceKey`. Defaults to \"local\". */\n  persist?: ProactiveSuggestionPersist;\n  /** The reason went away: say \"Resolved\" and drop the actions. */\n  resolved?: boolean;\n  /** Called once each time it is shown. */\n  onImpression?: () => void;\n}\n\nconst KEY = \"nucleux:proactive:\";\nconst SESSION_KEY = \"nucleux:proactive:session\";\n\nfunction getStore(kind: \"session\" | \"local\"): Storage | null {\n  try {\n    return typeof window === \"undefined\" ? null : kind === \"session\" ? window.sessionStorage : window.localStorage;\n  } catch {\n    return null;\n  }\n}\nfunction read(kind: \"session\" | \"local\", key: string) {\n  try {\n    return getStore(kind)?.getItem(key) ?? null;\n  } catch {\n    return null;\n  }\n}\nfunction write(kind: \"session\" | \"local\", key: string, value: string) {\n  try {\n    getStore(kind)?.setItem(key, value);\n  } catch {\n    /* storage unavailable: memory is best effort */\n  }\n}\n\n/**\n * An unsolicited suggestion the agent raises when it notices something\n * specific and actionable — a risk, an anomaly, an overdue step. It leads\n * with the finding, can show the evidence, and offers exactly one next action\n * plus a frictionless dismiss (× or Escape) and an optional snooze; nothing\n * happens until the person acts. It is announced politely, never as a\n * dialog. Use a contextual banner at the top of a surface, an inline\n * suggestion beside the row it is about, or a side toast in the corner. With\n * an `evidenceKey` it is capped at one per session and a dismissed one never\n * comes back for the same facts.\n */\nexport const ProactiveSuggestion = React.forwardRef<HTMLElement, ProactiveSuggestionProps>(\n  (\n    {\n      variant = \"contextual-banner\",\n      title,\n      description,\n      reason,\n      agentName = \"the assistant\",\n      actionLabel,\n      onAction,\n      pendingLabel = \"Preparing…\",\n      onSnooze,\n      snoozeLabel = \"Not now\",\n      onDismiss,\n      dismissLabel = \"Dismiss suggestion\",\n      open: openProp,\n      defaultOpen = true,\n      onOpenChange,\n      evidenceKey,\n      persist = \"local\",\n      resolved = false,\n      onImpression,\n      className,\n      onKeyDown,\n      ...props\n    },\n    ref,\n  ) => {\n    const baseId = React.useId();\n    const titleId = `${baseId}-title`;\n    const [internalOpen, setInternalOpen] = React.useState(defaultOpen);\n    const open = openProp ?? internalOpen;\n    const remembering = evidenceKey != null && persist !== \"none\";\n    const [allowed, setAllowed] = React.useState(!remembering);\n    const [pending, setPending] = React.useState(false);\n    const mounted = React.useRef(true);\n    React.useEffect(\n      () => () => {\n        mounted.current = false;\n      },\n      [],\n    );\n\n    React.useEffect(() => {\n      if (!remembering) {\n        setAllowed(true);\n        return;\n      }\n      const dismissed = read(persist as \"session\" | \"local\", KEY + evidenceKey);\n      const shown = read(\"session\", SESSION_KEY);\n      setAllowed(!dismissed && (!shown || shown === evidenceKey));\n    }, [remembering, persist, evidenceKey]);\n\n    const visible = open && allowed;\n\n    const impressed = React.useRef(false);\n    React.useEffect(() => {\n      if (!visible) {\n        impressed.current = false;\n        return;\n      }\n      if (impressed.current) return;\n      impressed.current = true;\n      if (evidenceKey != null) write(\"session\", SESSION_KEY, evidenceKey);\n      onImpression?.();\n    }, [visible, evidenceKey, onImpression]);\n\n    const setOpen = (next: boolean) => {\n      if (openProp === undefined) setInternalOpen(next);\n      onOpenChange?.(next);\n    };\n    const dismiss = () => {\n      if (remembering) write(persist as \"session\" | \"local\", KEY + evidenceKey, \"dismissed\");\n      setOpen(false);\n      onDismiss?.();\n    };\n    const snooze = () => {\n      setOpen(false);\n      onSnooze?.();\n    };\n    const act = () => {\n      if (!onAction || pending) return;\n      const result = onAction();\n      if (result && typeof (result as Promise<unknown>).then === \"function\") {\n        setPending(true);\n        (result as Promise<unknown>).finally(() => {\n          if (mounted.current) setPending(false);\n        });\n      }\n    };\n\n    const handleKeyDown = (e: React.KeyboardEvent<HTMLElement>) => {\n      onKeyDown?.(e);\n      if (e.key === \"Escape\") {\n        e.stopPropagation();\n        dismiss();\n      }\n    };\n\n    const label = `Suggestion from ${agentName}`;\n    const spinner = (\n      <Spinner aria-hidden=\"true\" role={undefined} aria-label={undefined} className=\"size-3.5 motion-reduce:animate-none\" />\n    );\n    const dismissButton = (\n      <Button\n        variant=\"ghost\"\n        size=\"icon-sm\"\n        aria-label={dismissLabel}\n        onClick={dismiss}\n        className=\"size-6 shrink-0 text-muted-foreground [&_svg]:size-3.5\"\n      >\n        <X aria-hidden=\"true\" />\n      </Button>\n    );\n\n    let body: React.ReactNode = null;\n    if (visible && variant === \"inline-suggestion\") {\n      body = (\n        <section\n          ref={ref}\n          aria-label={label}\n          onKeyDown={handleKeyDown}\n          className={cn(\"inline-flex items-center gap-1 animate-nx-fade-in motion-reduce:animate-none\", className)}\n          {...props}\n        >\n          <span id={titleId} className=\"sr-only\">\n            {title}\n            {description ? <> {description}</> : null}\n          </span>\n          {resolved ? (\n            <span className=\"inline-flex items-center gap-1.5 text-xs text-muted-foreground\">\n              <CheckCircle2 aria-hidden=\"true\" className=\"size-3.5 text-success\" />\n              Resolved\n            </span>\n          ) : (\n            <>\n              <Button\n                size=\"sm\"\n                aria-describedby={titleId}\n                aria-busy={pending || undefined}\n                onClick={act}\n                className=\"h-7 rounded-full px-3 text-xs\"\n                leftIcon={pending ? spinner : <Sparkles aria-hidden=\"true\" className=\"size-3.5\" />}\n              >\n                {pending ? pendingLabel : actionLabel}\n              </Button>\n              {dismissButton}\n            </>\n          )}\n        </section>\n      );\n    } else if (visible) {\n      const toast = variant === \"side-toast\";\n      body = (\n        <section\n          ref={ref}\n          aria-labelledby={titleId}\n          onKeyDown={handleKeyDown}\n          className={cn(\n            \"flex items-start gap-3 text-sm animate-nx-fade-in motion-reduce:animate-none\",\n            toast\n              ? \"fixed bottom-4 right-4 z-50 w-80 max-w-[calc(100vw-2rem)] rounded-xl border border-border bg-background p-3.5 shadow-lg\"\n              : \"rounded-lg border border-brand/30 bg-brand-muted/60 p-3.5\",\n            className,\n          )}\n          {...props}\n        >\n          {!toast && (\n            <span\n              aria-hidden=\"true\"\n              className=\"grid size-6 shrink-0 place-items-center rounded-md bg-brand text-brand-foreground [&_svg]:size-3.5\"\n            >\n              <Sparkles />\n            </span>\n          )}\n          <div className=\"flex min-w-0 flex-1 flex-col gap-1\">\n            {toast && (\n              <p className=\"flex items-center gap-1.5 text-xs font-semibold text-brand\">\n                <Sparkles aria-hidden=\"true\" className=\"size-3.5\" />\n                Worth a look\n              </p>\n            )}\n            <p id={titleId} className=\"font-semibold text-foreground\">\n              <span className=\"sr-only\">{label}: </span>\n              {title}\n            </p>\n            {description && <p className=\"text-muted-foreground\">{description}</p>}\n            {reason && <p className=\"text-xs text-muted-foreground\">{reason}</p>}\n            {resolved ? (\n              <p className=\"mt-1 inline-flex items-center gap-1.5 text-xs text-muted-foreground\">\n                <CheckCircle2 aria-hidden=\"true\" className=\"size-3.5 text-success\" />\n                Resolved\n              </p>\n            ) : (\n              <div className=\"mt-1.5 flex flex-wrap items-center gap-1.5\">\n                <Button size=\"sm\" onClick={act} aria-busy={pending || undefined} leftIcon={pending ? spinner : undefined}>\n                  {pending ? pendingLabel : actionLabel}\n                </Button>\n                {onSnooze && (\n                  <Button size=\"sm\" variant=\"ghost\" onClick={snooze}>\n                    {snoozeLabel}\n                  </Button>\n                )}\n              </div>\n            )}\n          </div>\n          {!resolved && dismissButton}\n        </section>\n      );\n    }\n\n    // A persistent polite live region, so a suggestion appearing is announced without stealing focus.\n    return (\n      <div aria-live=\"polite\" className=\"contents\">\n        {body}\n      </div>\n    );\n  },\n);\nProactiveSuggestion.displayName = \"ProactiveSuggestion\";\n"]}

package/dist/index.d.cts

@@ -0,0 +1,68 @@
+import * as React from 'react';
+
+/** Form of the suggestion, from the spec's variants. */
+type ProactiveSuggestionVariant = "contextual-banner" | "inline-suggestion" | "side-toast";
+/** Where dismissals are remembered when the suggestion has an `evidenceKey`. */
+type ProactiveSuggestionPersist = "none" | "session" | "local";
+interface ProactiveSuggestionProps extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
+    /** "contextual-banner" (default), "inline-suggestion" or "side-toast". */
+    variant?: ProactiveSuggestionVariant;
+    /** The finding, first ("Three renewals expire this week"). */
+    title: React.ReactNode;
+    /** The recommendation, phrased as a question ("Want Aria to draft outreach for each?"). */
+    description?: React.ReactNode;
+    /** The evidence it is based on ("Acme, Globex and Initech renew before Friday."). */
+    reason?: React.ReactNode;
+    /** The agent's name, used in the accessible label and the provenance line. Defaults to "the assistant". */
+    agentName?: string;
+    /** The one next action ("Draft emails"). */
+    actionLabel: string;
+    /**
+     * Called by the action. It should open a review the person confirms, not
+     * act on its own. May return a promise: while it is pending the action
+     * shows a spinner and `pendingLabel`.
+     */
+    onAction?: () => void | Promise<unknown>;
+    /** Shown on the action while `onAction` is pending. Defaults to "Preparing…". */
+    pendingLabel?: string;
+    /** Shows a snooze action ("Not now", "Remind me tomorrow"); hides without remembering a dismissal. */
+    onSnooze?: () => void;
+    /** Label of the snooze action. Defaults to "Not now". */
+    snoozeLabel?: string;
+    /** Called when dismissed (× or Escape). One press; remembered for `evidenceKey`. */
+    onDismiss?: () => void;
+    /** Accessible name of the dismiss button. Defaults to "Dismiss suggestion". */
+    dismissLabel?: string;
+    /** Whether the suggestion is showing (controlled). */
+    open?: boolean;
+    /** Initial visibility when uncontrolled. Defaults to true. */
+    defaultOpen?: boolean;
+    /** Called whenever it shows or hides. */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Identifies the facts behind it. With a key, a dismissal is remembered so
+     * the same evidence never brings it back, and only one suggestion with a
+     * key is shown per browser session.
+     */
+    evidenceKey?: string;
+    /** Where to remember dismissals of `evidenceKey`. Defaults to "local". */
+    persist?: ProactiveSuggestionPersist;
+    /** The reason went away: say "Resolved" and drop the actions. */
+    resolved?: boolean;
+    /** Called once each time it is shown. */
+    onImpression?: () => void;
+}
+/**
+ * An unsolicited suggestion the agent raises when it notices something
+ * specific and actionable — a risk, an anomaly, an overdue step. It leads
+ * with the finding, can show the evidence, and offers exactly one next action
+ * plus a frictionless dismiss (× or Escape) and an optional snooze; nothing
+ * happens until the person acts. It is announced politely, never as a
+ * dialog. Use a contextual banner at the top of a surface, an inline
+ * suggestion beside the row it is about, or a side toast in the corner. With
+ * an `evidenceKey` it is capped at one per session and a dismissed one never
+ * comes back for the same facts.
+ */
+declare const ProactiveSuggestion: React.ForwardRefExoticComponent<ProactiveSuggestionProps & React.RefAttributes<HTMLElement>>;
+
+export { ProactiveSuggestion, type ProactiveSuggestionPersist, type ProactiveSuggestionProps, type ProactiveSuggestionVariant };

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+import * as React from 'react';
+
+/** Form of the suggestion, from the spec's variants. */
+type ProactiveSuggestionVariant = "contextual-banner" | "inline-suggestion" | "side-toast";
+/** Where dismissals are remembered when the suggestion has an `evidenceKey`. */
+type ProactiveSuggestionPersist = "none" | "session" | "local";
+interface ProactiveSuggestionProps extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
+    /** "contextual-banner" (default), "inline-suggestion" or "side-toast". */
+    variant?: ProactiveSuggestionVariant;
+    /** The finding, first ("Three renewals expire this week"). */
+    title: React.ReactNode;
+    /** The recommendation, phrased as a question ("Want Aria to draft outreach for each?"). */
+    description?: React.ReactNode;
+    /** The evidence it is based on ("Acme, Globex and Initech renew before Friday."). */
+    reason?: React.ReactNode;
+    /** The agent's name, used in the accessible label and the provenance line. Defaults to "the assistant". */
+    agentName?: string;
+    /** The one next action ("Draft emails"). */
+    actionLabel: string;
+    /**
+     * Called by the action. It should open a review the person confirms, not
+     * act on its own. May return a promise: while it is pending the action
+     * shows a spinner and `pendingLabel`.
+     */
+    onAction?: () => void | Promise<unknown>;
+    /** Shown on the action while `onAction` is pending. Defaults to "Preparing…". */
+    pendingLabel?: string;
+    /** Shows a snooze action ("Not now", "Remind me tomorrow"); hides without remembering a dismissal. */
+    onSnooze?: () => void;
+    /** Label of the snooze action. Defaults to "Not now". */
+    snoozeLabel?: string;
+    /** Called when dismissed (× or Escape). One press; remembered for `evidenceKey`. */
+    onDismiss?: () => void;
+    /** Accessible name of the dismiss button. Defaults to "Dismiss suggestion". */
+    dismissLabel?: string;
+    /** Whether the suggestion is showing (controlled). */
+    open?: boolean;
+    /** Initial visibility when uncontrolled. Defaults to true. */
+    defaultOpen?: boolean;
+    /** Called whenever it shows or hides. */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Identifies the facts behind it. With a key, a dismissal is remembered so
+     * the same evidence never brings it back, and only one suggestion with a
+     * key is shown per browser session.
+     */
+    evidenceKey?: string;
+    /** Where to remember dismissals of `evidenceKey`. Defaults to "local". */
+    persist?: ProactiveSuggestionPersist;
+    /** The reason went away: say "Resolved" and drop the actions. */
+    resolved?: boolean;
+    /** Called once each time it is shown. */
+    onImpression?: () => void;
+}
+/**
+ * An unsolicited suggestion the agent raises when it notices something
+ * specific and actionable — a risk, an anomaly, an overdue step. It leads
+ * with the finding, can show the evidence, and offers exactly one next action
+ * plus a frictionless dismiss (× or Escape) and an optional snooze; nothing
+ * happens until the person acts. It is announced politely, never as a
+ * dialog. Use a contextual banner at the top of a surface, an inline
+ * suggestion beside the row it is about, or a side toast in the corner. With
+ * an `evidenceKey` it is capped at one per session and a dismissed one never
+ * comes back for the same facts.
+ */
+declare const ProactiveSuggestion: React.ForwardRefExoticComponent<ProactiveSuggestionProps & React.RefAttributes<HTMLElement>>;
+
+export { ProactiveSuggestion, type ProactiveSuggestionPersist, type ProactiveSuggestionProps, type ProactiveSuggestionVariant };

package/dist/index.js

@@ -0,0 +1,231 @@
+"use client";
+import * as React from 'react';
+import { CheckCircle2, Sparkles, X } from 'lucide-react';
+import { cn } from '@nucleux/utils';
+import { Button } from '@nucleux/button';
+import { Spinner } from '@nucleux/spinner';
+import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
+
+// src/index.tsx
+var KEY = "nucleux:proactive:";
+var SESSION_KEY = "nucleux:proactive:session";
+function getStore(kind) {
+  try {
+    return typeof window === "undefined" ? null : kind === "session" ? window.sessionStorage : window.localStorage;
+  } catch {
+    return null;
+  }
+}
+function read(kind, key) {
+  try {
+    return getStore(kind)?.getItem(key) ?? null;
+  } catch {
+    return null;
+  }
+}
+function write(kind, key, value) {
+  try {
+    getStore(kind)?.setItem(key, value);
+  } catch {
+  }
+}
+var ProactiveSuggestion = React.forwardRef(
+  ({
+    variant = "contextual-banner",
+    title,
+    description,
+    reason,
+    agentName = "the assistant",
+    actionLabel,
+    onAction,
+    pendingLabel = "Preparing\u2026",
+    onSnooze,
+    snoozeLabel = "Not now",
+    onDismiss,
+    dismissLabel = "Dismiss suggestion",
+    open: openProp,
+    defaultOpen = true,
+    onOpenChange,
+    evidenceKey,
+    persist = "local",
+    resolved = false,
+    onImpression,
+    className,
+    onKeyDown,
+    ...props
+  }, ref) => {
+    const baseId = React.useId();
+    const titleId = `${baseId}-title`;
+    const [internalOpen, setInternalOpen] = React.useState(defaultOpen);
+    const open = openProp ?? internalOpen;
+    const remembering = evidenceKey != null && persist !== "none";
+    const [allowed, setAllowed] = React.useState(!remembering);
+    const [pending, setPending] = React.useState(false);
+    const mounted = React.useRef(true);
+    React.useEffect(
+      () => () => {
+        mounted.current = false;
+      },
+      []
+    );
+    React.useEffect(() => {
+      if (!remembering) {
+        setAllowed(true);
+        return;
+      }
+      const dismissed = read(persist, KEY + evidenceKey);
+      const shown = read("session", SESSION_KEY);
+      setAllowed(!dismissed && (!shown || shown === evidenceKey));
+    }, [remembering, persist, evidenceKey]);
+    const visible = open && allowed;
+    const impressed = React.useRef(false);
+    React.useEffect(() => {
+      if (!visible) {
+        impressed.current = false;
+        return;
+      }
+      if (impressed.current) return;
+      impressed.current = true;
+      if (evidenceKey != null) write("session", SESSION_KEY, evidenceKey);
+      onImpression?.();
+    }, [visible, evidenceKey, onImpression]);
+    const setOpen = (next) => {
+      if (openProp === void 0) setInternalOpen(next);
+      onOpenChange?.(next);
+    };
+    const dismiss = () => {
+      if (remembering) write(persist, KEY + evidenceKey, "dismissed");
+      setOpen(false);
+      onDismiss?.();
+    };
+    const snooze = () => {
+      setOpen(false);
+      onSnooze?.();
+    };
+    const act = () => {
+      if (!onAction || pending) return;
+      const result = onAction();
+      if (result && typeof result.then === "function") {
+        setPending(true);
+        result.finally(() => {
+          if (mounted.current) setPending(false);
+        });
+      }
+    };
+    const handleKeyDown = (e) => {
+      onKeyDown?.(e);
+      if (e.key === "Escape") {
+        e.stopPropagation();
+        dismiss();
+      }
+    };
+    const label = `Suggestion from ${agentName}`;
+    const spinner = /* @__PURE__ */ jsx(Spinner, { "aria-hidden": "true", role: void 0, "aria-label": void 0, className: "size-3.5 motion-reduce:animate-none" });
+    const dismissButton = /* @__PURE__ */ jsx(
+      Button,
+      {
+        variant: "ghost",
+        size: "icon-sm",
+        "aria-label": dismissLabel,
+        onClick: dismiss,
+        className: "size-6 shrink-0 text-muted-foreground [&_svg]:size-3.5",
+        children: /* @__PURE__ */ jsx(X, { "aria-hidden": "true" })
+      }
+    );
+    let body = null;
+    if (visible && variant === "inline-suggestion") {
+      body = /* @__PURE__ */ jsxs(
+        "section",
+        {
+          ref,
+          "aria-label": label,
+          onKeyDown: handleKeyDown,
+          className: cn("inline-flex items-center gap-1 animate-nx-fade-in motion-reduce:animate-none", className),
+          ...props,
+          children: [
+            /* @__PURE__ */ jsxs("span", { id: titleId, className: "sr-only", children: [
+              title,
+              description ? /* @__PURE__ */ jsxs(Fragment, { children: [
+                " ",
+                description
+              ] }) : null
+            ] }),
+            resolved ? /* @__PURE__ */ jsxs("span", { className: "inline-flex items-center gap-1.5 text-xs text-muted-foreground", children: [
+              /* @__PURE__ */ jsx(CheckCircle2, { "aria-hidden": "true", className: "size-3.5 text-success" }),
+              "Resolved"
+            ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+              /* @__PURE__ */ jsx(
+                Button,
+                {
+                  size: "sm",
+                  "aria-describedby": titleId,
+                  "aria-busy": pending || void 0,
+                  onClick: act,
+                  className: "h-7 rounded-full px-3 text-xs",
+                  leftIcon: pending ? spinner : /* @__PURE__ */ jsx(Sparkles, { "aria-hidden": "true", className: "size-3.5" }),
+                  children: pending ? pendingLabel : actionLabel
+                }
+              ),
+              dismissButton
+            ] })
+          ]
+        }
+      );
+    } else if (visible) {
+      const toast = variant === "side-toast";
+      body = /* @__PURE__ */ jsxs(
+        "section",
+        {
+          ref,
+          "aria-labelledby": titleId,
+          onKeyDown: handleKeyDown,
+          className: cn(
+            "flex items-start gap-3 text-sm animate-nx-fade-in motion-reduce:animate-none",
+            toast ? "fixed bottom-4 right-4 z-50 w-80 max-w-[calc(100vw-2rem)] rounded-xl border border-border bg-background p-3.5 shadow-lg" : "rounded-lg border border-brand/30 bg-brand-muted/60 p-3.5",
+            className
+          ),
+          ...props,
+          children: [
+            !toast && /* @__PURE__ */ jsx(
+              "span",
+              {
+                "aria-hidden": "true",
+                className: "grid size-6 shrink-0 place-items-center rounded-md bg-brand text-brand-foreground [&_svg]:size-3.5",
+                children: /* @__PURE__ */ jsx(Sparkles, {})
+              }
+            ),
+            /* @__PURE__ */ jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-1", children: [
+              toast && /* @__PURE__ */ jsxs("p", { className: "flex items-center gap-1.5 text-xs font-semibold text-brand", children: [
+                /* @__PURE__ */ jsx(Sparkles, { "aria-hidden": "true", className: "size-3.5" }),
+                "Worth a look"
+              ] }),
+              /* @__PURE__ */ jsxs("p", { id: titleId, className: "font-semibold text-foreground", children: [
+                /* @__PURE__ */ jsxs("span", { className: "sr-only", children: [
+                  label,
+                  ": "
+                ] }),
+                title
+              ] }),
+              description && /* @__PURE__ */ jsx("p", { className: "text-muted-foreground", children: description }),
+              reason && /* @__PURE__ */ jsx("p", { className: "text-xs text-muted-foreground", children: reason }),
+              resolved ? /* @__PURE__ */ jsxs("p", { className: "mt-1 inline-flex items-center gap-1.5 text-xs text-muted-foreground", children: [
+                /* @__PURE__ */ jsx(CheckCircle2, { "aria-hidden": "true", className: "size-3.5 text-success" }),
+                "Resolved"
+              ] }) : /* @__PURE__ */ jsxs("div", { className: "mt-1.5 flex flex-wrap items-center gap-1.5", children: [
+                /* @__PURE__ */ jsx(Button, { size: "sm", onClick: act, "aria-busy": pending || void 0, leftIcon: pending ? spinner : void 0, children: pending ? pendingLabel : actionLabel }),
+                onSnooze && /* @__PURE__ */ jsx(Button, { size: "sm", variant: "ghost", onClick: snooze, children: snoozeLabel })
+              ] })
+            ] }),
+            !resolved && dismissButton
+          ]
+        }
+      );
+    }
+    return /* @__PURE__ */ jsx("div", { "aria-live": "polite", className: "contents", children: body });
+  }
+);
+ProactiveSuggestion.displayName = "ProactiveSuggestion";
+
+export { ProactiveSuggestion };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.tsx"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import * as React from \"react\";\nimport { CheckCircle2, Sparkles, X } from \"lucide-react\";\nimport { cn } from \"@nucleux/utils\";\nimport { Button } from \"@nucleux/button\";\nimport { Spinner } from \"@nucleux/spinner\";\n\n/** Form of the suggestion, from the spec's variants. */\nexport type ProactiveSuggestionVariant = \"contextual-banner\" | \"inline-suggestion\" | \"side-toast\";\n\n/** Where dismissals are remembered when the suggestion has an `evidenceKey`. */\nexport type ProactiveSuggestionPersist = \"none\" | \"session\" | \"local\";\n\nexport interface ProactiveSuggestionProps extends Omit<React.HTMLAttributes<HTMLElement>, \"title\"> {\n  /** \"contextual-banner\" (default), \"inline-suggestion\" or \"side-toast\". */\n  variant?: ProactiveSuggestionVariant;\n  /** The finding, first (\"Three renewals expire this week\"). */\n  title: React.ReactNode;\n  /** The recommendation, phrased as a question (\"Want Aria to draft outreach for each?\"). */\n  description?: React.ReactNode;\n  /** The evidence it is based on (\"Acme, Globex and Initech renew before Friday.\"). */\n  reason?: React.ReactNode;\n  /** The agent's name, used in the accessible label and the provenance line. Defaults to \"the assistant\". */\n  agentName?: string;\n  /** The one next action (\"Draft emails\"). */\n  actionLabel: string;\n  /**\n   * Called by the action. It should open a review the person confirms, not\n   * act on its own. May return a promise: while it is pending the action\n   * shows a spinner and `pendingLabel`.\n   */\n  onAction?: () => void | Promise<unknown>;\n  /** Shown on the action while `onAction` is pending. Defaults to \"Preparing…\". */\n  pendingLabel?: string;\n  /** Shows a snooze action (\"Not now\", \"Remind me tomorrow\"); hides without remembering a dismissal. */\n  onSnooze?: () => void;\n  /** Label of the snooze action. Defaults to \"Not now\". */\n  snoozeLabel?: string;\n  /** Called when dismissed (× or Escape). One press; remembered for `evidenceKey`. */\n  onDismiss?: () => void;\n  /** Accessible name of the dismiss button. Defaults to \"Dismiss suggestion\". */\n  dismissLabel?: string;\n  /** Whether the suggestion is showing (controlled). */\n  open?: boolean;\n  /** Initial visibility when uncontrolled. Defaults to true. */\n  defaultOpen?: boolean;\n  /** Called whenever it shows or hides. */\n  onOpenChange?: (open: boolean) => void;\n  /**\n   * Identifies the facts behind it. With a key, a dismissal is remembered so\n   * the same evidence never brings it back, and only one suggestion with a\n   * key is shown per browser session.\n   */\n  evidenceKey?: string;\n  /** Where to remember dismissals of `evidenceKey`. Defaults to \"local\". */\n  persist?: ProactiveSuggestionPersist;\n  /** The reason went away: say \"Resolved\" and drop the actions. */\n  resolved?: boolean;\n  /** Called once each time it is shown. */\n  onImpression?: () => void;\n}\n\nconst KEY = \"nucleux:proactive:\";\nconst SESSION_KEY = \"nucleux:proactive:session\";\n\nfunction getStore(kind: \"session\" | \"local\"): Storage | null {\n  try {\n    return typeof window === \"undefined\" ? null : kind === \"session\" ? window.sessionStorage : window.localStorage;\n  } catch {\n    return null;\n  }\n}\nfunction read(kind: \"session\" | \"local\", key: string) {\n  try {\n    return getStore(kind)?.getItem(key) ?? null;\n  } catch {\n    return null;\n  }\n}\nfunction write(kind: \"session\" | \"local\", key: string, value: string) {\n  try {\n    getStore(kind)?.setItem(key, value);\n  } catch {\n    /* storage unavailable: memory is best effort */\n  }\n}\n\n/**\n * An unsolicited suggestion the agent raises when it notices something\n * specific and actionable — a risk, an anomaly, an overdue step. It leads\n * with the finding, can show the evidence, and offers exactly one next action\n * plus a frictionless dismiss (× or Escape) and an optional snooze; nothing\n * happens until the person acts. It is announced politely, never as a\n * dialog. Use a contextual banner at the top of a surface, an inline\n * suggestion beside the row it is about, or a side toast in the corner. With\n * an `evidenceKey` it is capped at one per session and a dismissed one never\n * comes back for the same facts.\n */\nexport const ProactiveSuggestion = React.forwardRef<HTMLElement, ProactiveSuggestionProps>(\n  (\n    {\n      variant = \"contextual-banner\",\n      title,\n      description,\n      reason,\n      agentName = \"the assistant\",\n      actionLabel,\n      onAction,\n      pendingLabel = \"Preparing…\",\n      onSnooze,\n      snoozeLabel = \"Not now\",\n      onDismiss,\n      dismissLabel = \"Dismiss suggestion\",\n      open: openProp,\n      defaultOpen = true,\n      onOpenChange,\n      evidenceKey,\n      persist = \"local\",\n      resolved = false,\n      onImpression,\n      className,\n      onKeyDown,\n      ...props\n    },\n    ref,\n  ) => {\n    const baseId = React.useId();\n    const titleId = `${baseId}-title`;\n    const [internalOpen, setInternalOpen] = React.useState(defaultOpen);\n    const open = openProp ?? internalOpen;\n    const remembering = evidenceKey != null && persist !== \"none\";\n    const [allowed, setAllowed] = React.useState(!remembering);\n    const [pending, setPending] = React.useState(false);\n    const mounted = React.useRef(true);\n    React.useEffect(\n      () => () => {\n        mounted.current = false;\n      },\n      [],\n    );\n\n    React.useEffect(() => {\n      if (!remembering) {\n        setAllowed(true);\n        return;\n      }\n      const dismissed = read(persist as \"session\" | \"local\", KEY + evidenceKey);\n      const shown = read(\"session\", SESSION_KEY);\n      setAllowed(!dismissed && (!shown || shown === evidenceKey));\n    }, [remembering, persist, evidenceKey]);\n\n    const visible = open && allowed;\n\n    const impressed = React.useRef(false);\n    React.useEffect(() => {\n      if (!visible) {\n        impressed.current = false;\n        return;\n      }\n      if (impressed.current) return;\n      impressed.current = true;\n      if (evidenceKey != null) write(\"session\", SESSION_KEY, evidenceKey);\n      onImpression?.();\n    }, [visible, evidenceKey, onImpression]);\n\n    const setOpen = (next: boolean) => {\n      if (openProp === undefined) setInternalOpen(next);\n      onOpenChange?.(next);\n    };\n    const dismiss = () => {\n      if (remembering) write(persist as \"session\" | \"local\", KEY + evidenceKey, \"dismissed\");\n      setOpen(false);\n      onDismiss?.();\n    };\n    const snooze = () => {\n      setOpen(false);\n      onSnooze?.();\n    };\n    const act = () => {\n      if (!onAction || pending) return;\n      const result = onAction();\n      if (result && typeof (result as Promise<unknown>).then === \"function\") {\n        setPending(true);\n        (result as Promise<unknown>).finally(() => {\n          if (mounted.current) setPending(false);\n        });\n      }\n    };\n\n    const handleKeyDown = (e: React.KeyboardEvent<HTMLElement>) => {\n      onKeyDown?.(e);\n      if (e.key === \"Escape\") {\n        e.stopPropagation();\n        dismiss();\n      }\n    };\n\n    const label = `Suggestion from ${agentName}`;\n    const spinner = (\n      <Spinner aria-hidden=\"true\" role={undefined} aria-label={undefined} className=\"size-3.5 motion-reduce:animate-none\" />\n    );\n    const dismissButton = (\n      <Button\n        variant=\"ghost\"\n        size=\"icon-sm\"\n        aria-label={dismissLabel}\n        onClick={dismiss}\n        className=\"size-6 shrink-0 text-muted-foreground [&_svg]:size-3.5\"\n      >\n        <X aria-hidden=\"true\" />\n      </Button>\n    );\n\n    let body: React.ReactNode = null;\n    if (visible && variant === \"inline-suggestion\") {\n      body = (\n        <section\n          ref={ref}\n          aria-label={label}\n          onKeyDown={handleKeyDown}\n          className={cn(\"inline-flex items-center gap-1 animate-nx-fade-in motion-reduce:animate-none\", className)}\n          {...props}\n        >\n          <span id={titleId} className=\"sr-only\">\n            {title}\n            {description ? <> {description}</> : null}\n          </span>\n          {resolved ? (\n            <span className=\"inline-flex items-center gap-1.5 text-xs text-muted-foreground\">\n              <CheckCircle2 aria-hidden=\"true\" className=\"size-3.5 text-success\" />\n              Resolved\n            </span>\n          ) : (\n            <>\n              <Button\n                size=\"sm\"\n                aria-describedby={titleId}\n                aria-busy={pending || undefined}\n                onClick={act}\n                className=\"h-7 rounded-full px-3 text-xs\"\n                leftIcon={pending ? spinner : <Sparkles aria-hidden=\"true\" className=\"size-3.5\" />}\n              >\n                {pending ? pendingLabel : actionLabel}\n              </Button>\n              {dismissButton}\n            </>\n          )}\n        </section>\n      );\n    } else if (visible) {\n      const toast = variant === \"side-toast\";\n      body = (\n        <section\n          ref={ref}\n          aria-labelledby={titleId}\n          onKeyDown={handleKeyDown}\n          className={cn(\n            \"flex items-start gap-3 text-sm animate-nx-fade-in motion-reduce:animate-none\",\n            toast\n              ? \"fixed bottom-4 right-4 z-50 w-80 max-w-[calc(100vw-2rem)] rounded-xl border border-border bg-background p-3.5 shadow-lg\"\n              : \"rounded-lg border border-brand/30 bg-brand-muted/60 p-3.5\",\n            className,\n          )}\n          {...props}\n        >\n          {!toast && (\n            <span\n              aria-hidden=\"true\"\n              className=\"grid size-6 shrink-0 place-items-center rounded-md bg-brand text-brand-foreground [&_svg]:size-3.5\"\n            >\n              <Sparkles />\n            </span>\n          )}\n          <div className=\"flex min-w-0 flex-1 flex-col gap-1\">\n            {toast && (\n              <p className=\"flex items-center gap-1.5 text-xs font-semibold text-brand\">\n                <Sparkles aria-hidden=\"true\" className=\"size-3.5\" />\n                Worth a look\n              </p>\n            )}\n            <p id={titleId} className=\"font-semibold text-foreground\">\n              <span className=\"sr-only\">{label}: </span>\n              {title}\n            </p>\n            {description && <p className=\"text-muted-foreground\">{description}</p>}\n            {reason && <p className=\"text-xs text-muted-foreground\">{reason}</p>}\n            {resolved ? (\n              <p className=\"mt-1 inline-flex items-center gap-1.5 text-xs text-muted-foreground\">\n                <CheckCircle2 aria-hidden=\"true\" className=\"size-3.5 text-success\" />\n                Resolved\n              </p>\n            ) : (\n              <div className=\"mt-1.5 flex flex-wrap items-center gap-1.5\">\n                <Button size=\"sm\" onClick={act} aria-busy={pending || undefined} leftIcon={pending ? spinner : undefined}>\n                  {pending ? pendingLabel : actionLabel}\n                </Button>\n                {onSnooze && (\n                  <Button size=\"sm\" variant=\"ghost\" onClick={snooze}>\n                    {snoozeLabel}\n                  </Button>\n                )}\n              </div>\n            )}\n          </div>\n          {!resolved && dismissButton}\n        </section>\n      );\n    }\n\n    // A persistent polite live region, so a suggestion appearing is announced without stealing focus.\n    return (\n      <div aria-live=\"polite\" className=\"contents\">\n        {body}\n      </div>\n    );\n  },\n);\nProactiveSuggestion.displayName = \"ProactiveSuggestion\";\n"]}

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@nucleux/proactive",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.6.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Proactive Suggestions — invisible AI moments that arrive exactly when needed — Nucleux agentic UI for React.",
+  "keywords": [
+    "nucleux",
+    "react",
+    "ui",
+    "components",
+    "agentic",
+    "ai",
+    "tailwind",
+    "proactive"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "dependencies": {
+    "@nucleux/button": "0.6.0",
+    "@nucleux/spinner": "0.6.0",
+    "@nucleux/utils": "0.6.0",
+    "lucide-react": "^0.469.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "@types/react": "^18.3.18",
+    "react": "^18.3.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/intelligaia-open-labs/nucleux.git",
+    "directory": "packages/proactive"
+  },
+  "homepage": "https://github.com/intelligaia-open-labs/nucleux#readme",
+  "scripts": {
+    "build": "tsup"
+  }
 }