@libraz/mejiro-react 0.9.1 → 0.10.0

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,8 +4,9 @@ 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 { RenderPage } from '@libraz/mejiro/render';
+import { ChapterLayout, SpreadResult, BookOptions, MejiroBookOptions, ComputePageSizeOptions, InChapterAnchor, ReadingAnchor, ManuscriptChapter, PageResult, AnchorRect, AnchorRange, MejiroBook } from '@libraz/mejiro/book';
+import { PageNumberDisplay, RenderPage } from '@libraz/mejiro/render';
+export { PageNumberDisplay } from '@libraz/mejiro/render';
 import { FontFamily, InlineAnnotation } from '@libraz/mejiro/browser';
 
 /** Provider that scopes a message catalog to its descendants. */
@@ -16,7 +17,10 @@ declare function MejiroI18nProvider({ locale, messages, children, }: {
 }): ReactNode;
 /** Options for {@link useI18n}. */
 interface UseI18nOptions {
-    /** Built-in locale to use as the base catalog. @defaultValue 'en' */
+    /**
+     * Built-in locale to use as the base catalog. Defaults to the nearest
+     * `MejiroI18nProvider` locale, or `'en'` without one.
+     */
     locale?: MejiroLocale;
     /** Overrides merged on top of the built-in catalog. */
     messages?: Partial<MejiroMessages>;
@@ -107,7 +111,9 @@ interface MejiroEditorProps {
     /** Font choices passed to the preview reader. */
     fonts?: FontChoice[];
     /**
-     * Allow editing paragraph text (the "Proofread" section).
+     * Allow editing paragraph text (the "Proofread" section). When `false` and
+     * `enableRuby` is on, the paragraph text stays visible read-only so a ruby
+     * base range can still be selected.
      * @defaultValue true
      */
     enableProofread?: boolean;
@@ -158,8 +164,9 @@ interface MejiroEditorProps {
     /** Called after export completes. */
     onExport?: (buffer: ArrayBuffer) => void;
     /**
-     * Called when loading, image insertion or export fails. The error is also
-     * shown in the editor.
+     * Called when loading, image insertion, export or the preview reader fails.
+     * The error is also shown in the editor until a later load, image insertion
+     * or export succeeds.
      */
     onError?: (error: Error) => void;
 }
@@ -290,11 +297,7 @@ type MejiroReaderMode = 'paginated' | 'scroll';
  *   converting the index so the page on screen stays visible.
  */
 type MejiroSpreadMode = 'double' | 'single' | 'auto';
-/**
- * Which page of a spread prints its page number: `'both'` (right = odd,
- * left = even), only `'right'`, only `'left'`, or `'none'`.
- */
-type PageNumberDisplay = 'both' | 'right' | 'left' | 'none';
+
 /**
  * How the reader sizes itself inside its container.
  * - `fill` — fill the container's given height; the spread is fitted inside it,
@@ -360,18 +363,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 +439,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
@@ -522,7 +529,8 @@ interface MejiroReaderCommonProps {
     fetchEpub?: (url: string) => Promise<ArrayBuffer>;
     /**
      * Built-in locale for UI strings (`'en'` / `'ja'`). Pair with `messages`
-     * to override individual strings. @defaultValue 'en'
+     * to override individual strings. Defaults to the nearest `MejiroI18nProvider`
+     * locale, or `'en'` without one.
      */
     locale?: MejiroLocale;
     /**
@@ -621,9 +629,11 @@ interface MejiroReaderCommonProps {
     /** Called when the spread index changes — pair with the `spreadIdx` prop for controlled use. */
     onSpreadIdxChange?: (spreadIdx: number) => void;
     /**
-     * Called when the reader leaves a spread. Receives the anchor of the
-     * spread that was just left and the dwell time in milliseconds (computed
-     * via `performance.now()`). Useful for engagement analytics.
+     * Called when the reader moves from one spread to another within the shown
+     * book (a change of chapter or spread index, like `spreadChanged`). Receives
+     * the anchor of the spread that was just left and the dwell time in
+     * milliseconds (computed via `performance.now()`). A book swap and unmount
+     * do not report the spread being left. Useful for engagement analytics.
      */
     onPageRead?: (anchor: ReadingAnchor, dwellMs: number) => void;
     /**
@@ -809,7 +819,7 @@ interface MejiroManuscriptEditorProps {
     onExport?: (buffer: ArrayBuffer) => void;
     /**
      * Called when the EPUB export fails (asset resolution, cover reading, or
-     * packaging). The same error is shown in the editor panel, so hosts only
+     * packaging) or the preview reader fails. The same error is shown in the editor panel, so hosts only
      * need this to log or report it.
      */
     onError?: (error: Error) => void;
@@ -1013,6 +1023,11 @@ interface MejiroScrollViewProps {
      * provides one on every change.
      */
     images?: MultiImageItem[];
+    /**
+     * Which pages print their page number in the running head, by the same rule
+     * as the paginated reader. @defaultValue 'both'
+     */
+    pageNumbers?: PageNumberDisplay;
     /** Pointer-down on an image overlay. */
     onImagePointerDown?: (id: string, e: PointerEvent) => void;
     /** Pointer-down on an image resize handle. */
@@ -1026,7 +1041,7 @@ interface MejiroScrollViewProps {
  * detected via `IntersectionObserver` and reported through
  * {@link MejiroScrollViewProps.onVisiblePageChange}.
  */
-declare function MejiroScrollView({ layout, pageWidth, pageHeight, contentHeight, fontFamily, fontSize, lineSpacing, slotMode, onVisiblePageChange, scrollToPage, pageGap, selectionRects, spreadIdx, images, onImagePointerDown, onImageResizePointerDown, onImageClose, }: MejiroScrollViewProps): ReactNode;
+declare function MejiroScrollView({ layout, pageWidth, pageHeight, contentHeight, fontFamily, fontSize, lineSpacing, slotMode, onVisiblePageChange, scrollToPage, pageGap, selectionRects, spreadIdx, images, pageNumbers, onImagePointerDown, onImageResizePointerDown, onImageClose, }: MejiroScrollViewProps): ReactNode;
 
 /** Props for {@link MejiroSelectionLayer}. */
 interface MejiroSelectionLayerProps {
@@ -1281,7 +1296,9 @@ interface UseAnnotationsOptions {
      * every render is safe — only `key` triggers a re-hydration.
      */
     storage?: AnnotationsStorage;
-    /** Throttle ms between writes. @defaultValue 250 */
+    /**
+     * Debounce delay (ms): the latest value is written this long after the last change. A pending write is flushed on page hide, key change and unmount. @defaultValue 250
+     */
     throttleMs?: number;
     /**
      * Called immediately after each mutation (`add` / `remove` / `update` /
@@ -1350,6 +1367,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 +1405,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 +1638,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 +1758,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 +1796,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,
@@ -1779,7 +1817,8 @@ interface UseManuscriptLayoutReturn {
  * {@link useManuscriptDraft} for the chapter array and feed the resulting
  * {@link ChapterLayout} into {@link MejiroSpread} or {@link MejiroScrollView}.
  *
- * Re-layouts whenever `chapter`, `dialect`, or `book` change. The surface is
+ * Re-layouts whenever the chapter's id, title or body, `dialect`, or `book`
+ * change; a new chapter object with the same content does not. The surface is
  * observed with {@link ResizeObserver}; size changes trigger a full re-layout
  * so pagination stays correct after non-trivial container changes.
  *
@@ -1817,7 +1856,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 +1878,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;
@@ -1849,7 +1891,9 @@ interface UseReadingPositionOptions {
      * SSR consumers can omit this and the hook will fall back to in-memory.
      */
     storage?: ReadingPositionStorage;
-    /** Throttle ms between writes. @defaultValue 250 */
+    /**
+     * Debounce delay (ms): the latest value is written this long after the last change. A pending write is flushed on page hide, key change and unmount. @defaultValue 250
+     */
     throttleMs?: number;
     /**
      * Called immediately after `save()` (with the new anchor) or `clear()`
@@ -1862,14 +1906,14 @@ interface UseReadingPositionOptions {
 interface UseReadingPositionReturn {
     /** Most recently persisted position, or `null` if none. */
     position: ReadingPositionValue | null;
-    /** Persist a new position (throttled). */
+    /** Persist a new position (debounced by `throttleMs`). */
     save(next: ReadingPositionValue): void;
     /** Remove the persisted position. */
     clear(): void;
 }
 /**
  * Persistence helper for reader state. Returns the saved anchor and a
- * throttled saver. Pair with {@link MejiroReaderHandle.goToAnchor} and
+ * debounced saver. Pair with {@link MejiroReaderHandle.goToAnchor} and
  * {@link MejiroReaderHandle.subscribe} for exact reflow-safe restore.
  *
  * ```tsx
@@ -1958,4 +2002,5 @@ interface UseSpreadReturn {
  */
 declare function useSpread(layout: ChapterLayout | null, options?: UseSpreadOptions): UseSpreadReturn;
 
-export { type AnnotationsStorage, type EpubProjectChapterDraft, type ImageRect, type ManuscriptAutosaveDraft, type ManuscriptEditorChapter, type ManuscriptPageDimensions, type ManuscriptPreviewProps, type ManuscriptRecomputeOptions, MejiroChapterNav, type MejiroChapterNavMode, type MejiroChapterNavProps, type MejiroChapterNavVariant, MejiroDropZone, type MejiroDropZoneProps, MejiroEditor, type MejiroEditorProps, type MejiroExportPolicy, MejiroI18nProvider, MejiroImageOverlay, type MejiroImageOverlayProps, MejiroManuscriptEditor, type MejiroManuscriptEditorProps, MejiroNotationHighlighter, type MejiroNotationHighlighterProps, MejiroPage, MejiroPageIndicator, type MejiroPageIndicatorProps, type MejiroPageProps, MejiroPageView, type MejiroPageViewProps, MejiroReader, type MejiroReaderCommonProps, type MejiroReaderControlledProps, type MejiroReaderEventMap, type MejiroReaderFileProps, type MejiroReaderFit, type MejiroReaderHandle, type MejiroReaderManuscriptProps, type MejiroReaderMode, type MejiroReaderProps, type MejiroReaderSettingsSlot, type MejiroReaderUrlProps, MejiroScrollView, type MejiroScrollViewProps, MejiroSelectionLayer, type MejiroSelectionLayerProps, MejiroSettingsPanel, type MejiroSettingsPanelProps, MejiroShelf, type MejiroShelfProps, MejiroSpread, type MejiroSpreadMode, type MejiroSpreadProps, MejiroStats, type MejiroStatsProps, type MejiroTheme, type MejiroThemeName, MejiroToc, type MejiroTocProps, type MultiImageItem, type PageDimensions, type PageNumberDisplay, type ReadingPosition, type ReadingPositionStorage, type RecomputeOptions, type UseAnnotationsOptions, type UseAnnotationsReturn, type UseChapterLayoutOptions, type UseChapterLayoutReturn, type UseEditableEpubOptions, type UseEditableEpubReturn, type UseEpubOptions, type UseEpubProjectOptions, type UseEpubProjectReturn, type UseEpubReturn, type UseI18nOptions, type UseImageOverlayOptions, type UseImageOverlayReturn, type UseLibraryOptions, type UseLibraryReturn, type UseManuscriptDraftOptions, type UseManuscriptDraftReturn, type UseManuscriptLayoutOptions, type UseManuscriptLayoutReturn, type UseMejiroBookOptions, type UseMejiroBookReturn, type UseMultiImageOverlayOptions, type UseMultiImageOverlayReturn, type UseReadingPositionOptions, type UseReadingPositionReturn, type UseSpreadOptions, type UseSpreadReturn, type VolumeInfo, format, resolveMessages, useAnnotations, useChapterLayout, useEditableEpub, useEpub, useEpubProject, useI18n, useImageOverlay, useLibrary, useManuscriptDraft, useManuscriptLayout, useMejiroBook, useMultiImageOverlay, useReadingPosition, useSpread };
+export { MejiroChapterNav, MejiroDropZone, MejiroEditor, MejiroI18nProvider, MejiroImageOverlay, MejiroManuscriptEditor, MejiroNotationHighlighter, MejiroPage, MejiroPageIndicator, MejiroPageView, MejiroReader, MejiroScrollView, MejiroSelectionLayer, MejiroSettingsPanel, MejiroShelf, MejiroSpread, MejiroStats, MejiroToc, format, resolveMessages, useAnnotations, useChapterLayout, useEditableEpub, useEpub, useEpubProject, useI18n, useImageOverlay, useLibrary, useManuscriptDraft, useManuscriptLayout, useMejiroBook, useMultiImageOverlay, useReadingPosition, useSpread };
+export type { AnnotationsStorage, EpubProjectChapterDraft, ImageRect, ManuscriptAutosaveDraft, ManuscriptEditorChapter, ManuscriptPageDimensions, ManuscriptPreviewProps, ManuscriptRecomputeOptions, MejiroChapterNavMode, MejiroChapterNavProps, MejiroChapterNavVariant, MejiroDropZoneProps, MejiroEditorProps, MejiroExportPolicy, MejiroImageOverlayProps, MejiroManuscriptEditorProps, MejiroNotationHighlighterProps, MejiroPageIndicatorProps, MejiroPageProps, MejiroPageViewProps, MejiroReaderCommonProps, MejiroReaderControlledProps, MejiroReaderEventMap, MejiroReaderFileProps, MejiroReaderFit, MejiroReaderHandle, MejiroReaderManuscriptProps, MejiroReaderMode, MejiroReaderProps, MejiroReaderSettingsSlot, MejiroReaderUrlProps, MejiroScrollViewProps, MejiroSelectionLayerProps, MejiroSettingsPanelProps, MejiroShelfProps, MejiroSpreadMode, MejiroSpreadProps, MejiroStatsProps, MejiroTheme, MejiroThemeName, MejiroTocProps, MultiImageItem, PageDimensions, ReadingPosition, ReadingPositionStorage, RecomputeOptions, UseAnnotationsOptions, UseAnnotationsReturn, UseChapterLayoutOptions, UseChapterLayoutReturn, UseEditableEpubOptions, UseEditableEpubReturn, UseEpubOptions, UseEpubProjectOptions, UseEpubProjectReturn, UseEpubReturn, UseI18nOptions, UseImageOverlayOptions, UseImageOverlayReturn, UseLibraryOptions, UseLibraryReturn, UseManuscriptDraftOptions, UseManuscriptDraftReturn, UseManuscriptLayoutOptions, UseManuscriptLayoutReturn, UseMejiroBookOptions, UseMejiroBookReturn, UseMultiImageOverlayOptions, UseMultiImageOverlayReturn, UseReadingPositionOptions, UseReadingPositionReturn, UseSpreadOptions, UseSpreadReturn, VolumeInfo };