@deepcitation/deepcitation-js 1.1.28 → 1.1.30

package/lib/react/index.d.cts

@@ -0,0 +1,466 @@
+import { Citation, Verification, SearchStatus, CitationStatus } from '../types/index.cjs';
+export { C as CITATION_X_PADDING, c as CITATION_Y_PADDING, h as classNames, b as generateCitationInstanceId, g as generateCitationKey, d as getCitationDisplayText, f as getCitationKeySpanText, e as getCitationNumber } from '../utils-CSqRI6NU.cjs';
+import React$1 from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * 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         |
+ */
+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`
+ */
+type CitationContent = "keySpan" | "number" | "indicator";
+/**
+ * URL fetch status for URL citations.
+ */
+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.
+ */
+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.
+ */
+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
+ */
+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
+ */
+interface CitationCursorClasses {
+    zoomIn?: string;
+    zoomOut?: string;
+    pointer?: string;
+}
+/**
+ * Props for the base CitationComponent
+ */
+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.
+ */
+type UrlCitationVariant = "chip" | "inline" | "bracket";
+/**
+ * Props for URL citation component
+ */
+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
+ */
+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
+ */
+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
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+type CitationClickBehavior = (context: CitationBehaviorContext, event: React.MouseEvent | React.TouchEvent) => CitationBehaviorActions | false | void;
+/**
+ * Configuration for hover behavior.
+ */
+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 }}
+ * />
+ * ```
+ */
+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
+ */
+interface CitationTooltipProps {
+    children: React.ReactNode;
+    citation: Citation;
+    verification?: Verification | null;
+    shouldShowTooltip: boolean;
+}
+
+/**
+ * Extracts domain from URL for compact display.
+ */
+declare function extractDomain(url: string): string;
+/**
+ * Checks if status is a blocked status.
+ */
+declare function isBlockedStatus(status: UrlFetchStatus): boolean;
+/**
+ * Checks if status is an error status.
+ */
+declare function isErrorStatus(status: UrlFetchStatus): boolean;
+/**
+ * Checks if URL was successfully verified.
+ */
+declare function isVerifiedStatus(status: UrlFetchStatus): boolean;
+
+/**
+ * Props for the CitationComponent.
+ *
+ * ## Behavior
+ *
+ * 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
+ *
+ * Custom behavior:
+ * - Use `behaviorConfig.onClick` to replace the default click behavior
+ * - Use `eventHandlers.onClick` to add side effects (disables default)
+ *
+ * @example Default usage
+ * ```tsx
+ * <CitationComponent
+ *   citation={citation}
+ *   verification={verification}
+ * />
+ * ```
+ *
+ * @example Custom click behavior
+ * ```tsx
+ * <CitationComponent
+ *   citation={citation}
+ *   verification={verification}
+ *   behaviorConfig={{
+ *     onClick: (context) => {
+ *       // Custom action
+ *       console.log('Clicked:', context.citationKey);
+ *       return { setImageExpanded: true };
+ *     }
+ *   }}
+ * />
+ * ```
+ */
+interface CitationComponentProps extends BaseCitationProps {
+    /** Verification result from the DeepCitation API */
+    verification?: Verification | null;
+    /**
+     * Explicitly show loading spinner. When true, displays spinner regardless
+     * of verification status. Use this when verification is in-flight.
+     */
+    isLoading?: boolean;
+    /**
+     * Visual style variant for the citation.
+     * - `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
+     */
+    variant?: CitationVariant;
+    /**
+     * What content to display in the citation.
+     * - `keySpan`: Descriptive text (e.g., "Revenue Growth")
+     * - `number`: Citation number (e.g., "1", "2", "3")
+     * - `indicator`: Only the status icon, no text
+     *
+     * Defaults based on variant:
+     * - `chip` → `keySpan`
+     * - `brackets` → `keySpan`
+     * - `text` → `keySpan`
+     * - `superscript` → `number`
+     * - `minimal` → `number`
+     */
+    content?: CitationContent;
+    /** Event handlers for citation interactions */
+    eventHandlers?: CitationEventHandlers;
+    /**
+     * Configuration for customizing default click/hover behaviors.
+     * Providing onClick REPLACES the default click behavior.
+     */
+    behaviorConfig?: CitationBehaviorConfig;
+    /** Enable mobile touch handlers */
+    isMobile?: boolean;
+    /** Custom render function for the status indicator */
+    renderIndicator?: (status: CitationStatus) => React$1.ReactNode;
+    /** Custom render function for entire citation content */
+    renderContent?: (props: CitationRenderProps) => React$1.ReactNode;
+    /** Position of popover. Use "hidden" to disable. */
+    popoverPosition?: "top" | "bottom" | "hidden";
+    /** Custom render function for popover content */
+    renderPopoverContent?: (props: {
+        citation: BaseCitationProps["citation"];
+        verification: Verification | null;
+        status: CitationStatus;
+    }) => React$1.ReactNode;
+}
+/**
+ * CitationComponent displays a citation with verification status.
+ *
+ * ## 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
+ *
+ * ## Customization
+ *
+ * Use `behaviorConfig.onClick` to completely replace the click behavior,
+ * or `eventHandlers.onClick` to add side effects (which disables defaults).
+ */
+declare const CitationComponent: React$1.ForwardRefExoticComponent<CitationComponentProps & React$1.RefAttributes<HTMLSpanElement>>;
+declare const MemoizedCitationComponent: React$1.NamedExoticComponent<CitationComponentProps & React$1.RefAttributes<HTMLSpanElement>>;
+
+/**
+ * DeepCitation icon SVG (no dependencies)
+ */
+declare const DeepCitationIcon: ({ className }: {
+    className?: string;
+}) => react_jsx_runtime.JSX.Element;
+/**
+ * Check icon SVG (no dependencies)
+ */
+declare const CheckIcon: ({ className }: {
+    className?: string;
+}) => react_jsx_runtime.JSX.Element;
+/**
+ * Warning icon SVG (no dependencies)
+ */
+declare const WarningIcon: ({ className }: {
+    className?: string;
+}) => react_jsx_runtime.JSX.Element;
+/** Spinner component for loading/pending state */
+declare const SpinnerIcon: ({ className }: {
+    className?: string;
+}) => react_jsx_runtime.JSX.Element;
+
+export { CheckIcon, type CitationBehaviorActions, type CitationBehaviorConfig, type CitationBehaviorContext, type CitationClickBehavior, CitationComponent, type CitationComponentProps, type CitationContent, type CitationContentProps, type CitationCursorClasses, type CitationEventHandlers, type CitationHoverBehavior, type CitationRenderProps, type CitationStateClasses, type CitationStyles, type CitationTooltipProps, type CitationVariant, type CitationVariant as CitationVariantType, DeepCitationIcon, MemoizedCitationComponent, SpinnerIcon, type UrlCitationMeta, type UrlCitationProps, type UrlCitationVariant, type UrlFetchStatus, WarningIcon, extractDomain, isBlockedStatus, isErrorStatus, isVerifiedStatus };