AUI 9 upgrade guides

Upgrading from 8.x to 9.0

Focus changes

AUI ships focus styles that target default HTML element appearance when focussed. Previously, AUI set a style for the :focus pseudo-selector. AUI 9 also sets a style for the :focus-visible pseudo-selector.

There is one behavioural difference between :focus and :focus-visible.

• When an element is styled using :focus, a focus ring will be drawn whenever the element receives browser focus, regardless of how it was focussed — by mouse click, by keyboard input, or by programmatic means.
• When an element is styled using :focus-visible, a focus ring will only be drawn when the browser determines that focus should be made visually apparent. Typically, this means a focus ring will not be shown when focussed by mouse click, but will be shown when focussed by keyboard.

This update to using :focus-visible has been made to support the AUI 9 accessibility changes. Many AUI components now have an explicit focus indicator — dropdowns, dialogs, and more. If elements are only styled with :focus, a focus ring would be drawn when mouse users interact with elements, which they may find jarring. By adding :focus-visible, mouse users will not see focus rings after clicking elements, but other users will.

Not every browser supports :focus-visible. As a consequence, when upgrading, you may see focus rings on elements you did not expect. To account for this, AUI also supports the WICG focus-visible polyfill. If you add this polyfill to your application, focus rings should only be visible in non-mouse-usage scenarios.

Please check the browser support matrix for :focus-visible and decide whether you want to ship the WICG focus-visible polyfill, or whether the standard :focus behaviour will be acceptable in your application.

Accessibility changes

Dialog2

Focus management

The dialog element itself is now focusable by JavaScript. It will be focused as the first thing after dialog being opened unless you set explicitly the data-aui-focus-selector attribute.

Close button

Make sure the close button:

• is a button (and has a type="button" just in case you put it within HTML form somehow)
• has an aria-label attribute, with a translation string that evaluates to "Close"
• is in tab order (it will be by default if it's a button)

Markup example:

Inline Dialog 2

Inline dialog element is now focused after opening.

Make sure you set aria-label on aui-inline-dialog element to give screen reader friendly description of the the dialog's content. When aria-label is missing the AT will read whole content of the dialog.

Layered elements

Layered elements except Dialog2 will not alter their allocation in DOM tree by default.
To maintain a natural tab order for keyboard users, layered elements should be rendered as the next sibling of their trigger.

It may happen that due to the design of your application the layered components may get obscured - i.e. being clipped by the parent container with overflow:hidden; CSS property set.

You may need to alter your application's CSS to adjust to the new behaviour.

In rare cases when such adjustments are not possible - you may specify a rendering DOM container for any layered component.
Upon displaying of such layered component - it will temporarily move it's subtree into the specified container - allowing for unobstructed rendering.
You should always choose the closest container allowing for unobstructed render.
You are responsible for ensuring the component is properly cleaned up, adequately to your application's lifecycle.

In order to specify a rendering DOM container, set the data-aui-dom-container attribute to a selector matching the container element:

• If data-aui-dom-container attribute is set but the selector matches multiple elements - it will default to first available match.
• If data-aui-dom-container attribute is set but the selector does not match to any existing elements it will default to document.body
• If data-aui-dom-container attribute is not set, the dropdown will be left in place.

Even though this API is available for all layered components, only the components that guarantee adequate tab, keyboard and/or focus flow management will expose this API in their documentation.
Always refer to the component's documentation to see if it exposes any means to overcome similar rendering obstacles, i.e. by setting proper alignment.

Dropdown2

Styling changes

Previously, specific ARIA attributes would receive styling when used in a dropdown container. Now, ARIA attributes receive no explicit styling.

If you are using the markup-based pattern (not the web-component pattern) for your dropdowns, You must use one the following patterns to receive the dropdown item aesthetic:

• Use an <a> HTML element if the dropdown item will take the user to another page.
• Use a <button> HTML element if the dropdown item will do something dynamic.
• Use the .aui-dropdown2-radio or .aui-dropdown2-checkbox CSS classes to make an item present as a radio or checkbox respectively.

Note that these are changes to the CSS and affect visual aesthetic. You are responsible for using valid, semantic markup so that the items are perceived correctly in non-visual contexts, such as screen readers.

Application header

Markup changes

Previously, the application header's logo was wrapped in a <h1> element. The <h1> element should only be used inside the page's main content. The logo element has now been replaced with a <span> element.

The pattern's <nav> element must have an aria-label with a translated value of "site". This allows screen reader users to perceive the application header as "site navigation".

Make sure that the logo link has translation string that interpolates to "Go to home page" label.

Page layout changes

The .aui-panel class is gone

AUI used to include an .aui-panel CSS class. Its purpose was wholly replaced by .aui-page-panel in AUI 5. The upgrade is a simple 1:1 mapping: find and replace all .aui-panel with .aui-page-panel.

Page structure changes

The page layout pattern was updated; some markup changes were made to allow easier placement of key landmark roles, as well as to provide recommended labeling for each. Of note in the changes are:

• Where to place the <main> element on your page.
• The position of the sidebar has changed in markup.
• The recommended tag names of interstitial markup between page structure and content are slightly updated.
• Removal of redundant role attributes where all supported browsers and screen readers understand the native semantic of recommended tags.

Here are how some typical page layouts have changed in markup:

Please read the full page layout documentation page for more details on these changes.

Soy template changes

Previously, the aui.page.pagePanelContent template output a <section> element and had no id value.

In AUI 9, this template now outputs a <main> element with a default id value of main. It will also output the appropriate role attribute.

Changes to hiding and showing elements

AUI used to use aria-hidden attribute to visually hide elements, which is an incorrect usage of this attribute.

To improve how elements are shown and hidden, we made the following changes:

• We removed invalid uses of aria-hidden and replaced some of them with hidden.
• For several elements, we now use the open attribute to indicate whether the element should be visible or not.
• AUI's CSS reset sets display:none !important on any element with the hidden attribute.

If your code tests for the visibility of an element, check for the presence of the open attribute and the absence of a hidden attribute.

If an element should be hidden immediately, add the hidden attribute to it.

If you animate any elements when they appear or disappear, you should do this with the open attribute. The hidden attribute takes precedence over open and will take effect immediately; it will not be possible to animate visibility when this attribute is added to an element.

Dialog2

Previously in our docs examples markup for Dialog2 included aria-hidden="true" attribute on section element.

Now you should add hidden attribute.

Dropdown2

If you are still constructing dropdowns using markup instead of webcomponent you may need to update your HTML. If you are using Soy templates provided by AUI you are fine if not, make changes described below.

Layer component

Refactoring aria-hidden attributes required also changes in Layer component.

AUI library changes

Markup changes

Sidebar expand button

We replaced custom icon with icon font. Make sure that the span now has aui-iconfont-chevron-double-left class.

CSS changes

"Message" close icon was removed. Following classes are no longer supported:

• .aui-message .icon-close
• .aui-icon-close
• .aui-message .icon-close-inverted
• .aui-message.error .icon-close
• .aui-icon-close-inverted

jQuery configuration

jQuery ajaxSettings configuration was removed. Please specify it globaly for product or add it per request where needed. More information here https://api.jquery.com/jQuery.param/

Datepicker placeholders

In previous versions AUI relied on the dateFormat option from the jQuery UI datepicker widget. It was used as a placeholder for the input of type "date" if the "overrideBrowserDefault" option was set to "true".

Since the default format is represented by string "yy-mm-dd" it was confusing users because "yy" stands for the long year format (4-digits) - not the short, 2-digits year format.

We decided to break the dependency between the input placeholder and the format string by extending the configuration API and allowing the placeholder to be set explicitly. That requires you to review all the usages of the datepicker widget and set placeholders where they are needed to clarify understanding of given input purpose.

Our recommendation here is to not use placeholders and put the expected date format next to the input label - mostly for the accessibility reasons. Use placeholders only as a last resport. We suggest representing real values - not the format string: eg. 2020-01-29 instead of yyyy-mm-dd

Upgrading from 9.0.x to 9.1

AUI library changes

AUI's version of Popper.js - a third party library supporting AUI's layered components - has been bumped to v2.4.4, up from v1.14.5.

Markup changes

Due to changes introduced with Popper.js - shape of certain attributes might have changed for those components.
x-* have been replaced with data-popper-*
For details - visit Popper.js Migration guide

Even though these attributes have been used as internal API only and not explicitly guaranteed - for compatibility reasons - x-placement attribute is provided by AUI layered components.
Its use is considered as DEPRECATED, meaning - the attribute will be removed with further versions of AUI. If your application depends on the provided data - please adapt to new, namespaced markup data-popper-*

Upgrading from 9.2.x to 9.3.0

Tooltip changes

AUI's tooltips have been re-implemented using popper.js, the same library AUI uses for its other layered elements such as inline dialog, dropdown, modal, etc. As a result, tooltips are positioned correctly in more scenarios, and the bundle size for AUI is reduced.

Some behaviours have been hard-coded to match the ADG recommendations, eg. delay for tooltip appearance, removal of animation, removal of arrows pointing from tooltip to its trigger.

Previously, AUI used the jQuery Tipsy plugin to render tooltips. This was considered an internal implementation detail of AUI and was not intended to be used outside of AUI. As of AUI 9.3.0, calling AJS.$(selector).tipsy() will not work.

If you are using tooltips, you should consume the AUI tooltip component directly and use the AJS.$(selector).tooltip() function.

If you still require the jQuery Tipsy extension, you have two options:

• Using Node: add the @atlassian/tipsy NPM dependency to your project and depend on this library directly.
• Using the Atlassian Plugin: add a web-resource dependency for com.atlassian.auiplugin:jquery-tipsy to your feature. Note that this web-resource is deprecated and will be removed in a future major version.

Implementation notes

The new implementation of tooltips relies on single DOM node inserted at the bottom of document. Its text content changes every time new tooltip shows up. This was done mostly because removal of tooltip animations makes it impossible to have more than one tooltip visible in the same time on screen. It also slightly improves the DOM mutation performance.

Focus style changes

AUI ships focus styles that target default HTML element appearance when focussed. These styles were previously been shipped as part of AUI's CSS reset. In AUI 9.3, the focus styles are now opt-in. They have been extracted in to their own CSS file and dedicated web-resource. They have also been hidden behind a CSS feature flag.

As a consequence, some elements like hyperlinks (<a>) will no longer receive a focus ring style consistent with AUI's other components.

If you want to apply AUI's focus styles to default HTML elements, refer to the browser focus documentation page for usage instructions.

Upgrading from 9.5.x to 9.6.0

Inline Dialog 2 accessibility attributes changes

Why we change?

The current implementation of the Inline Dialog 2 misleads the Screen Reader's users. It happens because the Inline Dialog's 2 trigger by default gets aria-expanded="false" and aria-haspopup="true" attributes, and the popup element gets role="dialog" attribute.

As a result when a user moves focus on the trigger the Screen Reader announces that he/she is on the popup menu's trigger which is collapsed right now, but on pressing the trigger users redirected to a dialog, what is not expected by user.

Changes

In order to make the Inline Dialog 2 more accessible and fix inconsistencies we made the following changes:

• Removed default attribute role='dialog'.

  Now there is no any role on a popup element of the Inline Dialog 2 by default. It means that if the popup element is focused the Screen Reader will announce it as a group (not as a dialog as it was).

• Added inner handlers for cases when the role='dialog' attribute is provided manually by developers.

  So if you add role='dialog' in aui-inline-dialog element, the aria-haspopup and aria-expanded will not be added to the trigger element.

How to upgrade

The only what you need is to review all entrances of the Inline Dialog 2 component in codebase and decide on each case if the case should be considered as a popup menu/custom component/extended tooltip or a non-modal dialog.

In case it is a:

• Popup menu / custom component / extended tooltip. No changes is needed.
• Non-modal dialog. You need to add role="dialog" attribute to aui-inline-dialog element.

Icons accessibility

A distinction between informative and decorative icons has been clarified further, and the approach to informative icons (in other words, cases where the icon stands alone in a control) was changed.

If you're using an informative icon from soy, no change is required.

However, if an icon is defined in HTML like this:

then you should consider replacing it with the new form:

Both forms are supported, but the new one is preferred.

Upgrading to 9.7.0

Replace Multi-select with Select2

The default browser behavior of the select element requires to use modifier keys (Ctrl or Cmd) with the mouse or Up, Down, or Space keys in order to select multiple items. This behavior is non-intuitive and not accessible. Therefore, in this version we deprecate the multi-select component and ask you to migrate its uses to Select2: remove multi-select and initialize select2() in JavaScript.

Upgrading to 9.12.0

rem change from 14px to 16px

Atlaskit components are changing to expect a rem of 16px. To provide compatibility as much compatibility as possible, AUI has:

1. Changed its rem to 16px (from 14px) to prevent visual changes when upgrading Atlaskit.
2. Pinned the (internal) AUI spacing CSS variables to keep the same px value.
3. Updated the Atlassian design tokens have to match the rem change and provide as much forward compatibility as possible right before the next set of DC product LTS versions.

In the long-term AUI will align with the Atlassian design tokens and change its sizing.

Conversion table

If you wish to adjust your styles to minimise changes, here is a conversion table to assist with that: