@deepcitation/deepcitation-js 1.1.24 → 1.1.26

package/lib/index.d.ts

@@ -8,6 +8,7 @@ export { parseCitation, getCitationStatus, getAllCitationsFromLlmOutput, groupCi
 export { normalizeCitations, getCitationPageNumber, } from "./parsing/normalizeCitation.js";
 export { isGeminiGarbage, cleanRepeatingLastSentence, } from "./parsing/parseWorkAround.js";
 export type { Citation, CitationStatus, VerifyCitationRequest, VerifyCitationResponse, OutputImageFormat, } from "./types/citation.js";
+export { DeepCitationIcon } from "./react/icons.js";
 export { DEFAULT_OUTPUT_IMAGE_FORMAT } from "./types/citation.js";
 export type { Verification } from "./types/verification.js";
 export { NOT_FOUND_VERIFICATION_INDEX, PENDING_VERIFICATION_INDEX, BLANK_VERIFICATION, } from "./types/verification.js";

package/lib/index.js

@@ -8,6 +8,8 @@ export { DeepCitation } from "./client/index.js";
 export { parseCitation, getCitationStatus, getAllCitationsFromLlmOutput, groupCitationsByAttachmentId, groupCitationsByAttachmentIdObject, } from "./parsing/parseCitation.js";
 export { normalizeCitations, getCitationPageNumber, } from "./parsing/normalizeCitation.js";
 export { isGeminiGarbage, cleanRepeatingLastSentence, } from "./parsing/parseWorkAround.js";
+// Icons
+export { DeepCitationIcon } from "./react/icons.js";
 export { DEFAULT_OUTPUT_IMAGE_FORMAT } from "./types/citation.js";
 export { NOT_FOUND_VERIFICATION_INDEX, PENDING_VERIFICATION_INDEX, BLANK_VERIFICATION, } from "./types/verification.js";
 // Utilities

package/lib/react/CitationComponent.js

@@ -1,16 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { forwardRef, memo, useCallback, useEffect, useMemo, useState, } from "react";
 import { createPortal } from "react-dom";
-import { CheckIcon, WarningIcon } from "./icons.js";
+import { CheckIcon, SpinnerIcon, WarningIcon } from "./icons.js";
 import { Popover, PopoverContent, PopoverTrigger } from "./Popover.js";
-import { generateCitationInstanceId, generateCitationKey, getCitationDisplayText, } from "./utils.js";
+import { cn, generateCitationInstanceId, generateCitationKey, getCitationDisplayText, } from "./utils.js";
 import { useSmartDiff } from "./useSmartDiff.js";
-// =============================================================================
-// UTILITY FUNCTIONS
-// =============================================================================
-function cn(...classes) {
-    return classes.filter(Boolean).join(" ");
-}
 function getStatusLabel(status) {
     if (status.isVerified && !status.isPartialMatch)
         return "Verified";
@@ -30,7 +24,12 @@ function getStatusFromVerification(verification) {
     const status = verification?.status;
     // No verification or no status = pending
     if (!verification || !status) {
-        return { isVerified: false, isMiss: false, isPartialMatch: false, isPending: true };
+        return {
+            isVerified: false,
+            isMiss: false,
+            isPartialMatch: false,
+            isPending: true,
+        };
     }
     const isMiss = status === "not_found";
     const isPending = status === "pending" || status === "loading";
@@ -74,14 +73,12 @@ function ImageOverlay({ src, alt, onClose }) {
 //
 // Use `renderIndicator` prop to customize. Use `variant="indicator"` to show only the icon.
 // =============================================================================
-/** Spinner component for loading/pending state */
-const Spinner = ({ className }) => (_jsxs("svg", { className: cn("animate-spin", className), xmlns: "http://www.w3.org/2000/svg", fill: "none", viewBox: "0 0 24 24", width: "12", height: "12", children: [_jsx("circle", { className: "opacity-25", cx: "12", cy: "12", r: "10", stroke: "currentColor", strokeWidth: "4" }), _jsx("path", { className: "opacity-75", fill: "currentColor", d: "M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" })] }));
 /** Verified indicator - green checkmark for exact matches */
 const VerifiedIndicator = () => (_jsx("span", { className: "inline-flex relative ml-0.5 text-green-600 dark:text-green-500", "aria-hidden": "true", children: _jsx(CheckIcon, {}) }));
 /** Partial match indicator - amber checkmark for partial/relocated matches */
 const PartialIndicator = () => (_jsx("span", { className: "inline-flex relative ml-0.5 text-amber-600 dark:text-amber-500", "aria-hidden": "true", children: _jsx(CheckIcon, {}) }));
 /** Pending indicator - spinner for loading state */
-const PendingIndicator = () => (_jsx("span", { className: "inline-flex ml-1 text-gray-400 dark:text-gray-500", "aria-hidden": "true", children: _jsx(Spinner, {}) }));
+const PendingIndicator = () => (_jsx("span", { className: "inline-flex ml-1 text-gray-400 dark:text-gray-500", "aria-hidden": "true", children: _jsx(SpinnerIcon, {}) }));
 /** Miss indicator - red warning triangle for not found */
 const MissIndicator = () => (_jsx("span", { className: "inline-flex relative ml-0.5 text-red-500 dark:text-red-400", "aria-hidden": "true", children: _jsx(WarningIcon, {}) }));
 function DefaultPopoverContent({ citation, verification, status, onImageClick, }) {
@@ -101,7 +98,9 @@ function DefaultPopoverContent({ citation, verification, status, onImageClick, }
     const pageNumber = verification?.verifiedPageNumber;
     if (!hasSnippet && !statusLabel)
         return null;
-    return (_jsxs("div", { className: "p-3 flex flex-col gap-2 min-w-[200px] max-w-[400px]", children: [statusLabel && (_jsx("span", { className: cn("text-xs font-medium", status.isVerified && !status.isPartialMatch && "text-green-600 dark:text-green-500", status.isPartialMatch && "text-amber-600 dark:text-amber-500", status.isMiss && "text-red-600 dark:text-red-500", status.isPending && "text-gray-500 dark:text-gray-400"), children: statusLabel })), hasSnippet && (_jsxs("span", { className: "text-sm text-gray-700 dark:text-gray-300 italic", children: ["\"", verification.verifiedMatchSnippet, "\""] })), pageNumber && pageNumber > 0 && (_jsxs("span", { className: "text-xs text-gray-500 dark:text-gray-400", children: ["Page ", pageNumber] })), (isMiss || isPartialMatch) && (_jsx(DiffDetails, { citation: citation, verification: verification, status: status }))] }));
+    return (_jsxs("div", { className: "p-3 flex flex-col gap-2 min-w-[200px] max-w-[400px]", children: [statusLabel && (_jsx("span", { className: cn("text-xs font-medium", status.isVerified &&
+                    !status.isPartialMatch &&
+                    "text-green-600 dark:text-green-500", status.isPartialMatch && "text-amber-600 dark:text-amber-500", status.isMiss && "text-red-600 dark:text-red-500", status.isPending && "text-gray-500 dark:text-gray-400"), children: statusLabel })), hasSnippet && (_jsxs("span", { className: "text-sm text-gray-700 dark:text-gray-300 italic", children: ["\"", verification.verifiedMatchSnippet, "\""] })), pageNumber && pageNumber > 0 && (_jsxs("span", { className: "text-xs text-gray-500 dark:text-gray-400", children: ["Page ", pageNumber] })), (isMiss || isPartialMatch) && (_jsx(DiffDetails, { citation: citation, verification: verification, status: status }))] }));
 }
 // =============================================================================
 // DIFF DETAILS COMPONENT
@@ -128,10 +127,16 @@ function DiffDetails({ citation, verification, status, }) {
     const pageDiffers = expectedPage != null && actualPage != null && expectedPage !== actualPage;
     // For "not_found" status, show expected text and "Not found" message
     if (isMiss) {
-        return (_jsxs("div", { className: "mt-2 pt-2 border-t border-gray-200 dark:border-gray-700 text-xs space-y-2", children: [expectedText && (_jsxs("div", { children: [_jsx("span", { className: "text-gray-500 dark:text-gray-400 font-medium uppercase text-[10px]", children: "Expected" }), _jsx("p", { className: "mt-1 p-2 bg-gray-100 dark:bg-gray-800 rounded font-mono text-[11px] break-words text-red-600 dark:text-red-400 line-through opacity-70", children: expectedText.length > 100 ? expectedText.slice(0, 100) + "…" : expectedText })] })), _jsxs("div", { children: [_jsx("span", { className: "text-gray-500 dark:text-gray-400 font-medium uppercase text-[10px]", children: "Found" }), _jsx("p", { className: "mt-1 p-2 bg-gray-100 dark:bg-gray-800 rounded font-mono text-[11px] text-amber-600 dark:text-amber-500 italic", children: "Not found in source" })] })] }));
+        return (_jsxs("div", { className: "mt-2 pt-2 border-t border-gray-200 dark:border-gray-700 text-xs space-y-2", children: [expectedText && (_jsxs("div", { children: [_jsx("span", { className: "text-gray-500 dark:text-gray-400 font-medium uppercase text-[10px]", children: "Expected" }), _jsx("p", { className: "mt-1 p-2 bg-gray-100 dark:bg-gray-800 rounded font-mono text-[11px] break-words text-red-600 dark:text-red-400 line-through opacity-70", children: expectedText.length > 100
+                                ? expectedText.slice(0, 100) + "…"
+                                : expectedText })] })), _jsxs("div", { children: [_jsx("span", { className: "text-gray-500 dark:text-gray-400 font-medium uppercase text-[10px]", children: "Found" }), _jsx("p", { className: "mt-1 p-2 bg-gray-100 dark:bg-gray-800 rounded font-mono text-[11px] text-amber-600 dark:text-amber-500 italic", children: "Not found in source" })] })] }));
     }
     // For partial matches, show word-level diff
-    return (_jsxs("div", { className: "mt-2 pt-2 border-t border-gray-200 dark:border-gray-700 text-xs space-y-2", children: [expectedText && actualText && hasDiff ? (_jsxs("div", { children: [_jsx("span", { className: "text-gray-500 dark:text-gray-400 font-medium uppercase text-[10px]", children: "Diff" }), _jsx("div", { className: "mt-1 p-2 bg-gray-100 dark:bg-gray-800 rounded font-mono text-[11px] break-words text-gray-700 dark:text-gray-300", children: isHighVariance ? (_jsxs("div", { className: "space-y-2", children: [_jsxs("div", { children: [_jsx("span", { className: "text-gray-500 dark:text-gray-400 text-[10px]", children: "Expected: " }), _jsx("span", { className: "text-red-600 dark:text-red-400 line-through opacity-70", children: expectedText.length > 100 ? expectedText.slice(0, 100) + "…" : expectedText })] }), _jsxs("div", { children: [_jsx("span", { className: "text-gray-500 dark:text-gray-400 text-[10px]", children: "Found: " }), _jsx("span", { className: "text-green-600 dark:text-green-400", children: actualText.length > 100 ? actualText.slice(0, 100) + "…" : actualText })] })] })) : (
+    return (_jsxs("div", { className: "mt-2 pt-2 border-t border-gray-200 dark:border-gray-700 text-xs space-y-2", children: [expectedText && actualText && hasDiff ? (_jsxs("div", { children: [_jsx("span", { className: "text-gray-500 dark:text-gray-400 font-medium uppercase text-[10px]", children: "Diff" }), _jsx("div", { className: "mt-1 p-2 bg-gray-100 dark:bg-gray-800 rounded font-mono text-[11px] break-words text-gray-700 dark:text-gray-300", children: isHighVariance ? (_jsxs("div", { className: "space-y-2", children: [_jsxs("div", { children: [_jsxs("span", { className: "text-gray-500 dark:text-gray-400 text-[10px]", children: ["Expected:", " "] }), _jsx("span", { className: "text-red-600 dark:text-red-400 line-through opacity-70", children: expectedText.length > 100
+                                                ? expectedText.slice(0, 100) + "…"
+                                                : expectedText })] }), _jsxs("div", { children: [_jsxs("span", { className: "text-gray-500 dark:text-gray-400 text-[10px]", children: ["Found:", " "] }), _jsx("span", { className: "text-green-600 dark:text-green-400", children: actualText.length > 100
+                                                ? actualText.slice(0, 100) + "…"
+                                                : actualText })] })] })) : (
                         // Inline word-level diff
                         diffResult.map((block, blockIndex) => (_jsx("span", { children: block.parts.map((part, partIndex) => {
                                 const key = `p-${blockIndex}-${partIndex}`;
@@ -145,7 +150,9 @@ function DiffDetails({ citation, verification, status, }) {
                                 return _jsx("span", { children: part.value }, key);
                             }) }, `block-${blockIndex}`)))) })] })) : expectedText && !hasDiff ? (
             // Text matches exactly (partial match is due to location difference)
-            _jsxs("div", { children: [_jsx("span", { className: "text-gray-500 dark:text-gray-400 font-medium uppercase text-[10px]", children: "Text" }), _jsx("p", { className: "mt-1 p-2 bg-gray-100 dark:bg-gray-800 rounded font-mono text-[11px] break-words text-gray-700 dark:text-gray-300", children: expectedText.length > 100 ? expectedText.slice(0, 100) + "…" : expectedText })] })) : null, pageDiffers && (_jsxs("div", { children: [_jsx("span", { className: "text-gray-500 dark:text-gray-400 font-medium uppercase text-[10px]", children: "Page" }), _jsxs("p", { className: "mt-1 font-mono text-[11px] text-gray-700 dark:text-gray-300", children: [_jsx("span", { className: "text-red-600 dark:text-red-400 line-through opacity-70", children: expectedPage }), " → ", actualPage] })] })), lineIdDiffers && (_jsxs("div", { children: [_jsx("span", { className: "text-gray-500 dark:text-gray-400 font-medium uppercase text-[10px]", children: "Line" }), _jsxs("p", { className: "mt-1 font-mono text-[11px] text-gray-700 dark:text-gray-300", children: [_jsx("span", { className: "text-red-600 dark:text-red-400 line-through opacity-70", children: expectedLineIds?.join(", ") }), " → ", actualLineIds?.join(", ")] })] }))] }));
+            _jsxs("div", { children: [_jsx("span", { className: "text-gray-500 dark:text-gray-400 font-medium uppercase text-[10px]", children: "Text" }), _jsx("p", { className: "mt-1 p-2 bg-gray-100 dark:bg-gray-800 rounded font-mono text-[11px] break-words text-gray-700 dark:text-gray-300", children: expectedText.length > 100
+                            ? expectedText.slice(0, 100) + "…"
+                            : expectedText })] })) : null, pageDiffers && (_jsxs("div", { children: [_jsx("span", { className: "text-gray-500 dark:text-gray-400 font-medium uppercase text-[10px]", children: "Page" }), _jsxs("p", { className: "mt-1 font-mono text-[11px] text-gray-700 dark:text-gray-300", children: [_jsx("span", { className: "text-red-600 dark:text-red-400 line-through opacity-70", children: expectedPage }), " → ", actualPage] })] })), lineIdDiffers && (_jsxs("div", { children: [_jsx("span", { className: "text-gray-500 dark:text-gray-400 font-medium uppercase text-[10px]", children: "Line" }), _jsxs("p", { className: "mt-1 font-mono text-[11px] text-gray-700 dark:text-gray-300", children: [_jsx("span", { className: "text-red-600 dark:text-red-400 line-through opacity-70", children: expectedLineIds?.join(", ") }), " → ", actualLineIds?.join(", ")] })] }))] }));
 }
 // =============================================================================
 // MAIN COMPONENT
@@ -193,7 +200,8 @@ export const CitationComponent = forwardRef(({ citation, children, className, hi
             if (typeof actions.setImageExpanded === "string") {
                 setExpandedImageSrc(actions.setImageExpanded);
             }
-            else if (actions.setImageExpanded === true && verification?.verificationImageBase64) {
+            else if (actions.setImageExpanded === true &&
+                verification?.verificationImageBase64) {
                 setExpandedImageSrc(verification.verificationImageBase64);
             }
             else if (actions.setImageExpanded === false) {
@@ -240,14 +248,26 @@ export const CitationComponent = forwardRef(({ citation, children, className, hi
             behaviorConfig.onHover.onEnter(getBehaviorContext());
         }
         eventHandlers?.onMouseEnter?.(citation, citationKey);
-    }, [eventHandlers, behaviorConfig, citation, citationKey, getBehaviorContext]);
+    }, [
+        eventHandlers,
+        behaviorConfig,
+        citation,
+        citationKey,
+        getBehaviorContext,
+    ]);
     const handleMouseLeave = useCallback(() => {
         setIsHovering(false);
         if (behaviorConfig?.onHover?.onLeave) {
             behaviorConfig.onHover.onLeave(getBehaviorContext());
         }
         eventHandlers?.onMouseLeave?.(citation, citationKey);
-    }, [eventHandlers, behaviorConfig, citation, citationKey, getBehaviorContext]);
+    }, [
+        eventHandlers,
+        behaviorConfig,
+        citation,
+        citationKey,
+        getBehaviorContext,
+    ]);
     // Touch handler for mobile
     const handleTouchEnd = useCallback((e) => {
         if (isMobile) {
@@ -257,13 +277,18 @@ export const CitationComponent = forwardRef(({ citation, children, className, hi
         }
     }, [eventHandlers, citation, citationKey, isMobile]);
     // Early return for miss with fallback display
-    if (fallbackDisplay !== null && fallbackDisplay !== undefined && !hideKeySpan && isMiss) {
+    if (fallbackDisplay !== null &&
+        fallbackDisplay !== undefined &&
+        !hideKeySpan &&
+        isMiss) {
         return (_jsx("span", { className: cn("text-gray-400 dark:text-gray-500", className), children: fallbackDisplay }));
     }
     // Status classes for text styling
     const statusClasses = cn(
     // Found status (text color) - verified or partial match
-    (isVerified || isPartialMatch) && variant === "brackets" && "text-blue-600 dark:text-blue-400 hover:text-blue-700 dark:hover:text-blue-300 hover:underline", isMiss && "opacity-70 line-through text-gray-400 dark:text-gray-500", isPending && "text-gray-500 dark:text-gray-400");
+    (isVerified || isPartialMatch) &&
+        variant === "brackets" &&
+        "text-blue-600 dark:text-blue-400 hover:text-blue-700 dark:hover:text-blue-300 hover:underline", isMiss && "opacity-70 line-through text-gray-400 dark:text-gray-500", isPending && "text-gray-500 dark:text-gray-400");
     // Render indicator based on status priority:
     // 1. Custom renderIndicator (if provided)
     // 2. Pending → Spinner
@@ -310,7 +335,8 @@ export const CitationComponent = forwardRef(({ citation, children, className, hi
     const isPopoverHidden = popoverPosition === "hidden";
     const shouldShowPopover = !isPopoverHidden &&
         verification &&
-        (verification.verificationImageBase64 || verification.verifiedMatchSnippet);
+        (verification.verificationImageBase64 ||
+            verification.verifiedMatchSnippet);
     const hasImage = !!verification?.verificationImageBase64;
     // Image overlay
     const imageOverlay = expandedImageSrc ? (_jsx(ImageOverlay, { src: expandedImageSrc, alt: "Citation verification - full size", onClose: () => setExpandedImageSrc(null) })) : null;

package/lib/react/icons.d.ts

@@ -1,3 +1,9 @@
+/**
+ * DeepCitation icon SVG (no dependencies)
+ */
+export declare const DeepCitationIcon: ({ className }: {
+    className?: string;
+}) => import("react/jsx-runtime").JSX.Element;
 /**
  * Check icon SVG (no dependencies)
  */
@@ -6,3 +12,7 @@ export declare const CheckIcon: () => import("react/jsx-runtime").JSX.Element;
  * Warning icon SVG (no dependencies)
  */
 export declare const WarningIcon: () => import("react/jsx-runtime").JSX.Element;
+/** Spinner component for loading/pending state */
+export declare const SpinnerIcon: ({ className }: {
+    className?: string;
+}) => import("react/jsx-runtime").JSX.Element;

package/lib/react/icons.js

@@ -1,4 +1,9 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "./utils.js";
+/**
+ * DeepCitation icon SVG (no dependencies)
+ */
+export const DeepCitationIcon = ({ className }) => (_jsxs("svg", { xmlns: "http://www.w3.org/2000/svg", width: "24", height: "24", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "square", shapeRendering: "crispEdges", className: className, children: [_jsx("path", { d: "M7 3 L3 3 L3 21 L7 21" }), _jsx("path", { d: "M17 3 L21 3 L21 21 L17 21" })] }));
 /**
  * Check icon SVG (no dependencies)
  */
@@ -7,3 +12,5 @@ export const CheckIcon = () => (_jsx("svg", { className: "dc-check-icon", viewBo
  * Warning icon SVG (no dependencies)
  */
 export const WarningIcon = () => (_jsx("svg", { className: "dc-status-icon", viewBox: "0 0 256 256", fill: "currentColor", "aria-hidden": "true", children: _jsx("path", { d: "M236.8,188.09,149.35,36.22h0a24.76,24.76,0,0,0-42.7,0L19.2,188.09a23.51,23.51,0,0,0,0,23.72A24.35,24.35,0,0,0,40.55,224h174.9a24.35,24.35,0,0,0,21.33-12.19A23.51,23.51,0,0,0,236.8,188.09ZM120,104a8,8,0,0,1,16,0v40a8,8,0,0,1-16,0Zm8,88a12,12,0,1,1,12-12A12,12,0,0,1,128,192Z" }) }));
+/** Spinner component for loading/pending state */
+export const SpinnerIcon = ({ className }) => (_jsxs("svg", { className: cn("animate-spin", className), xmlns: "http://www.w3.org/2000/svg", fill: "none", viewBox: "0 0 24 24", width: "12", height: "12", children: [_jsx("circle", { className: "opacity-25", cx: "12", cy: "12", r: "10", stroke: "currentColor", strokeWidth: "4" }), _jsx("path", { className: "opacity-75", fill: "currentColor", d: "M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" })] }));

package/lib/react/utils.d.ts

@@ -1,5 +1,6 @@
 import type { Citation } from "../types/citation.js";
 import type { Verification } from "../types/verification.js";
+export declare function cn(...classes: (string | undefined | null | false)[]): string;
 /**
  * Generates a unique, deterministic key for a citation based on its content.
  *  @param citation - The citation to generate a key for

package/lib/react/utils.js

@@ -1,5 +1,11 @@
 import { sha1Hash } from "../utils/sha.js";
 import { getCitationPageNumber } from "../parsing/normalizeCitation.js";
+// =============================================================================
+// UTILITY FUNCTIONS
+// =============================================================================
+export function cn(...classes) {
+    return classes.filter(Boolean).join(" ");
+}
 /**
  * Generates a unique, deterministic key for a citation based on its content.
  *  @param citation - The citation to generate a key for

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@deepcitation/deepcitation-js",
-    "version": "1.1.24",
+    "version": "1.1.26",
     "description": "DeepCitation JavaScript SDK for deterministic AI citation verification",
     "type": "module",
     "private": false,