Skip to content

v4.0.0

Choose a tag to compare

View all tags
@marlo-longley marlo-longley released this 09 Oct 16:26
· 452 commits to main since this release
v4.0.0
ce377cf
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Mirador 4 Release Notes

Mirador v4 is a major refresh of many of the upstream dependencies of this project. Notably, Mirador v4 allows downstream application use to React 19 and Material UI 7. Many other Mirador dependencies, as well as a number of commonly used plugins, have been upgraded with modern equivalents.

This release includes breaking changes and significant architectural refactoring. Upgrading from Mirador 3.x or earlier requires updates to custom plugins, integrations, or theming.

Significant changes in Mirador 4

  • The upgrade from React 16 to version 19 required significant changes to core application behaviors due to fundamentally new or different methods and functions
  • The testing suite in version 4 has been replaced with React Test Library (RTL) and all tests have been rewritten
  • The upgrade to from Material UI 4 to version 7 required significant changes to class names and selectors corresponding to global interface elements
  • Mirador 4 replaces JSS with Emotion as its styling engine
  • Plugins for Mirador v4 will no longer offer UMD build options, only ES. Use vite to integrate the ES version of the packages.
  • The Mirador build now exposes most functions and components at the top level, requiring imports like e.g. import { settings } from 'mirador'; instead of import settings from 'mirador/dist/es/src/config/settings'. Downstream code (e.g. in plugins) has to be adapted, but the change should be straightforward.
  • After feedback from users and IIIF spec editors, Mirador 4 now displays multiple images on a Canvas from bottom to top to be more in line with expectations.

Most dependency upgrades needed to be performed in serial increments. For example, it was necessary to upgrade React from version 16 to version 17 first, then to 18, etc., rather than upgrade directly to version 19. Mirador application developers managing customized implementations are encouraged to read through the following upgrade guides referenced by core contributors in the course of update work:

Developers are further invited to review the changes listed below to see what was necessary in Mirador.

Special thanks to all contributors and maintainers for this massive modernization!

UI Improvements

  • Comprehensive style updates aligned with MUI 5, 6, and 7, ensuring consistent look and feel, better dark mode support, and fewer runtime style errors (#3648, #3857, #3839, #3842).
  • Improved collection and annotation chip display, workspace and sidebar padding, menu and button alignment, and visually cohesive component margins (#3810, #3812, #3809, #3808).
  • Significant refactor of style logic—styles moved "up" for consistent theming, easier maintenance, and transition to new theme APIs (#3841, #3838, #3854, #3834, #3852).
  • Many small fixes: proper focus styles, badge color use, custom tooltip margins, dark mode WorkspaceExport forms, branding alignment (#3831, #3856, #3843).
  • [MUI] Styles for ToC nodes, improved borders and collapse icons, companion window section, and drag handle spacing (#3811, #3813).
  • Workspace sidebar and window bar restyled, with better layout and flexbox (#3849, #3840).

React

  • Upgraded core from React 16 to 17, 18, and added preliminary support for React 19, with breaking changes as necessary (#3741, #3864, #4126).
  • All class components and higher-order components refactored to modern functional components and hooks for simpler, safer code (#3992, #3996, #4021, #4018).

MUI (Material UI)

  • Major migration from MUI v4 to v5, MUI 6, and to MUI 7 (#3648, #4092, #4139).
  • Removal of deprecated @mui/styles, upgrades of all component styles, replaced custom stylings with MUI variants, and improved theme handling (#3862, #3833).
  • New dialog/modal variants, sidebar collapsing sections now use MUI Accordion (#3827, #3822).
  • Numerous UI bug fixes related to component spacing, focus, menu states, and color (#3821, #3982, #3814).
  • MUI and react-i18next now peer dependencies (#4113).

Internationalization (i18n)

  • Expanded translations and locales: added Bulgarian, Farsi, Estonian, Croatian, Hungarian (#3589, #3738, #3891, #3931, #4143).
  • Numerous updates and improvements to existing translations: Italian, German, Chinese, Japanese, and UI locale handling (#3905, #3513, #3788, #3910).
  • Improved manifest summary/description locale detection (#3780).
  • Language picker enhancements and "lang" attribute support (#4058, #4132).
  • Demo page with i18n examples (#4076).

IIIF Support

  • IIIF v3 manifest summary and provider logos supported, along with v3 annotation captions (#3633, #3657, #3664).
  • Support for multiple IIIF resource services (#4133).
  • Improved IIIFThumbnail component (#3824).
  • Added selector and UI for related items (#3535).

Accessibility

  • Numerous a11y improvements: correct aria-hidden propagation, use of useId for unique IDs, cursor icon improvements (#3641, #4055, #3644).
  • Enhanced keyboard navigation in WindowTopMenu and tree views (#3914, #3728).

React Testing Library

  • Complete migration from Enzyme to React Testing Library (RTL), modernizing test suites for all components and plugin points (#3669, #3687, #3711, #3739).
  • CI and test reliability improvements, including compatibility with modern test environments (#3666, #3692).

Bug Fixes

  • Fixed numerous edge case and stability bugs, including viewport preservation, window focus, manifest errors, annotation rendering, and build regressions (#3922, #3986, #3510, #3927).
  • Menu and focus issues resolved, especially relating to MUI 5 updates (#3982, #3846).
  • Typos and logic errors corrected in CSS, settings, selectors, and language detection (#3519, #4134).
  • Crash prevention for mirador_crash and error handling for missing refs (#3927, #4076/commits/99e5a3e72a97eb3942ddd6e025219db59420244a).

Developer Experience

  • Vastly improved developer experience: switched to Vite from webpack, faster dev server and build (#3985, #4044).
  • Bumped CI to latest Node.js LTS versions, added Node 22.x, upgraded actions, sped up and stabilized tests (#3817, #3946).
  • Updated documentation (README, LICENSE, CONTRIBUTING, CODE_OF_CONDUCT), improved coverage tooling and reporting (#3554, #3682, #3800).
  • Dependency modernization: removed unused and deprecated packages, replaced polyfills, switched out / updated @redux-devtools, react-aria-live, react-full-screen, react-mosaic, react-dnd, puppeteer, and more (#3591, #3609, #3742).
  • Improved internal architecture: use of top-level named exports, structuredClone, and new hooks (#3991, #4083).

##Full Changelogs v3.3.0...v4.0.0.alpha-1
v4.0.0.alpha-1...v4.0.0.alpha-2
v4.0.0.alpha-2...v4.0.0-alpha.4
v4.0.0-alpha.4...v4.0.0-alpha.5
v4.0.0-alpha.5...v4.0.0-alpha.6
v4.0.0-alpha.6...v4.0.0-alpha.7
v4.0.0-alpha.7...v4.0.0-alpha.8
v4.0.0-alpha.5...v4.0.0-alpha.9
v4.0.0-alpha.9...v4.0.0-alpha.10
v4.0.0-alpha.10...v4.0.0-alpha.13
v4.0.0-alpha.13...v4.0.0-alpha.14
v4.0.0-alpha.14...v4.0.0-alpha.15
v4.0.0-alpha.15...v4.0.0-alpha.16
v4.0.0-alpha.16...v4.0.0-alpha.17

Assets 2
Loading