@libraz/mejiro-react 0.9.2 → 0.10.0

package/dist/index.d.ts

@@ -5,7 +5,8 @@ import { ReactNode, CSSProperties, PointerEvent, TextareaHTMLAttributes, Mutable
 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, MejiroBookOptions, ComputePageSizeOptions, InChapterAnchor, ReadingAnchor, ManuscriptChapter, PageResult, AnchorRect, AnchorRange, MejiroBook } from '@libraz/mejiro/book';
-import { RenderPage } from '@libraz/mejiro/render';
+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,
@@ -526,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;
     /**
@@ -625,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;
     /**
@@ -813,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;
@@ -1017,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. */
@@ -1030,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 {
@@ -1285,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` /
@@ -1804,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.
  *
@@ -1877,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()`
@@ -1890,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
@@ -1986,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 };