@athenaintel/react 0.10.38 → 0.10.40

package/README.md

@@ -144,13 +144,19 @@ Set `linkClicks={{ interceptAthenaCitations: false }}` to keep Athena citation l
 
 ## Standalone Asset Embeds
 
-Use `AthenaAssetEmbed` to render a native Athena asset without chat, thread history, tabs, or the SDK split-pane layout. Full mode supports documents, spreadsheets, and presentations.
+Use `AthenaAssetEmbed` to render a native Athena asset without chat, thread history, tabs, or the SDK split-pane layout. It defaults to the editable, full native asset experience (`readOnly={false}` and `displayMode="full"`). The embed token and the current user must still have edit permission; otherwise Athena renders the asset read-only.
 
 ```tsx
-import { AthenaAssetEmbed, AthenaProvider } from '@athenaintel/react';
+import { useState } from 'react';
+import {
+  AthenaAssetEmbed,
+  AthenaProvider,
+  type AthenaAssetCitationReference,
+} from '@athenaintel/react';
 
 function AssetView() {
-  const [linkedReference, setLinkedReference] = useState(null);
+  const [linkedReference, setLinkedReference] =
+    useState<AthenaAssetCitationReference | null>(null);
 
   return (
     <AthenaProvider config={{ token: accessToken }}>
@@ -158,7 +164,7 @@ function AssetView() {
         <AthenaAssetEmbed
           assetId="asset_123"
           displayMode="full"
-          readOnly
+          readOnly={false}
           onCitationClick={({ reference, sourceAssetId }) => {
             console.log('Citation clicked', { reference, sourceAssetId });
           }}
@@ -173,7 +179,7 @@ function AssetView() {
             assetId={linkedReference.id}
             reference={linkedReference}
             displayMode="full"
-            readOnly
+            readOnly={false}
           />
         )}
       </div>
@@ -187,8 +193,44 @@ When `onCitationClick` is provided, citation navigation is delegated to the host
 `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.
+`reference.id`. The embed uses the reference anchor to navigate PDFs to the cited page and highlight
+the cited excerpt or rectangular region. Updating the reference also navigates when the host opens
+another citation in the same asset.
+
+If the host starts with an Athena citation URL/string instead of an
+`onCitationAction` event, parse it and pass the returned `reference` directly to the embed:
+
+```tsx
+import {
+  AthenaAssetEmbed,
+  parseAthenaCitationLink,
+} from '@athenaintel/react';
+
+const citation = parseAthenaCitationLink({
+  href: citationString,
+  appUrl: 'https://app.athenaintel.com',
+});
+
+return citation ? (
+  <AthenaAssetEmbed
+    assetId={citation.assetId}
+    reference={citation.reference}
+    displayMode="full"
+    readOnly={false}
+  />
+) : null;
+```
+
+For example, this citation opens the PDF directly at page 34:
+
+```text
+https://app.athenaintel.com/dashboard/spaces/?asset_ids=asset_pdf&anchor=page&page=34&excerpt=Term%20debt
+```
+
+The important query parameters are `asset_ids`, `anchor=page`, `page`, and `excerpt`. Page ranges,
+text anchors, and positioned citations are also preserved by `parseAthenaCitationLink`. A
+`page_rect` may include `unit=percent` (the default) or `unit=point`; retain the unit so the region
+maps to the correct PDF coordinates.
 
 ## Theming
 

package/dist/assets/AthenaAssetEmbed.d.ts

@@ -6,7 +6,7 @@ export interface AthenaAssetEmbedProps extends Omit<IframeHTMLAttributes<HTMLIFr
     reference?: AthenaAssetCitationReference;
     /** Defaults to the native full asset experience. */
     displayMode?: "minimal" | "full";
-    /** Defaults to true. */
+    /** Defaults to false so authorized users can edit the embedded asset. */
     readOnly?: boolean;
     expiresInSeconds?: number;
     citationBehavior?: AthenaAssetCitationBehavior;

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

@@ -2,9 +2,11 @@ import type { AthenaAssetCitationReference } from './asset-embed-messages';
 export interface UseAssetEmbedOptions {
     readOnly?: boolean;
     expiresInSeconds?: number;
-    /** Native Olympus surface rendered by the iframe. Defaults to `minimal`. */
+    /** Native Olympus surface rendered by the iframe. Defaults to `full`. */
     displayMode?: 'minimal' | 'full';
 }
+export declare const DEFAULT_ASSET_EMBED_READ_ONLY = false;
+export declare const DEFAULT_ASSET_EMBED_DISPLAY_MODE: 'full';
 export interface UseAssetEmbedResult {
     embedUrl: string | null;
     isLoading: boolean;

package/dist/chat/athena-citation-links.d.ts

@@ -1,3 +1,4 @@
+import type { AthenaAssetCitationReference } from '../assets/asset-embed-messages';
 import { type AssetType } from '../assets/asset-panel-store';
 import type { AthenaCitationLinkHandler, AthenaLinkClickHandler } from '../provider/citation-links';
 export interface ParsedAthenaCitationLink {
@@ -5,6 +6,8 @@ export interface ParsedAthenaCitationLink {
     assetId: string;
     assetIds: string[];
     assetType: AssetType | null;
+    /** Complete target that can be passed directly to AthenaAssetEmbed.reference. */
+    reference: AthenaAssetCitationReference;
 }
 export declare const parseAthenaCitationLink: ({ href, appUrl, }: {
     href: string;

package/dist/index.cjs

@@ -47521,6 +47521,60 @@ const ASSET_TYPE_ALIASES = {
   word_document: "document"
 };
 const isAthenaSpacesPath = (url) => url.pathname.replace(/\/+$/, "") === "/dashboard/spaces";
+const getFiniteNumber = (url, key) => {
+  const value = url.searchParams.get(key);
+  if (value === null || value.trim() === "") return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+};
+const parseCitationReference = ({
+  url,
+  assetId
+}) => {
+  const reference2 = { id: assetId };
+  const anchorType = url.searchParams.get("anchor");
+  const page = getFiniteNumber(url, "page");
+  switch (anchorType) {
+    case "page":
+      if (page !== null) reference2.anchor = { type: anchorType, page };
+      break;
+    case "page_range": {
+      const startPage = getFiniteNumber(url, "start_page");
+      const endPage = getFiniteNumber(url, "end_page");
+      if (startPage !== null && endPage !== null) {
+        reference2.anchor = { type: anchorType, startPage, endPage };
+      }
+      break;
+    }
+    case "page_rect": {
+      const x = getFiniteNumber(url, "x");
+      const y = getFiniteNumber(url, "y");
+      const width = getFiniteNumber(url, "width");
+      const height = getFiniteNumber(url, "height");
+      if (page !== null && x !== null && y !== null && width !== null && height !== null) {
+        const unit = url.searchParams.get("unit");
+        reference2.anchor = {
+          type: anchorType,
+          page,
+          x,
+          y,
+          width,
+          height,
+          ...unit === "percent" || unit === "point" ? { unit } : {}
+        };
+      }
+      break;
+    }
+    case "page_text": {
+      const text2 = url.searchParams.get("text");
+      if (page !== null && text2) reference2.anchor = { type: anchorType, page, text: text2 };
+      break;
+    }
+  }
+  const excerpt = url.searchParams.get("excerpt");
+  if (excerpt) reference2.meta = { excerpt };
+  return reference2;
+};
 const normalizeAssetType = (value) => {
   if (!value) {
     return null;
@@ -47609,7 +47663,8 @@ const parseAthenaCitationLink = ({
     url,
     assetId,
     assetIds,
-    assetType: normalizeAssetType(url.searchParams.get("asset_type") ?? url.searchParams.get("type"))
+    assetType: normalizeAssetType(url.searchParams.get("asset_type") ?? url.searchParams.get("type")),
+    reference: parseCitationReference({ url, assetId })
   };
 };
 const isAthenaCitationUrl = ({
@@ -56278,6 +56333,8 @@ function isAthenaAssetCitationClickEvent(value) {
 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";
 }
+const DEFAULT_ASSET_EMBED_READ_ONLY = false;
+const DEFAULT_ASSET_EMBED_DISPLAY_MODE = "full";
 function buildAssetEmbedRequestBody({
   assetId,
   readOnly,
@@ -56453,6 +56510,9 @@ function appendCitationReferenceParams({
         key: "height",
         value: "height" in anchor ? anchor.height : void 0
       });
+      if ("unit" in anchor && (anchor.unit === "percent" || anchor.unit === "point")) {
+        params.set("unit", anchor.unit);
+      }
       break;
     case "page_text":
       params.set("anchor", anchor.type);
@@ -56511,9 +56571,9 @@ function useAssetEmbed(assetId, options = {
   backendUrl: ""
 }) {
   const {
-    readOnly = false,
+    readOnly = DEFAULT_ASSET_EMBED_READ_ONLY,
     expiresInSeconds = 60 * 60 * 24 * 30,
-    displayMode = "minimal",
+    displayMode = DEFAULT_ASSET_EMBED_DISPLAY_MODE,
     backendUrl,
     appUrl,
     apiKey,
@@ -56606,8 +56666,8 @@ const AUTH_SYNC_INTERVAL_MS = 6e4;
 const AthenaAssetEmbed = ({
   assetId,
   reference: reference2,
-  displayMode = "full",
-  readOnly = true,
+  displayMode = DEFAULT_ASSET_EMBED_DISPLAY_MODE,
+  readOnly = DEFAULT_ASSET_EMBED_READ_ONLY,
   expiresInSeconds,
   citationBehavior,
   onCitationClick,