@nypl/web-reader 4.2.0 → 4.3.1

package/dist/index.d.ts

@@ -0,0 +1,532 @@
+import { FC } from 'react';
+
+interface Injectable {
+    type: string;
+    url?: string;
+    r2after?: boolean;
+    r2before?: boolean;
+    r2default?: boolean;
+    fontFamily?: string;
+    systemFont?: boolean;
+    appearance?: string;
+    async?: boolean;
+}
+
+interface Locator {
+    href: string;
+    type?: string;
+    title?: string;
+    locations: Locations;
+    text?: LocatorText;
+}
+interface LocatorText {
+    after?: string;
+    before?: string;
+    highlight?: string;
+}
+interface Locations {
+    fragment?: string;
+    progression?: number;
+    position?: number;
+    totalProgression?: number;
+    remainingPositions?: number;
+    totalRemainingPositions?: number;
+}
+
+declare const ReadiumWebpubContext = "http://readium.org/webpub/default.jsonld";
+declare const IS_DEV: boolean;
+declare const HEADER_HEIGHT = 48;
+declare const FOOTER_HEIGHT = 48;
+declare const CHROME_HEIGHT: number;
+declare const DEFAULT_HEIGHT: string;
+declare const DEFAULT_SHOULD_GROW_WHEN_SCROLLING = true;
+declare const DEFAULT_SETTINGS: ReaderSettings;
+declare const FONT_DETAILS: {
+    publisher: {
+        heading: string;
+        body: string;
+        token: string;
+        fontWeight: string;
+    };
+    serif: {
+        heading: string;
+        body: string;
+        token: string;
+        fontWeight: string;
+    };
+    'sans-serif': {
+        heading: string;
+        body: string;
+        token: string;
+        fontWeight: string;
+    };
+    'open-dyslexic': {
+        heading: string;
+        body: string;
+        token: string;
+        fontWeight: string;
+    };
+};
+declare const LOCAL_STORAGE_SETTINGS_KEY = "web-reader-settings";
+declare const LOCAL_STORAGE_LOCATIONS_KEY = "web-reader-locations";
+
+declare const WebpubPdfConformsTo = "http://librarysimplified.org/terms/profiles/pdf";
+declare const EpubConformsTo = "https://readium.org/webpub-manifest/profiles/epub";
+declare type ConformsTo = typeof WebpubPdfConformsTo | typeof EpubConformsTo;
+
+interface EPUBExtensionLinkProperties {
+    /**
+     * Identifies content contained in the linked resource, that cannot be strictly identified using a media type.
+     */
+    contains?: ('mathml' | 'onix' | 'remote-resources' | 'js' | 'svg' | 'xmp')[];
+    /**
+     * Hints how the layout of the resource should be presented
+     */
+    layout?: 'fixed' | 'reflowable';
+    /**
+     * Indicates that a resource is encrypted/obfuscated and provides relevant information for decryption
+     */
+    encrypted?: {
+        /**
+         * Identifies the algorithm used to encrypt the resource
+         */
+        algorithm: string;
+        /**
+         * Compression method used on the resource
+         */
+        compression?: string;
+        /**
+         * Original length of the resource in bytes before compression and/or encryption
+         */
+        originalLength?: number;
+        /**
+         * Identifies the encryption profile used to encrypt the resource
+         */
+        profile?: string;
+        /**
+         * Identifies the encryption scheme used to encrypt the resource
+         */
+        scheme?: string;
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+interface EPUBExtensionMetadata {
+    presentation?: {
+        /**
+         * Hints how the layout of the resource should be presented
+         */
+        layout?: 'fixed' | 'reflowable';
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+
+interface OPDSLinkProperties {
+    /**
+     * Provide a hint about the expected number of items returned
+     */
+    numberOfItems?: number;
+    /**
+     * The price of a publication is tied to its acquisition link
+     */
+    price?: {
+        value: number;
+        currency: 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'UYI' | 'UYU' | 'UZS' | 'VEF' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'XXX' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL';
+        [k: string]: unknown;
+    };
+    /**
+     * Indirect acquisition provides a hint for the expected media type that will be acquired after additional steps
+     */
+    indirectAcquisition?: OPDSAcquisitionObject[];
+    /**
+     * Library-specific feature for unavailable books that support a hold list
+     */
+    holds?: {
+        total?: number;
+        position?: number;
+        [k: string]: unknown;
+    };
+    /**
+     * Library-specific feature that contains information about the copies that a library has acquired
+     */
+    copies?: {
+        total?: number;
+        available?: number;
+        [k: string]: unknown;
+    };
+    /**
+     * Indicates the availability of a given resource
+     */
+    availability?: {
+        state: 'available' | 'unavailable' | 'reserved' | 'ready';
+        /**
+         * Timestamp for the previous state change
+         */
+        since?: ({
+            [k: string]: unknown;
+        } | {
+            [k: string]: unknown;
+        }) & string;
+        /**
+         * Timestamp for the next state change
+         */
+        until?: ({
+            [k: string]: unknown;
+        } | {
+            [k: string]: unknown;
+        }) & string;
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+interface OPDSAcquisitionObject {
+    type: string;
+    child?: OPDSAcquisitionObject[];
+    [k: string]: unknown;
+}
+
+interface PresentationHintsLinkProperties {
+    /**
+     * Specifies whether or not the parts of a linked resource that flow out of the viewport are clipped.
+     */
+    clipped?: boolean;
+    /**
+     * Specifies constraints for the presentation of a linked resource within the viewport.
+     */
+    fit?: 'contain' | 'cover' | 'width' | 'height';
+    /**
+     * Suggested orientation for the device when displaying the linked resource.
+     */
+    orientation?: 'auto' | 'landscape' | 'portrait';
+    /**
+     * Indicates how the linked resource should be displayed in a reading environment that displays synthetic spreads.
+     */
+    page?: 'left' | 'right' | 'center';
+    /**
+     * Indicates the condition to be met for the linked resource to be rendered within a synthetic spread.
+     */
+    spread?: 'auto' | 'both' | 'none' | 'landscape';
+    [k: string]: unknown;
+}
+
+interface ReadiumLink {
+    /**
+     * URI or URI template of the linked resource
+     */
+    href: string;
+    /**
+     * MIME type of the linked resource
+     */
+    type?: string;
+    /**
+     * Indicates that a URI template is used in href
+     */
+    templated?: boolean;
+    /**
+     * Title of the linked resource
+     */
+    title?: string;
+    /**
+     * Relation between the linked resource and its containing collection
+     */
+    rel?: string | string[];
+    /**
+     * Properties associated to the linked resource
+     */
+    properties?: OPDSLinkProperties & EPUBExtensionLinkProperties & PresentationHintsLinkProperties;
+    /**
+     * Height of the linked resource in pixels
+     */
+    height?: number;
+    /**
+     * Width of the linked resource in pixels
+     */
+    width?: number;
+    /**
+     * Bitrate of the linked resource in kbps
+     */
+    bitrate?: number;
+    /**
+     * Length of the linked resource in seconds
+     */
+    duration?: number;
+    /**
+     * Expected language of the linked resource
+     */
+    language?: string | string[];
+    /**
+     * Alternate resources for the linked resource
+     */
+    alternate?: ReadiumLink[];
+    /**
+     * Resources that are children of the linked resource, in the context of a given collection role
+     */
+    children?: ReadiumLink[];
+    [k: string]: unknown;
+}
+
+interface ContributorObject {
+    name: string | {
+        /**
+         * This interface was referenced by `undefined`'s JSON-Schema definition
+         * via the `patternProperty` "^((?<grandfathered>(en-GB-oed|i-ami|i-bnn|i-default|i-enochian|i-hak|i-klingon|i-lux|i-mingo|i-navajo|i-pwn|i-tao|i-tay|i-tsu|sgn-BE-FR|sgn-BE-NL|sgn-CH-DE)|(art-lojban|cel-gaulish|no-bok|no-nyn|zh-guoyu|zh-hakka|zh-min|zh-min-nan|zh-xiang))|((?<language>([A-Za-z]{2,3}(-(?<extlang>[A-Za-z]{3}(-[A-Za-z]{3}){0,2}))?)|[A-Za-z]{4}|[A-Za-z]{5,8})(-(?<script>[A-Za-z]{4}))?(-(?<region>[A-Za-z]{2}|[0-9]{3}))?(-(?<variant>[A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(-(?<extension>[0-9A-WY-Za-wy-z](-[A-Za-z0-9]{2,8})+))*(-(?<privateUse>x(-[A-Za-z0-9]{1,8})+))?)|(?<privateUse2>x(-[A-Za-z0-9]{1,8})+))$".
+         */
+        [k: string]: string;
+    };
+    identifier?: string;
+    sortAs?: string;
+    role?: string | string[];
+    position?: number;
+    links?: ReadiumLink[];
+    [k: string]: unknown;
+}
+declare type Contributor = string | (string | ContributorObject)[] | ContributorObject;
+
+declare type LanguageMap = string | {
+    [k: string]: string;
+};
+
+interface SubjectObject {
+    name: string | {
+        /**
+         * This interface was referenced by `undefined`'s JSON-Schema definition
+         * via the `patternProperty` "^((?<grandfathered>(en-GB-oed|i-ami|i-bnn|i-default|i-enochian|i-hak|i-klingon|i-lux|i-mingo|i-navajo|i-pwn|i-tao|i-tay|i-tsu|sgn-BE-FR|sgn-BE-NL|sgn-CH-DE)|(art-lojban|cel-gaulish|no-bok|no-nyn|zh-guoyu|zh-hakka|zh-min|zh-min-nan|zh-xiang))|((?<language>([A-Za-z]{2,3}(-(?<extlang>[A-Za-z]{3}(-[A-Za-z]{3}){0,2}))?)|[A-Za-z]{4}|[A-Za-z]{5,8})(-(?<script>[A-Za-z]{4}))?(-(?<region>[A-Za-z]{2}|[0-9]{3}))?(-(?<variant>[A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(-(?<extension>[0-9A-WY-Za-wy-z](-[A-Za-z0-9]{2,8})+))*(-(?<privateUse>x(-[A-Za-z0-9]{1,8})+))?)|(?<privateUse2>x(-[A-Za-z0-9]{1,8})+))$".
+         */
+        [k: string]: string;
+    };
+    sortAs?: string;
+    code?: string;
+    scheme?: string;
+    links?: ReadiumLink[];
+    [k: string]: unknown;
+}
+declare type Subject = string | (string | SubjectObject)[] | SubjectObject;
+
+interface Metadata extends Contributors, EPUBExtensionMetadata {
+    identifier?: string;
+    '@type'?: string;
+    conformsTo?: ConformsTo;
+    title: LanguageMap;
+    subtitle?: LanguageMap;
+    modified?: string;
+    published?: {
+        [k: string]: unknown;
+    } & string;
+    /**
+     * The language must be a valid BCP 47 tag.
+     */
+    language?: string | string[];
+    sortAs?: LanguageMap;
+    subject?: Subject;
+    readingProgression?: 'rtl' | 'ltr' | 'ttb' | 'btt' | 'auto';
+    description?: string;
+    duration?: number;
+    numberOfPages?: number;
+    belongsTo?: {
+        collection?: Contributor;
+        series?: Contributor;
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+interface Contributors {
+    author?: Contributor;
+    translator?: Contributor;
+    editor?: Contributor;
+    artist?: Contributor;
+    illustrator?: Contributor;
+    letterer?: Contributor;
+    penciler?: Contributor;
+    colorist?: Contributor;
+    inker?: Contributor;
+    narrator?: Contributor;
+    contributor?: Contributor;
+    publisher?: Contributor;
+    imprint?: Contributor;
+}
+
+/**
+ * Type definitions for a manifest
+ */
+
+interface WebpubManifest {
+    '@context'?: typeof ReadiumWebpubContext;
+    metadata: Metadata;
+    links: ReadiumLink[];
+    readingOrder: ReadiumLink[];
+    resources?: ReadiumLink[];
+    toc?: ReadiumLink[];
+}
+
+declare type ColorMode = 'night' | 'sepia' | 'day';
+declare type FontFamily = 'publisher' | 'serif' | 'sans-serif' | 'open-dyslexic';
+declare type Navigator = {
+    goForward: () => void;
+    goBackward: () => void;
+    setScroll: (val: 'scrolling' | 'paginated') => Promise<void>;
+    goToPage: (href: string) => void;
+};
+declare type PdfNavigator = Navigator & {
+    zoomIn: () => Promise<void>;
+    zoomOut: () => Promise<void>;
+};
+declare type HtmlNavigator = Navigator & {
+    increaseFontSize: () => Promise<void>;
+    decreaseFontSize: () => Promise<void>;
+    resetSettings: () => Promise<void>;
+    setFontFamily: (family: FontFamily) => Promise<void>;
+    setColorMode: (mode: ColorMode) => Promise<void>;
+};
+declare type ReaderSettings = {
+    colorMode: ColorMode;
+    isScrolling: boolean;
+    fontSize: number;
+    fontFamily: FontFamily;
+};
+/**
+ * This is the "public" state of the reader that
+ * is returned to consumers of useWebReader. Each
+ * reader (pdf/html) has its own internal state with
+ * more details necessary for rendering
+ */
+declare type ReaderState = {
+    atStart: boolean;
+    atEnd: boolean;
+    location?: Locator;
+    settings: ReaderSettings | undefined;
+};
+declare type InactiveReader = null;
+declare type LoadingReader = {
+    isLoading: true;
+    content: JSX.Element;
+    navigator: null;
+    state: null;
+    manifest: null;
+    type: null;
+};
+declare type CommonReader = {
+    isLoading: false;
+    content: JSX.Element;
+    manifest: WebpubManifest;
+};
+declare type PDFActiveReader = CommonReader & {
+    state: ReaderState;
+    navigator: PdfNavigator;
+    type: 'PDF';
+};
+declare type HTMLActiveReader = CommonReader & {
+    state: ReaderState;
+    navigator: HtmlNavigator;
+    type: 'HTML';
+};
+declare type ActiveReader = PDFActiveReader | HTMLActiveReader;
+declare type ReaderReturn = InactiveReader | LoadingReader | ActiveReader;
+declare type GetContent = (href: string) => Promise<string>;
+declare type ReaderManagerArguments = {
+    headerLeft?: JSX.Element;
+};
+declare type UseWebReaderArguments = {
+    webpubManifestUrl: string;
+    proxyUrl?: string;
+    getContent?: GetContent;
+    pdfWorkerSrc?: string;
+    injectablesReflowable?: Injectable[];
+    injectablesFixed?: Injectable[];
+    /**
+     * CSS string to set the height of the reader in paginated mode, and also
+     * in scrolling mode if `growWhenScrolling` is `false`.
+     *
+     * eg: "800px" or `calc(100vh-${CHROME_HEIGHT})`
+     *
+     * Default: `calc(100vh-${CHROME_HEIGHT})`
+     */
+    height?: string;
+    /**
+     * Tells the renderer if it should grow to fit content in scrolling mode, or if should
+     * remain the same height and instead show an internal scroll bar. Set to `true` by
+     * default, as this should be used in a full-page reader, the most common use case.
+     *
+     * Default: `true`
+     */
+    growWhenScrolling?: boolean;
+    /**
+     * Initial user settings for the reader
+     */
+    readerSettings?: Partial<ReaderSettings>;
+    /**
+     * If enabled, reading location will be persisted to local storage and recalled from
+     * there upon initial load.
+     *
+     * Default: `true`
+     */
+    persistLastLocation?: boolean;
+    /**
+     * If enabled, reader settings will be persisted to local storage and recalled
+     * from there upon initial load.
+     *
+     * Default: `true`
+     */
+    persistSettings?: boolean;
+};
+declare type ActiveReaderArguments = UseWebReaderArguments & {
+    manifest: WebpubManifest;
+};
+declare type InactiveReaderArguments = undefined;
+declare type ReaderArguments = ActiveReaderArguments | InactiveReaderArguments;
+
+/**
+ * The React hook that exposes the main API into the reader. It
+ * will determine the type of the webpub, and then use the correct reader
+ * for that type.
+ */
+declare function useWebReader(args: UseWebReaderArguments): HTMLActiveReader | PDFActiveReader | LoadingReader;
+
+declare function useHtmlReader(args: ReaderArguments): ReaderReturn;
+
+/**
+ * The PDF reader
+ *
+ * The PDF reader loads resources in two stages:  First, it fetches the PDF resource as an Uint8Array
+ * Then, it passes this array into the <Document> object, which loads the PDF inside an iframe
+ *
+ * @param args T
+ * @returns
+ */
+declare function usePdfReader(args: ReaderArguments): ReaderReturn;
+
+declare type Dict<T = any> = Record<string, T>;
+
+/**
+ * See Chakra default theme for shape of theme object:
+ * https://github.com/chakra-ui/chakra-ui/tree/main/packages/theme
+ *
+ * Making this a function because we need to adjust the theme based
+ * on the colorMode that's being passed in.
+ *
+ * Returns the chakra theme object with an additional property `currentColorMode`
+ */
+declare function getTheme(colorMode?: ColorMode): Dict<unknown>;
+
+declare const useColorModeValue: (light: string, dark: string, sepia: string) => string;
+
+declare function clearWebReaderLocalStorage(): void;
+
+/**
+ * Adds TOC data to Webpub Manifest from single-resource PDF using PDF.js
+ * @param manifest
+ * @param getResource - a function to get the resource. This allows the caller
+ * to decide how to get the resource, for example through a proxy if necessary.
+ * @param pdfWorkerSrc - the path to the pdfjs worker file. Necessary to use pdfjs.
+ * @returns {WebpubManifest} manifest object
+ */
+declare function addTocToManifest(manifest: WebpubManifest, getResource: (url: string) => Promise<Uint8Array>, pdfWorkerSrc: string): Promise<WebpubManifest>;
+
+/**
+ * The main React component export.
+ */
+declare type WebReaderProps = UseWebReaderArguments & ReaderManagerArguments;
+declare const WebReaderWithoutBoundary: FC<WebReaderProps>;
+declare const WebReader: FC<WebReaderProps>;
+
+export { CHROME_HEIGHT, DEFAULT_HEIGHT, DEFAULT_SETTINGS, DEFAULT_SHOULD_GROW_WHEN_SCROLLING, FONT_DETAILS, FOOTER_HEIGHT, HEADER_HEIGHT, IS_DEV, LOCAL_STORAGE_LOCATIONS_KEY, LOCAL_STORAGE_SETTINGS_KEY, ReadiumWebpubContext, WebReaderProps, WebReaderWithoutBoundary, addTocToManifest, clearWebReaderLocalStorage, WebReader as default, getTheme, useColorModeValue, useHtmlReader, usePdfReader, useWebReader };