> For the complete documentation index, see [llms.txt](https://docs.wellcomecollection.org/request-for-comments-rfcs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wellcomecollection.org/request-for-comments-rfcs/086-item-viewer-refactor/13-migration-checklist.md). # Migration Checklist [← Back to Index](/request-for-comments-rfcs/086-item-viewer-refactor.md) This checklist helps you track progress through each phase. Check off items as you complete them. ## Before Starting * [ ] Create feature branch: `refactor/iiif-viewer-context` * [ ] Ensure all tests pass on main branch * [ ] Read through all phase documents * [ ] Understand the test-first workflow *** ## Phase 0: Type Audit and Cleanup Duration: 1-1.5 hours * [ ] Fix `setSearchResults: (v) => void` to `setSearchResults: (v: SearchResults | null) => void` in: * [ ] `content/webapp/contexts/ItemViewerContext/index.tsx` * [ ] `content/webapp/views/pages/works/work/IIIFViewer/IIIFViewer.tsx` * [ ] (Optional) Add `ImageService` type to `content/webapp/types/item-viewer.ts` * [ ] Document existing type structure in Phase 0 doc * [ ] Verify custom types properly use `@iiif/presentation-3` official types * [ ] (Optional) Check if Catalogue API has OpenAPI spec at * [ ] Run `yarn tsc` * [ ] Verify no TypeScript errors in ItemViewer files * [ ] Commit type fixes **Time checkpoint:** Should take 1-1.5 hours *** ## Phase 1: Feature Flag Setup **Duration: 1 hour** * [ ] Add `iiifViewerRefactored` toggle definition in `toggles/webapp/app/toggles.ts` * [ ] Create `content/webapp/contexts/ItemViewerContextV2` directory * [ ] Copy ItemViewerContext to ItemViewerContextV2 * [ ] Rename all component files to `.legacy.tsx` * [ ] Create wrapper component `index.tsx` that switches based on flag * [ ] Create `.refactored.tsx` files (copies of legacy) * [ ] Update `.refactored.tsx` imports to use ItemViewerContextV2 * [ ] Run `yarn content` - application starts * [ ] Test with flag OFF - uses legacy * [ ] Test with flag ON - uses refactored (identical to legacy) * [ ] No TypeScript errors * [ ] No console warnings **Time checkpoint:** Should take \~1 hour *** ## Phase 2: Split MainViewer Components **Duration: 3-4 hours** * [ ] Create `VirtualizedImageViewer.tsx` (extract from MainViewer) * [ ] Create `PaginatedItemViewer.tsx` (extract from MainViewer) * [ ] Update `MainViewer.tsx` to be simple router component * [ ] Write tests for `VirtualizedImageViewer.test.tsx` * [ ] Write tests for `PaginatedItemViewer.test.tsx` * [ ] Write tests for `MainViewer.test.tsx` (routing logic) * [ ] Verify image-only works still render correctly * [ ] Verify archive works still render correctly * [ ] No regression in E2E tests * [ ] No console errors * [ ] Bundle size hasn't increased significantly **Time checkpoint:** Should take \~3-4 hours *** ## Phase 3: Derived Canvas Data ### 3.1: Write Automated Tests FIRST * [ ] Create `content/webapp/contexts/ItemViewerContextV2/ItemViewerContextV2.test.tsx` * [ ] Create `content/webapp/contexts/ItemViewerContextV2/test-utils.ts` with typed mocks * [ ] Write tests for all derived canvas data * [ ] Write tests for all boolean flags * [ ] Write tests for edge cases (undefined, null, empty) * [ ] Create `IIIFViewer.refactored.test.tsx` integration tests * [ ] Create `ViewerTopBar.refactored.test.tsx` component tests * [ ] Run tests - all pass with current (minimal) implementation ### 3.2 Implementation * [ ] Add derived values to `IIIFViewer.refactored.tsx` provider * [ ] `currentCanvasIndex` * [ ] `currentCanvas` * [ ] `mainImageService` * [ ] `hasMultipleCanvases` * [ ] `isFirstCanvas`, `isLastCanvas` * [ ] `canNavigateNext`, `canNavigatePrevious` * [ ] `isCurrentCanvasRestricted` * [ ] `hasIiifImageService` * [ ] Update `ItemViewerContextV2` type definition * [ ] Update `ViewerTopBar.refactored.tsx` to use context values * [ ] Update `ZoomedImage.refactored.tsx` to use context values * [ ] Update `MainViewer.refactored.tsx` to use context values * [ ] Update styled components to use `hasMultipleCanvases` ### 3.3 Verification * [ ] Run automated tests - all pass * [ ] `yarn tsc` - no TypeScript errors * [ ] Toggle flag OFF/ON - behaviour identical * [ ] (Optional) Manual testing checklist from [14-testing-strategy.md](/request-for-comments-rfcs/086-item-viewer-refactor/14-testing-strategy.md) **Time checkpoint:** Should take \~6-7 hours total (3h tests + 3-4h implementation) *** ## Phase 4: Download Logic Hook ### 4.1 Write Tests FIRST * [ ] Create `content/webapp/hooks/useDownloadOptions.test.ts` * [ ] Test empty case (no canvas/manifest) * [ ] Test IIIF image downloads * [ ] Test canvas image downloads from services * [ ] Test canvas rendering downloads (PDFs) * [ ] Test manifest downloads * [ ] Test video/audio downloads * [ ] Test `ChoiceBody` handling * [ ] Test memoization * [ ] All tests pass ### 4.2 Implementation * [ ] Create `content/webapp/hooks/useDownloadOptions.ts` * [ ] Extract download logic from `ViewerTopBar` * [ ] Update `ViewerTopBar.refactored.tsx` to use hook * [ ] Remove \~65 lines from `ViewerTopBar` ### 4.3 Verification * [ ] Run automated tests - all pass * [ ] Download dropdown appears * [ ] All download options present * [ ] Download links work * [ ] Options update when navigating canvases **Time checkpoint:** Should take \~4 hours (2h tests + 2h implementation) *** ## Phase 5: Restriction Status * [ ] Add `isCurrentCanvasRestricted` to context type * [ ] Calculate in IIIFViewer.refactored.tsx * [ ] Update ViewerTopBar.refactored.tsx to use context value * [ ] Remove local calculation from ViewerTopBar * [ ] Test restricted badge appears correctly * [ ] Test download options respect restriction **Time checkpoint:** Should take \~1 hour *** ## Phase 6: Duplicate Index Calls * [ ] Find all `queryParamToArrayIndex(query.canvas)` calls * [ ] Update Thumbnails.tsx to use `currentCanvasIndex` from context * [ ] Update NoScriptImage.tsx to use `currentCanvasIndex` * [ ] Update MultipleManifestList.tsx to use `currentCanvasIndex` * [ ] Update any other files found * [ ] Test thumbnails highlight correctly * [ ] Test all navigation works **Time checkpoint:** Should take \~30 minutes *** ## Phase 7: Cleanup (After Defaulting to ON) **Only do this after toggle defaults to ON for 1+ week with no issues!** * [ ] Remove feature flag from `toggles.ts` * [ ] Delete all `.legacy.tsx` files- \[ ] Rename `.refactored.tsx` to `.tsx` * [ ] Delete wrapper `index.tsx` * [ ] Delete old `ItemViewerContext` directory * [ ] Rename `ItemViewerContextV2` to `ItemViewerContext` * [ ] Update all imports from V2 to standard * [ ] Rename test files (remove .refactored) * [ ] Update test imports * [ ] Run all tests - still pass * [ ] `yarn tsc` - no errors * [ ] Application runs correctly **Time checkpoint:** Should take \~1-2 hours *** ## Final Verification * [ ] All automated tests pass * [ ] No TypeScript errors * [ ] No console warnings * [ ] Feature flag works (or removed if cleanup done) * [ ] Manual testing on all browsers * [ ] Performance metrics unchanged * [ ] Code is cleaner and more maintainable * [ ] Documentation updated *** ## Rollout Checklist * [ ] **Internal testing** - Enable for team members, verify functionality * [ ] **Make toggle public** - Available in toggles dashboard for anyone to enable * [ ] **Monitor** - Watch Sentry, user reports, performance metrics * [ ] **Wait 1-2 weeks** - Let users opt in, gather feedback * [ ] **Default to ON** - Change defaultValue to true (users can still opt out) * [ ] **Monitor more** - Watch for issues with new default * [ ] **Wait 1+ week** - Ensure stability with new default * [ ] **Cleanup** - Remove feature flag entirely (Phase 7) **If issues at any stage:** Disable toggle or revert default, investigate, fix, try again. *** ## Total Time Estimate * Phase 0: 1-1.5 hours * Phase 1: 1 hour * Phase 2: 3-4 hours * Phase 3: 6-7 hours * Phase 4: 4 hours * Phase 5: 1 hour * Phase 6: 30 minutes * Phase 7: 1-2 hours **Total: 17.5-21 hours** *** **Next:** [Testing Strategy](/request-for-comments-rfcs/086-item-viewer-refactor/14-testing-strategy.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.wellcomecollection.org/request-for-comments-rfcs/086-item-viewer-refactor/13-migration-checklist.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.