@open-press/core 0.7.1 → 0.8.0

package/src/openpress/{publicPage.tsx → reader/PublicReaderPage.tsx}

@@ -1,30 +1,33 @@
 import {
-  useLayoutEffect,
   useMemo,
   useRef,
-  useState,
   type CSSProperties,
   type MouseEvent as ReactMouseEvent,
   type RefCallback,
   type RefObject,
 } from "react";
 import { BookOpen, ExternalLink, X } from "lucide-react";
-import { createAnchorPageMap, resolveAnchorPageIndex } from "./anchorMap";
-import { collectBookmarkIndex } from "./indexes";
-import type { InspectorState } from "./inspector";
-import { getProjectIdentity } from "./projectIdentity";
-import { useReaderRuntime } from "./readerRuntime";
-import { scheduleBrowserFrame } from "./frameScheduler";
-import type { DeploymentInfo, ReaderDocument, HtmlPageBlock } from "./types";
-import { Bookmarks, CurrentPagePanel } from "./workbenchPanels";
-import type { DisplayPage } from "./workbenchTypes";
+import {
+  collectBookmarkIndex,
+  createAnchorPageMap,
+  createPageObjectEntityId,
+  getProjectIdentity,
+  resolveAnchorPageIndex,
+  type DeploymentInfo,
+  type HtmlPageBlock,
+  type ReaderDocument,
+} from "../document-model";
+import type { InspectorState } from "../workbench/inspector";
+import { useReaderRuntime } from "./useReaderRuntime";
+import { Bookmarks, CurrentPagePanel } from "./ReaderNavigationPanel";
+import type { DisplayPage } from "./readerTypes";
+import { usePageViewportScale } from "./usePageViewportScale";
+import type { PageLayoutMode } from "./pageViewportScaleModel";
 
 export const PUBLIC_DRAWER_BREAKPOINT = 1185;
-export type ViewMode = "reading" | "paged";
+export type ViewMode = "paged";
 export type PageInspector = Pick<InspectorState, "enabled" | "handleClick">;
 
-const PAGED_VIEW_MIN_WIDTH = 360;
-
 export function PublicViewer({
   document,
   pages,
@@ -46,6 +49,12 @@ export function PublicViewer({
     pageCount: displayPages.length,
     rightPanelBreakpoint: PUBLIC_DRAWER_BREAKPOINT,
   });
+  usePageViewportScale({
+    stageRef: reader.stageRef,
+    pageContainerRef: sourceContainerRef,
+    pageCount: displayPages.length,
+    layoutMode: "single",
+  });
   const currentPage = displayPages[reader.currentPageIndex];
   const staticPdfHref = deploymentInfo.pdf;
   const projectIdentity = getProjectIdentity(document.meta);
@@ -135,7 +144,7 @@ export function PublicViewer({
             totalPageLabel={reader.totalPageLabel}
             progressPercent={reader.progressPercent}
             title={currentPage?.title || document.meta.title}
-            pageLabelPrefix={viewMode === "reading" ? "節" : "頁"}
+            pageLabelPrefix="頁"
             showHeading={false}
             showTitle={false}
           />
@@ -145,37 +154,8 @@ export function PublicViewer({
   );
 }
 
-export function useViewMode() {
-  const [pagedAllowed, setPagedAllowed] = useState(() => {
-    if (typeof window === "undefined") return true;
-    return viewportAllowsPagedMode();
-  });
-
-  useLayoutEffect(() => {
-    if (typeof window === "undefined") return undefined;
-
-    let cancelFrame: (() => void) | null = null;
-    const sync = () => {
-      cancelFrame?.();
-      cancelFrame = scheduleBrowserFrame(() => {
-        cancelFrame = null;
-        setPagedAllowed(viewportAllowsPagedMode());
-      });
-    };
-
-    sync();
-    window.addEventListener("resize", sync);
-    window.visualViewport?.addEventListener("resize", sync);
-    return () => {
-      window.removeEventListener("resize", sync);
-      window.visualViewport?.removeEventListener("resize", sync);
-      cancelFrame?.();
-    };
-  }, []);
-
-  const viewMode: ViewMode = pagedAllowed ? "paged" : "reading";
-
-  return { viewMode };
+export function useViewMode(): { viewMode: ViewMode } {
+  return { viewMode: "paged" };
 }
 
 export function PrintDocument({
@@ -210,11 +190,6 @@ export function PrintDocument({
   );
 }
 
-function viewportAllowsPagedMode() {
-  if (typeof window === "undefined") return true;
-  return window.innerWidth >= PAGED_VIEW_MIN_WIDTH;
-}
-
 export function PublicPage({
   pages,
   currentPageIndex,
@@ -224,6 +199,7 @@ export function PublicPage({
   exposeSourceData = false,
   inspector,
   onInternalAnchorNavigate,
+  pageLayoutMode = "single",
 }: {
   pages: DisplayPage[];
   currentPageIndex: number;
@@ -233,6 +209,7 @@ export function PublicPage({
   exposeSourceData?: boolean;
   inspector?: PageInspector;
   onInternalAnchorNavigate?: (anchorId: string, pageIndex?: number) => boolean;
+  pageLayoutMode?: PageLayoutMode;
 }) {
   const handlePageClick = (event: ReactMouseEvent<HTMLDivElement>) => {
     if (inspector?.enabled && inspector.handleClick(event)) return;
@@ -257,6 +234,7 @@ export function PublicPage({
       className="reader-pages openpress-public-page"
       ref={sourceContainerRef}
       data-openpress-public-page="true"
+      data-openpress-page-layout={pageLayoutMode}
       onClick={handlePageClick}
     >
       {pages.map((page) => (
@@ -265,7 +243,9 @@ export function PublicPage({
           ref={registerPage(page.pageNumber - 1)}
           id={`page-${String(page.pageNumber).padStart(2, "0")}`}
           className="openpress-html-page"
+          data-openpress-object-id={page.frameKey ? createPageObjectEntityId(page.frameKey) : undefined}
           data-openpress-page-index={page.pageNumber - 1}
+          data-openpress-page-spread-side={pageLayoutMode === "spread" ? ((page.pageNumber - 1) % 2 === 0 ? "left" : "right") : undefined}
           data-openpress-active={currentPageIndex === page.pageNumber - 1 ? "true" : "false"}
           data-source-path={exposeSourceData ? page.source?.path : undefined}
           data-source-file={exposeSourceData ? page.source?.file : undefined}

package/src/openpress/{workbenchPanels.tsx → reader/ReaderNavigationPanel.tsx}

@@ -1,5 +1,6 @@
 import { type CSSProperties, type MouseEvent as ReactMouseEvent } from "react";
-import type { BookmarkItem } from "./indexes";
+import type { BookmarkItem } from "../document-model";
+import { Panel } from "../shared";
 
 type BookmarkSelectOptions = {
   behavior?: ScrollBehavior;
@@ -20,7 +21,7 @@ export function Bookmarks({
   };
 
   if (items.length === 0) {
-    return <p className="openpress-asset-empty">尚無書籤</p>;
+    return <Panel.Empty className="openpress-asset-empty" role="status">尚無書籤</Panel.Empty>;
   }
 
   return (
@@ -103,8 +104,8 @@ export function CurrentPagePanel({
   showTitle?: boolean;
 }) {
   return (
-    <section className="openpress-panel-section openpress-panel-section--current" aria-label="目前頁面">
-      {showHeading ? <div className="openpress-panel-heading">目前頁面</div> : null}
+    <Panel.Section className="openpress-panel-section--current" aria-label="目前頁面">
+      {showHeading ? <Panel.SectionTitle className="openpress-panel-heading">目前頁面</Panel.SectionTitle> : null}
       <div className="openpress-current-page-card">
         <div className="openpress-current-page-card__number" aria-label="目前頁數">
           {pageLabelPrefix ? <span className="openpress-current-page-card__prefix">{pageLabelPrefix}</span> : null}
@@ -117,6 +118,6 @@ export function CurrentPagePanel({
           <span style={{ "--progress": `${progressPercent}%` } as CSSProperties} />
         </div>
       </div>
-    </section>
+    </Panel.Section>
   );
 }

package/src/openpress/reader/index.ts

@@ -0,0 +1,10 @@
+export * from "./PublicReaderPage";
+export * from "./ReaderNavigationPanel";
+export * from "./pageViewportScaleModel";
+export * from "./readerPageRegistry";
+export * from "./readerPageRoute";
+export * from "./readerScroll";
+export * from "./readerStateModel";
+export * from "./readerTypes";
+export * from "./usePageViewportScale";
+export * from "./useReaderRuntime";

package/src/openpress/reader/pageViewportScaleModel.ts

@@ -0,0 +1,73 @@
+export type PageLayoutMode = "single" | "spread";
+
+export type PageViewportScaleMode =
+  | "fit-width"
+  | "fit-page"
+  | "scale-25"
+  | "scale-50"
+  | "scale-75"
+  | "scale-100"
+  | "scale-125"
+  | "scale-150"
+  | "scale-200";
+
+export const PAGE_VIEWPORT_SCALE_OPTIONS: Array<{
+  value: PageViewportScaleMode;
+  label: string;
+}> = [
+  { value: "scale-25", label: "25%" },
+  { value: "scale-50", label: "50%" },
+  { value: "scale-75", label: "75%" },
+  { value: "scale-100", label: "100%" },
+  { value: "scale-125", label: "125%" },
+  { value: "scale-150", label: "150%" },
+  { value: "scale-200", label: "200%" },
+  { value: "fit-width", label: "符合頁面寬度" },
+  { value: "fit-page", label: "符合全開頁面" },
+];
+
+const MIN_PAGE_VIEWPORT_SCALE = 0.12;
+const MAX_FIT_PAGE_VIEWPORT_SCALE = 1;
+const MAX_FIXED_PAGE_VIEWPORT_SCALE = 2;
+
+export function resolvePageViewportScale({
+  mode,
+  fitWidthScale,
+  fitPageScale,
+}: {
+  mode: PageViewportScaleMode;
+  fitWidthScale: number;
+  fitPageScale: number;
+}) {
+  if (mode === "fit-width") return clampPageViewportScale(fitWidthScale, MAX_FIT_PAGE_VIEWPORT_SCALE);
+  if (mode === "fit-page") return clampPageViewportScale(fitPageScale, MAX_FIT_PAGE_VIEWPORT_SCALE);
+  return scaleModeToFixedValue(mode);
+}
+
+export function formatPageViewportScaleLabel(mode: PageViewportScaleMode, scale: number) {
+  void mode;
+  return formatPageViewportScalePercent(scale);
+}
+
+export function formatPageViewportScalePercent(scale: number) {
+  return `${Math.round(clampPageViewportScale(scale, MAX_FIXED_PAGE_VIEWPORT_SCALE) * 100)}%`;
+}
+
+export function formatPageViewportScaleValue(scale: number) {
+  return clampPageViewportScale(scale, MAX_FIXED_PAGE_VIEWPORT_SCALE)
+    .toFixed(4)
+    .replace(/0+$/, "")
+    .replace(/\.$/, "");
+}
+
+function scaleModeToFixedValue(mode: PageViewportScaleMode) {
+  const match = /^scale-(\d+)$/.exec(mode);
+  if (!match) return 1;
+  return clampPageViewportScale(Number.parseInt(match[1] ?? "100", 10) / 100, MAX_FIXED_PAGE_VIEWPORT_SCALE);
+}
+
+function clampPageViewportScale(value: number, maxScale: number) {
+  if (!Number.isFinite(value)) return 1;
+  const safeMaxScale = Number.isFinite(maxScale) && maxScale > 0 ? maxScale : MAX_FIXED_PAGE_VIEWPORT_SCALE;
+  return Math.min(Math.max(value, MIN_PAGE_VIEWPORT_SCALE), safeMaxScale);
+}

package/src/openpress/reader/readerTypes.ts

@@ -0,0 +1,4 @@
+import type { IndexedHtmlPage } from "../document-model";
+import type { HtmlPageBlock } from "../document-model";
+
+export type DisplayPage = IndexedHtmlPage & Pick<HtmlPageBlock, "source" | "frameKey">;

package/src/openpress/reader/usePageViewportScale.ts

@@ -0,0 +1,119 @@
+import { useLayoutEffect, useMemo, useState, type RefObject } from "react";
+import { scheduleBrowserFrame } from "../shared";
+import {
+  formatPageViewportScaleLabel,
+  formatPageViewportScaleValue,
+  resolvePageViewportScale,
+  type PageLayoutMode,
+  type PageViewportScaleMode,
+} from "./pageViewportScaleModel";
+
+export function usePageViewportScale({
+  stageRef,
+  pageContainerRef,
+  pageCount,
+  layoutMode = "single",
+}: {
+  stageRef: RefObject<HTMLElement | null>;
+  pageContainerRef: RefObject<HTMLElement | null>;
+  pageCount: number;
+  layoutMode?: PageLayoutMode;
+}) {
+  const [scaleMode, setScaleMode] = useState<PageViewportScaleMode>("fit-width");
+  const [scale, setScale] = useState(1);
+
+  useLayoutEffect(() => {
+    if (typeof window === "undefined") return undefined;
+
+    let cancelFrame: (() => void) | null = null;
+
+    const syncScale = () => {
+      cancelFrame?.();
+      cancelFrame = scheduleBrowserFrame(() => {
+        cancelFrame = null;
+        const container = pageContainerRef.current;
+        if (!container) return;
+
+        const pageSurface = container.querySelector<HTMLElement>(".openpress-html-page__html");
+        if (!pageSurface) {
+          container.style.setProperty("--openpress-page-viewport-scale", "1");
+          container.dataset.openpressPageScaleMode = scaleMode;
+          container.dataset.openpressPageScale = "1";
+          setScale(1);
+          return;
+        }
+
+        const stage = stageRef.current ?? container.parentElement;
+        const containerStyle = window.getComputedStyle(container);
+        const paddingLeft = parseCssPixelValue(containerStyle.paddingLeft);
+        const paddingRight = parseCssPixelValue(containerStyle.paddingRight);
+        const paddingTop = parseCssPixelValue(containerStyle.paddingTop);
+        const paddingBottom = parseCssPixelValue(containerStyle.paddingBottom);
+        const columnGap = parseCssPixelValue(containerStyle.columnGap || containerStyle.gap);
+        const availableWidth = Math.max(
+          1,
+          (stage?.clientWidth || container.clientWidth || window.innerWidth) - paddingLeft - paddingRight,
+        );
+        const availableHeight = Math.max(
+          1,
+          (stage?.clientHeight || container.clientHeight || window.innerHeight) - paddingTop - paddingBottom,
+        );
+        const pageWidth = pageSurface.offsetWidth;
+        const pageHeight = pageSurface.offsetHeight;
+        const canonicalWidth = layoutMode === "spread" ? (pageWidth * 2) + columnGap : pageWidth;
+        const canonicalHeight = pageHeight;
+        const fitWidthScale = canonicalWidth > 0 ? availableWidth / canonicalWidth : 1;
+        const fitPageScale = canonicalWidth > 0 && canonicalHeight > 0
+          ? Math.min(availableWidth / canonicalWidth, availableHeight / canonicalHeight)
+          : 1;
+        const nextScale = resolvePageViewportScale({ mode: scaleMode, fitWidthScale, fitPageScale });
+        const nextScaleValue = formatPageViewportScaleValue(nextScale);
+
+        container.style.setProperty("--openpress-page-viewport-scale", nextScaleValue);
+        container.dataset.openpressPageScaleMode = scaleMode;
+        container.dataset.openpressPageScale = nextScaleValue;
+        setScale((current) => (current === nextScale ? current : nextScale));
+      });
+    };
+
+    syncScale();
+
+    const ResizeObserverCtor = window.ResizeObserver;
+    const observer = ResizeObserverCtor ? new ResizeObserverCtor(syncScale) : null;
+    const stage = stageRef.current;
+    const container = pageContainerRef.current;
+    if (stage) observer?.observe(stage);
+    if (container) observer?.observe(container);
+
+    window.addEventListener("resize", syncScale);
+    window.visualViewport?.addEventListener("resize", syncScale);
+    return () => {
+      cancelFrame?.();
+      observer?.disconnect();
+      window.removeEventListener("resize", syncScale);
+      window.visualViewport?.removeEventListener("resize", syncScale);
+    };
+  }, [layoutMode, pageContainerRef, pageCount, scaleMode, stageRef]);
+
+  const scaleLabel = useMemo(
+    () => {
+      const labelScale = scaleMode.startsWith("scale-")
+        ? resolvePageViewportScale({ mode: scaleMode, fitWidthScale: scale, fitPageScale: scale })
+        : scale;
+      return formatPageViewportScaleLabel(scaleMode, labelScale);
+    },
+    [scale, scaleMode],
+  );
+
+  return {
+    scale,
+    scaleMode,
+    scaleLabel,
+    setScaleMode,
+  };
+}
+
+function parseCssPixelValue(value: string) {
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) ? parsed : 0;
+}

package/src/openpress/reader/usePanelState.ts

@@ -0,0 +1,56 @@
+import { useCallback, useEffect, useState } from "react";
+
+export interface UsePanelStateOptions {
+  leftPanelBreakpoint?: number;
+  rightPanelBreakpoint?: number;
+  onAfterResize?: () => void;
+}
+
+export interface PanelState {
+  leftPanelOpen: boolean;
+  rightPanelOpen: boolean;
+  toggleLeftPanel: () => void;
+  toggleRightPanel: () => void;
+}
+
+export function usePanelState({
+  leftPanelBreakpoint,
+  rightPanelBreakpoint = 1000,
+  onAfterResize,
+}: UsePanelStateOptions = {}): PanelState {
+  const shouldOpenLeftPanel = useCallback(
+    () =>
+      leftPanelBreakpoint === undefined || typeof window === "undefined" || window.innerWidth >= leftPanelBreakpoint,
+    [leftPanelBreakpoint],
+  );
+  const shouldOpenRightPanel = useCallback(
+    () => typeof window === "undefined" || window.innerWidth >= rightPanelBreakpoint,
+    [rightPanelBreakpoint],
+  );
+
+  const [rightPanelOpen, setRightPanelOpen] = useState(false);
+  const [leftPanelOpen, setLeftPanelOpen] = useState(false);
+
+  useEffect(() => {
+    if (typeof window === "undefined") return undefined;
+
+    const handleResize = () => {
+      setLeftPanelOpen((open) => (open && !shouldOpenLeftPanel() ? false : open));
+      setRightPanelOpen((open) => (open && !shouldOpenRightPanel() ? false : open));
+      onAfterResize?.();
+    };
+
+    handleResize();
+    window.addEventListener("resize", handleResize);
+    window.visualViewport?.addEventListener("resize", handleResize);
+    return () => {
+      window.removeEventListener("resize", handleResize);
+      window.visualViewport?.removeEventListener("resize", handleResize);
+    };
+  }, [shouldOpenLeftPanel, shouldOpenRightPanel, onAfterResize]);
+
+  const toggleLeftPanel = useCallback(() => setLeftPanelOpen((open) => !open), []);
+  const toggleRightPanel = useCallback(() => setRightPanelOpen((open) => !open), []);
+
+  return { leftPanelOpen, rightPanelOpen, toggleLeftPanel, toggleRightPanel };
+}

package/src/openpress/reader/useReaderHashSync.ts

@@ -0,0 +1,61 @@
+import { useEffect, type MutableRefObject } from "react";
+import { pageIndexFromHash, replacePageRoute } from "./readerPageRoute";
+import { scrollToPage } from "./readerScroll";
+
+export interface UseReaderHashSyncOptions {
+  stageRef: MutableRefObject<HTMLElement | null>;
+  pageRefs: MutableRefObject<Array<HTMLElement | null>>;
+  currentPageIndex: number;
+  currentPageIndexRef: MutableRefObject<number>;
+  normalizedPageCount: number;
+  setCurrentPageIndex: (index: number) => void;
+  armPendingScrollTarget: (target: number) => void;
+}
+
+export function useReaderHashSync({
+  stageRef,
+  pageRefs,
+  currentPageIndex,
+  currentPageIndexRef,
+  normalizedPageCount,
+  setCurrentPageIndex,
+  armPendingScrollTarget,
+}: UseReaderHashSyncOptions) {
+  // Mirror currentPageIndex into the URL hash so deep links + history work.
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    replacePageRoute(currentPageIndex);
+  }, [currentPageIndex]);
+
+  // Listen for hash/back/forward navigation and drive scroll to match.
+  useEffect(() => {
+    if (typeof window === "undefined") return undefined;
+
+    const syncFromHash = (behavior: ScrollBehavior) => {
+      const refs = pageRefs.current;
+      const hashPage = pageIndexFromHash(window.location.hash, normalizedPageCount);
+      if (hashPage === null) return;
+      // replacePageRoute writes the hash to mirror state; skip if it already
+      // matches so we don't fight ourselves.
+      if (hashPage === currentPageIndexRef.current) return;
+      armPendingScrollTarget(hashPage);
+      setCurrentPageIndex(hashPage);
+      scrollToPage(refs, hashPage, behavior, stageRef.current);
+    };
+
+    const onHashChange = () => syncFromHash("smooth");
+    window.addEventListener("hashchange", onHashChange);
+    window.addEventListener("popstate", onHashChange);
+    return () => {
+      window.removeEventListener("hashchange", onHashChange);
+      window.removeEventListener("popstate", onHashChange);
+    };
+  }, [
+    armPendingScrollTarget,
+    currentPageIndexRef,
+    normalizedPageCount,
+    pageRefs,
+    setCurrentPageIndex,
+    stageRef,
+  ]);
+}

package/src/openpress/reader/useReaderKeyboardNav.ts

@@ -0,0 +1,48 @@
+import { useEffect } from "react";
+
+export interface UseReaderKeyboardNavOptions {
+  nextPage: () => void;
+  prevPage: () => void;
+  setPage: (pageIndex: number) => void;
+  normalizedPageCount: number;
+}
+
+export function useReaderKeyboardNav({
+  nextPage,
+  prevPage,
+  setPage,
+  normalizedPageCount,
+}: UseReaderKeyboardNavOptions) {
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (isEditableTarget(event.target)) return;
+      if (hasActiveTextSelection()) return;
+      if (event.key === "ArrowRight" || event.key === "PageDown") {
+        event.preventDefault();
+        nextPage();
+      } else if (event.key === "ArrowLeft" || event.key === "PageUp") {
+        event.preventDefault();
+        prevPage();
+      } else if (event.key === "Home") {
+        event.preventDefault();
+        setPage(0);
+      } else if (event.key === "End") {
+        event.preventDefault();
+        setPage(Math.max(0, normalizedPageCount - 1));
+      }
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [nextPage, prevPage, setPage, normalizedPageCount]);
+}
+
+function isEditableTarget(target: EventTarget | null) {
+  if (!(target instanceof HTMLElement)) return false;
+  return Boolean(target.closest("input, textarea, select, button, [contenteditable]"));
+}
+
+function hasActiveTextSelection() {
+  const selection = window.getSelection?.();
+  if (!selection || selection.isCollapsed) return false;
+  return Boolean(selection.toString().trim());
+}