@deepcitation/deepcitation-js 1.0.2 → 1.0.3

package/lib/react/VerificationTabs.js

@@ -0,0 +1,36 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { useSmartDiff } from "./useSmartDiff.js";
+import { classNames } from "./utils.js";
+import { CheckIcon } from "./icons.js";
+// Sub-component: The individual tab button
+const TabButton = ({ isActive, onClick, label }) => (_jsx("button", { onClick: e => {
+        e.stopPropagation(); // Prevent tooltip from closing or dragging
+        onClick();
+    }, className: classNames("dc-tab-button", isActive ? "dc-tab-button--active" : ""), type: "button", children: label }));
+export const VerificationTabs = ({ expected, actual, label, renderCopyButton, emptyText = "No text found", }) => {
+    const { diffResult, isHighVariance, hasDiff } = useSmartDiff(expected, actual);
+    const [activeTab, setActiveTab] = useState("diff");
+    useEffect(() => {
+        if (isHighVariance) {
+            setActiveTab("found");
+        }
+        else {
+            setActiveTab("diff");
+        }
+    }, [isHighVariance, expected, actual]);
+    const renderFoundContent = () => (_jsx("div", { className: "dc-tab-content dc-tab-content--found", children: actual ? (_jsxs("div", { className: "dc-tab-text-wrapper", children: [renderCopyButton && _jsx("div", { className: "dc-copy-button-wrapper", children: renderCopyButton(actual, "found") }), _jsx("div", { className: "dc-tab-text", children: actual })] })) : (_jsx("span", { className: "dc-tab-empty", children: emptyText })) }));
+    const isExactMatch = !hasDiff && Boolean(actual) && Boolean(expected);
+    if (isExactMatch) {
+        return (_jsxs("div", { className: "dc-verification-tabs dc-verification-tabs--exact", children: [label && _jsx("div", { className: "dc-verification-label", children: label }), _jsxs("div", { className: "dc-exact-match-badge", children: [_jsx(CheckIcon, {}), _jsx("span", { children: "Exact match" })] }), _jsx("div", { className: "dc-exact-match-content", children: renderFoundContent() })] }));
+    }
+    return (_jsxs("div", { className: "dc-verification-tabs", children: [label && _jsx("div", { className: "dc-verification-label", children: label }), _jsx("div", { className: "dc-tabs-container", children: _jsxs("div", { className: "dc-tabs-nav", children: [_jsx(TabButton, { label: "Expected", isActive: activeTab === "expected", onClick: () => setActiveTab("expected") }), _jsx(TabButton, { label: "Diff", isActive: activeTab === "diff", onClick: () => setActiveTab("diff") }), _jsx(TabButton, { label: "Found", isActive: activeTab === "found", onClick: () => setActiveTab("found") })] }) }), _jsxs("div", { className: "dc-tabs-content", children: [activeTab === "found" && renderFoundContent(), activeTab === "expected" && (_jsx("div", { className: "dc-tab-content dc-tab-content--expected", children: _jsxs("div", { className: "dc-tab-text-wrapper", children: [renderCopyButton && (_jsx("div", { className: "dc-copy-button-wrapper", children: renderCopyButton(expected, "expected") })), _jsx("div", { className: "dc-tab-text", children: expected })] }) })), activeTab === "diff" && (_jsx("div", { className: "dc-tab-content dc-tab-content--diff", children: !hasDiff ? (_jsxs("div", { className: "dc-exact-match-indicator", children: [_jsx(CheckIcon, {}), _jsx("span", { children: "Exact Match" })] })) : (_jsx("div", { className: "dc-diff-result", children: diffResult.map((block, i) => (_jsx("div", { className: classNames("dc-diff-block", block.type === "added" ? "dc-diff-block--added" : "", block.type === "removed" ? "dc-diff-block--removed" : ""), children: block.parts.map((part, j) => {
+                                    if (part.removed) {
+                                        return (_jsx("span", { className: "dc-diff-part dc-diff-part--removed", title: "Expected but not found", children: part.value }, j));
+                                    }
+                                    if (part.added) {
+                                        return (_jsx("span", { className: "dc-diff-part dc-diff-part--added", title: "Actually found in source", children: part.value }, j));
+                                    }
+                                    return (_jsx("span", { className: "dc-diff-part dc-diff-part--unchanged", children: part.value }, j));
+                                }) }, i))) })) }))] })] }));
+};

package/lib/react/icons.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Check icon SVG (no dependencies)
+ */
+export declare const CheckIcon: () => import("react/jsx-runtime").JSX.Element;
+/**
+ * Warning icon SVG (no dependencies)
+ */
+export declare const WarningIcon: () => import("react/jsx-runtime").JSX.Element;

package/lib/react/icons.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Check icon SVG (no dependencies)
+ */
+export const CheckIcon = () => (_jsx("svg", { className: "dc-check-icon", viewBox: "0 0 256 256", fill: "currentColor", "aria-hidden": "true", children: _jsx("path", { d: "M229.66,66.34 L96,200 L34.34,138.34 L51,121.66 L96,166.69 L213,50 Z", stroke: "currentColor", strokeWidth: "12" }) }));
+/**
+ * Warning icon SVG (no dependencies)
+ */
+export const WarningIcon = () => (_jsx("svg", { className: "dc-status-icon", viewBox: "0 0 256 256", fill: "currentColor", "aria-hidden": "true", children: _jsx("path", { d: "M236.8,188.09,149.35,36.22h0a24.76,24.76,0,0,0-42.7,0L19.2,188.09a23.51,23.51,0,0,0,0,23.72A24.35,24.35,0,0,0,40.55,224h174.9a24.35,24.35,0,0,0,21.33-12.19A23.51,23.51,0,0,0,236.8,188.09ZM120,104a8,8,0,0,1,16,0v40a8,8,0,0,1-16,0Zm8,88a12,12,0,1,1,12-12A12,12,0,0,1,128,192Z" }) }));

package/lib/react/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * DeepCitation React Utilities
+ *
+ * Note: UI components have been moved to a shadcn-style copy-paste pattern.
+ * See the documentation at https://deepcitation.com/docs/components for
+ * ready-to-use React components.
+ *
+ * This module exports utilities and types that are useful for building
+ * your own citation components.
+ *
+ * @packageDocumentation
+ */
+export type { CitationContentProps, CitationRenderProps, CitationTooltipProps, CitationStyles, CitationStateClasses, CitationCursorClasses, CitationEventHandlers, CitationVariant as CitationVariantType, UrlFetchStatus, UrlCitationMeta, UrlCitationProps, } from "./types.js";
+export { extractDomain, isBlockedStatus, isErrorStatus, isVerifiedStatus } from "./UrlCitationComponent.js";
+export { generateCitationKey, generateCitationInstanceId, getCitationDisplayText, getCitationValueText, classNames, CITATION_X_PADDING, CITATION_Y_PADDING, } from "./utils.js";
+export { CitationComponent, MemoizedCitationComponent, type CitationVariant, type CitationComponentProps, } from "./CitationComponent.js";

package/lib/react/index.js

@@ -0,0 +1,18 @@
+/**
+ * DeepCitation React Utilities
+ *
+ * Note: UI components have been moved to a shadcn-style copy-paste pattern.
+ * See the documentation at https://deepcitation.com/docs/components for
+ * ready-to-use React components.
+ *
+ * This module exports utilities and types that are useful for building
+ * your own citation components.
+ *
+ * @packageDocumentation
+ */
+// URL Utilities - For handling URL citation metadata
+export { extractDomain, isBlockedStatus, isErrorStatus, isVerifiedStatus } from "./UrlCitationComponent.js";
+// Utilities - For generating citation keys and display text
+export { generateCitationKey, generateCitationInstanceId, getCitationDisplayText, getCitationValueText, classNames, CITATION_X_PADDING, CITATION_Y_PADDING, } from "./utils.js";
+// Components
+export { CitationComponent, MemoizedCitationComponent, } from "./CitationComponent.js";

package/lib/react/primitives.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Citation Primitives - Composable building blocks for citation components
+ * @packageDocumentation
+ */
+import React, { type ReactNode, type HTMLAttributes, type MouseEvent, type TouchEvent } from "react";
+import type { Citation as CitationType, CitationStatus } from "../types/citation.js";
+import type { FoundHighlightLocation } from "../types/foundHighlight.js";
+import type { SearchState } from "../types/search.js";
+interface CitationContextValue {
+    citation: CitationType;
+    citationKey: string;
+    citationInstanceId: string;
+    status: CitationStatus;
+    foundCitation: FoundHighlightLocation | null;
+    searchState: SearchState | null;
+    config: {
+        displayCitationValue: boolean;
+        fallbackDisplay: string | null;
+        pendingContent: ReactNode;
+    };
+}
+/** Access citation context. Must be used within Citation.Root. */
+export declare function useCitationContext(): CitationContextValue;
+/** Safely access citation context (returns null if not in context). */
+export declare function useCitationContextSafe(): CitationContextValue | null;
+export interface CitationRootProps {
+    citation: CitationType;
+    foundCitation?: FoundHighlightLocation | null;
+    searchState?: SearchState | null;
+    children: ReactNode;
+    displayCitationValue?: boolean;
+    fallbackDisplay?: string | null;
+    pendingContent?: ReactNode;
+}
+/** Root component that provides citation context to all child primitives. */
+export declare const CitationRoot: React.ForwardRefExoticComponent<CitationRootProps & React.HTMLAttributes<HTMLSpanElement> & React.RefAttributes<HTMLSpanElement>>;
+export interface CitationTriggerProps extends HTMLAttributes<HTMLSpanElement> {
+    onCitationClick?: (citation: CitationType, citationKey: string, event: MouseEvent) => void;
+    onCitationMouseEnter?: (citation: CitationType, citationKey: string) => void;
+    onCitationMouseLeave?: (citation: CitationType, citationKey: string) => void;
+    onCitationTouchEnd?: (citation: CitationType, citationKey: string, event: TouchEvent) => void;
+    isMobile?: boolean;
+    disableHover?: boolean;
+}
+/** Interactive trigger component for the citation. */
+export declare const CitationTrigger: React.ForwardRefExoticComponent<CitationTriggerProps & React.RefAttributes<HTMLSpanElement>>;
+export interface CitationBracketProps extends HTMLAttributes<HTMLSpanElement> {
+    open?: string;
+    close?: string;
+}
+/** Bracket wrapper component for citation content. */
+export declare const CitationBracket: React.ForwardRefExoticComponent<CitationBracketProps & React.RefAttributes<HTMLSpanElement>>;
+export interface CitationNumberProps extends HTMLAttributes<HTMLSpanElement> {
+    number?: string | number;
+}
+/** Displays the citation number. */
+export declare const CitationNumber: React.ForwardRefExoticComponent<CitationNumberProps & React.RefAttributes<HTMLSpanElement>>;
+export interface CitationValueProps extends HTMLAttributes<HTMLSpanElement> {
+    value?: string;
+    separator?: string;
+}
+/** Displays the citation value (summary text). */
+export declare const CitationValue: React.ForwardRefExoticComponent<CitationValueProps & React.RefAttributes<HTMLSpanElement>>;
+export interface CitationIndicatorProps extends HTMLAttributes<HTMLSpanElement> {
+    verifiedIndicator?: ReactNode;
+    partialIndicator?: ReactNode;
+    missIndicator?: ReactNode;
+    pendingIndicator?: ReactNode;
+    showFor?: Array<"verified" | "partial" | "miss" | "pending">;
+}
+/** Displays a status indicator based on citation verification state. */
+export declare const CitationIndicator: React.ForwardRefExoticComponent<CitationIndicatorProps & React.RefAttributes<HTMLSpanElement>>;
+export interface CitationStatusProps {
+    children: (status: CitationStatus) => ReactNode;
+}
+/** Render prop component for accessing citation status. */
+export declare function CitationStatusComponent({ children }: CitationStatusProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace CitationStatusComponent {
+    var displayName: string;
+}
+export interface CitationPhraseProps extends HTMLAttributes<HTMLSpanElement> {
+    maxLength?: number;
+    truncationSuffix?: string;
+}
+/** Displays the citation's full phrase with optional truncation. */
+export declare const CitationPhrase: React.ForwardRefExoticComponent<CitationPhraseProps & React.RefAttributes<HTMLSpanElement>>;
+export interface CitationPageProps extends HTMLAttributes<HTMLSpanElement> {
+    prefix?: string;
+}
+/** Displays the citation's page number. */
+export declare const CitationPage: React.ForwardRefExoticComponent<CitationPageProps & React.RefAttributes<HTMLSpanElement>>;
+/** Citation primitives namespace for composable citation components. */
+export declare const Citation: {
+    readonly Root: React.ForwardRefExoticComponent<CitationRootProps & React.HTMLAttributes<HTMLSpanElement> & React.RefAttributes<HTMLSpanElement>>;
+    readonly Trigger: React.ForwardRefExoticComponent<CitationTriggerProps & React.RefAttributes<HTMLSpanElement>>;
+    readonly Bracket: React.ForwardRefExoticComponent<CitationBracketProps & React.RefAttributes<HTMLSpanElement>>;
+    readonly Number: React.ForwardRefExoticComponent<CitationNumberProps & React.RefAttributes<HTMLSpanElement>>;
+    readonly Value: React.ForwardRefExoticComponent<CitationValueProps & React.RefAttributes<HTMLSpanElement>>;
+    readonly Indicator: React.ForwardRefExoticComponent<CitationIndicatorProps & React.RefAttributes<HTMLSpanElement>>;
+    readonly Status: typeof CitationStatusComponent;
+    readonly Phrase: React.ForwardRefExoticComponent<CitationPhraseProps & React.RefAttributes<HTMLSpanElement>>;
+    readonly Page: React.ForwardRefExoticComponent<CitationPageProps & React.RefAttributes<HTMLSpanElement>>;
+};
+export {};

package/lib/react/primitives.js

@@ -0,0 +1,190 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * Citation Primitives - Composable building blocks for citation components
+ * @packageDocumentation
+ */
+import { createContext, useContext, useMemo, useCallback, forwardRef, } from "react";
+import { getCitationStatus } from "../parsing/parseCitation.js";
+import { generateCitationKey, generateCitationInstanceId, classNames } from "./utils.js";
+const CitationContext = createContext(null);
+/** Access citation context. Must be used within Citation.Root. */
+export function useCitationContext() {
+    const context = useContext(CitationContext);
+    if (!context) {
+        throw new Error("Citation components must be used within a Citation.Root");
+    }
+    return context;
+}
+/** Safely access citation context (returns null if not in context). */
+export function useCitationContextSafe() {
+    return useContext(CitationContext);
+}
+/** Root component that provides citation context to all child primitives. */
+export const CitationRoot = forwardRef(({ citation, foundCitation = null, searchState = null, children, displayCitationValue = false, fallbackDisplay = null, pendingContent = "..", className, ...props }, ref) => {
+    const citationKey = useMemo(() => generateCitationKey(citation), [citation]);
+    const citationInstanceId = useMemo(() => generateCitationInstanceId(citationKey), [citationKey]);
+    const status = getCitationStatus(foundCitation);
+    const contextValue = useMemo(() => ({
+        citation,
+        citationKey,
+        citationInstanceId,
+        status,
+        foundCitation,
+        searchState,
+        config: {
+            displayCitationValue,
+            fallbackDisplay,
+            pendingContent,
+        },
+    }), [
+        citation,
+        citationKey,
+        citationInstanceId,
+        status,
+        foundCitation,
+        searchState,
+        displayCitationValue,
+        fallbackDisplay,
+        pendingContent,
+    ]);
+    return (_jsx(CitationContext.Provider, { value: contextValue, children: _jsx("span", { ref: ref, "data-citation-id": citationKey, "data-citation-instance": citationInstanceId, className: classNames("citation-root", className), ...props, children: children }) }));
+});
+CitationRoot.displayName = "Citation.Root";
+/** Interactive trigger component for the citation. */
+export const CitationTrigger = forwardRef(({ children, className, onCitationClick, onCitationMouseEnter, onCitationMouseLeave, onCitationTouchEnd, isMobile = false, disableHover = false, onClick, onMouseEnter, onMouseLeave, onMouseDown, onTouchEnd, ...props }, ref) => {
+    const { citation, citationKey, status } = useCitationContext();
+    const handleClick = useCallback((e) => {
+        e.stopPropagation();
+        onClick?.(e);
+    }, [onClick]);
+    const handleMouseDown = useCallback((e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        onMouseDown?.(e);
+        onCitationClick?.(citation, citationKey, e);
+    }, [onMouseDown, onCitationClick, citation, citationKey]);
+    const handleMouseEnter = useCallback((e) => {
+        onMouseEnter?.(e);
+        if (!disableHover) {
+            onCitationMouseEnter?.(citation, citationKey);
+        }
+    }, [onMouseEnter, disableHover, onCitationMouseEnter, citation, citationKey]);
+    const handleMouseLeave = useCallback((e) => {
+        onMouseLeave?.(e);
+        if (!disableHover) {
+            onCitationMouseLeave?.(citation, citationKey);
+        }
+    }, [onMouseLeave, disableHover, onCitationMouseLeave, citation, citationKey]);
+    const handleTouchEnd = useCallback((e) => {
+        onTouchEnd?.(e);
+        if (isMobile) {
+            e.preventDefault();
+            e.stopPropagation();
+            onCitationTouchEnd?.(citation, citationKey, e);
+        }
+    }, [onTouchEnd, isMobile, onCitationTouchEnd, citation, citationKey]);
+    const statusClasses = classNames(status.isVerified && !status.isPartialMatch && "citation-trigger--verified", status.isPartialMatch && "citation-trigger--partial", status.isMiss && "citation-trigger--miss", status.isPending && "citation-trigger--pending");
+    return (_jsx("span", { ref: ref, role: "button", tabIndex: 0, className: classNames("citation-trigger", statusClasses, className), onClick: handleClick, onMouseDown: handleMouseDown, onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, onTouchEndCapture: isMobile ? handleTouchEnd : undefined, ...props, children: children }));
+});
+CitationTrigger.displayName = "Citation.Trigger";
+/** Bracket wrapper component for citation content. */
+export const CitationBracket = forwardRef(({ children, className, open = "[", close = "]", ...props }, ref) => {
+    return (_jsxs("span", { ref: ref, className: classNames("citation-bracket", className), "aria-hidden": "true", ...props, children: [_jsx("span", { className: "citation-bracket__open", children: open }), _jsx("span", { className: "citation-bracket__content", children: children }), _jsx("span", { className: "citation-bracket__close", children: close })] }));
+});
+CitationBracket.displayName = "Citation.Bracket";
+/** Displays the citation number. */
+export const CitationNumber = forwardRef(({ className, number, ...props }, ref) => {
+    const { citation, config, status } = useCitationContext();
+    const displayNumber = useMemo(() => {
+        if (number !== undefined)
+            return String(number);
+        if (config.displayCitationValue) {
+            return citation.value || citation.citationNumber?.toString() || config.fallbackDisplay || "";
+        }
+        return citation.citationNumber?.toString() || "";
+    }, [number, citation, config]);
+    if (status.isPending) {
+        return (_jsx("span", { ref: ref, className: classNames("citation-number citation-number--pending", className), ...props, children: config.pendingContent }));
+    }
+    return (_jsx("span", { ref: ref, className: classNames("citation-number", className), ...props, children: displayNumber }));
+});
+CitationNumber.displayName = "Citation.Number";
+/** Displays the citation value (summary text). */
+export const CitationValue = forwardRef(({ className, value, separator = " ", ...props }, ref) => {
+    const { citation, config } = useCitationContext();
+    const displayValue = useMemo(() => {
+        if (value !== undefined)
+            return value;
+        if (config.displayCitationValue)
+            return "";
+        return citation.value || "";
+    }, [value, citation, config]);
+    if (!displayValue)
+        return null;
+    return (_jsxs("span", { ref: ref, className: classNames("citation-value", className), ...props, children: [displayValue, separator] }));
+});
+CitationValue.displayName = "Citation.Value";
+/** Displays a status indicator based on citation verification state. */
+export const CitationIndicator = forwardRef(({ className, verifiedIndicator = "✓", partialIndicator = "*", missIndicator = null, pendingIndicator = null, showFor, ...props }, ref) => {
+    const { status } = useCitationContext();
+    const shouldShow = useCallback((state) => {
+        if (!showFor)
+            return true;
+        return showFor.includes(state);
+    }, [showFor]);
+    if (status.isPartialMatch && shouldShow("partial")) {
+        return (_jsx("span", { ref: ref, className: classNames("citation-indicator citation-indicator--partial", className), "aria-label": "Partial match", ...props, children: partialIndicator }));
+    }
+    if (status.isVerified && !status.isPartialMatch && shouldShow("verified")) {
+        return (_jsx("span", { ref: ref, className: classNames("citation-indicator citation-indicator--verified", className), "aria-label": "Verified", ...props, children: verifiedIndicator }));
+    }
+    if (status.isMiss && shouldShow("miss") && missIndicator) {
+        return (_jsx("span", { ref: ref, className: classNames("citation-indicator citation-indicator--miss", className), "aria-label": "Not found", ...props, children: missIndicator }));
+    }
+    if (status.isPending && shouldShow("pending") && pendingIndicator) {
+        return (_jsx("span", { ref: ref, className: classNames("citation-indicator citation-indicator--pending", className), "aria-label": "Pending", ...props, children: pendingIndicator }));
+    }
+    return null;
+});
+CitationIndicator.displayName = "Citation.Indicator";
+/** Render prop component for accessing citation status. */
+export function CitationStatusComponent({ children }) {
+    const { status } = useCitationContext();
+    return _jsx(_Fragment, { children: children(status) });
+}
+CitationStatusComponent.displayName = "Citation.Status";
+/** Displays the citation's full phrase with optional truncation. */
+export const CitationPhrase = forwardRef(({ className, maxLength, truncationSuffix = "...", ...props }, ref) => {
+    const { citation } = useCitationContext();
+    const displayPhrase = useMemo(() => {
+        const phrase = citation.fullPhrase || "";
+        if (!maxLength || phrase.length <= maxLength)
+            return phrase;
+        return phrase.slice(0, maxLength) + truncationSuffix;
+    }, [citation.fullPhrase, maxLength, truncationSuffix]);
+    if (!displayPhrase)
+        return null;
+    return (_jsx("span", { ref: ref, className: classNames("citation-phrase", className), ...props, children: displayPhrase }));
+});
+CitationPhrase.displayName = "Citation.Phrase";
+/** Displays the citation's page number. */
+export const CitationPage = forwardRef(({ className, prefix = "", ...props }, ref) => {
+    const { citation } = useCitationContext();
+    if (citation.pageNumber === undefined || citation.pageNumber === null) {
+        return null;
+    }
+    return (_jsxs("span", { ref: ref, className: classNames("citation-page", className), ...props, children: [prefix, citation.pageNumber] }));
+});
+CitationPage.displayName = "Citation.Page";
+/** Citation primitives namespace for composable citation components. */
+export const Citation = {
+    Root: CitationRoot,
+    Trigger: CitationTrigger,
+    Bracket: CitationBracket,
+    Number: CitationNumber,
+    Value: CitationValue,
+    Indicator: CitationIndicator,
+    Status: CitationStatusComponent,
+    Phrase: CitationPhrase,
+    Page: CitationPage,
+};

package/lib/react/types.d.ts

@@ -0,0 +1,192 @@
+import type { Citation, CitationStatus } from "../types/citation.js";
+import type { FoundHighlightLocation } from "../types/foundHighlight.js";
+import type { SearchState } from "../types/search.js";
+/**
+ * Available citation display variants.
+ *
+ * - `brackets`: Shows value/number in brackets with blue text styling (default)
+ * - `numeric`: Shows citation number with indicator, no brackets
+ * - `text`: Shows the value, no text styling, no truncate, shows indicator
+ * - `minimal`: No brackets, just display text with indicator
+ * - `indicator`: Only the status indicator (checkmark/warning), no text
+ */
+export type CitationVariant = "brackets" | "numeric" | "text" | "minimal" | "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;
+    /** When true, displays value/citationNumber merged in the bracket */
+    displayCitationValue?: boolean;
+    /** Fallback display text when citation value is empty */
+    fallbackDisplay?: string | null;
+    /** Display variant for the citation */
+    variant?: CitationVariant;
+}
+/**
+ * Props for URL citation component
+ */
+export interface UrlCitationProps extends Omit<BaseCitationProps, "citation"> {
+    /** 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 */
+    foundCitation: FoundHighlightLocation | null | undefined;
+    /** Current search state */
+    searchState: SearchState | 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 value 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;
+}
+/**
+ * Props for the tooltip wrapper component
+ */
+export interface CitationTooltipProps {
+    children: React.ReactNode;
+    citation: Citation;
+    foundHighlight?: FoundHighlightLocation | null;
+    searchState?: SearchState | null;
+    shouldShowTooltip: boolean;
+}

package/lib/react/types.js

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

package/lib/react/useSmartDiff.d.ts

@@ -0,0 +1,16 @@
+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;
+};