@open-press/core 0.7.1 → 1.0.0

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());
+}

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();
-}