Lector

Lector's dark mode uses OKLab color space remapping to flip perceived lightness while preserving hue and chroma.

Key Behaviors:

• Images: Stay pixel-perfect and are NOT inverted.
• Scanned PDFs: Since they are treated as single images, they remain in light mode.
• Text/Lines: Black text becomes the palette foreground; white paper becomes the palette background.

Limitations:

• Midtones: Can land a few percent off original opacity in luminosity soft-masks.
• Mesh-gradients: Keep their original colors.
• DOM Annotations: Elements rendered via AnnotationLayer (like form widgets or link borders) keep original colors and must be styled via CSS.
• Blend Modes: Overlays using mix-blend-multiply may need to be switched to mix-blend-screen for dark mode.
• Custom CanvasFactory: Providing your own CanvasFactory via documentOptions will disable scratch-canvas recoloring.

To create custom navigation controls (like 'Previous', 'Next', or a page number input) in Lector, you can use the usePdf and usePdfJump hooks.

1. Use usePdf to access the current state of the PDF, such as state.currentPage and state.pdfDocumentProxy?.numPages.
2. Use usePdfJump to obtain the jumpToPage function, which allows you to programmatically navigate to a specific page.
3. Wrap your viewer in the Root component to provide the PDF source and context to these hooks.

import { usePdf, usePdfJump } from "@anaralabs/lector";
import { useEffect, useState } from "react";

const PageNavigationButtons = () => {
  const pages = usePdf((state) => state.pdfDocumentProxy?.numPages);
  const currentPage = usePdf((state) => state.currentPage);
  const [pageNumber, setPageNumber] = useState<string | number>(currentPage);
  const { jumpToPage } = usePdfJump();

  const handlePreviousPage = () => {
    if (currentPage > 1) {
      jumpToPage(currentPage - 1, { behavior: "auto" });
    }
  };

  const handleNextPage = () => {
    if (currentPage < pages) {
      jumpToPage(currentPage + 1, { behavior: "auto" });
    }
  };

  // ... implementation of UI components using these handlers
};

To create a minimal PDF viewer, use the Root component to wrap your viewer configuration. You must provide a source (the URL to the PDF file) and define the rendering structure using Pages, Page, CanvasLayer, and TextLayer.

Key features of this implementation pattern:

• Container Control: Use className on the Root component to define the viewer's dimensions (e.g., w-full h-[500px]).
• Loading States: Pass a React component to the loader prop to display a placeholder while the PDF is being fetched.
• Theming: Use the colorScheme prop ('light' or 'dark') to control the native rendering mode of the PDF.
• Rendering Layers:
  • <CanvasLayer />: Renders the visual content of the PDF page.
  • <TextLayer />: Enables text selection and copying capabilities.
• Structure: The hierarchy must follow Root -> Pages -> Page -> [CanvasLayer, TextLayer].

"use client";

import { CanvasLayer, Page, Pages, Root, TextLayer } from "@anaralabs/lector";
import React from "react";

const fileUrl = "/pdf/pathways.pdf";

const Basic = () => {
  return (
    <Root
      source={fileUrl}
      className='w-full h-[500px] border overflow-hidden rounded-lg'
      loader={<div className='p-4'>Loading...</div>}
      colorScheme="light">
      <Pages>
        <Page>
          <CanvasLayer />
          <TextLayer />
        </Page>
      </Pages>
    </Root>
  );
};

export default Basic;

To enable text selection and highlighting in a PDF, use the @anaralabs/lector components. You must wrap your viewer in a Root component providing the PDF source, and include a HighlightLayer within your page structure to render the visual highlights.

Key components required:

• Root: The main provider that manages the PDF state and source.
• Pages & Page: Container components for the PDF pages.
• CanvasLayer: Renders the actual PDF content.
• TextLayer: Enables text selection capabilities.
• HighlightLayer: Renders the visual highlight overlays.

"use client";

import {
  Root,
  Pages,
  Page,
  CanvasLayer,
  TextLayer,
  HighlightLayer,
  usePdf,
  useSelectionDimensions,
} from "@anaralabs/lector";

const PdfHighlightSelect = () => (
  <Root
    source="/pdf/document.pdf"
    className="flex bg-gray-50 h-[500px]"
    loader={<div className="p-4">Loading...</div>}
  >
    <HighlightLayerContent />
  </Root>
);

const HighlightLayerContent = () => {
  const selectionDimensions = useSelectionDimensions();
  const setHighlights = usePdf((state) => state.setHighlight);

  const handleHighlight = () => {
    const dimension = selectionDimensions.getDimension();
    if (dimension && !dimension.isCollapsed) {
      setHighlights(dimension.highlights);
    }
  };

  return (
    <Pages className="p-4 w-full">
      <Page>
        {/* Custom selection logic can be injected here */}
        <CanvasLayer />
        <TextLayer />
        <HighlightLayer className="bg-yellow-200/70" />
      </Page>
    </Pages>
  );
};

You can build a custom search interface by using the useSearch hook to access search results and the search function. To implement a complete search experience, follow these steps:

1. Wrap your application in the <Root> component and provide a PDF source.
2. Use the <Search> component as a provider for your search UI.
3. Access search state via useSearch(), which provides searchResults (containing exactMatches and fuzzyMatches) and the search method.
4. Handle results by mapping over results.exactMatches and using calculateHighlightRects combined with usePdfJump to navigate to the found text.
5. Implement pagination by checking results.hasMoreResults and calling search with an increased limit.

Note: It is recommended to use debouncing on your search input to prevent excessive search calls.

import {
  Root,
  Pages,
  Page,
  CanvasLayer,
  TextLayer,
  HighlightLayer,
  Search,
  calculateHighlightRects,
  usePdf,
  usePdfJump,
  useSearch,
} from "@anaralabs/lector";

// ... inside your component
const { searchResults: results, search } = useSearch();

// To search with a limit:
await search(debouncedSearchText, { limit: 5 });

// To jump to a result:
const { jumpToHighlightRects } = usePdfJump();
const pageProxy = getPdfPageProxy(result.pageNumber);
const rects = await calculateHighlightRects(pageProxy, {
  pageNumber: result.pageNumber,
  text: result.text,
  matchIndex: result.matchIndex,
  searchText: originalSearchText,
});
jumpToHighlightRects(rects, "pixels");