@deepcitation/deepcitation-js 1.1.15 → 1.1.16

package/lib/react/CitationComponent.d.ts

@@ -16,22 +16,22 @@ export type { CitationVariant } from "./types.js";
  * // Renders: [Revenue grew by 25%✓] with blue text
  * ```
  *
- * @example Numeric only - use displayKeySpan=false with brackets variant
+ * @example Numeric only - use hideKeySpan=true with brackets variant
  * ```tsx
  * <CitationComponent
  *   citation={{ citationNumber: 1, keySpan: "25% growth" }}
  *   verification={verificationResult}
- *   displayKeySpan={false}
+ *   hideKeySpan={true}
  * />
  * // Renders: [1✓]
  * ```
  *
- * @example Without brackets - use displayBrackets=false
+ * @example Without brackets - use hideBrackets=true
  * ```tsx
  * <CitationComponent
  *   citation={{ citationNumber: 1, keySpan: "25% growth" }}
  *   verification={verificationResult}
- *   displayBrackets={false}
+ *   hideBrackets={true}
  * />
  * // Renders: 25% growth✓ (no brackets)
  * ```
@@ -114,11 +114,11 @@ export interface CitationComponentProps extends BaseCitationProps {
      */
     variant?: CitationVariant;
     /**
-     * Whether to show square brackets around the citation.
+     * Whether to hide square brackets around the citation.
      * Only applies to the `brackets` variant.
-     * @default true
+     * @default false
      */
-    displayBrackets?: boolean;
+    hideBrackets?: boolean;
     /**
      * Event handlers for citation interactions.
      * These are always called regardless of behaviorConfig settings.
@@ -149,7 +149,7 @@ export interface CitationComponentProps extends BaseCitationProps {
     renderIndicator?: (status: CitationStatus) => ReactNode;
     /**
      * Custom render function for the entire citation content.
-     * When provided, takes full control of rendering (ignores format, showBrackets).
+     * When provided, takes full control of rendering.
      */
     renderContent?: (props: CitationRenderProps) => ReactNode;
     /**

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, behaviorConfig, isMobile = false, renderIndicator, renderContent, popoverPosition = "top", renderPopoverContent, }, ref) => {
+export const CitationComponent = forwardRef(({ citation, children, className, hideKeySpan = false, hideBrackets = false, 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);
@@ -280,7 +280,7 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
         e.preventDefault();
         e.stopPropagation();
         const context = getBehaviorContext();
-        // If custom onClick handler is provided, it REPLACES default behavior
+        // If custom onClick handler is provided via behaviorConfig, it REPLACES default behavior
         if (behaviorConfig?.onClick) {
             const result = behaviorConfig.onClick(context, e);
             // If custom handler returns actions, apply them
@@ -292,7 +292,13 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
             eventHandlers?.onClick?.(citation, citationKey, e);
             return;
         }
-        // Default click behavior (only runs when no custom onClick is provided)
+        // If eventHandlers.onClick is provided, disable default click behavior
+        // (no popover pinning, no image expansion) - just call the handler
+        if (eventHandlers?.onClick) {
+            eventHandlers.onClick(citation, citationKey, e);
+            return;
+        }
+        // Default click behavior (only runs when no click handlers are provided)
         if (verification?.verificationImageBase64) {
             if (expandedImageSrc) {
                 // Image is open - close it and unpin
@@ -313,7 +319,6 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
             setIsTooltipExpanded((prev) => !prev);
             setIsPhrasesExpanded((prev) => !prev);
         }
-        eventHandlers?.onClick?.(citation, citationKey, e);
     }, [
         eventHandlers,
         behaviorConfig,
@@ -329,15 +334,15 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
     // const { isVerified, isPending } = status;
     const { isMiss, isPartialMatch, isVerified, isPending } = status;
     const displayText = useMemo(() => {
-        // For text/minimal variants, always show keySpan
-        // For brackets variant, show keySpan based on displayKeySpan prop
+        // For text/minimal variants, always show keySpan (hideKeySpan is ignored)
+        // For brackets variant, show keySpan based on hideKeySpan prop
         return getCitationDisplayText(citation, {
-            displayKeySpan: variant === "text" ||
-                variant === "minimal" ||
-                displayKeySpan,
+            hideKeySpan: variant !== "text" &&
+                variant !== "minimal" &&
+                hideKeySpan,
             fallbackDisplay,
         });
-    }, [citation, variant, displayKeySpan, fallbackDisplay]);
+    }, [citation, variant, hideKeySpan, fallbackDisplay]);
     // Found status class for text styling (blue for found, gray for miss)
     const foundStatusClass = useMemo(() => getFoundStatusClass(status), [status]);
     // Event handlers
@@ -365,7 +370,7 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
     // Early return for miss with fallback display
     if (fallbackDisplay !== null &&
         fallbackDisplay !== undefined &&
-        displayKeySpan &&
+        !hideKeySpan &&
         isMiss) {
         return (_jsx("span", { className: classNames("dc-citation-fallback", className), children: fallbackDisplay }));
     }
@@ -398,7 +403,7 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
                 status,
                 citationKey,
                 displayText,
-                isMergedDisplay: variant === "text" || variant === "brackets" || displayKeySpan,
+                isMergedDisplay: variant === "text" || variant === "brackets" || !hideKeySpan,
             });
         }
         // Indicator-only variant - just the checkmark/warning
@@ -414,7 +419,7 @@ export const CitationComponent = forwardRef(({ citation, children, className, di
             return (_jsxs("span", { className: "dc-citation-text", children: [displayText, renderStatusIndicator()] }));
         }
         // Brackets variant (default) - keySpan/number in brackets with styling
-        return (_jsxs("span", { className: "dc-citation-bracket", "aria-hidden": "true", role: "presentation", children: [displayBrackets && "[", _jsxs("span", { className: "dc-citation-text", children: [displayText, renderStatusIndicator()] }), displayBrackets && "]"] }));
+        return (_jsxs("span", { className: "dc-citation-bracket", "aria-hidden": "true", role: "presentation", children: [!hideBrackets && "[", _jsxs("span", { className: "dc-citation-text", children: [displayText, renderStatusIndicator()] }), !hideBrackets && "]"] }));
     };
     // Determine if popover should be shown
     const isPopoverHidden = popoverPosition === "hidden";

package/lib/react/CitationVariants.d.ts

@@ -43,8 +43,8 @@ export interface ChipCitationProps extends CitationVariantProps {
  */
 export declare const ChipCitation: React.ForwardRefExoticComponent<ChipCitationProps & React.RefAttributes<HTMLSpanElement>>;
 export interface SuperscriptCitationProps extends CitationVariantProps {
-    /** Whether to show brackets around the superscript */
-    showBrackets?: boolean;
+    /** Whether to hide brackets around the superscript */
+    hideBrackets?: boolean;
 }
 /**
  * Superscript style citation component.

package/lib/react/CitationVariants.js

@@ -31,16 +31,16 @@ const DefaultPartialIndicator = () => (_jsx("span", { className: "citation-parti
  * <ChipCitation citation={citation} verification={found} size="md" />
  * ```
  */
-export const ChipCitation = forwardRef(({ citation, children, className, displayKeySpan = false, fallbackDisplay, verification, eventHandlers, isMobile = false, preventTooltips = false, pendingContent = TWO_DOTS_THINKING_CONTENT, renderVerifiedIndicator = () => _jsx(DefaultVerifiedIndicator, {}), renderPartialIndicator = () => _jsx(DefaultPartialIndicator, {}), size = "md", showIcon = false, icon, }, ref) => {
+export const ChipCitation = forwardRef(({ citation, children, className, hideKeySpan = false, fallbackDisplay, verification, eventHandlers, isMobile = false, preventTooltips = false, pendingContent = TWO_DOTS_THINKING_CONTENT, renderVerifiedIndicator = () => _jsx(DefaultVerifiedIndicator, {}), renderPartialIndicator = () => _jsx(DefaultPartialIndicator, {}), size = "md", showIcon = false, icon, }, ref) => {
     const { citationKey, citationInstanceId, status } = useCitationData(citation, verification);
     const { isVerified, isMiss, isPartialMatch, isPending } = status;
     const displayText = useMemo(() => getCitationDisplayText(citation, {
-        displayKeySpan,
+        hideKeySpan,
         fallbackDisplay,
-    }), [citation, displayKeySpan, fallbackDisplay]);
+    }), [citation, hideKeySpan, fallbackDisplay]);
     const keySpanText = useMemo(() => getCitationKeySpanText(citation, {
-        displayKeySpan,
-    }), [citation, displayKeySpan]);
+        hideKeySpan,
+    }), [citation, hideKeySpan]);
     const handleClick = useCallback((e) => {
         e.preventDefault();
         e.stopPropagation();
@@ -81,13 +81,13 @@ ChipCitation.displayName = "ChipCitation";
  * // Renders: Text content¹
  * ```
  */
-export const SuperscriptCitation = forwardRef(({ citation, children, className, displayKeySpan = false, fallbackDisplay, verification, eventHandlers, isMobile = false, preventTooltips = false, pendingContent = TWO_DOTS_THINKING_CONTENT, renderVerifiedIndicator = () => _jsx(DefaultVerifiedIndicator, {}), renderPartialIndicator = () => _jsx(DefaultPartialIndicator, {}), showBrackets = false, }, ref) => {
+export const SuperscriptCitation = forwardRef(({ citation, children, className, hideKeySpan = false, fallbackDisplay, verification, eventHandlers, isMobile = false, preventTooltips = false, pendingContent = TWO_DOTS_THINKING_CONTENT, renderVerifiedIndicator = () => _jsx(DefaultVerifiedIndicator, {}), renderPartialIndicator = () => _jsx(DefaultPartialIndicator, {}), hideBrackets = false, }, ref) => {
     const { citationKey, citationInstanceId, status } = useCitationData(citation, verification);
     const { isVerified, isMiss, isPartialMatch, isPending } = status;
     const displayText = useMemo(() => getCitationDisplayText(citation, {
-        displayKeySpan,
+        hideKeySpan,
         fallbackDisplay,
-    }), [citation, displayKeySpan, fallbackDisplay]);
+    }), [citation, hideKeySpan, fallbackDisplay]);
     const handleClick = useCallback((e) => {
         e.preventDefault();
         e.stopPropagation();
@@ -109,7 +109,7 @@ export const SuperscriptCitation = forwardRef(({ citation, children, className,
                 : isPending
                     ? "citation-superscript--pending"
                     : "";
-    return (_jsxs(_Fragment, { children: [children, _jsxs("sup", { ref: ref, "data-citation-id": citationKey, "data-citation-instance": citationInstanceId, "data-variant": "superscript", className: classNames("citation-superscript", statusClass, className), onMouseEnter: preventTooltips ? undefined : handleMouseEnter, onMouseLeave: preventTooltips ? undefined : handleMouseLeave, onMouseDown: handleClick, onClick: (e) => e.stopPropagation(), "aria-label": `Citation ${displayText}`, children: [showBrackets && "[", displayText, isPartialMatch && renderPartialIndicator(status), isVerified && !isPartialMatch && renderVerifiedIndicator(status), isPending && pendingContent, showBrackets && "]"] })] }));
+    return (_jsxs(_Fragment, { children: [children, _jsxs("sup", { ref: ref, "data-citation-id": citationKey, "data-citation-instance": citationInstanceId, "data-variant": "superscript", className: classNames("citation-superscript", statusClass, className), onMouseEnter: preventTooltips ? undefined : handleMouseEnter, onMouseLeave: preventTooltips ? undefined : handleMouseLeave, onMouseDown: handleClick, onClick: (e) => e.stopPropagation(), "aria-label": `Citation ${displayText}`, children: [!hideBrackets && "[", displayText, isPartialMatch && renderPartialIndicator(status), isVerified && !isPartialMatch && renderVerifiedIndicator(status), isPending && pendingContent, !hideBrackets && "]"] })] }));
 });
 SuperscriptCitation.displayName = "SuperscriptCitation";
 const FOOTNOTE_SYMBOLS = ["*", "†", "‡", "§", "‖", "¶"];
@@ -173,14 +173,14 @@ FootnoteCitation.displayName = "FootnoteCitation";
  * // Renders: "quoted text" with subtle underline
  * ```
  */
-export const InlineCitation = forwardRef(({ citation, children, className, displayKeySpan = true, // Default to merged for inline
+export const InlineCitation = forwardRef(({ citation, children, className, hideKeySpan = false, // Default to showing keySpan for inline
 fallbackDisplay, verification, eventHandlers, preventTooltips = false, pendingContent = TWO_DOTS_THINKING_CONTENT, renderVerifiedIndicator = () => _jsx(DefaultVerifiedIndicator, {}), renderPartialIndicator = () => _jsx(DefaultPartialIndicator, {}), underlineStyle = "dotted", }, ref) => {
     const { citationKey, citationInstanceId, status } = useCitationData(citation, verification);
     const { isVerified, isMiss, isPartialMatch, isPending } = status;
     const displayText = useMemo(() => getCitationDisplayText(citation, {
-        displayKeySpan,
+        hideKeySpan,
         fallbackDisplay,
-    }), [citation, displayKeySpan, fallbackDisplay]);
+    }), [citation, hideKeySpan, fallbackDisplay]);
     const handleClick = useCallback((e) => {
         e.preventDefault();
         e.stopPropagation();
@@ -216,13 +216,13 @@ InlineCitation.displayName = "InlineCitation";
  * // Renders: 1
  * ```
  */
-export const MinimalCitation = forwardRef(({ citation, children, className, displayKeySpan = false, fallbackDisplay, verification, eventHandlers, preventTooltips = false, pendingContent = TWO_DOTS_THINKING_CONTENT, renderVerifiedIndicator = () => _jsx(DefaultVerifiedIndicator, {}), renderPartialIndicator = () => _jsx(DefaultPartialIndicator, {}), showStatusIndicator = true, }, ref) => {
+export const MinimalCitation = forwardRef(({ citation, children, className, hideKeySpan = false, fallbackDisplay, verification, eventHandlers, preventTooltips = false, pendingContent = TWO_DOTS_THINKING_CONTENT, renderVerifiedIndicator = () => _jsx(DefaultVerifiedIndicator, {}), renderPartialIndicator = () => _jsx(DefaultPartialIndicator, {}), showStatusIndicator = true, }, ref) => {
     const { citationKey, citationInstanceId, status } = useCitationData(citation, verification);
     const { isVerified, isMiss, isPartialMatch, isPending } = status;
     const displayText = useMemo(() => getCitationDisplayText(citation, {
-        displayKeySpan,
+        hideKeySpan,
         fallbackDisplay,
-    }), [citation, displayKeySpan, fallbackDisplay]);
+    }), [citation, hideKeySpan, fallbackDisplay]);
     const handleClick = useCallback((e) => {
         e.preventDefault();
         e.stopPropagation();

package/lib/react/primitives.d.ts

@@ -14,7 +14,7 @@ interface CitationContextValue {
     verification: Verification | null;
     searchState: SearchState | null;
     config: {
-        displayKeySpan: boolean;
+        hideKeySpan: boolean;
         fallbackDisplay: string | null;
         pendingContent: ReactNode;
     };
@@ -28,7 +28,7 @@ export interface CitationRootProps {
     verification?: Verification | null;
     searchState?: SearchState | null;
     children: ReactNode;
-    displayKeySpan?: boolean;
+    hideKeySpan?: boolean;
     fallbackDisplay?: string | null;
     pendingContent?: ReactNode;
 }

package/lib/react/primitives.js

@@ -20,7 +20,7 @@ export function useCitationContextSafe() {
     return useContext(CitationContext);
 }
 /** Root component that provides citation context to all child primitives. */
-export const CitationRoot = forwardRef(({ citation, verification = null, searchState = null, children, displayKeySpan = false, fallbackDisplay = null, pendingContent = "..", className, ...props }, ref) => {
+export const CitationRoot = forwardRef(({ citation, verification = null, searchState = null, children, hideKeySpan = false, fallbackDisplay = null, pendingContent = "..", className, ...props }, ref) => {
     const citationKey = useMemo(() => generateCitationKey(citation), [citation]);
     const citationInstanceId = useMemo(() => generateCitationInstanceId(citationKey), [citationKey]);
     const status = getCitationStatus(verification);
@@ -32,7 +32,7 @@ export const CitationRoot = forwardRef(({ citation, verification = null, searchS
         verification,
         searchState,
         config: {
-            displayKeySpan,
+            hideKeySpan,
             fallbackDisplay,
             pendingContent,
         },
@@ -43,7 +43,7 @@ export const CitationRoot = forwardRef(({ citation, verification = null, searchS
         status,
         verification,
         searchState,
-        displayKeySpan,
+        hideKeySpan,
         fallbackDisplay,
         pendingContent,
     ]);
@@ -100,7 +100,7 @@ export const CitationNumber = forwardRef(({ className, number, ...props }, ref)
     const displayNumber = useMemo(() => {
         if (number !== undefined)
             return String(number);
-        if (config.displayKeySpan) {
+        if (!config.hideKeySpan) {
             return (citation.keySpan?.toString() ||
                 citation.citationNumber?.toString() ||
                 config.fallbackDisplay ||
@@ -120,7 +120,7 @@ export const CitationKeySpan = forwardRef(({ className, keySpan, separator = " "
     const displayKeySpan = useMemo(() => {
         if (keySpan !== undefined)
             return keySpan;
-        if (!config.displayKeySpan)
+        if (config.hideKeySpan)
             return "";
         return citation.keySpan?.toString() || "";
     }, [keySpan, citation, config]);

package/lib/react/types.d.ts

@@ -5,8 +5,8 @@ import type { SearchState } from "../types/search.js";
  * Available citation display variants.
  *
  * - `brackets`: Shows keySpan/number in brackets with blue text styling (default).
- *               Use displayKeySpan=false for numeric-only display.
- *               Use displayBrackets=false to hide the square brackets.
+ *               Use hideKeySpan=true for numeric-only display.
+ *               Use hideBrackets=true to hide the square brackets.
  * - `text`: Shows the keySpan, inherits parent text styling, no truncation, shows indicator
  * - `minimal`: No brackets, just display text with indicator
  * - `indicator`: Only the status indicator (checkmark/warning), no text
@@ -91,10 +91,10 @@ export interface BaseCitationProps {
     /** Class name for controlling inner content width */
     innerWidthClassName?: string;
     /**
-     * When true, displays keySpan text. When false, displays citation number only.
-     * @default true
+     * When true, hides keySpan and displays citation number only. When false, displays keySpan text.
+     * @default false
      */
-    displayKeySpan?: boolean;
+    hideKeySpan?: boolean;
     /** Fallback display text when citation keySpan is empty */
     fallbackDisplay?: string | null;
     /** Display variant for the citation */

package/lib/react/utils.d.ts

@@ -13,14 +13,14 @@ export declare function generateCitationInstanceId(citationKey: string): string;
  * Gets the display text for a citation based on configuration.
  */
 export declare function getCitationDisplayText(citation: Citation, options?: {
-    displayKeySpan?: boolean;
+    hideKeySpan?: boolean;
     fallbackDisplay?: string | null;
 }): string;
 /**
  * Gets the keySpan text to display before the citation bracket.
  */
 export declare function getCitationKeySpanText(citation: Citation, options?: {
-    displayKeySpan?: boolean;
+    hideKeySpan?: boolean;
 }): string;
 /**
  * Joins class names, filtering out falsy values.

package/lib/react/utils.js

@@ -29,8 +29,8 @@ export function generateCitationInstanceId(citationKey) {
  * Gets the display text for a citation based on configuration.
  */
 export function getCitationDisplayText(citation, options = {}) {
-    const { displayKeySpan = false, fallbackDisplay } = options;
-    if (displayKeySpan) {
+    const { hideKeySpan = false, fallbackDisplay } = options;
+    if (!hideKeySpan) {
         return (citation.keySpan?.toString() ||
             citation.citationNumber?.toString() ||
             fallbackDisplay ||
@@ -42,8 +42,8 @@ export function getCitationDisplayText(citation, options = {}) {
  * Gets the keySpan text to display before the citation bracket.
  */
 export function getCitationKeySpanText(citation, options = {}) {
-    const { displayKeySpan = false } = options;
-    if (displayKeySpan) {
+    const { hideKeySpan = false } = options;
+    if (!hideKeySpan) {
         return "";
     }
     return citation.keySpan?.toString() || "";

package/package.json

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