@anaralabs/lector 3.3.0 → 3.5.0

package/README.md

@@ -50,6 +50,39 @@ export default function PDFViewer() {
 }
 ```
 
+## Local Development using PNPM and Yalc
+
+When you are using "pnpm link", you are bound to use pnpm on your consumer project when you are developing locally.
+With yalc, we are decoupling the need for pnpm and now the package can be tested with any package managers. Any
+changes should be automatically published to yalc on save, forcing a rebuilt and updating the consumer project.
+
+Install yalc globally:
+
+```
+pnpm i yalc -g
+```
+
+From lector:
+
+```bash
+# navigate to lector package folder and install dependencies
+pnpm i
+# when you first start development, make sure you publish the package locally
+yalc publish
+# and run the project in development mode to start a watcher that rebuilds the project and pushes the changes locally on save
+pnpm dev
+```
+
+From consumer project:
+(It doesn't really matter what package manager you are using)
+
+```bash
+# add local package to your package.json of the consumer project using yalc
+yalc add @anaralabs/lector
+# or if you don't want to add the yalc package in your package.json
+yalc link @anaralabs/lector
+```
+
 ## Features
 
 - 📱 Responsive and mobile-friendly

package/dist/_tsup-dts-rollup.d.ts

@@ -16,17 +16,101 @@ import { ReactNode } from 'react';
 import { RefAttributes } from 'react';
 import { StoreApi } from 'zustand';
 import type { TypedArray } from 'pdfjs-dist/types/src/display/api';
+import { UseBoundStore } from 'zustand';
+import { useFloating } from '@floating-ui/react';
+import { useInteractions } from '@floating-ui/react';
 import { Virtualizer } from '@tanstack/react-virtual';
 
-export declare const AnnotationLayer: ({ renderForms, className, style, ...props }: AnnotationLayerParams & HTMLProps<HTMLDivElement>) => JSX.Element;
+declare interface Annotation {
+    id: string;
+    pageNumber: number;
+    highlights: Array<{
+        height: number;
+        left: number;
+        top: number;
+        width: number;
+        pageNumber: number;
+    }>;
+    comment?: string;
+    color?: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export { Annotation }
+export { Annotation as Annotation_alias_1 }
+
+export declare const AnnotationHighlightLayer: ({ className, style, renderTooltipContent, focusedAnnotationId, onAnnotationClick, }: AnnotationHighlightLayerProps) => JSX.Element;
+
+declare interface AnnotationHighlightLayerProps {
+    className?: string;
+    style?: React.CSSProperties;
+    renderTooltipContent?: (props: {
+        annotation: Annotation;
+        onClose: () => void;
+    }) => React.ReactNode;
+    focusedAnnotationId?: string;
+    onAnnotationClick?: (annotation: Annotation) => void;
+}
+
+/**
+ * AnnotationLayer renders PDF annotations like links, highlights, and form fields.
+ *
+ * @param renderForms - Whether to render form fields in the annotation layer.
+ * @param externalLinksEnabled - Whether external links should be clickable. When false, external links won't open.
+ * @param jumpOptions - Options for page navigation behavior when clicking internal links.
+ *                      See `usePdfJump` hook for available options.
+ */
+export declare const AnnotationLayer: ({ renderForms, externalLinksEnabled, jumpOptions, className, style, ...props }: AnnotationLayerParams & HTMLProps<HTMLDivElement>) => JSX.Element;
 
 declare interface AnnotationLayerParams {
     /**
      * Whether to render forms.
      */
     renderForms?: boolean;
+    /**
+     * Whether external links are enabled.
+     * If false, external links will not open.
+     * @default true
+     */
+    externalLinksEnabled?: boolean;
+    /**
+     * Options to pass to the jumpToPage function when navigating.
+     * See usePdfJump hook for available options.
+     * @default { behavior: "smooth", align: "start" }
+     */
+    jumpOptions?: Parameters<ReturnType<typeof usePdfJump>['jumpToPage']>[1];
+}
+
+declare interface AnnotationState {
+    annotations: Annotation[];
+    addAnnotation: (annotation: Omit<Annotation, "id" | "createdAt" | "updatedAt">) => void;
+    updateAnnotation: (id: string, updates: Partial<Annotation>) => void;
+    deleteAnnotation: (id: string) => void;
+    setAnnotations: (annotations: Annotation[]) => void;
 }
 
+export declare const AnnotationTooltip: ({ annotation, children, tooltipContent, onOpenChange, isOpen: controlledIsOpen, }: AnnotationTooltipProps) => JSX.Element;
+
+declare interface AnnotationTooltipProps {
+    annotation: Annotation;
+    children: React.ReactNode;
+    tooltipContent: React.ReactNode;
+    onOpenChange?: (open: boolean) => void;
+    isOpen?: boolean;
+}
+
+/**
+ * Calculates the highlight rectangles for a given text match.
+ *
+ * @param pageProxy - The PDF page proxy object
+ * @param textMatch - An object containing:
+ *   - pageNumber: The page number where the match is found
+ *   - text: The text content containing the match (usually a larger chunk of text)
+ *   - matchIndex: The index within the text where the match starts
+ *   - searchText: (Optional) The exact search term to highlight. If provided, only highlights
+ *                 this exact term instead of the entire text. If not provided, highlights the full text.
+ * @returns An array of HighlightRect objects representing the areas to highlight
+ */
 export declare function calculateHighlightRects(pageProxy: PDFPageProxy, textMatch: TextPosition): Promise<HighlightRect[]>;
 
 export declare const cancellable: <T extends Promise<unknown>>(promise: T) => {
@@ -40,6 +124,28 @@ export declare const CanvasLayer: ({ style, background, ...props }: HTMLProps<HT
 
 export declare const clamp: (value: number, min: number, max: number) => number;
 
+declare type CollapsibleSelection = {
+    highlights: HighlightRect[];
+    text: string;
+    isCollapsed: boolean;
+};
+
+declare type ColoredHighlight = {
+    color: string;
+    rectangles: HighlightRect[];
+    pageNumber: number;
+    text: string;
+    uuid: string;
+};
+export { ColoredHighlight }
+export { ColoredHighlight as ColoredHighlight_alias_1 }
+
+export declare const ColoredHighlightLayer: ({ onHighlight, }: ColoredHighlightLayerProps) => JSX.Element;
+
+declare type ColoredHighlightLayerProps = {
+    onHighlight?: (highlight: ColoredHighlight) => void;
+};
+
 export declare const CurrentPage: ({ ...props }: HTMLProps<HTMLInputElement>) => JSX.Element;
 
 export declare const CurrentZoom: ({ ...props }: HTMLProps<HTMLInputElement>) => JSX.Element;
@@ -50,11 +156,15 @@ export declare const CustomLayer: ({ children, }: {
 
 export declare const firstMemo: <T>(first: boolean, memo: unknown, initializer: () => T) => T;
 
+export declare const getEndOfHighlight: (selection: ColoredHighlight) => number;
+
 export declare const getFitWidthZoom: (containerWidth: number, viewports: PageViewport[], zoomOptions: {
     minZoom: number;
     maxZoom: number;
 }) => number;
 
+export declare const getMidHeightOfHighlightLine: (selection: ColoredHighlight) => number;
+
 export declare const HighlightLayer: ForwardRefExoticComponent<HighlightLayerProps & RefAttributes<HTMLDivElement>>;
 
 declare interface HighlightLayerProps extends ComponentPropsWithoutRef<"div"> {
@@ -85,13 +195,28 @@ export declare class LinkService implements IPDFLinkService {
     _pdfDocumentProxy?: PDFDocumentProxy;
     externalLinkEnabled: boolean;
     isInPresentationMode: boolean;
+    _currentPageNumber: number;
+    _pageNavigationCallback?: (pageNumber: number) => void;
     get pdfDocumentProxy(): PDFDocumentProxy;
     constructor();
     get pagesCount(): number;
+    get page(): number;
+    set page(value: number);
+    setDocument(pdfDocument: PDFDocumentProxy): void;
+    setViewer(): void;
     getDestinationHash(dest: unknown[]): string;
-    getAnchorUrl(): string;
+    getAnchorUrl(hash: string): string;
     addLinkAttributes(link: HTMLAnchorElement, url: string, newWindow?: boolean | undefined): void;
     goToDestination(dest: string | unknown[] | Promise<unknown[]>): Promise<void>;
+    executeNamedAction(): void;
+    navigateTo(dest: string | unknown[] | Promise<unknown[]>): void;
+    get rotation(): number;
+    set rotation(value: number);
+    goToPage(pageNumber: number): void;
+    setHash(hash: string): void;
+    executeSetOCGState(): void;
+    registerPageNavigationCallback(callback: (pageNumber: number) => void): void;
+    unregisterPageNavigationCallback(): void;
 }
 
 export declare const NextPage: () => void;
@@ -153,6 +278,9 @@ declare interface PDFState {
     getPdfPageProxy: (pageNumber: number) => PDFPageProxy;
     customSelectionRects: HighlightRect[];
     setCustomSelectionRects: (rects: HighlightRect[]) => void;
+    coloredHighlights: ColoredHighlight[];
+    addColoredHighlight: (value: ColoredHighlight) => void;
+    deleteColoredHighlight: (uuid: string) => void;
 }
 
 export declare const PDFStore: {
@@ -191,6 +319,7 @@ export declare interface SearchResult {
     score: number;
     matchIndex: number;
     isExactMatch: boolean;
+    searchText?: string;
 }
 
 export declare interface SearchResults {
@@ -199,6 +328,8 @@ export declare interface SearchResults {
     hasMoreResults: boolean;
 }
 
+declare type Selection_2 = Omit<CollapsibleSelection, "isCollapsed">;
+
 export declare const SelectionTooltip: ({ children }: SelectionTooltipProps) => JSX.Element;
 
 declare interface SelectionTooltipProps {
@@ -218,6 +349,7 @@ declare interface TextPosition {
     pageNumber: number;
     text: string;
     matchIndex: number;
+    searchText?: string;
 }
 
 export declare const Thumbnail: ({ pageNumber, ...props }: HTMLProps<HTMLCanvasElement> & {
@@ -230,6 +362,44 @@ export declare const Thumbnails: ({ children, ...props }: HTMLProps<HTMLDivEleme
 
 export declare const TotalPages: ({ ...props }: HTMLProps<HTMLDivElement>) => JSX.Element;
 
+export declare const useAnnotationActions: ({ annotation, onClose, }: UseAnnotationActionsProps) => UseAnnotationActionsReturn;
+
+declare interface UseAnnotationActionsProps {
+    annotation: Annotation;
+    onClose?: () => void;
+}
+
+declare interface UseAnnotationActionsReturn {
+    comment: string;
+    isEditing: boolean;
+    setComment: (comment: string) => void;
+    setIsEditing: (isEditing: boolean) => void;
+    handleSaveComment: () => void;
+    handleColorChange: (color: string) => void;
+    handleCancelEdit: () => void;
+    colors: string[];
+}
+
+declare const useAnnotations: UseBoundStore<StoreApi<AnnotationState>>;
+export { useAnnotations }
+export { useAnnotations as useAnnotations_alias_1 }
+
+export declare const useAnnotationTooltip: ({ annotation, onOpenChange, }: UseAnnotationTooltipProps) => UseAnnotationTooltipReturn;
+
+declare interface UseAnnotationTooltipProps {
+    annotation: Annotation;
+    onOpenChange?: (open: boolean) => void;
+}
+
+declare interface UseAnnotationTooltipReturn {
+    isOpen: boolean;
+    setIsOpen: (open: boolean) => void;
+    refs: ReturnType<typeof useFloating>["refs"];
+    floatingStyles: ReturnType<typeof useFloating>["floatingStyles"];
+    getFloatingProps: ReturnType<typeof useInteractions>["getFloatingProps"];
+    getReferenceProps: ReturnType<typeof useInteractions>["getReferenceProps"];
+}
+
 declare const usePdf: <T>(selector: (state: PDFState) => T) => T;
 export { usePdf }
 export { usePdf as usePdf_alias_1 }
@@ -275,6 +445,8 @@ declare const usePDFOutline: () => {
     items: Array<any>;
 }[] | undefined;
 
+export declare const usePDFPageNumber: () => number;
+
 export declare const useSearch: () => {
     textContent: {
         pageNumber: number;
@@ -286,11 +458,8 @@ export declare const useSearch: () => {
 };
 
 export declare const useSelectionDimensions: () => {
-    getDimension: () => {
-        highlights: HighlightRect[];
-        text: string;
-        isCollapsed: boolean;
-    } | undefined;
+    getDimension: () => CollapsibleSelection | undefined;
+    getSelection: () => Selection_2;
 };
 
 export declare const ZoomIn: ({ ...props }: HTMLProps<HTMLButtonElement>) => JSX.Element;

package/dist/index.d.ts

@@ -1,5 +1,8 @@
+export { AnnotationTooltip } from './_tsup-dts-rollup.js';
+export { AnnotationHighlightLayer } from './_tsup-dts-rollup.js';
 export { AnnotationLayer } from './_tsup-dts-rollup.js';
 export { CanvasLayer } from './_tsup-dts-rollup.js';
+export { ColoredHighlightLayer } from './_tsup-dts-rollup.js';
 export { CustomLayer } from './_tsup-dts-rollup.js';
 export { HighlightLayer } from './_tsup-dts-rollup.js';
 export { TextLayer } from './_tsup-dts-rollup.js';
@@ -25,7 +28,11 @@ export { SearchResult } from './_tsup-dts-rollup.js';
 export { SearchResults } from './_tsup-dts-rollup.js';
 export { useSearch } from './_tsup-dts-rollup.js';
 export { calculateHighlightRects } from './_tsup-dts-rollup.js';
+export { Annotation } from './_tsup-dts-rollup.js';
+export { useAnnotations } from './_tsup-dts-rollup.js';
 export { LinkService } from './_tsup-dts-rollup.js';
+export { usePDFPageNumber } from './_tsup-dts-rollup.js';
 export { useSelectionDimensions } from './_tsup-dts-rollup.js';
+export { ColoredHighlight } from './_tsup-dts-rollup.js';
 export { HighlightRect } from './_tsup-dts-rollup.js';
 export { usePdf } from './_tsup-dts-rollup.js';