@deepcitation/deepcitation-js 1.1.27 → 1.1.28

package/lib/react/types.d.ts

@@ -1,315 +0,0 @@
-import type { Citation, CitationStatus } from "../types/citation.js";
-import type { Verification } from "../types/verification.js";
-import type { SearchStatus } from "../types/search.js";
-/**
- * Visual style variants for citations.
- *
- * | Variant       | Description                                    |
- * |---------------|------------------------------------------------|
- * | `chip`        | Pill/badge style with background color         |
- * | `brackets`    | [text✓] with square brackets (default)         |
- * | `text`        | Plain text, inherits parent styling            |
- * | `superscript` | Small raised text like footnotes¹              |
- * | `minimal`     | Compact text with indicator, truncated         |
- */
-export type CitationVariant = "chip" | "brackets" | "text" | "superscript" | "minimal";
-/**
- * Content to display in the citation.
- *
- * | Content       | Description                                    |
- * |---------------|------------------------------------------------|
- * | `keySpan`     | Descriptive text (e.g., "Revenue Growth")      |
- * | `number`      | Citation number (e.g., "1", "2", "3")          |
- * | `indicator`   | Only the status icon (✓/⚠), no text            |
- *
- * Default content per variant:
- * - `chip` → `keySpan`
- * - `brackets` → `number`
- * - `text` → `keySpan`
- * - `superscript` → `number`
- * - `minimal` → `number`
- */
-export type CitationContent = "keySpan" | "number" | "indicator";
-/**
- * URL fetch status for URL citations.
- */
-export type UrlFetchStatus = "verified" | "partial" | "pending" | "blocked_antibot" | "blocked_login" | "blocked_paywall" | "blocked_geo" | "blocked_rate_limit" | "error_timeout" | "error_not_found" | "error_server" | "error_network" | "unknown";
-/**
- * URL citation metadata.
- */
-export interface UrlCitationMeta {
-    /** The full URL */
-    url: string;
-    /** Display domain (e.g., "example.com") */
-    domain?: string;
-    /** Page title if fetched */
-    title?: string;
-    /** Fetch/verification status */
-    fetchStatus: UrlFetchStatus;
-    /** When the URL was last verified */
-    verifiedAt?: Date | string;
-    /** HTTP status code if available */
-    httpStatus?: number;
-    /** Error message if applicable */
-    errorMessage?: string;
-    /** Favicon URL if available */
-    faviconUrl?: string;
-}
-/**
- * Style configuration for the citation component.
- * All properties are optional class name strings.
- */
-export interface CitationStyles {
-    /** Container wrapper class */
-    container?: string;
-    /** Citation number bracket wrapper */
-    bracketWrapper?: string;
-    /** Inner bracket content */
-    bracketContent?: string;
-    /** Citation text/number itself */
-    citationText?: string;
-    /** Verified status indicator */
-    verifiedIcon?: string;
-    /** Partial match indicator */
-    partialIcon?: string;
-    /** Pending/loading state */
-    pendingText?: string;
-}
-/**
- * State classes applied based on citation verification status
- */
-export interface CitationStateClasses {
-    /** Applied when citation is verified (found in document) */
-    verified?: string;
-    /** Applied when citation is a miss (not found) */
-    miss?: string;
-    /** Applied when citation is a partial match */
-    partial?: string;
-    /** Applied when citation verification is pending */
-    pending?: string;
-}
-/**
- * Cursor classes for different zoom states
- */
-export interface CitationCursorClasses {
-    zoomIn?: string;
-    zoomOut?: string;
-    pointer?: string;
-}
-/**
- * Props for the base CitationComponent
- */
-export interface BaseCitationProps {
-    /** The citation data to display */
-    citation: Citation;
-    /** Child content to render before the citation bracket */
-    children?: React.ReactNode;
-    /** Additional class name for the container */
-    className?: string;
-    /** Class name for controlling inner content width */
-    innerWidthClassName?: string;
-    /**
-     * Visual style variant for the citation.
-     * @default "brackets"
-     */
-    variant?: CitationVariant;
-    /**
-     * What content to display in the citation.
-     * If not specified, defaults based on variant:
-     * - `chip` → `keySpan`
-     * - `brackets` → `number`
-     * - `text` → `keySpan`
-     * - `superscript` → `number`
-     * - `minimal` → `number`
-     */
-    content?: CitationContent;
-    /** Fallback display text when citation keySpan is empty */
-    fallbackDisplay?: string | null;
-}
-/**
- * Visual style variants for URL citations.
- */
-export type UrlCitationVariant = "chip" | "inline" | "bracket";
-/**
- * Props for URL citation component
- */
-export interface UrlCitationProps extends Omit<BaseCitationProps, "citation" | "variant"> {
-    /** Visual style variant for the URL citation */
-    variant?: UrlCitationVariant;
-    /** URL metadata including fetch status */
-    urlMeta: UrlCitationMeta;
-    /** The citation data (optional, will be derived from urlMeta if not provided) */
-    citation?: Citation;
-    /** Whether to show the full URL on hover */
-    showFullUrlOnHover?: boolean;
-    /** Whether to show favicon */
-    showFavicon?: boolean;
-    /** Whether to show the page title instead of domain */
-    showTitle?: boolean;
-    /** Maximum characters for truncated display */
-    maxDisplayLength?: number;
-    /** Custom render for the blocked status indicator */
-    renderBlockedIndicator?: (status: UrlFetchStatus, errorMessage?: string) => React.ReactNode;
-    /** Click handler for the URL */
-    onUrlClick?: (url: string, event: React.MouseEvent) => void;
-    /** Event handlers for citation interactions */
-    eventHandlers?: CitationEventHandlers;
-    /** Whether tooltips should be prevented */
-    preventTooltips?: boolean;
-}
-/**
- * Extended props for the citation content renderer
- */
-export interface CitationContentProps extends BaseCitationProps {
-    /** Unique key for this citation */
-    citationKey: string;
-    /** Unique instance ID for this citation render */
-    citationInstanceId: string;
-    /** Found citation highlight data */
-    verification: Verification | null | undefined;
-    /** Search status */
-    searchStatus: SearchStatus | undefined | null;
-    /** Actual page number where citation was found */
-    actualPageNumber?: number | null;
-    /** Page number from citation data */
-    citationPageNumber?: number | null;
-    /** Unique highlight ID */
-    highlightId?: string;
-    /** Citation verification status */
-    status: CitationStatus;
-    /** Whether tooltips should be suppressed */
-    preventTooltips?: boolean;
-    /** Whether on mobile device */
-    isMobile?: boolean;
-    /** Style configuration */
-    styles?: CitationStyles;
-    /** State-based classes */
-    stateClasses?: CitationStateClasses;
-    /** Cursor classes */
-    cursorClasses?: CitationCursorClasses;
-}
-/**
- * Render props for custom citation rendering
- */
-export interface CitationRenderProps {
-    /** The citation data */
-    citation: Citation;
-    /** Citation verification status */
-    status: CitationStatus;
-    /** The citation key */
-    citationKey: string;
-    /** Display text for the citation */
-    displayText: string;
-    /** Whether this is a merged keySpan display */
-    isMergedDisplay: boolean;
-}
-/**
- * Event handlers for citation interactions
- */
-export interface CitationEventHandlers {
-    /** Called when mouse enters citation */
-    onMouseEnter?: (citation: Citation, citationKey: string) => void;
-    /** Called when mouse leaves citation */
-    onMouseLeave?: (citation: Citation, citationKey: string) => void;
-    /** Called when citation is clicked */
-    onClick?: (citation: Citation, citationKey: string, event: React.MouseEvent | React.TouchEvent) => void;
-    /** 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
- */
-export interface CitationTooltipProps {
-    children: React.ReactNode;
-    citation: Citation;
-    verification?: Verification | null;
-    shouldShowTooltip: boolean;
-}

package/lib/react/types.js

@@ -1 +0,0 @@
-export {};

package/lib/react/useSmartDiff.d.ts

@@ -1,16 +0,0 @@
-export type DiffBlockType = "modified" | "added" | "removed" | "unchanged";
-export interface DiffPart {
-    value: string;
-    added?: boolean;
-    removed?: boolean;
-}
-export interface DiffBlock {
-    type: DiffBlockType;
-    parts: DiffPart[];
-}
-export declare const useSmartDiff: (expected?: string, actual?: string) => {
-    diffResult: DiffBlock[];
-    hasDiff: boolean;
-    similarity: number;
-    isHighVariance: boolean;
-};

package/lib/react/useSmartDiff.js

@@ -1,64 +0,0 @@
-import { diffLines, diffWordsWithSpace } from "../utils/diff.js";
-import { useMemo } from "react";
-export const useSmartDiff = (expected = "", actual = "") => {
-    return useMemo(() => {
-        // 1. Sanitize standard noise (CRLF, trailing spaces)
-        const cleanExpected = (expected || "").trim().replace(/\r\n/g, "\n");
-        const cleanActual = (actual || "").trim().replace(/\r\n/g, "\n");
-        // 2. First Pass: Diff by LINES.
-        // This isolates the "extra line" issue. The extra line becomes one "added" chunk,
-        // and it prevents the tokenizer from getting confused on the rest of the text.
-        const lineDiffs = diffLines(cleanExpected, cleanActual);
-        // 3. Second Pass: Process the line results to find "Modifications"
-        const processedDiffs = [];
-        let hasDiff = false;
-        let totalChange = 0;
-        for (let i = 0; i < lineDiffs.length; i++) {
-            const part = lineDiffs[i];
-            const nextPart = lineDiffs[i + 1];
-            // CHECK FOR MODIFICATION:
-            // If we see a "Removed" block immediately followed by an "Added" block,
-            // it means this specific line changed. We should DIFF WORDS inside this line.
-            if (part.removed && nextPart && nextPart.added) {
-                // Run word diff ONLY on this pair of lines
-                const wordDiffs = diffWordsWithSpace(part.value, nextPart.value);
-                processedDiffs.push({
-                    type: "modified",
-                    parts: wordDiffs,
-                });
-                hasDiff = true;
-                // Calculate raw change amount for variance score
-                totalChange += Math.abs(part.value.length - nextPart.value.length);
-                i++; // Skip the next part since we merged it into this block
-            }
-            // CHECK FOR PURE ADDITION/DELETION (The "Extra Line" Scenario)
-            else if (part.added || part.removed) {
-                processedDiffs.push({
-                    type: part.added ? "added" : "removed",
-                    parts: [{ value: part.value, added: part.added, removed: part.removed }],
-                });
-                hasDiff = true;
-                totalChange += part.value.length;
-            }
-            // UNCHANGED BLOCKS
-            else {
-                processedDiffs.push({
-                    type: "unchanged",
-                    parts: [{ value: part.value }],
-                });
-            }
-        }
-        // 4. Calculate a similarity score to decide UI defaults
-        // 1.0 = Perfect match, 0.0 = Totally different
-        const maxLength = Math.max(cleanExpected.length, cleanActual.length);
-        const similarity = maxLength === 0 ? 1 : 1 - totalChange / maxLength;
-        return {
-            diffResult: processedDiffs,
-            hasDiff,
-            similarity,
-            // If similarity is too low (< 60%), the Diff view is likely "Fruit Salad" (messy).
-            // We can use this boolean to default the UI to the "Source" tab.
-            isHighVariance: similarity < 0.6,
-        };
-    }, [expected, actual]);
-};

package/lib/react/utils.d.ts

@@ -1,44 +0,0 @@
-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
- * @returns A unique, deterministic key for the citation
- */
-export declare function generateCitationKey(citation: Citation): string;
-/**
- * Generates a unique, deterministic key for a verification based on its content.
- * @param verification - The verification to generate a key for
- * @returns
- */
-export declare function generateVerificationKey(verification: Verification): string;
-/**
- * Generates a unique instance ID for a citation component render.
- * Combines the citation key with a random suffix for uniqueness.
- */
-export declare function generateCitationInstanceId(citationKey: string): string;
-/**
- * Gets the display text for a citation (keySpan with fallback to number).
- */
-export declare function getCitationDisplayText(citation: Citation, options?: {
-    fallbackDisplay?: string | null;
-}): string;
-/**
- * Gets the citation number as a string.
- */
-export declare function getCitationNumber(citation: Citation): string;
-/**
- * Gets the keySpan text from a citation.
- */
-export declare function getCitationKeySpanText(citation: Citation): string;
-/**
- * Joins class names, filtering out falsy values.
- * This is a minimal implementation for the base component.
- */
-export declare function classNames(...classes: (string | undefined | null | false)[]): string;
-/**
- * Default padding values for citation styling.
- */
-export declare const CITATION_X_PADDING = 4;
-export declare const CITATION_Y_PADDING = 1;

package/lib/react/utils.js

@@ -1,88 +0,0 @@
-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
- * @returns A unique, deterministic key for the citation
- */
-export function generateCitationKey(citation) {
-    const pageNumber = citation.pageNumber || getCitationPageNumber(citation.startPageKey);
-    const keyParts = [
-        citation.attachmentId || "",
-        pageNumber?.toString() || "",
-        citation.fullPhrase || "",
-        citation.keySpan?.toString() || "",
-        citation.lineIds?.join(",") || "",
-        citation.timestamps?.startTime || "",
-        citation.timestamps?.endTime || "",
-    ];
-    return sha1Hash(keyParts.join("|")).slice(0, 16);
-}
-/**
- * Generates a unique, deterministic key for a verification based on its content.
- * @param verification - The verification to generate a key for
- * @returns
- */
-export function generateVerificationKey(verification) {
-    const keyParts = [
-        verification.attachmentId || "",
-        verification.label || "",
-        verification.verifiedFullPhrase || "",
-        verification.verifiedKeySpan || "",
-        verification.verifiedLineIds?.join(",") || "",
-        verification.verifiedPageNumber?.toString() || "",
-        verification.verifiedTimestamps?.startTime || "",
-        verification.verifiedTimestamps?.endTime || "",
-        verification.verifiedMatchSnippet || "",
-        verification.hitIndexWithinPage?.toString() || "",
-    ];
-    return sha1Hash(keyParts.join("|")).slice(0, 16);
-}
-/**
- * Generates a unique instance ID for a citation component render.
- * Combines the citation key with a random suffix for uniqueness.
- */
-export function generateCitationInstanceId(citationKey) {
-    const randomSuffix = Math.random().toString(36).slice(2, 11);
-    return `${citationKey}-${randomSuffix}`;
-}
-/**
- * Gets the display text for a citation (keySpan with fallback to number).
- */
-export function getCitationDisplayText(citation, options = {}) {
-    const { fallbackDisplay } = options;
-    return (citation.keySpan?.toString() ||
-        citation.citationNumber?.toString() ||
-        fallbackDisplay ||
-        "1");
-}
-/**
- * Gets the citation number as a string.
- */
-export function getCitationNumber(citation) {
-    return citation.citationNumber?.toString() || "1";
-}
-/**
- * Gets the keySpan text from a citation.
- */
-export function getCitationKeySpanText(citation) {
-    return citation.keySpan?.toString() || "";
-}
-/**
- * Joins class names, filtering out falsy values.
- * This is a minimal implementation for the base component.
- */
-export function classNames(...classes) {
-    return classes.filter(Boolean).join(" ");
-}
-/**
- * Default padding values for citation styling.
- */
-export const CITATION_X_PADDING = 4;
-export const CITATION_Y_PADDING = 1;

package/lib/types/boxes.d.ts

@@ -1,11 +0,0 @@
-export interface PdfSpaceItem extends ScreenBox {
-    text?: string;
-}
-export type IVertex = {
-    x: number;
-    y: number;
-};
-export interface ScreenBox extends IVertex {
-    width: number;
-    height: number;
-}

package/lib/types/boxes.js

@@ -1 +0,0 @@
-export {};

package/lib/types/citation.d.ts

@@ -1,39 +0,0 @@
-import { type ScreenBox } from "./boxes.js";
-import { type Verification } from "./verification.js";
-export type OutputImageFormat = "jpeg" | "png" | "avif" | undefined | null;
-export declare const DEFAULT_OUTPUT_IMAGE_FORMAT: "avif";
-export interface VerifyCitationResponse {
-    verifications: {
-        [key: string]: Verification;
-    };
-}
-export interface VerifyCitationRequest {
-    attachmentId: string;
-    citations: {
-        [key: string]: Citation;
-    };
-    outputImageFormat?: OutputImageFormat;
-    apiKey?: string;
-}
-export interface Citation {
-    attachmentId?: string;
-    fullPhrase?: string | null;
-    keySpan?: string | null;
-    startPageKey?: string | null;
-    lineIds?: number[] | null;
-    reasoning?: string | null;
-    selection?: ScreenBox | null;
-    citationNumber?: number;
-    pageNumber?: number | null;
-    timestamps?: {
-        endTime?: string;
-        startTime?: string;
-    };
-    beforeCite?: string;
-}
-export interface CitationStatus {
-    isVerified: boolean;
-    isMiss: boolean;
-    isPartialMatch: boolean;
-    isPending: boolean;
-}

package/lib/types/citation.js

@@ -1 +0,0 @@
-export const DEFAULT_OUTPUT_IMAGE_FORMAT = "avif";

package/lib/types/search.d.ts

@@ -1,19 +0,0 @@
-export type SearchStatus = "loading" | "pending" | "not_found" | "partial_text_found" | "found" | "found_key_span_only" | "found_phrase_missed_value" | "found_on_other_page" | "found_on_other_line" | "first_word_found" | "timestamp_wip";
-export type SearchMethod = "exact_line_match" | "line_with_buffer" | "current_page" | "keyspan_fallback" | "adjacent_pages" | "expanded_window" | "regex_search" | "bm25_search" | "fuzzy_regex" | "first_word_fallback";
-export interface SearchAttempt {
-    method: SearchMethod;
-    success: boolean;
-    searchPhrases: string[];
-    pageSearched?: number;
-    matchedPhrases?: string[];
-    matchedVariation?: string;
-    phraseVariations?: string[];
-    matchQuality?: string;
-    isPartialMatch?: boolean;
-    matchScore?: number;
-    matchSnippet?: string;
-    notes?: string;
-    startTime?: number;
-    endTime?: number;
-    durationMs?: number;
-}

package/lib/types/search.js

@@ -1 +0,0 @@
-export {};

package/lib/types/verification.d.ts

@@ -1,27 +0,0 @@
-import { type Citation } from "./citation.js";
-import { type SearchStatus, type SearchAttempt } from "./search.js";
-import { type PdfSpaceItem } from "./boxes.js";
-export declare const NOT_FOUND_VERIFICATION_INDEX = -1;
-export declare const PENDING_VERIFICATION_INDEX = -2;
-export declare const BLANK_VERIFICATION: Verification;
-export interface Verification {
-    attachmentId?: string | null;
-    label?: string | null;
-    citation?: Citation;
-    status?: SearchStatus | null;
-    searchAttempts?: SearchAttempt[];
-    highlightColor?: string | null;
-    verifiedPageNumber?: number | null;
-    verifiedLineIds?: number[] | null;
-    verifiedTimestamps?: {
-        startTime?: string;
-        endTime?: string;
-    } | null;
-    verifiedFullPhrase?: string | null;
-    verifiedKeySpan?: string | null;
-    verifiedMatchSnippet?: string | null;
-    hitIndexWithinPage?: number | null;
-    pdfSpaceItem?: PdfSpaceItem;
-    verificationImageBase64?: string | null;
-    verifiedAt?: Date;
-}

package/lib/types/verification.js

@@ -1,11 +0,0 @@
-export const NOT_FOUND_VERIFICATION_INDEX = -1;
-export const PENDING_VERIFICATION_INDEX = -2;
-export const BLANK_VERIFICATION = {
-    attachmentId: null,
-    verifiedPageNumber: NOT_FOUND_VERIFICATION_INDEX,
-    verifiedMatchSnippet: null,
-    citation: {
-        pageNumber: NOT_FOUND_VERIFICATION_INDEX,
-    },
-    status: "not_found",
-};