zreader 0.0.0-stage → 0.2.0

package/dist/react/index.d.ts

@@ -0,0 +1,392 @@
+import * as react from 'react';
+import { ComponentType, AnchorHTMLAttributes, ReactNode } from 'react';
+import { BookMeta, ReaderClientOptions, StorageAdapter, ReaderStore, Bookmark, Highlight, PadScope, Pad, BookProgress, ReaderSettings, ChapterMeta, TocEntry, ResolvedHighlight, TextSpan, TextIndex, PadScopeKind, FontFamily, Leading, Measure, HighlightColor, TextSize } from 'zreader';
+export { BookMeta, BookProgress, Bookmark, ChapterMeta, ChapterProgress, Highlight, HighlightColor, Pad, PadScope, ReaderClientOptions, ReaderSettings, ThemeName, TocEntry } from 'zreader';
+
+/** Any router link with an `href` (e.g. next/link). */
+type LinkComponent = ComponentType<AnchorHTMLAttributes<HTMLAnchorElement> & {
+    href: string;
+    children?: ReactNode;
+}>;
+declare const DefaultLink: react.ForwardRefExoticComponent<AnchorHTMLAttributes<HTMLAnchorElement> & {
+    href: string;
+} & react.RefAttributes<HTMLAnchorElement>>;
+/** `${basePath}/${bookId}/${chapterId}#${hash}` */
+declare function defaultHref(basePath: string, bookId: string, chapterId?: string, hash?: string): string;
+
+type DeepPartial<T> = T extends unknown[] ? T : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/** Deep merge for client options (arrays replace). Kept here so zod stays out of the client bundle. */
+declare function mergeOptions<T>(base: T, ...overrides: unknown[]): T;
+/** Builds a link into the reader. `chapterId` omitted = the book's contents page. */
+type HrefFor = (bookId: string, chapterId?: string, hash?: string) => string;
+/** What the reader shows in the middle of its top bar. */
+type HeaderSlot = ReactNode | ((ctx: {
+    book: BookMeta;
+    chapter: {
+        id: string;
+        title: string;
+    };
+}) => ReactNode);
+interface Library {
+    /** Every book known to the provider (from `books`). */
+    books: BookMeta[];
+    getBook(id: string): BookMeta | undefined;
+    Link: LinkComponent;
+    href: HrefFor;
+    headerSlot?: HeaderSlot;
+    readerActions?: ReactNode;
+}
+interface ReaderContextValue {
+    store: ReaderStore;
+    options: ReaderClientOptions;
+    library: Library;
+}
+interface ReaderProviderProps {
+    /** Usually `config.reader` from reader.config.ts (see <ReaderRoot>). */
+    options?: DeepPartial<ReaderClientOptions>;
+    /** Inline overrides, merged on top of `options`. */
+    overrides?: DeepPartial<ReaderClientOptions>;
+    adapter?: StorageAdapter;
+    /** Provide your own store (advanced; e.g. tests). */
+    store?: ReaderStore;
+    onStorageError?: (error: unknown) => void;
+    /**
+     * Manage the colour theme with next-themes (class on <html>, no-flash script).
+     * Set to `false` if your app already renders a next-themes <ThemeProvider>.
+     */
+    manageTheme?: boolean;
+    /** Render a sonner <Toaster>. Set to `false` if your app already has one. */
+    toaster?: boolean;
+    /**
+     * The catalogue: lets <BookShelf />, <BookHome book="id" /> and
+     * <Reader book="id" chapter="id" /> work from ids alone.
+     */
+    books?: BookMeta[];
+    /** Router link used by every component (e.g. next/link). Defaults to <a>. */
+    Link?: LinkComponent;
+    /** URL builder. Defaults to `${basePath}/${bookId}/${chapterId}#hash`. */
+    hrefFor?: HrefFor;
+    /**
+     * Default content for the middle of the reader's top bar: text, your logo,
+     * or any component. Omit to show the book and chapter titles.
+     */
+    headerSlot?: HeaderSlot;
+    /**
+     * Default buttons for the right of the reader's top bar (before the bookmark
+     * toggle), e.g. `<CopyReference markdown />`. A <Reader>'s `actions` replaces
+     * them; `actions={null}` hides them for that chapter.
+     */
+    readerActions?: ReactNode;
+    children: ReactNode;
+}
+declare function ReaderProvider({ options, overrides, adapter, store: external, onStorageError, manageTheme, toaster, books, Link, hrefFor, headerSlot, readerActions, children, }: ReaderProviderProps): react.JSX.Element;
+declare function useReader(): ReaderContextValue;
+/** The provider's catalogue, link component and URL builder. */
+declare function useLibrary(): Library;
+/**
+ * Resolve a book given as an id (looked up in the provider's `books`) or as
+ * metadata. Throws a descriptive error when an id is unknown.
+ */
+declare function useBook(book: BookMeta | string): BookMeta;
+declare function useReaderStore(): ReaderStore;
+/** `false` during SSR and hydration, `true` afterwards. */
+declare function useHydrated(): boolean;
+declare function useSettings(): [ReaderSettings, ReaderStore["updateSettings"]];
+declare function useHighlights(bookId: string, chapterId?: string): Highlight[];
+declare function useBookmarks(bookId: string): Bookmark[];
+declare function useProgress(bookId: string): BookProgress;
+declare function usePad(scope: PadScope): Pad;
+declare function useMediaQuery(query: string, serverValue?: boolean): boolean;
+/** Desktop layout breakpoint (Tailwind `lg`). Mobile-first: `false` on the server. */
+declare function useIsDesktop(): boolean;
+
+interface ReaderProps {
+    /** A book id from the provider's catalogue, or the book's metadata. */
+    book: BookMeta | string;
+    /** A chapter id of that book, or the chapter's metadata. */
+    chapter: ChapterMeta | string;
+    /** Defaults to the neighbouring chapters in the book. Pass `null` to hide. */
+    prev?: ChapterMeta | null;
+    next?: ChapterMeta | null;
+    /** Contents of this chapter. Defaults to the h2/h3 headings found in the rendered content. */
+    toc?: TocEntry[];
+    contentHash?: string;
+    /** Sanitized chapter HTML (from `renderChapter()` / `renderHtml()` on the server). */
+    html?: string;
+    /** Or render the chapter yourself (e.g. an MDX component). */
+    children?: ReactNode;
+    /** Router link, e.g. `next/link`. Defaults to the provider's. */
+    Link?: LinkComponent;
+    /** Override URL building. Defaults to the provider's. */
+    hrefFor?: HrefFor;
+    /**
+     * Middle of the top bar: a string (shown as text), any element (your logo,
+     * a description…), or a function of `{ book, chapter }`. Defaults to the
+     * provider's `headerSlot`, then to <ReaderTitle />. Combine freely, e.g.
+     * `<><Logo /><ReaderTitle /></>`.
+     */
+    header?: HeaderSlot;
+    /**
+     * Buttons for the right side of the top bar, before the bookmark toggle,
+     * e.g. `<CopyReference />` from `zreader/agent/react`. Defaults to the
+     * provider's `readerActions`; `null` hides them.
+     */
+    actions?: ReactNode;
+    /** Where the back button goes. Defaults to the book page. */
+    backHref?: string;
+    className?: string;
+}
+interface ReaderChapterValue {
+    book: BookMeta;
+    chapter: ChapterMeta;
+    /** Page URL within this book (the reader's `hrefFor`): `href()` is the book, `href(chapterId)` a chapter. */
+    href: (chapterId?: string, hash?: string) => string;
+}
+/** The book and chapter of the surrounding <Reader> (for custom header content and actions). */
+declare function useReaderChapter(): ReaderChapterValue;
+/** The default header content: book title over chapter title. */
+declare function ReaderTitle({ className }: {
+    className?: string;
+}): react.JSX.Element;
+declare function Reader({ book: bookArg, chapter: chapterArg, prev: prevArg, next: nextArg, toc: tocProp, contentHash, html, children, Link: LinkProp, hrefFor, header, actions, backHref, className, }: ReaderProps): react.JSX.Element;
+
+interface BookNavProps {
+    /** A book id from the provider's catalogue, or the book's metadata. */
+    book: BookMeta | string;
+    /** Overrides the provider's link component. */
+    Link?: LinkComponent;
+    /** Overrides the provider's URL builder. */
+    hrefFor?: HrefFor;
+    className?: string;
+}
+/** "Start reading" / "Continue: Chapter 3 · 42%" card for a book page. */
+declare function ContinueReading({ book: bookArg, Link: LinkProp, hrefFor, className }: BookNavProps): react.JSX.Element | null;
+/** Chapter list with read state, grouped by `part` when chapters declare one. */
+declare function ChapterList({ book: bookArg, Link: LinkProp, hrefFor, className }: BookNavProps): react.JSX.Element;
+interface BookShelfProps {
+    /** Defaults to the provider's catalogue (<ReaderProvider books>). */
+    books?: BookMeta[];
+    Link?: LinkComponent;
+    hrefFor?: HrefFor;
+    title?: string;
+    description?: string;
+    /**
+     * Render only the grid, without the full-page shell (background, padding,
+     * title), for embedding inside a host site's own page layout.
+     */
+    embedded?: boolean;
+    className?: string;
+}
+/** Grid of book cards linking to each book's home. */
+declare function BookShelf({ books: booksProp, Link: LinkProp, hrefFor, title, description, embedded, className }: BookShelfProps): react.JSX.Element;
+interface BookHomeProps extends BookNavProps {
+    /** Back link (e.g. to the shelf). */
+    backHref?: string;
+    backLabel?: string;
+    /**
+     * Render only the continue card and chapter list, without the full-page shell
+     * or title block, for embedding inside a host site's own page layout.
+     */
+    embedded?: boolean;
+}
+/** A book's contents page: title, authors, continue card and chapter list. */
+declare function BookHome({ book: bookArg, Link: LinkProp, hrefFor, backHref, backLabel, embedded, className }: BookHomeProps): react.JSX.Element;
+/** Alias of <BookHome>: a book's contents page. */
+declare const BookContents: typeof BookHome;
+type BookContentsProps = BookHomeProps;
+
+type ContentsTab = "contents" | "highlights" | "bookmarks";
+interface ContentsSheetProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    tab: ContentsTab;
+    onTabChange: (tab: ContentsTab) => void;
+    book: BookMeta;
+    chapterId: string;
+    toc: TocEntry[];
+    hrefFor: (chapterId: string, hash?: string) => string;
+    Link: LinkComponent;
+    orphanedIds: ReadonlySet<string>;
+    onJumpHighlight: (id: string) => void;
+    onJumpBlock: (blockId: string) => void;
+    onJumpHeading: (id: string) => void;
+}
+declare function ContentsSheet(p: ContentsSheetProps): react.JSX.Element;
+
+interface HighlightPanelProps {
+    highlight: Highlight | null;
+    colors: string[];
+    focusNote?: boolean;
+    onColor: (color: string) => void;
+    onNote: (note: string) => void;
+    onDelete: () => void;
+    onQuote?: () => void;
+    onCopy?: () => void;
+    onClose: () => void;
+}
+declare function HighlightPanel({ highlight, colors, focusNote, onColor, onNote, onDelete, onQuote, onCopy, onClose }: HighlightPanelProps): react.JSX.Element;
+
+interface SelectionRect {
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+    width: number;
+    height: number;
+}
+interface SelectionState {
+    span: TextSpan;
+    text: string;
+    rect: SelectionRect;
+}
+interface ResumeState {
+    blockId: string;
+    percent: number;
+}
+interface ChapterEngineOptions {
+    bookId: string;
+    chapterId: string;
+    contentHash?: string;
+    /** The chapter root element (pass callback-ref state so remounts re-bind). */
+    root: HTMLElement | null;
+    /** Scrolling element. `null` = the window (mobile layout). */
+    scroller?: HTMLElement | null;
+    /** px reserved at the top of the scroll viewport (sticky header). */
+    topOffset?: number;
+    onHighlightTap?: (id: string) => void;
+}
+/** Tiny external store so only <ReadingProgress> re-renders while scrolling. */
+declare function createValueStore(initial: number): {
+    get: () => number;
+    set(v: number): void;
+    subscribe(l: () => void): () => boolean;
+};
+type ValueStore = ReturnType<typeof createValueStore>;
+declare function useValueStore(store: ValueStore): number;
+declare function useChapterEngine(opts: ChapterEngineOptions): {
+    highlights: Highlight[];
+    resolved: ResolvedHighlight[];
+    orphaned: Highlight[];
+    selection: SelectionState | null;
+    activeId: string | null;
+    setActiveId: react.Dispatch<react.SetStateAction<string | null>>;
+    resume: ResumeState | null;
+    dismissResume: () => void;
+    percentStore: {
+        get: () => number;
+        set(v: number): void;
+        subscribe(l: () => void): () => boolean;
+    };
+    domToc: TocEntry[];
+    clearSelection: () => void;
+    selectSpan: (span: TextSpan) => void;
+    expandSelectionToSentences: (span?: TextSpan) => void;
+    createHighlight: (span: TextSpan, color?: string, note?: string) => Highlight | null;
+    scrollToHighlight: (id: string, smooth?: boolean) => boolean;
+    scrollToBlock: (blockId: string, smooth?: boolean) => boolean;
+    scrollToHeading: (id: string, smooth?: boolean) => boolean;
+    scrollToTop: () => void;
+    getTopBlock: () => Element | null;
+    getIndex: () => TextIndex | null;
+};
+type ChapterEngine = ReturnType<typeof useChapterEngine>;
+
+interface SelectionToolbarProps {
+    selection: SelectionState | null;
+    colors: string[];
+    onHighlight: (span: TextSpan, color: string) => void;
+    onNote: (span: TextSpan) => void;
+    onSentence: (span: TextSpan) => void;
+    onQuote?: (span: TextSpan, text: string) => void;
+    onCopy?: (text: string) => void;
+    onDismiss: () => void;
+}
+/**
+ * Actions for the current text selection. Desktop: a Popover anchored to the
+ * selection (virtual anchor). Mobile: docked above the safe area, out of the
+ * way of the native selection callout.
+ */
+declare function SelectionToolbar({ selection, colors, onHighlight, onNote, onSentence, onQuote, onCopy, onDismiss }: SelectionToolbarProps): react.JSX.Element | null;
+
+interface SettingsPanelProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    book?: BookMeta;
+}
+declare function SettingsPanel({ open, onOpenChange, book }: SettingsPanelProps): react.JSX.Element;
+
+declare function scopeFor(kind: PadScopeKind, bookId: string, chapterId: string): PadScope;
+declare function scopeKey(scope: PadScope): string;
+interface ScratchpadPanelProps {
+    bookId: string;
+    chapterId: string;
+    kind: PadScopeKind;
+    onKindChange: (kind: PadScopeKind) => void;
+    onClose?: () => void;
+    onEditorFocus?: () => void;
+    /** Filename stem for exports. */
+    title?: string;
+}
+declare function ScratchpadPanel({ bookId, chapterId, kind, onKindChange, onClose, onEditorFocus, title }: ScratchpadPanelProps): react.JSX.Element;
+
+interface ResponsivePanelProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    title: ReactNode;
+    description?: ReactNode;
+    /** Desktop surface. Mobile is always a bottom drawer. */
+    desktop?: "dialog" | "sheet-left" | "sheet-right";
+    /** Hide the header visually (still announced to assistive tech). */
+    hideHeader?: boolean;
+    footer?: ReactNode;
+    className?: string;
+    children: ReactNode;
+}
+/**
+ * shadcn "responsive dialog" pattern: a vaul Drawer on mobile, a Dialog or
+ * Sheet on desktop. Mobile-first: renders the Drawer during SSR.
+ */
+declare function ResponsivePanel({ open, onOpenChange, title, description, desktop, hideHeader, footer, className, children, }: ResponsivePanelProps): react.JSX.Element;
+
+interface PartGroup {
+    part: string | null;
+    items: Array<{
+        chapter: ChapterMeta;
+        index: number;
+    }>;
+}
+/** Consecutive chapters sharing a `part` are grouped; books without parts yield one group. */
+declare function groupByPart(chapters: ChapterMeta[]): PartGroup[];
+/** Short list marker: frontmatter `number`, else the 1-based position. */
+declare function chapterMarker(chapter: ChapterMeta, index: number): string;
+
+/** Trigger a client-side file download. */
+declare function downloadFile(filename: string, content: string, type?: string): void;
+declare function copyText(text: string): Promise<boolean>;
+
+interface CalloutProps {
+    title?: string;
+    children?: ReactNode;
+}
+/** `<Callout title="…">…</Callout>` for MDX chapters. Ignored by highlighting. */
+declare function Callout({ title, children }: CalloutProps): react.JSX.Element;
+
+/**
+ * Settings → literal Tailwind classes. Keeping every class as a full string
+ * literal lets Tailwind see them at build time; nothing is styled inline.
+ */
+declare const TEXT_SIZE_CLASS: Record<TextSize, string>;
+declare const LEADING_CLASS: Record<Leading, string>;
+declare const MEASURE_CLASS: Record<Measure, string>;
+declare const FONT_CLASS: Record<FontFamily, string>;
+declare const SWATCH_CLASS: Record<HighlightColor, string>;
+declare const QUOTE_BORDER_CLASS: Record<HighlightColor, string>;
+declare function swatchClass(color: string): string;
+declare function quoteBorderClass(color: string): string;
+/** Shared typography for chapter content: shadcn tokens via typography modifiers. */
+declare const PROSE_CLASS = "prose max-w-none text-foreground prose-headings:text-foreground prose-headings:scroll-mt-20 prose-p:text-foreground prose-li:text-foreground prose-strong:text-foreground prose-a:text-primary prose-a:underline-offset-4 prose-blockquote:border-l-border prose-blockquote:text-muted-foreground prose-code:text-foreground prose-pre:bg-muted prose-pre:text-foreground prose-hr:border-border prose-th:text-foreground prose-td:text-foreground prose-figcaption:text-muted-foreground prose-img:rounded-lg prose-table:block prose-table:max-w-full prose-table:overflow-x-auto prose-th:align-bottom prose-td:align-top";
+
+export { BookContents, BookHome, BookShelf, Callout, ChapterList, ContentsSheet, ContinueReading, DefaultLink, FONT_CLASS, HighlightPanel, LEADING_CLASS, MEASURE_CLASS, PROSE_CLASS, QUOTE_BORDER_CLASS, Reader, ReaderProvider, ReaderTitle, ResponsivePanel, SWATCH_CLASS, ScratchpadPanel, SelectionToolbar, SettingsPanel, TEXT_SIZE_CLASS, chapterMarker, copyText, defaultHref, downloadFile, groupByPart, mergeOptions, quoteBorderClass, scopeFor, scopeKey, swatchClass, useBook, useBookmarks, useChapterEngine, useHighlights, useHydrated, useIsDesktop, useLibrary, useMediaQuery, usePad, useProgress, useReader, useReaderChapter, useReaderStore, useSettings, useValueStore };
+export type { BookContentsProps, BookHomeProps, BookNavProps, BookShelfProps, CalloutProps, ChapterEngine, ChapterEngineOptions, ContentsSheetProps, ContentsTab, HeaderSlot, HighlightPanelProps, HrefFor, Library, LinkComponent, PartGroup, ReaderChapterValue, ReaderProps, ReaderProviderProps, ResponsivePanelProps, ScratchpadPanelProps, SelectionState, SelectionToolbarProps, SettingsPanelProps };