@open-press/core 0.7.0 → 0.8.0

package/src/openpress/reader/useReaderRuntime.ts

@@ -0,0 +1,146 @@
+import { useCallback, useEffect, useMemo, useRef, useState, type RefCallback } from "react";
+import { pageIndexFromHash } from "./readerPageRoute";
+import { createReaderPageRegistry } from "./readerPageRegistry";
+import { clampReaderPageIndex, formatReaderPageNumber, normalizeReaderPageCount } from "./readerStateModel";
+import { createPageVisibilityObserver, scrollToPage } from "./readerScroll";
+import { usePanelState } from "./usePanelState";
+import { useReaderScrollAnchor } from "./useReaderScrollAnchor";
+import { useReaderHashSync } from "./useReaderHashSync";
+import { useReaderKeyboardNav } from "./useReaderKeyboardNav";
+
+export interface SetPageOptions {
+  behavior?: ScrollBehavior;
+}
+
+interface UseReaderRuntimeOptions {
+  pageCount: number;
+  leftPanelBreakpoint?: number;
+  rightPanelBreakpoint?: number;
+}
+
+export function useReaderRuntime({
+  pageCount,
+  leftPanelBreakpoint,
+  rightPanelBreakpoint = 1000,
+}: UseReaderRuntimeOptions) {
+  const normalizedPageCount = normalizeReaderPageCount(pageCount);
+  const stageRef = useRef<HTMLElement | null>(null);
+  const [pageRegistrationVersion, setPageRegistrationVersion] = useState(0);
+  const pageRegistry = useRef<ReturnType<typeof createReaderPageRegistry<HTMLElement>> | null>(null);
+  if (!pageRegistry.current) {
+    pageRegistry.current = createReaderPageRegistry<HTMLElement>(setPageRegistrationVersion);
+  }
+  const pageRefs = useMemo(() => ({
+    get current() {
+      return pageRegistry.current?.refs ?? [];
+    },
+  }), []) as { current: Array<HTMLElement | null> };
+
+  const [currentPageIndex, setCurrentPageIndex] = useState(() => {
+    if (typeof window === "undefined") return 0;
+    const fromHash = pageIndexFromHash(window.location.hash, normalizedPageCount);
+    return fromHash ?? 0;
+  });
+
+  const currentPageIndexRef = useRef(currentPageIndex);
+  currentPageIndexRef.current = currentPageIndex;
+
+  const { pendingScrollTargetRef, armPendingScrollTarget, clearPendingScrollTarget, reAnchorAfterPaint } =
+    useReaderScrollAnchor({ stageRef, pageRefs, currentPageIndexRef });
+
+  const { leftPanelOpen, rightPanelOpen, toggleLeftPanel, toggleRightPanel } = usePanelState({
+    leftPanelBreakpoint,
+    rightPanelBreakpoint,
+    // scroll-snap-type: y mandatory re-aligns to the closest snap point on
+    // viewport change, which can land one page off from where the reader was.
+    onAfterResize: reAnchorAfterPaint,
+  });
+
+  // Trim the registry + clamp current page when the page count shrinks.
+  useEffect(() => {
+    pageRegistry.current?.trim(normalizedPageCount);
+    setCurrentPageIndex((idx) => clampReaderPageIndex(idx, normalizedPageCount));
+  }, [normalizedPageCount]);
+
+  // Drive currentPageIndex from visible pages. Suppress intermediates while a
+  // programmatic scroll is in flight.
+  useEffect(() => {
+    const stage = stageRef.current;
+    if (!stage) return undefined;
+    const observer = createPageVisibilityObserver(stage, (pageIndex) => {
+      if (pendingScrollTargetRef.current !== null) {
+        if (pageIndex !== pendingScrollTargetRef.current) return;
+        clearPendingScrollTarget();
+      }
+      setCurrentPageIndex((prev) => (prev === pageIndex ? prev : pageIndex));
+    });
+    if (!observer) return undefined;
+    pageRegistry.current?.refs.forEach((el) => el && observer.observe(el));
+    return () => observer.disconnect();
+  }, [clearPendingScrollTarget, normalizedPageCount, pageRegistrationVersion, pendingScrollTargetRef]);
+
+  // When refs change (initial mount, pagination kicks in), re-anchor the stage
+  // to the page we already believe we're on so scroll-snap mandatory doesn't
+  // pull us to whichever page is closest.
+  useEffect(() => {
+    const refs = pageRegistry.current?.refs ?? [];
+    const idx = currentPageIndexRef.current;
+    if (idx === 0) return;
+    if (!refs[idx]) return;
+    armPendingScrollTarget(idx);
+    scrollToPage(refs, idx, "instant", stageRef.current);
+  }, [armPendingScrollTarget, pageRegistrationVersion]);
+
+  const setPage = useCallback(
+    (pageIndex: number, options: SetPageOptions = {}) => {
+      const refs = pageRegistry.current?.refs ?? [];
+      const target = clampReaderPageIndex(pageIndex, normalizedPageCount);
+      armPendingScrollTarget(target);
+      setCurrentPageIndex(target);
+      scrollToPage(refs, target, options.behavior ?? "smooth", stageRef.current);
+    },
+    [armPendingScrollTarget, normalizedPageCount],
+  );
+
+  const nextPage = useCallback(() => {
+    setPage(currentPageIndexRef.current + 1);
+  }, [setPage]);
+
+  const prevPage = useCallback(() => {
+    setPage(currentPageIndexRef.current - 1);
+  }, [setPage]);
+
+  useReaderHashSync({
+    stageRef,
+    pageRefs,
+    currentPageIndex,
+    currentPageIndexRef,
+    normalizedPageCount,
+    setCurrentPageIndex,
+    armPendingScrollTarget,
+  });
+
+  useReaderKeyboardNav({ nextPage, prevPage, setPage, normalizedPageCount });
+
+  const registerPage = useCallback<(pageIndex: number) => RefCallback<HTMLElement>>(
+    (pageIndex) => pageRegistry.current?.registerPage(pageIndex) ?? (() => undefined),
+    [],
+  );
+
+  const progressPercent =
+    normalizedPageCount <= 1 ? 100 : ((currentPageIndex + 1) / normalizedPageCount) * 100;
+
+  return {
+    stageRef,
+    currentPageIndex,
+    currentPageLabel: formatReaderPageNumber(currentPageIndex + 1),
+    totalPageLabel: formatReaderPageNumber(normalizedPageCount),
+    progressPercent,
+    leftPanelOpen,
+    rightPanelOpen,
+    registerPage,
+    setPage,
+    toggleLeftPanel,
+    toggleRightPanel,
+  };
+}

package/src/openpress/reader/useReaderScrollAnchor.ts

@@ -0,0 +1,64 @@
+import { useCallback, useEffect, useRef, type MutableRefObject } from "react";
+import { scrollToPage } from "./readerScroll";
+
+// Generous upper bound on a smooth scrollIntoView. If the target ref is gone or
+// the browser never settles on it, clear the guard so the IO observer regains
+// authority over currentPageIndex.
+const PROGRAMMATIC_SCROLL_FALLBACK_MS = 2500;
+
+export interface UseReaderScrollAnchorOptions {
+  stageRef: MutableRefObject<HTMLElement | null>;
+  pageRefs: MutableRefObject<Array<HTMLElement | null>>;
+  currentPageIndexRef: MutableRefObject<number>;
+}
+
+export interface ReaderScrollAnchor {
+  pendingScrollTargetRef: MutableRefObject<number | null>;
+  armPendingScrollTarget: (target: number) => void;
+  clearPendingScrollTarget: () => void;
+  reAnchorAfterPaint: () => void;
+}
+
+export function useReaderScrollAnchor({
+  stageRef,
+  pageRefs,
+  currentPageIndexRef,
+}: UseReaderScrollAnchorOptions): ReaderScrollAnchor {
+  // While a programmatic scroll is in flight, the IntersectionObserver should
+  // only accept the destination page (not the intermediates we sweep past).
+  const pendingScrollTargetRef = useRef<number | null>(null);
+  const pendingScrollClearTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const armPendingScrollTarget = useCallback((target: number) => {
+    pendingScrollTargetRef.current = target;
+    if (pendingScrollClearTimerRef.current !== null) clearTimeout(pendingScrollClearTimerRef.current);
+    pendingScrollClearTimerRef.current = setTimeout(() => {
+      pendingScrollTargetRef.current = null;
+      pendingScrollClearTimerRef.current = null;
+    }, PROGRAMMATIC_SCROLL_FALLBACK_MS);
+  }, []);
+
+  const clearPendingScrollTarget = useCallback(() => {
+    pendingScrollTargetRef.current = null;
+    if (pendingScrollClearTimerRef.current !== null) {
+      clearTimeout(pendingScrollClearTimerRef.current);
+      pendingScrollClearTimerRef.current = null;
+    }
+  }, []);
+
+  useEffect(() => () => clearPendingScrollTarget(), [clearPendingScrollTarget]);
+
+  // Re-anchor the stage to the page we already believe we're on. scroll-snap
+  // mandatory would otherwise snap to whichever page is closest after a layout
+  // change. Pin to the active programmatic target if there is one.
+  const reAnchorAfterPaint = useCallback(() => {
+    if (typeof window === "undefined") return;
+    window.requestAnimationFrame(() => {
+      const refs = pageRefs.current;
+      const target = pendingScrollTargetRef.current ?? currentPageIndexRef.current;
+      scrollToPage(refs, target, "instant", stageRef.current);
+    });
+  }, [currentPageIndexRef, pageRefs, stageRef]);
+
+  return { pendingScrollTargetRef, armPendingScrollTarget, clearPendingScrollTarget, reAnchorAfterPaint };
+}

package/src/openpress/shared/Panel.tsx

@@ -0,0 +1,77 @@
+import { type ComponentPropsWithoutRef } from "react";
+import { cn } from "../core/cn";
+
+type PanelProps = ComponentPropsWithoutRef<"section">;
+type PanelHeaderProps = ComponentPropsWithoutRef<"header">;
+type PanelDivProps = ComponentPropsWithoutRef<"div">;
+type PanelTextProps = ComponentPropsWithoutRef<"p">;
+type PanelTitleProps = ComponentPropsWithoutRef<"h2">;
+type PanelSectionTitleProps = ComponentPropsWithoutRef<"h3">;
+type PanelButtonProps = ComponentPropsWithoutRef<"button">;
+
+function PanelRoot({ className, ...props }: PanelProps) {
+  return <section {...props} className={cn("openpress-panel", className)} />;
+}
+
+function PanelHeader({ className, ...props }: PanelHeaderProps) {
+  return <header {...props} className={cn("openpress-panel-header", className)} />;
+}
+
+function PanelKicker({ className, ...props }: ComponentPropsWithoutRef<"span">) {
+  return <span {...props} className={cn("openpress-panel-kicker", className)} />;
+}
+
+function PanelTitle({ className, ...props }: PanelTitleProps) {
+  return <h2 {...props} className={cn("openpress-panel-title", className)} />;
+}
+
+function PanelDescription({ className, ...props }: PanelTextProps) {
+  return <p {...props} className={cn("openpress-panel-description", className)} />;
+}
+
+function PanelActions({ className, ...props }: PanelDivProps) {
+  return <div {...props} className={cn("openpress-panel-actions", className)} />;
+}
+
+function PanelActionButton({ className, ...props }: PanelButtonProps) {
+  return <button {...props} className={cn("openpress-panel-action-button", className)} />;
+}
+
+function PanelBody({ className, ...props }: PanelDivProps) {
+  return <div {...props} className={cn("openpress-panel-body", className)} />;
+}
+
+function PanelSection({ className, ...props }: PanelProps) {
+  return <section {...props} className={cn("openpress-panel-section", className)} />;
+}
+
+function PanelSectionTitle({ className, ...props }: PanelSectionTitleProps) {
+  return <h3 {...props} className={cn("openpress-panel-section-title", className)} />;
+}
+
+function PanelSectionDescription({ className, ...props }: PanelTextProps) {
+  return <p {...props} className={cn("openpress-panel-section-description", className)} />;
+}
+
+function PanelEmpty({ className, ...props }: PanelDivProps) {
+  return <div {...props} className={cn("openpress-panel-empty", className)} />;
+}
+
+function PanelError({ className, role = "alert", ...props }: PanelTextProps) {
+  return <p {...props} role={role} className={cn("openpress-panel-error", className)} />;
+}
+
+export const Panel = Object.assign(PanelRoot, {
+  Header: PanelHeader,
+  Kicker: PanelKicker,
+  Title: PanelTitle,
+  Description: PanelDescription,
+  Actions: PanelActions,
+  ActionButton: PanelActionButton,
+  Body: PanelBody,
+  Section: PanelSection,
+  SectionTitle: PanelSectionTitle,
+  SectionDescription: PanelSectionDescription,
+  Empty: PanelEmpty,
+  Error: PanelError,
+});

package/src/openpress/shared/index.ts

@@ -0,0 +1,4 @@
+export * from "./frameScheduler";
+export * from "./numberUtils";
+export * from "./Panel";
+export * from "./runtimeMode";

package/src/openpress/shared/numberUtils.ts

@@ -0,0 +1,3 @@
+export function clampNumber(value: number, min: number, max: number) {
+  return Math.min(Math.max(value, min), Math.max(min, max));
+}

package/src/openpress/{runtimeMode.ts → shared/runtimeMode.ts}

@@ -9,14 +9,3 @@ export function isWorkspaceModeLocation(location: Pick<Location, "hostname" | "s
 export function isPrintModeLocation(location: Pick<Location, "search">) {
   return new URLSearchParams(location.search).has("print");
 }
-
-export function buildPublicPreviewHref(currentHref: string, pageIndex?: number) {
-  const url = new URL(currentHref);
-  url.searchParams.delete("dev");
-  url.searchParams.delete("workspace");
-  url.searchParams.delete("fontPreview");
-  if (typeof pageIndex === "number") {
-    url.hash = `page-${String(pageIndex + 1).padStart(2, "0")}`;
-  }
-  return url.toString();
-}