Skip to content

feat(epub-reader): improve chapter resolution and progress slider UX - #3201

Merged
AlexAndBear merged 11 commits into
mainfrom
feat/epub-slider-preview-percent
Aug 24, 2026
Merged

feat(epub-reader): improve chapter resolution and progress slider UX#3201
AlexAndBear merged 11 commits into
mainfrom
feat/epub-slider-preview-percent

Conversation

@AlexAndBear

@AlexAndBear AlexAndBear commented Aug 22, 2026

Copy link
Copy Markdown
Member

Description

This PR improves the EPUB reader with multiple enhancements:

Chapter Resolution

  • Fixed multi-chapter resolution bug: EPUBs with multiple chapters in the same file (e.g., Moby Dick with 15 chapters in one .xhtml file) now correctly highlight the active chapter using DOM position comparison
  • Added fallback strategy using compareDocumentPosition() for accurate chapter detection

Progress Slider UX

  • Live seek while dragging: Slider now updates reading position in real-time during drag for more direct interaction

Code Quality & Stability

  • Type safety: Removed all as any type casts, added proper TypeScript definitions for epubjs
  • Props handling: Use destructuring instead of props.x pattern for cleaner code
  • Translations: Components handle their own translatable labels instead of receiving them as props
  • Null safety: Added comprehensive null checks for rendition access throughout
  • Race conditions: Fixed cleanup issues in text search and component destruction
  • Resource management: Proper cleanup on unmount to prevent memory leaks

Related Issue

  • Fixes N/A

How Has This Been Tested?

  • test environment: local macOS dev environment
  • test case 1: pnpm test:unit --run packages/web-app-epub-reader (all 50 tests passing)
  • test case 2: pnpm check:all (types, lint, format, tests)
  • test case 3: manually test with complex EPUBs (Moby Dick) - chapter highlighting works correctly
  • test case 4: manually drag progress slider - real-time seeking works smoothly

Types of changes

  • Bugfix (chapter resolution for multi-chapter files)
  • Enhancement (live slider seek, type safety improvements)
  • Breaking change (a modification that affects current functionality)
  • Technical debt (code cleanup, proper TypeScript definitions)
  • Tests (updated tests for new slider behavior)
  • Documentation (updates or additions to documentation)
  • Maintenance (like dependency updates or tooling adjustments)

- Remove unnecessary label props from all components
- Components now use $gettext() directly in templates instead of passing labels from parents
- ReaderProgressBar calculates its own progress label from percent value
- Remove 55 lines of redundant label prop handling and intermediate variables
- Update tests to reflect simplified component APIs
@AlexAndBear
AlexAndBear force-pushed the feat/epub-slider-preview-percent branch from f537d76 to dc4d6dc Compare August 22, 2026 21:13
@AlexAndBear
AlexAndBear force-pushed the feat/epub-slider-preview-percent branch 2 times, most recently from f9ac0ed to 4d5d5c3 Compare August 23, 2026 11:32
@AlexAndBear AlexAndBear changed the title feat(epub-reader): preview percent while dragging progress slider feat(epub-reader): improve chapter resolution and progress slider UX Aug 23, 2026
@github-project-automation github-project-automation Bot moved this to Qualification in OpenCloud Team Board Aug 24, 2026
@AlexAndBear AlexAndBear moved this from Qualification to In Progress in OpenCloud Team Board Aug 24, 2026
Remove preview bubble, slider now updates reading position in real-time during drag.
Use lodash throttle (150ms) to limit seek frequency during drag for smooth performance.
- Extract chapter resolution functions to dedicated helper file
- Add comprehensive unit tests for all resolution strategies
- Improve Strategy 4b with spine-index fallback for edge cases
- Consolidate fallback logic to return first chapter consistently
- Remove redundant fallback handling from App.vue
@AlexAndBear
AlexAndBear force-pushed the feat/epub-slider-preview-percent branch from fbaf9e0 to 7790c80 Compare August 24, 2026 08:54
@AlexAndBear
AlexAndBear merged commit 1e52dd0 into main Aug 24, 2026
31 checks passed
@AlexAndBear
AlexAndBear deleted the feat/epub-slider-preview-percent branch August 24, 2026 12:58
@github-project-automation github-project-automation Bot moved this from In Progress to Done in OpenCloud Team Board Aug 24, 2026
@openclouders openclouders mentioned this pull request Aug 24, 2026
1 task
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

2 participants