[Nutrient Web SDK 2024.2](https://www.nutrient.io/blog/pspdfkit-web-2024-2-new-unified-ui-icons/) introduces some potentially breaking changes. To determine if you need to take action, check your implementation and refer to the information below. ## Notable changes ### New API interface for clipboard annotation events The interface for the `annotations.paste` and `annotations.duplicate` events has changed. Instead of multiple events emitted for each annotation in the copy group, one event is emitted with an array of all the annotations that were duplicated or pasted: ```diff - type AnnotationsPasteEvent = { - annotation: AnnotationsUnion; - formField?: FormField; - previousAction: 'COPY' | 'CUT'; - originalAnnotation: AnnotationsUnion; - originalFormField?: FormField; + type AnnotationsDuplicateEvent = { + annotations: AnnotationsUnion[]; + formFields?: FormField[]; + originalAnnotations: AnnotationsUnion[]; + originalFormFields?: Map; }; - type AnnotationsDuplicateEvent = { - annotation: AnnotationsUnion; - formField?: FormField; - originalAnnotation: AnnotationsUnion; - originalFormField?: FormField; + type AnnotationsPasteEvent = AnnotationsDuplicateEvent & { + previousAction: 'COPY' | 'CUT'; }; ``` ### Viewer CSS reset In preparation for the upcoming user interface (UI) redesign, we added the following CSS reset to the SDK: ```css * { box-sizing: border-box; margin: 0; padding: 0; -moz-osx-font-smoothing: grayscale; -webkit-font-smoothing: antialiased; } ``` If you have custom styles that rely on the default box sizing or margins/paddings, you may need to update them to account for this change. ### Annotation keyboard navigation order The viewer now honors the annotation keyboard navigation order specified in a document. Due to this change, the order in which annotations are accessed with the keyboard may change. If you want to restore the previous tab order or a different one, you can do so using the new [`instance#setPageTabOrder`](https://www.nutrient.io/api/web/classes/NutrientViewer.Instance.html#setpagetaborder) API method: ```js // This example will reverse the keyboard navigation order of the annotations in page 0. instance.setPageTabOrder(0, (annotations) => annotations.map((annotation) => annotation.id).reverse() ); ``` ### Using shadow DOM instead of iframe With the move to using the shadow DOM by default for embedding Nutrient, it may be necessary to update your code to work with the new implementation. The following sections outline the changes you may need to make. #### Handling event targets in the shadow DOM A notable change is in how event targets are determined during event handling. This adjustment is crucial for accurately identifying elements within the Nutrient viewer, especially when dealing with events that bubble through the shadow DOM. Previously, when Nutrient was encapsulated within an iframe, event handling directly accessed `event.target` to identify the element interacting with the user. This straightforward approach worked well within the isolated document environment provided by the iframe. In the shadow DOM setup, events are retargeted as they bubble up to the main document, which can alter the `event.target` to reflect the shadow DOM’s host element, rather than the actual target element within the shadow DOM. To accurately identify the original target element where the event was dispatched, developers must now use `event.composedPath()`. This method returns an array of the nodes through which the event will pass. The first element of this array, `composedPath()[0]`, is the original target of the event, allowing for precise interaction handling within the Nutrient viewer: ```diff - const target = event.target; + const target = event.composedPath()[0]; ``` #### Drag events with shadow DOM Using the shadow DOM integration, handling drag events within Nutrient Web SDK has been updated to accommodate the encapsulation provided by the shadow DOM. Previously, handling drag events used to be done by attaching event handlers directly to the `contentDocument` of the Nutrient instance, which represented the document object of the viewer frame when using an iframe. With the shift to the shadow DOM, `instance.contentDocument` can now also return a `ShadowRoot` object, depending on whether Nutrient is running in shadow DOM mode. This change requires a different strategy for attaching event listeners. Instead of binding event listeners directly to the `contentDocument`, developers must now retrieve the host element of the shadow root to attach event listeners. This host element serves as the root container for Nutrient in shadow DOM mode, ensuring that events are captured and handled correctly within the encapsulated viewer environment: ```diff - instance.contentDocument.ondragover = function (event) { + // Get shadow root for `instance.contentDocument`. + const container = instance.contentDocument.host; + container.ondragover = function (event) { // Your logic here. } ``` #### End-to-end (E2E) testing To ensure seamless integration and maintain the effectiveness of tests, there will be a need to adapt E2E testing strategies in the following areas: 1. **Element access** — Nutrient now runs within a shadow DOM, and direct access methods used in iframe-based tests should be replaced with selectors that are compatible with the shadow DOM. This involves using `instance.contentDocument.querySelector` — as `instance.contentDocument` now returns the shadow root in case of the shadow DOM — or equivalent methods in testing frameworks that pierce the shadow DOM boundary. 2. **Event simulation** — Adjustments in simulating user interactions, such as clicks or drags, are necessary because of the shadow DOM’s event handling model. Particularly, the use of `composedPath()` may be required to accurately target events within the shadow DOM. 3. **Assertions** — Tests that perform assertions on the DOM structure or CSS styles may need to be updated to reflect the new changes in the shadow DOM. #### Querying coordinates in the shadow DOM When querying coordinates within the Nutrient viewer, it’s important to consider the encapsulation provided by the shadow DOM. The coordinates returned are now relative to the parent document, and they’re no longer relative to the previously used iframe. This means that to get the correct coordinates, you need to adjust the coordinates to be relative to the shadow DOM’s host element: ```diff - const rect = instance.contentDocument.querySelector(”#myElement”).getBoundingClientRect() + const rect = instance.contentDocument.querySelector(”#myElement”).getBoundingClientRect() + const shadowDOMRect = instance.contentDocument.host.getBoundingClientRect() + const relativeRect = { + x: rect.x - shadowDOMRect.x, + y: rect.y - shadowDOMRect.y, + left: rect.left - shadowDOMRect.left, + top: rect.top - shadowDOMRect.top, + width: rect.width, + height: rect.height + } ``` #### Custom stylesheet adjustments - **Positioning and layout** — Avoid using `position: fixed` within custom styles targeting elements inside the Nutrient UI, as positioning becomes relative to the parent document. Use other positioning strategies that respect the relative positioning context of the shadow DOM container. - **Viewport-relative sizes** — The use of viewport-relative units (e.g. `vw`, `vh`) is discouraged. These units will reference the full browser window rather than the size of the Nutrient UI container, potentially leading to unintended styling outcomes. - **CSS variable scoping** — Shift CSS variables from being scoped to `:root` to `:host` within the shadow DOM to ensure they’re applied correctly. - **Font declarations** — Move any `@font-face` declarations to the parent document’s stylesheets. This ensures custom fonts are loaded and rendered as expected within the Nutrient UI. Minimum Document Engine version required: 2024.1.0 For a full list of changes, check out the [changelog](https://www.nutrient.io/guides/web/changelog.md#2024.2.0). For the previous release notes, see [Web SDK 2024.1 release notes](https://www.nutrient.io/guides/web/release-notes/2024-1.md). --- ## Related pages - [1 1](/guides/web/release-notes/1-1.md) - [1 14](/guides/web/release-notes/1-14.md) - [1 10](/guides/web/release-notes/1-10.md) - [1 0](/guides/web/release-notes/1-0.md) - [1 11](/guides/web/release-notes/1-11.md) - [1 13 1](/guides/web/release-notes/1-13-1.md) - [1 3](/guides/web/release-notes/1-3.md) - [1 2](/guides/web/release-notes/1-2.md) - [1 5](/guides/web/release-notes/1-5.md) - [1 4](/guides/web/release-notes/1-4.md) - [1 9](/guides/web/release-notes/1-9.md) - [1 8](/guides/web/release-notes/1-8.md) - [1 12](/guides/web/release-notes/1-12.md) - [1 13](/guides/web/release-notes/1-13.md) - [1 7](/guides/web/release-notes/1-7.md) - [1 6](/guides/web/release-notes/1-6.md) - [2017 3](/guides/web/release-notes/2017-3.md) - [Upgrade annotations in PSPDFKit Web 2017.8](/guides/web/release-notes/2017-8.md) - [2017 6](/guides/web/release-notes/2017-6.md) - [2019 2](/guides/web/release-notes/2019-2.md) - [Explore new features in PSPDFKit for Web 2017.9](/guides/web/release-notes/2017-9.md) - [Explore the new features in PSPDFKit 2018.7](/guides/web/release-notes/2018-7.md) - [Explore PSPDFKit for Web 2018.4 features](/guides/web/release-notes/2018-4.md) - [Update your PSPDFKit for Web to version 2017.7](/guides/web/release-notes/2017-7.md) - [Explore new features in PSPDFKit 2018.5](/guides/web/release-notes/2018-5.md) - [Explore PSPDFKit for Web 2018.6 enhancements](/guides/web/release-notes/2018-6.md) - [Key updates in PSPDFKit for Web 2019.1](/guides/web/release-notes/2019-1.md) - [PSPDFKit for Web 2019.3 migration highlights](/guides/web/release-notes/2019-3.md) - [New features in the 2018.1 migration guide](/guides/web/release-notes/2018-1.md) - [PSPDFKit for Web 2018.2 migration insights](/guides/web/release-notes/2018-2.md) - [Seamless migration to PSPDFKit for Web 2020.2](/guides/web/release-notes/2020-2.md) - [PSPDFKit for Web 2019.5 migration insights](/guides/web/release-notes/2019-5.md) - [Essential updates in PSPDFKit for Web 2019.4](/guides/web/release-notes/2019-4.md) - [Upgrade to PSPDFKit Web 2020.3 seamlessly](/guides/web/release-notes/2020-3.md) - [PSPDFKit Web and Server 2020.4 migration update](/guides/web/release-notes/2020-4.md) - [2021 3](/guides/web/release-notes/2021-3.md) - [Key changes in PSPDFKit for Web 2020.1](/guides/web/release-notes/2020-1.md) - [Discover the new features in PSPDFKit for Web 2018.3](/guides/web/release-notes/2018-3.md) - [Seamlessly migrate to PSPDFKit for Web 2021.2](/guides/web/release-notes/2021-2.md) - [PSPDFKit Web 2020.6 migration insights](/guides/web/release-notes/2020-6.md) - [Unified CRUD API enhancements for easy migration](/guides/web/release-notes/2020-5.md) - [Upgrade to PSPDFKit for Web 2021.1 with ease](/guides/web/release-notes/2021-1.md) - [PSPDFKit 2021.4 migration guide for seamless updates](/guides/web/release-notes/2021-4.md) - [Migration guide for PSPDFKit 2021.5](/guides/web/release-notes/2021-5.md) - [2021 6](/guides/web/release-notes/2021-6.md) - [Key updates in PSPDFKit for Web 2023.3](/guides/web/release-notes/2023-3.md) - [Discover the key updates in PSPDFKit for Web 2023.1](/guides/web/release-notes/2023-1.md) - [PSPDFKit 2022.1.1 migration changes](/guides/web/release-notes/2022-1.md) - [PSPDFKit 2023.2 migration and updates](/guides/web/release-notes/2023-2.md) - [Enhancements in PSPDFKit for Web 2022.2](/guides/web/release-notes/2022-2.md) - [Key improvements in PSPDFKit for Web 2022.5](/guides/web/release-notes/2022-5.md) - [Explore the new features of PSPDFKit for Web 2022.3](/guides/web/release-notes/2022-3.md) - [PSPDFKit for Web 2022.4 migration overview](/guides/web/release-notes/2022-4.md) - [Key updates in PSPDFKit for Web 2023.5](/guides/web/release-notes/2023-5.md) - [Explore key updates in PSPDFKit for Web 2023.4](/guides/web/release-notes/2023-4.md) - [Essential Nutrient Web SDK 2024.1 migration tips](/guides/web/release-notes/2024-1.md) - [2024 3](/guides/web/release-notes/2024-3.md) - [2024 4](/guides/web/release-notes/2024-4.md) - [Upgrading Nutrient Web SDK](/guides/web/release-notes/upgrading.md) - [2024 5](/guides/web/release-notes/2024-5.md) - [2024 7](/guides/web/release-notes/2024-7.md) - [2024 8](/guides/web/release-notes/2024-8.md)