@libraz/mejiro-react 0.9.1 → 0.9.2

package/README.md

@@ -64,7 +64,9 @@ one-liner that rewrites them to the matching published release — run it before
 
 ## Documentation
 
-- [React / Vue guide](https://github.com/libraz/mejiro/tree/main/docs/en/08-react-and-vue.md) — components, hooks, props, theming, SSR
+- [React / Vue guide](https://github.com/libraz/mejiro/tree/main/docs/en/08-react-and-vue.md) — components, hooks, props, theming
+- [API reference](https://github.com/libraz/mejiro/tree/main/docs/en/10-api-reference.md#librazmejiro-react--react-component) — every component prop and hook
+- [SSR first paint](https://github.com/libraz/mejiro/tree/main/docs/en/09-advanced.md#722-first-paint-under-ssr) — a `renderEpubStatic` fallback until the reader hydrates
 - [Project README](https://github.com/libraz/mejiro)
 - 日本語ドキュメント: [docs/ja/08-react-and-vue.md](https://github.com/libraz/mejiro/tree/main/docs/ja/08-react-and-vue.md)
 

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import * as react from 'react';
 import { ReactNode, CSSProperties, PointerEvent, TextareaHTMLAttributes, MutableRefObject, RefObject } from 'react';
 import { EpubBook, AssetResolver, EpubParseLimits, EditableEpub, ManuscriptDialect, EpubChapter, EditableEpubBook, EditableEpubSelection, AnnotatedParagraph, AddImageInput, EditableEpubImage, EpubExportOptions, EpubProjectMetadata, EpubProjectAsset, EpubProject } from '@libraz/mejiro/epub';
 export { EditableEpubSelection } from '@libraz/mejiro/epub';
-import { ChapterLayout, SpreadResult, BookOptions, ComputePageSizeOptions, InChapterAnchor, ReadingAnchor, ManuscriptChapter, PageResult, AnchorRect, AnchorRange, MejiroBook } from '@libraz/mejiro/book';
+import { ChapterLayout, SpreadResult, BookOptions, MejiroBookOptions, ComputePageSizeOptions, InChapterAnchor, ReadingAnchor, ManuscriptChapter, PageResult, AnchorRect, AnchorRange, MejiroBook } from '@libraz/mejiro/book';
 import { RenderPage } from '@libraz/mejiro/render';
 import { FontFamily, InlineAnnotation } from '@libraz/mejiro/browser';
 
@@ -360,18 +360,20 @@ interface MejiroReaderHandle {
     next(): void;
     /** Go back one spread. */
     prev(): void;
-    /** Jump to a chapter (resets spread index to 0). */
+    /** Jump to a chapter (clamped to the book's chapters; resets spread index to 0). */
     goToChapter(index: number): void;
     /** Read the current reading position. */
     getReadingPosition(): ReadingPosition;
     /**
      * Navigate to a {@link ReadingAnchor}. If the chapter differs from the
      * current one, the chapter is switched first; once the new layout is ready
-     * the anchor is resolved and the matching spread is opened.
+     * the anchor is resolved and the matching spread is opened. A call made
+     * before the book has loaded is applied once it has.
      *
-     * Returns a promise that resolves once the spread has been applied. If
-     * another `goToAnchor` is invoked before the previous one settles, the
-     * earlier promise resolves immediately (superseded). Resolves on unmount.
+     * Returns a promise that resolves once the spread has been applied, or
+     * without moving when the anchor's chapter or position does not exist in the
+     * book. If another `goToAnchor` is invoked before the previous one settles,
+     * the earlier promise resolves immediately (superseded). Resolves on unmount.
      */
     goToAnchor(anchor: ReadingAnchor): Promise<void>;
     /**
@@ -434,8 +436,10 @@ interface MejiroReaderCommonProps {
      * ```ts
      * { ...DEFAULT_BOOK_OPTIONS, fontFamily: '"Noto Serif JP"', fontSize: 18 }
      * ```
+     *
+     * `strictFontCheck` is read once, when the reader mounts.
      */
-    options?: Partial<BookOptions>;
+    options?: Partial<MejiroBookOptions>;
     /**
      * Page-geometry overrides forwarded to `MejiroBook.computePageSize`. Use to
      * tune how the spread is sized inside the surface — most usefully to shrink
@@ -1350,6 +1354,12 @@ interface UseChapterLayoutOptions {
      * first. Without it, consume `pendingRestore` yourself.
      */
     restorePosition?: (layout: ChapterLayout, position: InChapterAnchor) => void;
+    /**
+     * Called once when a layout of the current source fails, whichever path
+     * started it (source change, resize or `recompute`); a superseded layout
+     * reports nothing. When supplied, `recompute` resolves instead of rejecting.
+     */
+    onError?: (error: Error) => void;
 }
 /** Options for {@link UseChapterLayoutReturn.recompute}. */
 interface RecomputeOptions {
@@ -1382,7 +1392,10 @@ interface UseChapterLayoutReturn {
     contentHeight: number;
     /** Most recent layout time (ms). */
     elapsedMs: number;
-    /** Force a fresh layout computation. */
+    /**
+     * Force a fresh layout computation. A failure goes to `onError` when one is
+     * supplied; otherwise the returned promise rejects.
+     */
     recompute: (opts?: RecomputeOptions) => Promise<void>;
     /**
      * Anchor captured by `capturePosition` before the most recent reflow,
@@ -1612,7 +1625,10 @@ interface UseEpubProjectReturn {
     previewError: Error | null;
     /** Whether a preview build is pending or running. */
     previewing: boolean;
-    /** Merges `patch` into the metadata. */
+    /**
+     * Merges `patch` into the metadata. A missing or blank `identifier` keeps the
+     * current one.
+     */
     setMetadata: (patch: Partial<EpubProjectMetadata>) => void;
     /** Replaces every chapter; an empty list becomes one generated chapter. */
     setChapters: (chapters: EpubProjectChapterDraft[]) => void;
@@ -1729,6 +1745,12 @@ interface UseManuscriptLayoutOptions {
      * first. Without it, consume `pendingRestore` yourself.
      */
     restorePosition?: (layout: ChapterLayout, position: InChapterAnchor) => void;
+    /**
+     * Called once when a layout of the current source fails, whichever path
+     * started it (source change, resize or `recompute`); a superseded layout
+     * reports nothing. When supplied, `recompute` resolves instead of rejecting.
+     */
+    onError?: (error: Error) => void;
 }
 /** Options for {@link UseManuscriptLayoutReturn.recompute}. */
 interface ManuscriptRecomputeOptions {
@@ -1761,7 +1783,10 @@ interface UseManuscriptLayoutReturn {
     contentHeight: number;
     /** Most recent layout time (ms). */
     elapsedMs: number;
-    /** Force a fresh layout computation. */
+    /**
+     * Force a fresh layout computation. A failure goes to `onError` when one is
+     * supplied; otherwise the returned promise rejects.
+     */
     recompute: (opts?: ManuscriptRecomputeOptions) => Promise<void>;
     /**
      * Anchor captured by `capturePosition` before the most recent reflow,
@@ -1817,7 +1842,10 @@ interface UseMejiroBookOptions {
 interface UseMejiroBookReturn {
     /** The managed {@link MejiroBook} instance. Stable across renders. */
     book: MejiroBook;
-    /** Reactive snapshot of the current options. */
+    /**
+     * Reactive snapshot of the current options. Once the latest application
+     * settles it holds what the book applied, so a rejected change rolls back.
+     */
     options: Readonly<BookOptions>;
     /**
      * Update options on the underlying book and the snapshot. The snapshot is
@@ -1836,7 +1864,7 @@ interface UseMejiroBookReturn {
  * @param initial - Initial book options (passed to the {@link MejiroBook} constructor).
  * @param options - Behavior overrides (debouncing, error reporting).
  */
-declare function useMejiroBook(initial: BookOptions, options?: UseMejiroBookOptions): UseMejiroBookReturn;
+declare function useMejiroBook(initial: MejiroBookOptions, options?: UseMejiroBookOptions): UseMejiroBookReturn;
 
 /** Minimal storage interface required by {@link useReadingPosition}. */
 type ReadingPositionStorage = MejiroStorage;