@deepcitation/deepcitation-js 1.1.13 → 1.1.14

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,29 @@ export type { CitationVariant } from "./types.js";
  *   popoverPosition="hidden"
  * />
  * ```
+ *
+ * @example Customize click behavior - disable image expand
+ * ```tsx
+ * <CitationComponent
+ *   citation={citation}
+ *   verification={verificationResult}
+ *   behaviorConfig={{ disableImageExpand: true }}
+ * />
+ * ```
+ *
+ * @example Custom click handler with default behavior
+ * ```tsx
+ * <CitationComponent
+ *   citation={citation}
+ *   verification={verificationResult}
+ *   behaviorConfig={{
+ *     onClick: (context, event) => {
+ *       // Log analytics, then let default behavior proceed
+ *       analytics.track('citation_clicked', { key: context.citationKey });
+ *     }
+ *   }}
+ * />
+ * ```
  */
 export interface CitationComponentProps extends BaseCitationProps {
     /**
@@ -97,8 +120,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,9 +247,63 @@ 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();
+        const context = getBehaviorContext();
+        // Call custom onClick handler first (if provided)
+        if (behaviorConfig?.onClick) {
+            const result = behaviorConfig.onClick(context, e);
+            // If custom handler returns actions, apply them and skip default behavior
+            if (result && typeof result === "object") {
+                applyBehaviorActions(result);
+                // Always call eventHandlers.onClick regardless of custom behavior
+                eventHandlers?.onClick?.(citation, citationKey, e);
+                return;
+            }
+            // If custom handler returns false, skip default behavior entirely
+            if (result === false) {
+                // Always call eventHandlers.onClick regardless of custom behavior
+                eventHandlers?.onClick?.(citation, citationKey, e);
+                return;
+            }
+            // Otherwise (undefined/void), proceed with default behavior
+        }
+        // Check if click behavior is completely disabled
+        if (behaviorConfig?.disableClickBehavior) {
+            eventHandlers?.onClick?.(citation, citationKey, e);
+            return;
+        }
+        // Default click behavior
         // If we have a verification image
         if (verification?.verificationImageBase64) {
             if (expandedImageSrc) {
@@ -258,27 +312,36 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
                 setIsTooltipExpanded(false);
             }
             else if (isTooltipExpanded) {
-                // Already pinned - second click expands image
-                setExpandedImageSrc(verification.verificationImageBase64);
+                // Already pinned - second click expands image (unless disabled)
+                if (!behaviorConfig?.disableImageExpand) {
+                    setExpandedImageSrc(verification.verificationImageBase64);
+                }
             }
             else {
-                // First click - just pin the popover open
-                setIsTooltipExpanded(true);
+                // First click - just pin the popover open (unless disabled)
+                if (!behaviorConfig?.disablePopoverPin) {
+                    setIsTooltipExpanded(true);
+                }
             }
         }
         else {
             // No image - toggle phrases expansion for miss/partial tooltips
-            setIsTooltipExpanded((prev) => !prev);
-            setIsPhrasesExpanded((prev) => !prev);
+            if (!behaviorConfig?.disablePopoverPin) {
+                setIsTooltipExpanded((prev) => !prev);
+                setIsPhrasesExpanded((prev) => !prev);
+            }
         }
         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 +360,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,147 @@ 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.
+ *
+ * @example Use defaults (no config needed)
+ * ```tsx
+ * <CitationComponent citation={citation} verification={verification} />
+ * ```
+ *
+ * @example Disable click-to-expand image (popover still pins on click)
+ * ```tsx
+ * <CitationComponent
+ *   citation={citation}
+ *   verification={verification}
+ *   behaviorConfig={{ disableImageExpand: true }}
+ * />
+ * ```
+ *
+ * @example Disable all click behavior
+ * ```tsx
+ * <CitationComponent
+ *   citation={citation}
+ *   verification={verification}
+ *   behaviorConfig={{ disableClickBehavior: true }}
+ * />
+ * ```
+ *
+ * @example Custom click behavior (extend defaults)
+ * ```tsx
+ * <CitationComponent
+ *   citation={citation}
+ *   verification={verification}
+ *   behaviorConfig={{
+ *     onClick: (context, event) => {
+ *       // Log analytics
+ *       analytics.track('citation_clicked', { key: context.citationKey });
+ *       // Return nothing to use default behavior
+ *     }
+ *   }}
+ * />
+ * ```
+ *
+ * @example Override click behavior completely
+ * ```tsx
+ * <CitationComponent
+ *   citation={citation}
+ *   verification={verification}
+ *   behaviorConfig={{
+ *     onClick: (context, event) => {
+ *       // Custom behavior: always open image immediately
+ *       if (context.hasImage) {
+ *         return { setImageExpanded: true };
+ *       }
+ *       return false; // Prevent default behavior
+ *     }
+ *   }}
+ * />
+ * ```
+ */
+export interface CitationBehaviorConfig {
+    /**
+     * Disable the default click behavior entirely.
+     * When true, clicks won't pin popovers or expand images.
+     * Your eventHandlers.onClick will still be called.
+     * @default false
+     */
+    disableClickBehavior?: boolean;
+    /**
+     * Disable the click-to-expand image behavior.
+     * First click still pins the popover, but second click won't expand the image.
+     * @default false
+     */
+    disableImageExpand?: boolean;
+    /**
+     * Disable the popover pinning behavior.
+     * Clicks won't pin the popover open; it will only show on hover.
+     * @default false
+     */
+    disablePopoverPin?: boolean;
+    /**
+     * Custom click behavior handler.
+     *
+     * - Return `CitationBehaviorActions` to override default behavior with specific actions
+     * - Return `false` to prevent default behavior entirely
+     * - Return `void`/`undefined` to let default behavior proceed
+     *
+     * This is called BEFORE the default behavior, allowing you to:
+     * 1. Add side effects (analytics, etc.) and let defaults proceed (return void)
+     * 2. Completely override behavior (return actions or false)
+     *
+     * Note: eventHandlers.onClick is always called regardless of this handler's return value.
+     */
+    onClick?: CitationClickBehavior;
+    /**
+     * Custom hover behavior handlers.
+     * These are called in addition to (not instead of) eventHandlers.onMouseEnter/Leave.
+     */
+    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.14",
     "description": "DeepCitation JavaScript SDK for deterministic AI citation verification",
     "type": "module",
     "private": false,