@deepcitation/deepcitation-js 1.1.27 → 1.1.29

package/lib/react/{types.d.ts → index.d.cts}

@@ -1,6 +1,8 @@
-import type { Citation, CitationStatus } from "../types/citation.js";
-import type { Verification } from "../types/verification.js";
-import type { SearchStatus } from "../types/search.js";
+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.
  *
@@ -12,7 +14,7 @@ import type { SearchStatus } from "../types/search.js";
  * | `superscript` | Small raised text like footnotes¹              |
  * | `minimal`     | Compact text with indicator, truncated         |
  */
-export type CitationVariant = "chip" | "brackets" | "text" | "superscript" | "minimal";
+type CitationVariant = "chip" | "brackets" | "text" | "superscript" | "minimal";
 /**
  * Content to display in the citation.
  *
@@ -29,15 +31,15 @@ export type CitationVariant = "chip" | "brackets" | "text" | "superscript" | "mi
  * - `superscript` → `number`
  * - `minimal` → `number`
  */
-export type CitationContent = "keySpan" | "number" | "indicator";
+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";
+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 {
+interface UrlCitationMeta {
     /** The full URL */
     url: string;
     /** Display domain (e.g., "example.com") */
@@ -59,7 +61,7 @@ export interface UrlCitationMeta {
  * Style configuration for the citation component.
  * All properties are optional class name strings.
  */
-export interface CitationStyles {
+interface CitationStyles {
     /** Container wrapper class */
     container?: string;
     /** Citation number bracket wrapper */
@@ -78,7 +80,7 @@ export interface CitationStyles {
 /**
  * State classes applied based on citation verification status
  */
-export interface CitationStateClasses {
+interface CitationStateClasses {
     /** Applied when citation is verified (found in document) */
     verified?: string;
     /** Applied when citation is a miss (not found) */
@@ -91,7 +93,7 @@ export interface CitationStateClasses {
 /**
  * Cursor classes for different zoom states
  */
-export interface CitationCursorClasses {
+interface CitationCursorClasses {
     zoomIn?: string;
     zoomOut?: string;
     pointer?: string;
@@ -99,7 +101,7 @@ export interface CitationCursorClasses {
 /**
  * Props for the base CitationComponent
  */
-export interface BaseCitationProps {
+interface BaseCitationProps {
     /** The citation data to display */
     citation: Citation;
     /** Child content to render before the citation bracket */
@@ -129,11 +131,11 @@ export interface BaseCitationProps {
 /**
  * Visual style variants for URL citations.
  */
-export type UrlCitationVariant = "chip" | "inline" | "bracket";
+type UrlCitationVariant = "chip" | "inline" | "bracket";
 /**
  * Props for URL citation component
  */
-export interface UrlCitationProps extends Omit<BaseCitationProps, "citation" | "variant"> {
+interface UrlCitationProps extends Omit<BaseCitationProps, "citation" | "variant"> {
     /** Visual style variant for the URL citation */
     variant?: UrlCitationVariant;
     /** URL metadata including fetch status */
@@ -160,7 +162,7 @@ export interface UrlCitationProps extends Omit<BaseCitationProps, "citation" | "
 /**
  * Extended props for the citation content renderer
  */
-export interface CitationContentProps extends BaseCitationProps {
+interface CitationContentProps extends BaseCitationProps {
     /** Unique key for this citation */
     citationKey: string;
     /** Unique instance ID for this citation render */
@@ -191,7 +193,7 @@ export interface CitationContentProps extends BaseCitationProps {
 /**
  * Render props for custom citation rendering
  */
-export interface CitationRenderProps {
+interface CitationRenderProps {
     /** The citation data */
     citation: Citation;
     /** Citation verification status */
@@ -206,7 +208,7 @@ export interface CitationRenderProps {
 /**
  * Event handlers for citation interactions
  */
-export interface CitationEventHandlers {
+interface CitationEventHandlers {
     /** Called when mouse enters citation */
     onMouseEnter?: (citation: Citation, citationKey: string) => void;
     /** Called when mouse leaves citation */
@@ -219,7 +221,7 @@ export interface CitationEventHandlers {
 /**
  * Context provided to behavior handlers for making decisions.
  */
-export interface CitationBehaviorContext {
+interface CitationBehaviorContext {
     /** The citation data */
     citation: Citation;
     /** Unique key for this citation */
@@ -237,7 +239,7 @@ export interface CitationBehaviorContext {
  * Actions that can be performed by the citation component.
  * These are returned by behavior handlers to control component state.
  */
-export interface CitationBehaviorActions {
+interface CitationBehaviorActions {
     /** Pin or unpin the popover (keeps it visible without hover) */
     setTooltipExpanded?: boolean;
     /** Open or close the full-size image overlay */
@@ -249,11 +251,11 @@ export interface CitationBehaviorActions {
  * 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;
+type CitationClickBehavior = (context: CitationBehaviorContext, event: React.MouseEvent | React.TouchEvent) => CitationBehaviorActions | false | void;
 /**
  * Configuration for hover behavior.
  */
-export interface CitationHoverBehavior {
+interface CitationHoverBehavior {
     /** Called when mouse enters the citation */
     onEnter?: (context: CitationBehaviorContext) => void;
     /** Called when mouse leaves the citation */
@@ -289,7 +291,7 @@ export interface CitationHoverBehavior {
  * />
  * ```
  */
-export interface CitationBehaviorConfig {
+interface CitationBehaviorConfig {
     /**
      * Custom click behavior handler. When provided, REPLACES the default click behavior.
      *
@@ -307,9 +309,158 @@ export interface CitationBehaviorConfig {
 /**
  * Props for the tooltip wrapper component
  */
-export interface CitationTooltipProps {
+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 };