@deepcitation/deepcitation-js 1.1.22 → 1.1.24

package/README.md

@@ -187,8 +187,8 @@ import {
 import type {
   Citation,
   Verification,
-  SearchState,
   SearchStatus,
+  SearchAttempt,
 } from "@deepcitation/deepcitation-js";
 ```
 

package/lib/index.d.ts

@@ -10,12 +10,11 @@ export { isGeminiGarbage, cleanRepeatingLastSentence, } from "./parsing/parseWor
 export type { Citation, CitationStatus, VerifyCitationRequest, VerifyCitationResponse, OutputImageFormat, } from "./types/citation.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, deterministicIdFromVerification, } from "./types/verification.js";
-export type { SearchState, SearchStatus, SearchMethod, SearchAttempt, } from "./types/search.js";
+export { NOT_FOUND_VERIFICATION_INDEX, PENDING_VERIFICATION_INDEX, BLANK_VERIFICATION, } from "./types/verification.js";
+export type { SearchStatus, SearchMethod, SearchAttempt, } from "./types/search.js";
 export type { ScreenBox, PdfSpaceItem, IVertex } from "./types/boxes.js";
 export { sha1Hash } from "./utils/sha.js";
-export { generateCitationKey } from "./react/utils.js";
-export { generateCitationInstanceId } from "./react/utils.js";
+export { generateCitationKey, generateVerificationKey, generateCitationInstanceId, } from "./react/utils.js";
 export { CITATION_X_PADDING, CITATION_Y_PADDING } from "./react/utils.js";
 export { CITATION_JSON_OUTPUT_FORMAT, CITATION_MARKDOWN_SYNTAX_PROMPT, AV_CITATION_MARKDOWN_SYNTAX_PROMPT, CITATION_AV_BASED_JSON_OUTPUT_FORMAT, wrapSystemCitationPrompt, wrapCitationPrompt, } from "./prompts/citationPrompts.js";
 export type { WrapSystemPromptOptions, WrapCitationPromptOptions, WrapCitationPromptResult, } from "./prompts/citationPrompts.js";

package/lib/index.js

@@ -9,11 +9,10 @@ export { parseCitation, getCitationStatus, getAllCitationsFromLlmOutput, groupCi
 export { normalizeCitations, getCitationPageNumber, } from "./parsing/normalizeCitation.js";
 export { isGeminiGarbage, cleanRepeatingLastSentence, } from "./parsing/parseWorkAround.js";
 export { DEFAULT_OUTPUT_IMAGE_FORMAT } from "./types/citation.js";
-export { NOT_FOUND_VERIFICATION_INDEX, PENDING_VERIFICATION_INDEX, BLANK_VERIFICATION, deterministicIdFromVerification, } from "./types/verification.js";
+export { NOT_FOUND_VERIFICATION_INDEX, PENDING_VERIFICATION_INDEX, BLANK_VERIFICATION, } from "./types/verification.js";
 // Utilities
 export { sha1Hash } from "./utils/sha.js";
-export { generateCitationKey } from "./react/utils.js";
-export { generateCitationInstanceId } from "./react/utils.js";
+export { generateCitationKey, generateVerificationKey, generateCitationInstanceId, } from "./react/utils.js";
 export { CITATION_X_PADDING, CITATION_Y_PADDING } from "./react/utils.js";
 // Prompts
 export { CITATION_JSON_OUTPUT_FORMAT, CITATION_MARKDOWN_SYNTAX_PROMPT, AV_CITATION_MARKDOWN_SYNTAX_PROMPT, CITATION_AV_BASED_JSON_OUTPUT_FORMAT, wrapSystemCitationPrompt, wrapCitationPrompt, } from "./prompts/citationPrompts.js";

package/lib/parsing/parseCitation.js

@@ -52,21 +52,19 @@ function parseLineIds(lineIdsString) {
  * @returns An object containing boolean flags for verification status
  */
 export function getCitationStatus(verification) {
-    const searchState = verification?.searchState;
-    const isMiss = searchState?.status === "not_found";
-    const isFullMatchWithMissedValue = searchState?.status === "found_phrase_missed_value";
-    const isFoundValueMissedFullMatch = searchState?.status === "found_key_span_only";
-    const isPartialMatch = searchState?.status === "partial_text_found" ||
-        searchState?.status === "found_on_other_page" ||
-        searchState?.status === "found_on_other_line" ||
-        searchState?.status === "first_word_found";
-    const isVerified = searchState?.status === "found" ||
+    const status = verification?.status;
+    const isMiss = status === "not_found";
+    const isFullMatchWithMissedValue = status === "found_phrase_missed_value";
+    const isFoundValueMissedFullMatch = status === "found_key_span_only";
+    const isPartialMatch = status === "partial_text_found" ||
+        status === "found_on_other_page" ||
+        status === "found_on_other_line" ||
+        status === "first_word_found";
+    const isVerified = status === "found" ||
         isFoundValueMissedFullMatch ||
         isPartialMatch ||
         isFullMatchWithMissedValue;
-    const isPending = searchState?.status === "pending" ||
-        searchState?.status === "loading" ||
-        !searchState;
+    const isPending = status === "pending" || status === "loading" || !status;
     return { isVerified, isMiss, isPartialMatch, isPending };
 }
 export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVerbose) => {

package/lib/react/CitationComponent.d.ts

@@ -1,187 +1,93 @@
-import React, { type ReactNode } from "react";
+import React from "react";
 import { type CitationStatus } from "../types/citation.js";
 import type { Verification } from "../types/verification.js";
 import type { BaseCitationProps, CitationBehaviorConfig, CitationEventHandlers, CitationRenderProps, CitationVariant } from "./types.js";
-import "./styles.css";
 export type { CitationVariant } from "./types.js";
 /**
  * Props for the CitationComponent.
  *
- * @example Brackets variant (default) - shows keySpan in brackets with blue styling
- * ```tsx
- * <CitationComponent
- *   citation={{ citationNumber: 1, keySpan: "Revenue grew by 25%" }}
- *   verification={verificationResult}
- * />
- * // Renders: [Revenue grew by 25%✓] with blue text
- * ```
- *
- * @example Numeric only - use hideKeySpan=true with brackets variant
- * ```tsx
- * <CitationComponent
- *   citation={{ citationNumber: 1, keySpan: "25% growth" }}
- *   verification={verificationResult}
- *   hideKeySpan={true}
- * />
- * // Renders: [1✓]
- * ```
- *
- * @example Without brackets - use hideBrackets=true
- * ```tsx
- * <CitationComponent
- *   citation={{ citationNumber: 1, keySpan: "25% growth" }}
- *   verification={verificationResult}
- *   hideBrackets={true}
- * />
- * // Renders: 25% growth✓ (no brackets)
- * ```
+ * ## Behavior
  *
- * @example Text variant - inherits parent text styling, no truncation
- * ```tsx
- * <CitationComponent
- *   citation={{ citationNumber: 1, keySpan: "25% growth" }}
- *   verification={verificationResult}
- *   variant="text"
- * />
- * // Renders: 25% growth✓ (inherits parent styling)
- * ```
+ * Default interaction pattern:
+ * - **Hover**: Shows popover with verification image/details
+ * - **Click**: Opens full-size image overlay (zoom)
+ * - **Escape / Click outside / Click overlay**: Closes image overlay
  *
- * @example Minimal variant - no brackets, just text and indicator
- * ```tsx
- * <CitationComponent
- *   citation={citation}
- *   verification={verificationResult}
- *   variant="minimal"
- * />
- * // Renders: Revenue grew...✓
- * ```
- *
- * @example Indicator-only variant
- * ```tsx
- * <CitationComponent
- *   citation={citation}
- *   verification={verificationResult}
- *   variant="indicator"
- * />
- * // Renders: ✓
- * ```
+ * Custom behavior:
+ * - Use `behaviorConfig.onClick` to replace the default click behavior
+ * - Use `eventHandlers.onClick` to add side effects (disables default)
  *
- * @example Hidden popover
+ * @example Default usage
  * ```tsx
  * <CitationComponent
  *   citation={citation}
- *   verification={verificationResult}
- *   popoverPosition="hidden"
+ *   verification={verification}
  * />
  * ```
  *
- * @example Custom click behavior (replaces default)
+ * @example Custom click behavior
  * ```tsx
  * <CitationComponent
  *   citation={citation}
- *   verification={verificationResult}
+ *   verification={verification}
  *   behaviorConfig={{
- *     onClick: (context, event) => {
- *       if (context.hasImage) {
- *         return { setImageExpanded: true };
- *       }
+ *     onClick: (context) => {
+ *       // Custom action
+ *       console.log('Clicked:', context.citationKey);
+ *       return { setImageExpanded: true };
  *     }
  *   }}
  * />
  * ```
- *
- * @example Disable all click behavior
- * ```tsx
- * <CitationComponent
- *   citation={citation}
- *   verification={verificationResult}
- *   behaviorConfig={{ onClick: () => false }}
- * />
- * ```
  */
 export interface CitationComponentProps extends BaseCitationProps {
-    /**
-     * Verification result from the DeepCitation API.
-     * Contains match snippet, page number, and verification image.
-     */
+    /** Verification result from the DeepCitation API */
     verification?: Verification | null;
     /**
      * Display variant for the citation.
-     * - `brackets`: Shows keySpan/number in brackets, blue text styling (default)
-     * - `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
+     * - `brackets`: [keySpan✓] with styling (default)
+     * - `text`: keySpan✓ inherits parent styling
+     * - `minimal`: text with indicator, no brackets
+     * - `indicator`: only the status indicator
      */
     variant?: CitationVariant;
-    /**
-     * Whether to hide square brackets around the citation.
-     * Only applies to the `brackets` variant.
-     * @default false
-     */
+    /** Hide square brackets (only for brackets variant) */
     hideBrackets?: boolean;
-    /**
-     * Event handlers for citation interactions.
-     * These are always called regardless of behaviorConfig settings.
-     */
+    /** Event handlers for citation interactions */
     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
+     * Providing onClick REPLACES the default click behavior.
      */
     behaviorConfig?: CitationBehaviorConfig;
-    /**
-     * Enable mobile touch handlers.
-     * @default false
-     */
+    /** Enable mobile touch handlers */
     isMobile?: boolean;
-    /**
-     * Custom render function for the status indicator.
-     * Receives the citation status and should return a ReactNode.
-     */
-    renderIndicator?: (status: CitationStatus) => ReactNode;
-    /**
-     * Custom render function for the entire citation content.
-     * When provided, takes full control of rendering.
-     */
-    renderContent?: (props: CitationRenderProps) => ReactNode;
-    /**
-     * Position of the verification popover.
-     * Use "hidden" to disable the popover entirely.
-     * @default "top"
-     */
+    /** Custom render function for the status indicator */
+    renderIndicator?: (status: CitationStatus) => React.ReactNode;
+    /** Custom render function for entire citation content */
+    renderContent?: (props: CitationRenderProps) => React.ReactNode;
+    /** Position of popover. Use "hidden" to disable. */
     popoverPosition?: "top" | "bottom" | "hidden";
-    /**
-     * Custom render function for popover content.
-     */
+    /** Custom render function for popover content */
     renderPopoverContent?: (props: {
         citation: BaseCitationProps["citation"];
         verification: Verification | null;
         status: CitationStatus;
-    }) => ReactNode;
+    }) => React.ReactNode;
 }
 /**
  * CitationComponent displays a citation with verification status.
  *
- * The component separates two concepts:
- * 1. **Found status** (text styling) - whether the citation was found in the document
- *    - Verified & Partial both use "found" styling (blue text)
- *    - Miss uses "not found" styling (gray/strikethrough)
+ * ## Interaction Pattern
+ *
+ * - **Hover**: Shows popover with verification image or details
+ * - **Click**: Opens full-size image overlay (if image available)
+ * - **Escape / Click overlay**: Closes the image overlay
  *
- * 2. **Match quality** (indicator styling) - how well the citation matched
- *    - Exact match: green checkmark
- *    - Partial match: orange checkmark
- *    - Miss: no indicator
+ * ## Customization
  *
- * This means partial matches have blue text (because they were found) but
- * an orange indicator (because they didn't match exactly).
+ * Use `behaviorConfig.onClick` to completely replace the click behavior,
+ * or `eventHandlers.onClick` to add side effects (which disables defaults).
  */
 export declare const CitationComponent: React.ForwardRefExoticComponent<CitationComponentProps & React.RefAttributes<HTMLSpanElement>>;
 export declare const MemoizedCitationComponent: React.NamedExoticComponent<CitationComponentProps & React.RefAttributes<HTMLSpanElement>>;