@athenaintel/react 0.10.36 → 0.10.38

package/README.md

@@ -150,6 +150,8 @@ Use `AthenaAssetEmbed` to render a native Athena asset without chat, thread hist
 import { AthenaAssetEmbed, AthenaProvider } from '@athenaintel/react';
 
 function AssetView() {
+  const [linkedReference, setLinkedReference] = useState(null);
+
   return (
     <AthenaProvider config={{ token: accessToken }}>
       <div style={{ height: 800 }}>
@@ -160,14 +162,33 @@ function AssetView() {
           onCitationClick={({ reference, sourceAssetId }) => {
             console.log('Citation clicked', { reference, sourceAssetId });
           }}
+          onCitationAction={({ action, reference }) => {
+            if (action === 'open-in-spaces') {
+              setLinkedReference(reference);
+            }
+          }}
         />
+        {linkedReference && (
+          <AthenaAssetEmbed
+            assetId={linkedReference.id}
+            reference={linkedReference}
+            displayMode="full"
+            readOnly
+          />
+        )}
       </div>
     </AthenaProvider>
   );
 }
 ```
 
-When `onCitationClick` is provided, citation navigation is delegated to the host by default. Set `citationBehavior="browser"` to observe the event while preserving Athena's default new-tab navigation, or `citationBehavior="host"` to delegate navigation without providing a callback.
+When `onCitationClick` is provided, citation navigation is delegated to the host by default. Set `citationBehavior="browser"` to observe the event while preserving Athena's default new-tab navigation. Host mode requires `onCitationClick`; without a handler, the SDK safely falls back to browser navigation.
+
+`onCitationAction` handles actions initiated from a citation popover. It currently receives `action: 'open-in-spaces'` when the user clicks the (+) button. Providing the handler delegates that action to the host by default. Set `citationActionBehavior="browser"` to observe the event while preserving Athena's default navigation; requesting host mode without a handler safely falls back to browser behavior.
+
+Pass the callback's complete `reference` to the linked `AthenaAssetEmbed`, rather than storing only
+`reference.id`. The embed uses the reference anchor to navigate PDFs to the cited page. Updating the
+reference also navigates when the host opens another citation in the same asset.
 
 ## Theming
 

package/dist/assets/AthenaAssetEmbed.d.ts

@@ -1,7 +1,9 @@
 import { type FC, type IframeHTMLAttributes } from "react";
-import { type AthenaAssetCitationBehavior, type AthenaAssetCitationClickEvent } from "./asset-embed-messages";
+import { type AthenaAssetCitationActionEvent, type AthenaAssetCitationBehavior, type AthenaAssetCitationClickEvent, type AthenaAssetCitationReference } from "./asset-embed-messages";
 export interface AthenaAssetEmbedProps extends Omit<IframeHTMLAttributes<HTMLIFrameElement>, "src" | "onError" | "onLoad"> {
     assetId: string;
+    /** Optional citation target to open inside the embedded asset, such as a PDF page. */
+    reference?: AthenaAssetCitationReference;
     /** Defaults to the native full asset experience. */
     displayMode?: "minimal" | "full";
     /** Defaults to true. */
@@ -9,6 +11,9 @@ export interface AthenaAssetEmbedProps extends Omit<IframeHTMLAttributes<HTMLIFr
     expiresInSeconds?: number;
     citationBehavior?: AthenaAssetCitationBehavior;
     onCitationClick?: (event: AthenaAssetCitationClickEvent) => void;
+    /** Controls the citation popover's actions, including the (+) Open in Spaces button. */
+    citationActionBehavior?: AthenaAssetCitationBehavior;
+    onCitationAction?: (event: AthenaAssetCitationActionEvent) => void;
     onLoad?: () => void;
     onError?: (error: Error) => void;
     loadingFallback?: React.ReactNode;

package/dist/assets/asset-embed-messages.d.ts

@@ -1,7 +1,9 @@
 export declare const ATHENA_ASSET_EMBED_READY_MESSAGE: "athena:asset-embed-ready";
 export declare const ATHENA_ASSET_EMBED_CONFIG_MESSAGE: "athena:asset-embed-config";
 export declare const ATHENA_ASSET_CITATION_CLICK_MESSAGE: "athena:asset-citation-click";
+export declare const ATHENA_ASSET_CITATION_ACTION_MESSAGE: "athena:asset-citation-action";
 export type AthenaAssetCitationBehavior = "browser" | "host";
+export type AthenaAssetCitationAction = "open-in-spaces";
 export interface AthenaAssetCitationReference {
     id: string;
     anchor?: unknown;
@@ -13,6 +15,12 @@ export interface AthenaAssetCitationClickEvent {
     sourceAssetId?: string;
     reference: AthenaAssetCitationReference;
 }
+export interface AthenaAssetCitationActionEvent {
+    type: typeof ATHENA_ASSET_CITATION_ACTION_MESSAGE;
+    version: 1;
+    action: AthenaAssetCitationAction;
+    reference: AthenaAssetCitationReference;
+}
 export interface AthenaAssetEmbedReadyEvent {
     type: typeof ATHENA_ASSET_EMBED_READY_MESSAGE;
     version: 1;
@@ -22,10 +30,16 @@ export interface AthenaAssetEmbedConfigEvent {
     version: 1;
     token?: string;
     citationBehavior: AthenaAssetCitationBehavior;
+    citationActionBehavior?: AthenaAssetCitationBehavior;
 }
 export declare function resolveAthenaAssetCitationBehavior({ citationBehavior, hasCitationClickHandler, }: {
     citationBehavior?: AthenaAssetCitationBehavior;
     hasCitationClickHandler: boolean;
 }): AthenaAssetCitationBehavior;
+export declare function resolveAthenaAssetCitationActionBehavior({ citationActionBehavior, hasCitationActionHandler, }: {
+    citationActionBehavior?: AthenaAssetCitationBehavior;
+    hasCitationActionHandler: boolean;
+}): AthenaAssetCitationBehavior;
 export declare function isAthenaAssetEmbedReadyEvent(value: unknown): value is AthenaAssetEmbedReadyEvent;
 export declare function isAthenaAssetCitationClickEvent(value: unknown): value is AthenaAssetCitationClickEvent;
+export declare function isAthenaAssetCitationActionEvent(value: unknown): value is AthenaAssetCitationActionEvent;

package/dist/assets/use-asset-embed.d.ts

@@ -1,3 +1,4 @@
+import type { AthenaAssetCitationReference } from './asset-embed-messages';
 export interface UseAssetEmbedOptions {
     readOnly?: boolean;
     expiresInSeconds?: number;
@@ -26,7 +27,7 @@ export declare function resolveAssetEmbedUrl({ embedUrl, appUrl, backendUrl, cur
     backendUrl?: string | null;
     currentOrigin?: string | null;
 }): string;
-export declare function buildSdkAssetEmbedUrl(embedUrl: string): string;
+export declare function buildSdkAssetEmbedUrl(embedUrl: string, reference?: AthenaAssetCitationReference): string;
 export declare function getAssetEmbedAuthContext({ token, apiKey }: {
     token?: string | null;
     apiKey?: string;

package/dist/index.cjs

@@ -56254,6 +56254,7 @@ const AthenaUserMessage = ({
 const ATHENA_ASSET_EMBED_READY_MESSAGE = "athena:asset-embed-ready";
 const ATHENA_ASSET_EMBED_CONFIG_MESSAGE = "athena:asset-embed-config";
 const ATHENA_ASSET_CITATION_CLICK_MESSAGE = "athena:asset-citation-click";
+const ATHENA_ASSET_CITATION_ACTION_MESSAGE = "athena:asset-citation-action";
 function resolveAthenaAssetCitationBehavior({
   citationBehavior,
   hasCitationClickHandler
@@ -56261,12 +56262,22 @@ function resolveAthenaAssetCitationBehavior({
   if (citationBehavior === "host" && !hasCitationClickHandler) return "browser";
   return citationBehavior ?? (hasCitationClickHandler ? "host" : "browser");
 }
+function resolveAthenaAssetCitationActionBehavior({
+  citationActionBehavior,
+  hasCitationActionHandler
+}) {
+  if (citationActionBehavior === "host" && !hasCitationActionHandler) return "browser";
+  return citationActionBehavior ?? (hasCitationActionHandler ? "host" : "browser");
+}
 function isAthenaAssetEmbedReadyEvent(value) {
   return typeof value === "object" && value !== null && "type" in value && value.type === ATHENA_ASSET_EMBED_READY_MESSAGE && "version" in value && value.version === 1;
 }
 function isAthenaAssetCitationClickEvent(value) {
   return typeof value === "object" && value !== null && "type" in value && value.type === ATHENA_ASSET_CITATION_CLICK_MESSAGE && "version" in value && value.version === 1 && "reference" in value && typeof value.reference === "object" && value.reference !== null && "id" in value.reference && typeof value.reference.id === "string";
 }
+function isAthenaAssetCitationActionEvent(value) {
+  return typeof value === "object" && value !== null && "type" in value && value.type === ATHENA_ASSET_CITATION_ACTION_MESSAGE && "version" in value && value.version === 1 && "action" in value && value.action === "open-in-spaces" && "reference" in value && typeof value.reference === "object" && value.reference !== null && "id" in value.reference && typeof value.reference.id === "string";
+}
 function buildAssetEmbedRequestBody({
   assetId,
   readOnly,
@@ -56379,10 +56390,92 @@ function resolveAssetEmbedUrl({
     return embedUrl;
   }
 }
-function buildSdkAssetEmbedUrl(embedUrl) {
+function setFiniteNumberParam({ params, key, value }) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    params.set(key, String(value));
+  }
+}
+function appendCitationReferenceParams({
+  params,
+  reference: reference2
+}) {
+  var _a2;
+  const anchor = reference2 == null ? void 0 : reference2.anchor;
+  if (!anchor || typeof anchor !== "object" || !("type" in anchor) || typeof anchor.type !== "string") {
+    return;
+  }
+  switch (anchor.type) {
+    case "page":
+      params.set("anchor", anchor.type);
+      setFiniteNumberParam({
+        params,
+        key: "page",
+        value: "page" in anchor ? anchor.page : void 0
+      });
+      break;
+    case "page_range":
+      params.set("anchor", anchor.type);
+      setFiniteNumberParam({
+        params,
+        key: "start_page",
+        value: "startPage" in anchor ? anchor.startPage : void 0
+      });
+      setFiniteNumberParam({
+        params,
+        key: "end_page",
+        value: "endPage" in anchor ? anchor.endPage : void 0
+      });
+      break;
+    case "page_rect":
+      params.set("anchor", anchor.type);
+      setFiniteNumberParam({
+        params,
+        key: "page",
+        value: "page" in anchor ? anchor.page : void 0
+      });
+      setFiniteNumberParam({
+        params,
+        key: "x",
+        value: "x" in anchor ? anchor.x : void 0
+      });
+      setFiniteNumberParam({
+        params,
+        key: "y",
+        value: "y" in anchor ? anchor.y : void 0
+      });
+      setFiniteNumberParam({
+        params,
+        key: "width",
+        value: "width" in anchor ? anchor.width : void 0
+      });
+      setFiniteNumberParam({
+        params,
+        key: "height",
+        value: "height" in anchor ? anchor.height : void 0
+      });
+      break;
+    case "page_text":
+      params.set("anchor", anchor.type);
+      setFiniteNumberParam({
+        params,
+        key: "page",
+        value: "page" in anchor ? anchor.page : void 0
+      });
+      if ("text" in anchor && typeof anchor.text === "string") {
+        params.set("text", anchor.text);
+      }
+      break;
+  }
+  const excerpt = (_a2 = reference2.meta) == null ? void 0 : _a2.excerpt;
+  if (typeof excerpt === "string" && excerpt) {
+    params.set("excerpt", excerpt);
+  }
+}
+function buildSdkAssetEmbedUrl(embedUrl, reference2) {
   try {
     const url = new URL(embedUrl);
     url.searchParams.set("athena_sdk_bridge", "1");
+    appendCitationReferenceParams({ params: url.searchParams, reference: reference2 });
     return url.toString();
   } catch {
     return embedUrl;
@@ -56512,11 +56605,14 @@ const DEFAULT_STYLE = {
 const AUTH_SYNC_INTERVAL_MS = 6e4;
 const AthenaAssetEmbed = ({
   assetId,
+  reference: reference2,
   displayMode = "full",
   readOnly = true,
   expiresInSeconds,
   citationBehavior,
   onCitationClick,
+  citationActionBehavior,
+  onCitationAction,
   onLoad,
   onError,
   loadingFallback,
@@ -56547,11 +56643,18 @@ const AthenaAssetEmbed = ({
       return null;
     }
   }, [embedUrl]);
-  const iframeSrc = React.useMemo(() => embedUrl ? buildSdkAssetEmbedUrl(embedUrl) : null, [embedUrl]);
+  const iframeSrc = React.useMemo(
+    () => embedUrl ? buildSdkAssetEmbedUrl(embedUrl, reference2) : null,
+    [embedUrl, reference2]
+  );
   const effectiveCitationBehavior = resolveAthenaAssetCitationBehavior({
     citationBehavior,
     hasCitationClickHandler: !!onCitationClick
   });
+  const effectiveCitationActionBehavior = resolveAthenaAssetCitationActionBehavior({
+    citationActionBehavior,
+    hasCitationActionHandler: !!onCitationAction
+  });
   const sendConfig = React.useCallback(() => {
     var _a2, _b;
     if (!targetOrigin) return;
@@ -56560,11 +56663,12 @@ const AthenaAssetEmbed = ({
         type: ATHENA_ASSET_EMBED_CONFIG_MESSAGE,
         version: 1,
         ...athenaConfig.token ? { token: athenaConfig.token } : {},
-        citationBehavior: effectiveCitationBehavior
+        citationBehavior: effectiveCitationBehavior,
+        citationActionBehavior: effectiveCitationActionBehavior
       },
       targetOrigin
     );
-  }, [athenaConfig, effectiveCitationBehavior, targetOrigin]);
+  }, [athenaConfig, effectiveCitationActionBehavior, effectiveCitationBehavior, targetOrigin]);
   React.useEffect(() => {
     if (!embedUrl || !targetOrigin) return;
     const handleMessage = (event) => {
@@ -56576,11 +56680,15 @@ const AthenaAssetEmbed = ({
       }
       if (isAthenaAssetCitationClickEvent(event.data)) {
         onCitationClick == null ? void 0 : onCitationClick(event.data);
+        return;
+      }
+      if (isAthenaAssetCitationActionEvent(event.data)) {
+        onCitationAction == null ? void 0 : onCitationAction(event.data);
       }
     };
     window.addEventListener("message", handleMessage);
     return () => window.removeEventListener("message", handleMessage);
-  }, [embedUrl, onCitationClick, sendConfig, targetOrigin]);
+  }, [embedUrl, onCitationAction, onCitationClick, sendConfig, targetOrigin]);
   React.useEffect(() => {
     if (!embedUrl) return;
     sendConfig();