@deepcitation/deepcitation-js 1.1.13 → 1.1.15

package/lib/react/CitationComponent.d.ts

@@ -1,7 +1,7 @@
 import React, { type ReactNode } from "react";
 import { type CitationStatus } from "../types/citation.js";
 import type { Verification } from "../types/verification.js";
-import type { BaseCitationProps, CitationEventHandlers, CitationRenderProps, CitationVariant } from "./types.js";
+import type { BaseCitationProps, CitationBehaviorConfig, CitationEventHandlers, CitationRenderProps, CitationVariant } from "./types.js";
 import "./styles.css";
 export type { CitationVariant } from "./types.js";
 /**
@@ -74,6 +74,30 @@ export type { CitationVariant } from "./types.js";
  *   popoverPosition="hidden"
  * />
  * ```
+ *
+ * @example Custom click behavior (replaces default)
+ * ```tsx
+ * <CitationComponent
+ *   citation={citation}
+ *   verification={verificationResult}
+ *   behaviorConfig={{
+ *     onClick: (context, event) => {
+ *       if (context.hasImage) {
+ *         return { setImageExpanded: true };
+ *       }
+ *     }
+ *   }}
+ * />
+ * ```
+ *
+ * @example Disable all click behavior
+ * ```tsx
+ * <CitationComponent
+ *   citation={citation}
+ *   verification={verificationResult}
+ *   behaviorConfig={{ onClick: () => false }}
+ * />
+ * ```
  */
 export interface CitationComponentProps extends BaseCitationProps {
     /**
@@ -97,8 +121,22 @@ export interface CitationComponentProps extends BaseCitationProps {
     displayBrackets?: boolean;
     /**
      * Event handlers for citation interactions.
+     * These are always called regardless of behaviorConfig settings.
      */
     eventHandlers?: CitationEventHandlers;
+    /**
+     * Configuration for customizing default click/hover behaviors.
+     * Use this to disable or extend the built-in behaviors.
+     *
+     * Default behaviors:
+     * - Hover: Shows zoom-in cursor when popover is pinned and has image
+     * - Click 1: Pins the popover open (stays visible without hover)
+     * - Click 2: Opens full-size image overlay (if image available)
+     * - Click 3: Closes image and unpins popover
+     *
+     * @see CitationBehaviorConfig for all options
+     */
+    behaviorConfig?: CitationBehaviorConfig;
     /**
      * Enable mobile touch handlers.
      * @default false

package/lib/react/CitationComponent.js

@@ -198,7 +198,7 @@ const DefaultPopoverContent = ({ citation, verification, status, onImageClick, }
  * This means partial matches have blue text (because they were found) but
  * an orange indicator (because they didn't match exactly).
  */
-export const CitationComponent = forwardRef(({ citation, children, className, displayKeySpan = true, displayBrackets = true, fallbackDisplay, verification, variant = "brackets", eventHandlers, isMobile = false, renderIndicator, renderContent, popoverPosition = "top", renderPopoverContent, }, ref) => {
+export const CitationComponent = forwardRef(({ citation, children, className, displayKeySpan = true, displayBrackets = true, fallbackDisplay, verification, variant = "brackets", eventHandlers, behaviorConfig, isMobile = false, renderIndicator, renderContent, popoverPosition = "top", renderPopoverContent, }, ref) => {
     const containerRef = useRef(null);
     const wrapperRef = useRef(null);
     const [expandedImageSrc, setExpandedImageSrc] = useState(null);
@@ -247,10 +247,52 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
     }, [isTooltipExpanded]);
     const citationKey = useMemo(() => generateCitationKey(citation), [citation]);
     const citationInstanceId = useMemo(() => generateCitationInstanceId(citationKey), [citationKey]);
+    // Create behavior context for custom handlers
+    const getBehaviorContext = useCallback(() => ({
+        citation,
+        citationKey,
+        verification: verification ?? null,
+        isTooltipExpanded,
+        isImageExpanded: !!expandedImageSrc,
+        hasImage: !!verification?.verificationImageBase64,
+    }), [citation, citationKey, verification, isTooltipExpanded, expandedImageSrc]);
+    // Apply behavior actions from custom handler
+    const applyBehaviorActions = useCallback((actions) => {
+        if (actions.setTooltipExpanded !== undefined) {
+            setIsTooltipExpanded(actions.setTooltipExpanded);
+        }
+        if (actions.setImageExpanded !== undefined) {
+            if (typeof actions.setImageExpanded === "string") {
+                setExpandedImageSrc(actions.setImageExpanded);
+            }
+            else if (actions.setImageExpanded === true && verification?.verificationImageBase64) {
+                setExpandedImageSrc(verification.verificationImageBase64);
+            }
+            else if (actions.setImageExpanded === false) {
+                setExpandedImageSrc(null);
+            }
+        }
+        if (actions.setPhrasesExpanded !== undefined) {
+            setIsPhrasesExpanded(actions.setPhrasesExpanded);
+        }
+    }, [verification?.verificationImageBase64]);
     const handleToggleTooltip = useCallback((e) => {
         e.preventDefault();
         e.stopPropagation();
-        // If we have a verification image
+        const context = getBehaviorContext();
+        // If custom onClick handler is provided, it REPLACES default behavior
+        if (behaviorConfig?.onClick) {
+            const result = behaviorConfig.onClick(context, e);
+            // If custom handler returns actions, apply them
+            if (result && typeof result === "object") {
+                applyBehaviorActions(result);
+            }
+            // If returns false or void, no state changes
+            // Always call eventHandlers.onClick regardless of custom behavior
+            eventHandlers?.onClick?.(citation, citationKey, e);
+            return;
+        }
+        // Default click behavior (only runs when no custom onClick is provided)
         if (verification?.verificationImageBase64) {
             if (expandedImageSrc) {
                 // Image is open - close it and unpin
@@ -262,7 +304,7 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
                 setExpandedImageSrc(verification.verificationImageBase64);
             }
             else {
-                // First click - just pin the popover open
+                // First click - pin the popover open
                 setIsTooltipExpanded(true);
             }
         }
@@ -274,11 +316,14 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
         eventHandlers?.onClick?.(citation, citationKey, e);
     }, [
         eventHandlers,
+        behaviorConfig,
         citation,
         citationKey,
         verification?.verificationImageBase64,
         expandedImageSrc,
         isTooltipExpanded,
+        getBehaviorContext,
+        applyBehaviorActions,
     ]);
     const status = getCitationStatus(verification ?? null);
     // const { isVerified, isPending } = status;
@@ -297,11 +342,19 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
     const foundStatusClass = useMemo(() => getFoundStatusClass(status), [status]);
     // Event handlers
     const handleMouseEnter = useCallback(() => {
+        // Call custom onHover.onEnter handler (if provided)
+        if (behaviorConfig?.onHover?.onEnter) {
+            behaviorConfig.onHover.onEnter(getBehaviorContext());
+        }
         eventHandlers?.onMouseEnter?.(citation, citationKey);
-    }, [eventHandlers, citation, citationKey]);
+    }, [eventHandlers, behaviorConfig, citation, citationKey, getBehaviorContext]);
     const handleMouseLeave = useCallback(() => {
+        // Call custom onHover.onLeave handler (if provided)
+        if (behaviorConfig?.onHover?.onLeave) {
+            behaviorConfig.onHover.onLeave(getBehaviorContext());
+        }
         eventHandlers?.onMouseLeave?.(citation, citationKey);
-    }, [eventHandlers, citation, citationKey]);
+    }, [eventHandlers, behaviorConfig, citation, citationKey, getBehaviorContext]);
     const handleTouchEnd = useCallback((e) => {
         if (isMobile) {
             e.preventDefault();

package/lib/react/index.d.ts

@@ -10,7 +10,7 @@
  *
  * @packageDocumentation
  */
-export type { CitationContentProps, CitationRenderProps, CitationTooltipProps, CitationStyles, CitationStateClasses, CitationCursorClasses, CitationEventHandlers, CitationVariant as CitationVariantType, UrlFetchStatus, UrlCitationMeta, UrlCitationProps, } from "./types.js";
+export type { CitationContentProps, CitationRenderProps, CitationTooltipProps, CitationStyles, CitationStateClasses, CitationCursorClasses, CitationEventHandlers, CitationVariant as CitationVariantType, UrlFetchStatus, UrlCitationMeta, UrlCitationProps, CitationBehaviorConfig, CitationBehaviorContext, CitationBehaviorActions, CitationClickBehavior, CitationHoverBehavior, } from "./types.js";
 export { extractDomain, isBlockedStatus, isErrorStatus, isVerifiedStatus, } from "./UrlCitationComponent.js";
 export { generateCitationKey, generateCitationInstanceId, getCitationDisplayText, getCitationKeySpanText, classNames, CITATION_X_PADDING, CITATION_Y_PADDING, } from "./utils.js";
 export { CitationComponent, MemoizedCitationComponent, type CitationVariant, type CitationComponentProps, } from "./CitationComponent.js";

package/lib/react/types.d.ts

@@ -184,6 +184,94 @@ export interface CitationEventHandlers {
     /** Called on touch end (mobile) */
     onTouchEnd?: (citation: Citation, citationKey: string, event: React.TouchEvent) => void;
 }
+/**
+ * Context provided to behavior handlers for making decisions.
+ */
+export interface CitationBehaviorContext {
+    /** The citation data */
+    citation: Citation;
+    /** Unique key for this citation */
+    citationKey: string;
+    /** Verification result if available */
+    verification: Verification | null;
+    /** Whether the popover is currently pinned open */
+    isTooltipExpanded: boolean;
+    /** Whether the full-size image overlay is currently open */
+    isImageExpanded: boolean;
+    /** Whether a verification image is available */
+    hasImage: boolean;
+}
+/**
+ * Actions that can be performed by the citation component.
+ * These are returned by behavior handlers to control component state.
+ */
+export interface CitationBehaviorActions {
+    /** Pin or unpin the popover (keeps it visible without hover) */
+    setTooltipExpanded?: boolean;
+    /** Open or close the full-size image overlay */
+    setImageExpanded?: boolean | string;
+    /** Expand or collapse the search phrases list (for miss/partial states) */
+    setPhrasesExpanded?: boolean;
+}
+/**
+ * Configuration for click behavior.
+ * Return actions to perform, or `false` to prevent default behavior.
+ */
+export type CitationClickBehavior = (context: CitationBehaviorContext, event: React.MouseEvent | React.TouchEvent) => CitationBehaviorActions | false | void;
+/**
+ * Configuration for hover behavior.
+ */
+export interface CitationHoverBehavior {
+    /** Called when mouse enters the citation */
+    onEnter?: (context: CitationBehaviorContext) => void;
+    /** Called when mouse leaves the citation */
+    onLeave?: (context: CitationBehaviorContext) => void;
+}
+/**
+ * Configuration for customizing default citation behaviors.
+ *
+ * When you provide `onClick` or `onHover`, they REPLACE the corresponding default behaviors.
+ * Use `eventHandlers` for side effects that should run alongside defaults.
+ *
+ * @example Custom click behavior (replaces default)
+ * ```tsx
+ * <CitationComponent
+ *   citation={citation}
+ *   verification={verification}
+ *   behaviorConfig={{
+ *     onClick: (context, event) => {
+ *       if (context.hasImage) {
+ *         return { setImageExpanded: true };
+ *       }
+ *     }
+ *   }}
+ * />
+ * ```
+ *
+ * @example Disable click behavior entirely
+ * ```tsx
+ * <CitationComponent
+ *   citation={citation}
+ *   verification={verification}
+ *   behaviorConfig={{ onClick: () => false }}
+ * />
+ * ```
+ */
+export interface CitationBehaviorConfig {
+    /**
+     * Custom click behavior handler. When provided, REPLACES the default click behavior.
+     *
+     * Return values:
+     * - `CitationBehaviorActions`: Apply specific state changes
+     * - `false`: Prevent any state changes
+     * - `void`/`undefined`: No state changes
+     */
+    onClick?: CitationClickBehavior;
+    /**
+     * Custom hover behavior handlers. When provided, REPLACE the default hover behavior.
+     */
+    onHover?: CitationHoverBehavior;
+}
 /**
  * Props for the tooltip wrapper component
  */

package/package.json

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