Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

fix(reading): expose EPUB display and page layout controls (#1447)

Bingxi Zhao (Frank)e5e960feda8b
diff --git a/web/components/reading/EpubDocumentView.tsx b/web/components/reading/EpubDocumentView.tsx
index 2b72eb730..45f314ede 100644
--- a/web/components/reading/EpubDocumentView.tsx
+++ b/web/components/reading/EpubDocumentView.tsx
@@ -20,8 +20,15 @@ import {
type EpubPageTurnDirection,
} from "@/lib/epub-page-turn";
import { extractEpubHeadings, type ReaderHeading } from "@/lib/reading-outline";
+import {
+ DEFAULT_READER_DISPLAY_PREFERENCES,
+ loadReaderDisplayPreferences,
+ saveReaderDisplayPreferences,
+ type ReaderDisplayPreferences,
+} from "@/lib/reading-display-preferences";
import { cleanQuote } from "@/lib/reading-selection";
import type { JumpRequest, SelectionPayload } from "./PdfDocumentView";
+import { ReaderDisplayControls } from "./ReaderDisplayControls";
type EpubLocation = {
start?: { cfi?: string; href?: string; percentage?: number };
@@ -45,8 +52,11 @@ type EpubAnnotationLayer = {
type EpubRendition = {
display: (target?: string) => Promise<unknown>;
+ currentLocation: () => EpubLocation | undefined;
next: () => Promise<unknown>;
prev: () => Promise<unknown>;
+ resize: (width: number, height: number) => void;
+ spread: (mode: "none" | "auto") => void;
destroy: () => void;
on: (event: string, callback: (...args: unknown[]) => void) => void;
off: (event: string, callback: (...args: unknown[]) => void) => void;
@@ -62,6 +72,9 @@ type EpubRendition = {
rules: Record<string, Record<string, string>>,
) => void;
select: (name: string) => void;
+ fontSize: (size: string) => void;
+ override: (name: string, value: string, priority?: boolean) => void;
+ removeOverride: (name: string) => void;
};
};
@@ -93,6 +106,40 @@ const HIGHLIGHT_COLORS: Record<string, string> = {
purple: "rgba(199, 174, 250, 0.55)",
};
+function applyEpubDisplayPreferences(
+ rendition: EpubRendition,
+ preferences: ReaderDisplayPreferences,
+) {
+ rendition.themes.fontSize(`${preferences.fontSize}px`);
+ rendition.themes.override(
+ "font-family",
+ preferences.serif
+ ? "ui-serif, Georgia, 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', serif"
+ : "ui-sans-serif, system-ui, -apple-system, 'PingFang SC', sans-serif",
+ true,
+ );
+ // epub.js sets column-width but leaves column-count automatic. A wide pane
+ // can fit a third visible column after the sidebar collapses (#1447).
+ rendition.themes.override(
+ "column-count",
+ preferences.spreadMode === "none" ? "1" : "2",
+ true,
+ );
+ const paper =
+ preferences.readerTheme === "sepia"
+ ? { background: "#f4ecd8", color: "#473c2c" }
+ : preferences.readerTheme === "night"
+ ? { background: "#16181d", color: "#e8e5df" }
+ : null;
+ if (paper) {
+ rendition.themes.override("background-color", paper.background, true);
+ rendition.themes.override("color", paper.color, true);
+ } else {
+ rendition.themes.removeOverride("background-color");
+ rendition.themes.removeOverride("color");
+ }
+}
+
export interface EpubDocumentViewProps {
materialId: string;
unitCount: number;
@@ -142,9 +189,56 @@ export function EpubDocumentView({
const headingsByLocatorRef = useRef<Map<number, ReaderHeading[]>>(new Map());
const errorRef = useRef(onError);
const locatorRef = useRef(1);
+ const preferencesRef = useRef(DEFAULT_READER_DISPLAY_PREFERENCES);
+ const activeSpreadRef = useRef(DEFAULT_READER_DISPLAY_PREFERENCES.spreadMode);
+ const relayoutTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+ const relayoutAnchorRef = useRef<string | undefined>(undefined);
+ const [preferences, setPreferences] = useState<ReaderDisplayPreferences>(
+ DEFAULT_READER_DISPLAY_PREFERENCES,
+ );
const [loading, setLoading] = useState(true);
const [loadError, setLoadError] = useState("");
+ useEffect(() => {
+ const saved = loadReaderDisplayPreferences();
+ preferencesRef.current = saved;
+ setPreferences(saved);
+ }, []);
+
+ const updatePreferences = useCallback(
+ (next: Partial<ReaderDisplayPreferences>) => {
+ const merged = { ...preferencesRef.current, ...next };
+ preferencesRef.current = merged;
+ setPreferences(merged);
+ saveReaderDisplayPreferences(merged);
+ },
+ [],
+ );
+
+ const scheduleRelayout = useCallback((anchor?: string) => {
+ if (anchor) relayoutAnchorRef.current = anchor;
+ if (relayoutTimerRef.current) clearTimeout(relayoutTimerRef.current);
+ relayoutTimerRef.current = setTimeout(() => {
+ relayoutTimerRef.current = null;
+ const rendition = renditionRef.current;
+ const host = hostRef.current;
+ if (!rendition || !host) return;
+ const bounds = host.getBoundingClientRect();
+ const width = Math.round(bounds.width);
+ const height = Math.round(bounds.height);
+ if (!width || !height) return;
+ const cfi =
+ relayoutAnchorRef.current ?? rendition.currentLocation()?.start?.cfi;
+ relayoutAnchorRef.current = undefined;
+ rendition.resize(width, height);
+ if (cfi) {
+ void rendition.display(cfi).catch(() => {
+ // A stale publisher CFI must not break the current reading page.
+ });
+ }
+ }, 100);
+ }, []);
+
useEffect(() => {
refsRef.current = unitRefs;
}, [unitRefs]);
@@ -337,19 +431,22 @@ export function EpubDocumentView({
width: "100%",
height: "100%",
flow: "paginated",
- spread: "auto",
+ spread: preferencesRef.current.spreadMode,
allowScriptedContent: false,
});
renditionRef.current = rendition;
+ activeSpreadRef.current = preferencesRef.current.spreadMode;
rendition.themes.register("deeptutor", {
- "body, p, span, div": {
- "font-family":
- "ui-serif, Georgia, 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', serif !important",
- },
"body *": { "vertical-align": "baseline" },
- img: { "max-width": "100%", height: "auto" },
+ img: {
+ "max-width": "100%",
+ "max-height": "85vh",
+ height: "auto",
+ "object-fit": "contain",
+ },
});
rendition.themes.select("deeptutor");
+ applyEpubDisplayPreferences(rendition, preferencesRef.current);
rendition.on("relocated", onRelocated);
rendition.on("selected", onSelected);
rendition.on("keydown", onRenditionKey);
@@ -386,6 +483,7 @@ export function EpubDocumentView({
return () => {
cancelled = true;
if (saveTimerRef.current) clearTimeout(saveTimerRef.current);
+ if (relayoutTimerRef.current) clearTimeout(relayoutTimerRef.current);
if (rendition) {
rendition.off("relocated", onRelocated);
rendition.off("selected", onSelected);
@@ -399,6 +497,29 @@ export function EpubDocumentView({
};
}, [materialId, unitCount, onSelection, t, turnPage]);
+ useEffect(() => {
+ const rendition = renditionRef.current;
+ if (!rendition || loading) return;
+ applyEpubDisplayPreferences(rendition, preferences);
+ let anchor: string | undefined;
+ if (activeSpreadRef.current !== preferences.spreadMode) {
+ // Keep the current CFI before epub.js replaces its page geometry.
+ anchor = rendition.currentLocation()?.start?.cfi;
+ rendition.spread(preferences.spreadMode);
+ activeSpreadRef.current = preferences.spreadMode;
+ }
+ scheduleRelayout(anchor);
+ }, [loading, preferences, scheduleRelayout]);
+
+ useEffect(() => {
+ const host = hostRef.current;
+ if (loading || !host || !renditionRef.current) return;
+ if (typeof ResizeObserver === "undefined") return;
+ const observer = new ResizeObserver(() => scheduleRelayout());
+ observer.observe(host);
+ return () => observer.disconnect();
+ }, [loading, scheduleRelayout]);
+
useEffect(() => {
if (!headingJump || !renditionRef.current || !bookRef.current) return;
const section = bookRef.current.spine.get(
@@ -502,47 +623,76 @@ export function EpubDocumentView({
});
}, [jump, unitRefs]);
+ const surface =
+ preferences.readerTheme === "sepia"
+ ? { background: "#f4ecd8", color: "#473c2c" }
+ : preferences.readerTheme === "night"
+ ? { background: "#16181d", color: "#e8e5df" }
+ : { background: "var(--background)" };
+
return (
- <div className="relative h-full min-h-0 overflow-hidden bg-[var(--background)] pb-[env(safe-area-inset-bottom)]">
- <div
- ref={hostRef}
- className="h-full w-full"
- aria-label={t("Immersive reading")}
- />
- {loading && (
- <div className="absolute inset-0 flex items-center justify-center gap-2 bg-[var(--background)] text-xs text-[var(--muted-foreground)]">
- <Loader2 size={15} className="animate-spin" />
- {t("Opening document…")}
- </div>
- )}
- {!loading && loadError && (
+ <div
+ className="flex h-full min-h-0 flex-col overflow-hidden pb-[env(safe-area-inset-bottom)]"
+ style={surface}
+ >
+ <div className="flex shrink-0 items-center gap-2 overflow-x-auto border-b border-[var(--border)] px-2 py-2 sm:px-3">
+ <ReaderDisplayControls
+ preferences={preferences}
+ onChange={updatePreferences}
+ showSpread
+ />
+ </div>
+ <div className="relative min-h-0 flex-1">
<div
- role="alert"
- className="absolute inset-0 grid place-items-center p-8 text-center text-sm text-[var(--destructive)]"
- >
- {loadError}
- </div>
- )}
- {!loadError && (
- <>
- <button
- type="button"
- onClick={() => turnPage("previous")}
- className="absolute left-2 top-1/2 inline-flex h-10 w-10 -translate-y-1/2 items-center justify-center rounded-full border border-[var(--border)] bg-[color-mix(in_srgb,var(--background)_90%,transparent)] text-[var(--foreground)] shadow-sm backdrop-blur transition hover:bg-[var(--muted)]"
- aria-label={t("Previous")}
+ ref={hostRef}
+ className="mx-auto h-full w-full"
+ style={{
+ maxWidth:
+ preferences.spreadMode === "none"
+ ? `calc(${preferences.lineWidth}ch + 4rem)`
+ : `calc(${preferences.lineWidth * 2}ch + 6rem)`,
+ fontSize: `${preferences.fontSize}px`,
+ }}
+ aria-label={t("Immersive reading")}
+ />
+ {loading && (
+ <div
+ className="absolute inset-0 flex items-center justify-center gap-2 text-xs"
+ style={surface}
>
- <ChevronLeft size={19} />
- </button>
- <button
- type="button"
- onClick={() => turnPage("next")}
- className="absolute right-2 top-1/2 inline-flex h-10 w-10 -translate-y-1/2 items-center justify-center rounded-full border border-[var(--border)] bg-[color-mix(in_srgb,var(--background)_90%,transparent)] text-[var(--foreground)] shadow-sm backdrop-blur transition hover:bg-[var(--muted)]"
- aria-label={t("Next")}
+ <Loader2 size={15} className="animate-spin" />
+ {t("Opening document…")}
+ </div>
+ )}
+ {!loading && loadError && (
+ <div
+ role="alert"
+ className="absolute inset-0 grid place-items-center p-8 text-center text-sm text-[var(--destructive)]"
>
- <ChevronRight size={19} />
- </button>
- </>
- )}
+ {loadError}
+ </div>
+ )}
+ {!loadError && (
+ <>
+ <button
+ type="button"
+ onClick={() => turnPage("previous")}
+ className="absolute left-2 top-1/2 inline-flex h-10 w-10 -translate-y-1/2 items-center justify-center rounded-full border border-current/20 bg-[color-mix(in_srgb,currentColor_8%,transparent)] text-inherit shadow-sm backdrop-blur transition hover:bg-[color-mix(in_srgb,currentColor_14%,transparent)]"
+ aria-label={t("Previous")}
+ >
+ <ChevronLeft size={19} />
+ </button>
+ <button
+ type="button"
+ onClick={() => turnPage("next")}
+ className="absolute right-2 top-1/2 inline-flex h-10 w-10 -translate-y-1/2 items-center justify-center rounded-full border border-current/20 bg-[color-mix(in_srgb,currentColor_8%,transparent)] text-inherit shadow-sm backdrop-blur transition hover:bg-[color-mix(in_srgb,currentColor_14%,transparent)]"
+ aria-label={t("Next")}
+ >
+ <ChevronRight size={19} />
+ </button>
+ </>
+ )}
+ </div>
</div>
);
}
diff --git a/web/components/reading/ReaderDisplayControls.tsx b/web/components/reading/ReaderDisplayControls.tsx
new file mode 100644
index 000000000..ce6e62d60
--- /dev/null
+++ b/web/components/reading/ReaderDisplayControls.tsx
@@ -0,0 +1,139 @@
+"use client";
+
+import {
+ ALargeSmall,
+ Columns2,
+ Minus,
+ Plus,
+ RotateCcw,
+ Rows3,
+ SunMoon,
+ type LucideIcon,
+} from "lucide-react";
+import { useTranslation } from "react-i18next";
+
+import {
+ DEFAULT_READER_DISPLAY_PREFERENCES,
+ MAX_FONT_SIZE,
+ MIN_FONT_SIZE,
+ MIN_LINE_WIDTH,
+ type ReaderDisplayPreferences,
+} from "@/lib/reading-display-preferences";
+
+const LINE_WIDTH_STEPS = [48, 64, 84, 104];
+
+export function PreferenceButton({
+ label,
+ icon: Icon,
+ active = false,
+ disabled = false,
+ onClick,
+}: {
+ label: string;
+ icon: LucideIcon;
+ active?: boolean;
+ disabled?: boolean;
+ onClick: () => void;
+}) {
+ return (
+ <button
+ type="button"
+ title={label}
+ aria-label={label}
+ aria-pressed={active}
+ disabled={disabled}
+ onClick={onClick}
+ className={`inline-flex h-7 w-7 items-center justify-center rounded-lg text-inherit transition hover:bg-[color-mix(in_srgb,currentColor_10%,transparent)] disabled:opacity-35 disabled:hover:bg-transparent ${
+ active ? "opacity-100" : "opacity-70 hover:opacity-100"
+ }`}
+ >
+ <Icon size={15} />
+ </button>
+ );
+}
+
+/** The text and native EPUB readers share one display preference contract. */
+export function ReaderDisplayControls({
+ preferences,
+ onChange,
+ showSpread = false,
+}: {
+ preferences: ReaderDisplayPreferences;
+ onChange: (next: Partial<ReaderDisplayPreferences>) => void;
+ showSpread?: boolean;
+}) {
+ const { t } = useTranslation();
+ const { fontSize, lineWidth, serif, readerTheme, spreadMode } = preferences;
+
+ return (
+ <div className="flex shrink-0 items-center gap-0.5">
+ <PreferenceButton
+ label={t("Smaller text ({{percent}}%)", {
+ percent: Math.round((fontSize / 16) * 100),
+ })}
+ icon={Minus}
+ disabled={fontSize <= MIN_FONT_SIZE}
+ onClick={() => onChange({ fontSize: Math.max(MIN_FONT_SIZE, fontSize - 1) })}
+ />
+ <PreferenceButton
+ label={t("Larger text ({{percent}}%)", {
+ percent: Math.round((fontSize / 16) * 100),
+ })}
+ icon={Plus}
+ disabled={fontSize >= MAX_FONT_SIZE}
+ onClick={() => onChange({ fontSize: Math.min(MAX_FONT_SIZE, fontSize + 1) })}
+ />
+ <PreferenceButton
+ label={serif ? t("Use sans-serif font") : t("Use serif font")}
+ icon={ALargeSmall}
+ active={!serif}
+ onClick={() => onChange({ serif: !serif })}
+ />
+ <PreferenceButton
+ label={t("Change line width ({{width}} characters)", { width: lineWidth })}
+ icon={Rows3}
+ onClick={() =>
+ onChange({
+ lineWidth:
+ LINE_WIDTH_STEPS.find((width) => width > lineWidth) ??
+ MIN_LINE_WIDTH,
+ })
+ }
+ />
+ <PreferenceButton
+ label={t("Change reading theme")}
+ icon={SunMoon}
+ active={readerTheme !== "auto"}
+ onClick={() =>
+ onChange({
+ readerTheme:
+ readerTheme === "auto"
+ ? "sepia"
+ : readerTheme === "sepia"
+ ? "night"
+ : "auto",
+ })
+ }
+ />
+ {showSpread && (
+ <PreferenceButton
+ label={
+ spreadMode === "none"
+ ? t("Switch to two-page spread")
+ : t("Switch to single-page view")
+ }
+ icon={Columns2}
+ active={spreadMode === "auto"}
+ onClick={() =>
+ onChange({ spreadMode: spreadMode === "none" ? "auto" : "none" })
+ }
+ />
+ )}
+ <PreferenceButton
+ label={t("Reset reading display")}
+ icon={RotateCcw}
+ onClick={() => onChange(DEFAULT_READER_DISPLAY_PREFERENCES)}
+ />
+ </div>
+ );
+}
diff --git a/web/components/reading/TextUnitView.tsx b/web/components/reading/TextUnitView.tsx
index dfb8c1c10..1355579d8 100644
--- a/web/components/reading/TextUnitView.tsx
+++ b/web/components/reading/TextUnitView.tsx
@@ -1,7 +1,5 @@
"use client";
-import { browserStorage } from "@/shared/storage";
-
import {
Fragment,
useCallback,
@@ -11,15 +9,9 @@ import {
useState,
} from "react";
import {
- ALargeSmall,
ChevronLeft,
ChevronRight,
Loader2,
- Minus,
- Plus,
- RotateCcw,
- Rows3,
- SunMoon,
} from "lucide-react";
import { useTranslation } from "react-i18next";
import RichMarkdownRenderer from "@/components/common/RichMarkdownRenderer";
@@ -30,11 +22,12 @@ import {
DEFAULT_LINE_WIDTH,
DEFAULT_READER_DISPLAY_PREFERENCES,
MAX_FONT_SIZE,
- MAX_LINE_WIDTH,
MIN_FONT_SIZE,
- MIN_LINE_WIDTH,
- normaliseReaderDisplayPreferences,
+ loadReaderDisplayPreferences,
readerDisplayShortcut,
+ saveReaderDisplayPreferences,
+ type EpubSpreadMode,
+ type ReaderDisplayPreferences,
type ReaderTheme,
} from "@/lib/reading-display-preferences";
import {
@@ -47,6 +40,7 @@ import { cleanQuote } from "@/lib/reading-selection";
import { MarkdownLine } from "@/lib/reading-inline-markdown";
import { toRecogitoTextAnnotation } from "@/lib/reading-w3c-annotations";
import type { JumpRequest, SelectionPayload } from "./PdfDocumentView";
+import { PreferenceButton, ReaderDisplayControls } from "./ReaderDisplayControls";
const COLOR_INK: Record<string, string> = {
yellow: "250 220 90",
@@ -56,9 +50,6 @@ const COLOR_INK: Record<string, string> = {
purple: "199 174 250",
};
-const READER_PREFS_KEY = "dt.reader.textPreferences";
-const LINE_WIDTH_STEPS = [48, 64, 84, 104];
-
export interface TextUnitViewProps {
materialId: string;
unit: UnitKind;
@@ -121,50 +112,34 @@ export function TextUnitView({
const [lineWidth, setLineWidth] = useState(DEFAULT_LINE_WIDTH);
const [serif, setSerif] = useState(true);
const [readerTheme, setReaderTheme] = useState<ReaderTheme>("auto");
+ const [spreadMode, setSpreadMode] = useState<EpubSpreadMode>("none");
const isWebMarkdown = contentFormat === "web_markdown";
// Sepia and Night are whole-surface paper: a sheet drawn on top of them
// would be a second, differently coloured page inside the first.
const paperSheet = readerTheme === "auto";
useEffect(() => {
- try {
- const value = normaliseReaderDisplayPreferences(
- JSON.parse(browserStorage.readRaw("local", READER_PREFS_KEY) || "{}"),
- );
- setFontSize(value.fontSize);
- setLineWidth(value.lineWidth);
- setSerif(value.serif);
- setReaderTheme(value.readerTheme);
- } catch {
- // Invalid or unavailable local storage falls back to readable defaults.
- }
+ const value = loadReaderDisplayPreferences();
+ setFontSize(value.fontSize);
+ setLineWidth(value.lineWidth);
+ setSerif(value.serif);
+ setReaderTheme(value.readerTheme);
+ setSpreadMode(value.spreadMode);
}, []);
const updatePreferences = useCallback(
(
- next: Partial<{
- fontSize: number;
- lineWidth: number;
- serif: boolean;
- readerTheme: ReaderTheme;
- }>,
+ next: Partial<ReaderDisplayPreferences>,
) => {
- const merged = { fontSize, lineWidth, serif, readerTheme, ...next };
+ const merged = { fontSize, lineWidth, serif, readerTheme, spreadMode, ...next };
setFontSize(merged.fontSize);
setLineWidth(merged.lineWidth);
setSerif(merged.serif);
setReaderTheme(merged.readerTheme);
- try {
- browserStorage.writeRaw(
- "local",
- READER_PREFS_KEY,
- JSON.stringify(merged),
- );
- } catch {
- // Preferences still apply for the current session.
- }
+ setSpreadMode(merged.spreadMode);
+ saveReaderDisplayPreferences(merged);
},
- [fontSize, lineWidth, readerTheme, serif],
+ [fontSize, lineWidth, readerTheme, serif, spreadMode],
);
const changeFontSize = useCallback(
@@ -180,12 +155,6 @@ export function TextUnitView({
updatePreferences(DEFAULT_READER_DISPLAY_PREFERENCES);
}, [updatePreferences]);
- const cycleLineWidth = useCallback(() => {
- const nextWidth =
- LINE_WIDTH_STEPS.find((width) => width > lineWidth) ?? MIN_LINE_WIDTH;
- updatePreferences({ lineWidth: nextWidth });
- }, [lineWidth, updatePreferences]);
-
useEffect(() => {
const onKeyDown = (event: KeyboardEvent) => {
const root = readerRootRef.current;
@@ -485,57 +454,10 @@ export function TextUnitView({
position is the header's to state, since that is the one line that is
there in every render mode. What is left here is what you can *do*. */}
<div className="flex items-center justify-between gap-2 overflow-x-auto border-b border-[var(--border)] px-2 py-2 sm:px-3">
- <div className="flex shrink-0 items-center gap-0.5">
- <PreferenceButton
- label={t("Smaller text ({{percent}}%)", {
- percent: Math.round((fontSize / 16) * 100),
- })}
- icon={Minus}
- disabled={fontSize <= MIN_FONT_SIZE}
- onClick={() => changeFontSize(fontSize - 1)}
- />
- <PreferenceButton
- label={t("Larger text ({{percent}}%)", {
- percent: Math.round((fontSize / 16) * 100),
- })}
- icon={Plus}
- disabled={fontSize >= MAX_FONT_SIZE}
- onClick={() => changeFontSize(fontSize + 1)}
- />
- <PreferenceButton
- label={serif ? t("Use sans-serif font") : t("Use serif font")}
- icon={ALargeSmall}
- active={!serif}
- onClick={() => updatePreferences({ serif: !serif })}
- />
- <PreferenceButton
- label={t("Change line width ({{width}} characters)", {
- width: lineWidth,
- })}
- icon={Rows3}
- onClick={cycleLineWidth}
- />
- <PreferenceButton
- label={t("Change reading theme")}
- icon={SunMoon}
- active={readerTheme !== "auto"}
- onClick={() =>
- updatePreferences({
- readerTheme:
- readerTheme === "auto"
- ? "sepia"
- : readerTheme === "sepia"
- ? "night"
- : "auto",
- })
- }
- />
- <PreferenceButton
- label={t("Reset reading display")}
- icon={RotateCcw}
- onClick={resetPreferences}
- />
- </div>
+ <ReaderDisplayControls
+ preferences={{ fontSize, lineWidth, serif, readerTheme, spreadMode }}
+ onChange={updatePreferences}
+ />
<div className="flex shrink-0 items-center gap-0.5">
<PreferenceButton
label={t("Previous {{unit}}", { unit: t(unitLabel(unit)) })}
@@ -624,38 +546,6 @@ export function TextUnitView({
);
}
-function PreferenceButton({
- label,
- icon: Icon,
- active = false,
- disabled = false,
- onClick,
-}: {
- label: string;
- icon: typeof Minus;
- active?: boolean;
- disabled?: boolean;
- onClick: () => void;
-}) {
- return (
- <button
- type="button"
- title={label}
- aria-label={label}
- aria-pressed={active}
- disabled={disabled}
- onClick={onClick}
- className={`inline-flex h-7 w-7 items-center justify-center rounded-lg transition hover:bg-[var(--muted)] disabled:opacity-35 disabled:hover:bg-transparent ${
- active
- ? "text-[var(--foreground)]"
- : "text-[var(--muted-foreground)] hover:text-[var(--foreground)]"
- }`}
- >
- <Icon size={15} />
- </button>
- );
-}
-
function TextWithHeadings({
text,
headings,
diff --git a/web/lib/reading-display-preferences.ts b/web/lib/reading-display-preferences.ts
index d97fc0427..201c67782 100644
--- a/web/lib/reading-display-preferences.ts
+++ b/web/lib/reading-display-preferences.ts
@@ -1,10 +1,14 @@
+import { browserStorage } from "@/shared/storage";
+
export type ReaderTheme = "auto" | "sepia" | "night";
+export type EpubSpreadMode = "none" | "auto";
export interface ReaderDisplayPreferences {
fontSize: number;
lineWidth: number;
serif: boolean;
readerTheme: ReaderTheme;
+ spreadMode: EpubSpreadMode;
}
export const DEFAULT_FONT_SIZE = 17;
@@ -13,11 +17,13 @@ export const MAX_FONT_SIZE = 28;
export const DEFAULT_LINE_WIDTH = 84;
export const MIN_LINE_WIDTH = 48;
export const MAX_LINE_WIDTH = 104;
+export const READER_PREFS_KEY = "dt.reader.textPreferences";
export const DEFAULT_READER_DISPLAY_PREFERENCES: ReaderDisplayPreferences = {
fontSize: DEFAULT_FONT_SIZE,
lineWidth: DEFAULT_LINE_WIDTH,
serif: true,
readerTheme: "auto",
+ spreadMode: "none",
};
function bounded(
@@ -43,6 +49,7 @@ export function normaliseReaderDisplayPreferences(
)
? (row.readerTheme as ReaderTheme)
: DEFAULT_READER_DISPLAY_PREFERENCES.readerTheme;
+ const spreadMode = row.spreadMode === "auto" ? "auto" : "none";
return {
fontSize: bounded(
row.fontSize,
@@ -61,9 +68,26 @@ export function normaliseReaderDisplayPreferences(
? row.serif
: DEFAULT_READER_DISPLAY_PREFERENCES.serif,
readerTheme,
+ spreadMode,
};
}
+export function loadReaderDisplayPreferences(): ReaderDisplayPreferences {
+ try {
+ return normaliseReaderDisplayPreferences(
+ JSON.parse(browserStorage.readRaw("local", READER_PREFS_KEY) || "{}"),
+ );
+ } catch {
+ return DEFAULT_READER_DISPLAY_PREFERENCES;
+ }
+}
+
+export function saveReaderDisplayPreferences(
+ preferences: ReaderDisplayPreferences,
+): void {
+ browserStorage.writeRaw("local", READER_PREFS_KEY, JSON.stringify(preferences));
+}
+
export type ReaderDisplayShortcut = "increase" | "decrease" | "reset";
export function readerDisplayShortcut(input: {
diff --git a/web/tests/epub-display-preferences.spec.tsx b/web/tests/epub-display-preferences.spec.tsx
new file mode 100644
index 000000000..b1763217a
--- /dev/null
+++ b/web/tests/epub-display-preferences.spec.tsx
@@ -0,0 +1,136 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { beforeEach, expect, it, vi } from "vitest";
+
+import { initI18n } from "@/i18n/init";
+
+initI18n("en");
+
+const fixture = vi.hoisted(() => {
+ const rendition = {
+ display: vi.fn(async () => undefined),
+ currentLocation: vi.fn(() => ({ start: { cfi: "epubcfi(/6/2)" } })),
+ next: vi.fn(async () => undefined),
+ prev: vi.fn(async () => undefined),
+ resize: vi.fn(),
+ spread: vi.fn(),
+ destroy: vi.fn(),
+ on: vi.fn(),
+ off: vi.fn(),
+ annotations: { highlight: vi.fn(), remove: vi.fn() },
+ hooks: { content: { register: vi.fn() } },
+ themes: {
+ register: vi.fn(),
+ select: vi.fn(),
+ fontSize: vi.fn(),
+ override: vi.fn(),
+ removeOverride: vi.fn(),
+ },
+ };
+ return {
+ rendition,
+ renderTo: vi.fn(() => rendition),
+ apiFetch: vi.fn(async () => ({
+ ok: true,
+ arrayBuffer: async () => new ArrayBuffer(8),
+ })),
+ };
+});
+
+vi.mock("epubjs", () => ({
+ default: () => ({
+ open: async () => undefined,
+ ready: Promise.resolve(),
+ renderTo: fixture.renderTo,
+ spine: { get: () => ({ href: "one.xhtml" }) },
+ destroy: vi.fn(),
+ }),
+}));
+vi.mock("@/lib/api", () => ({ apiFetch: fixture.apiFetch }));
+vi.mock("@/lib/reading-api", () => ({
+ rawMaterialUrl: () => "/api/reading/materials/book/raw",
+ getReadingPosition: async () => ({ locator: 1 }),
+ saveReadingPosition: vi.fn(async () => undefined),
+}));
+
+import { EpubDocumentView } from "@/components/reading/EpubDocumentView";
+
+beforeEach(() => {
+ vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockReturnValue({
+ x: 0,
+ y: 0,
+ top: 0,
+ left: 0,
+ right: 900,
+ bottom: 600,
+ width: 900,
+ height: 600,
+ toJSON: () => ({}),
+ });
+});
+
+it("opens EPUB in single-page mode and keeps the CFI when switching spreads", async () => {
+ render(
+ <EpubDocumentView
+ materialId="book"
+ unitCount={1}
+ unitRefs={[]}
+ annotations={[]}
+ jump={null}
+ onSelection={() => undefined}
+ />,
+ );
+
+ await waitFor(() =>
+ expect(fixture.renderTo).toHaveBeenCalledWith(
+ expect.any(Element),
+ expect.objectContaining({ spread: "none" }),
+ ),
+ );
+ fireEvent.click(screen.getByRole("button", { name: "Switch to two-page spread" }));
+
+ await waitFor(() => expect(fixture.rendition.spread).toHaveBeenCalledWith("auto"));
+ await waitFor(() =>
+ expect(fixture.rendition.resize).toHaveBeenCalledWith(900, 600),
+ );
+ expect(fixture.rendition.display).toHaveBeenCalledWith("epubcfi(/6/2)");
+ expect(JSON.parse(localStorage.getItem("dt.reader.textPreferences") || "{}"))
+ .toMatchObject({ spreadMode: "auto" });
+});
+
+it("applies saved typography and theme to EPUB content", async () => {
+ localStorage.setItem(
+ "dt.reader.textPreferences",
+ JSON.stringify({ fontSize: 23, serif: false, readerTheme: "night", spreadMode: "auto" }),
+ );
+ render(
+ <EpubDocumentView
+ materialId="book"
+ unitCount={1}
+ unitRefs={[]}
+ annotations={[]}
+ jump={null}
+ onSelection={() => undefined}
+ />,
+ );
+
+ await waitFor(() =>
+ expect(fixture.renderTo).toHaveBeenCalledWith(
+ expect.any(Element),
+ expect.objectContaining({ spread: "auto" }),
+ ),
+ );
+ expect(fixture.rendition.themes.fontSize).toHaveBeenCalledWith("23px");
+ expect(fixture.rendition.themes.override).toHaveBeenCalledWith(
+ "background-color",
+ "#16181d",
+ true,
+ );
+ fireEvent.click(screen.getByRole("button", { name: "Reset reading display" }));
+ await waitFor(() =>
+ expect(fixture.rendition.themes.removeOverride).toHaveBeenCalledWith(
+ "background-color",
+ ),
+ );
+ expect(JSON.parse(localStorage.getItem("dt.reader.textPreferences") || "{}"))
+ .toMatchObject({ fontSize: 17, readerTheme: "auto", spreadMode: "none" });
+});
diff --git a/web/tests/reading-display-preferences.test.ts b/web/tests/reading-display-preferences.test.ts
index a3e191403..e0fbe37c0 100644
--- a/web/tests/reading-display-preferences.test.ts
+++ b/web/tests/reading-display-preferences.test.ts
@@ -14,11 +14,13 @@ import {
} from "../lib/reading-display-preferences";
const reader = readFileSync("components/reading/TextUnitView.tsx", "utf8");
+const controls = readFileSync("components/reading/ReaderDisplayControls.tsx", "utf8");
+const preferenceStore = readFileSync("lib/reading-display-preferences.ts", "utf8");
const en = readFileSync("locales/en/app.json", "utf8");
const zh = readFileSync("locales/zh/app.json", "utf8");
test("text reader exposes persistent display preferences", () => {
- assert.match(reader, /dt\.reader\.textPreferences/);
+ assert.match(preferenceStore, /dt\.reader\.textPreferences/);
assert.deepEqual(
[DEFAULT_FONT_SIZE, MIN_FONT_SIZE, MAX_FONT_SIZE],
[17, 12, 28],
@@ -27,7 +29,8 @@ test("text reader exposes persistent display preferences", () => {
[DEFAULT_LINE_WIDTH, MIN_LINE_WIDTH, MAX_LINE_WIDTH],
[84, 48, 104],
);
- assert.match(reader, /browserStorage\.writeRaw\(\s*"local"/);
+ assert.match(preferenceStore, /browserStorage\.writeRaw\(\s*"local"/);
+ assert.match(reader, /saveReaderDisplayPreferences\(merged\)/);
});
test("reset includes typography and theme preferences", () => {
@@ -36,6 +39,7 @@ test("reset includes typography and theme preferences", () => {
lineWidth: 84,
serif: true,
readerTheme: "auto",
+ spreadMode: "none",
});
assert.match(
reader,
@@ -50,8 +54,15 @@ test("stored preferences are bounded and malformed values fall back", () => {
lineWidth: 3,
serif: false,
readerTheme: "night",
+ spreadMode: "auto",
}),
- { fontSize: 28, lineWidth: 48, serif: false, readerTheme: "night" },
+ {
+ fontSize: 28,
+ lineWidth: 48,
+ serif: false,
+ readerTheme: "night",
+ spreadMode: "auto",
+ },
);
assert.deepEqual(
normaliseReaderDisplayPreferences({ readerTheme: "invalid" }),
@@ -60,6 +71,7 @@ test("stored preferences are bounded and malformed values fall back", () => {
lineWidth: 84,
serif: true,
readerTheme: "auto",
+ spreadMode: "none",
},
);
});
@@ -102,6 +114,8 @@ test("reader display copy is translated", () => {
"Use serif font",
"Change line width ({{width}} characters)",
"Change reading theme",
+ "Switch to two-page spread",
+ "Switch to single-page view",
]) {
const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
assert.match(en, new RegExp(`"${escaped}": "`));
@@ -110,7 +124,7 @@ test("reader display copy is translated", () => {
});
test("the reader's state is spoken by the control that changes it", () => {
- const view = reader;
+ const view = controls;
// The size and width used to sit in silent spans beside their buttons —
// visible to a sighted reader, announced to nobody, and reading like debug