Side navigation

d82e6f76528ab, (opens new window) - Add direct subpath package exports as part of the linking-platform, search, media, and design-system barrel-removal (de-barrel) migration.

These packages now expose their individual modules via explicit package.json exports subpaths so that consumers can import directly from the leaf module (e.g. @atlaskit/pkg/thing) instead of the package barrel/index. This adds new public entry points without changing or removing any existing exports, so it is a backwards-compatible additive change.

No runtime behaviour changes; this is an API-surface (entry-point) addition to support tree-shaking and to unblock removal of the barrel index files.

f6328151ae86c, (opens new window) - Apply Volt entry-point and multi-export standards via volt-migrate-package. This is a major change to @atlaskit/side-navigation: the package exports map has been restructured so every public subpath now resolves directly to its ./src/* implementation instead of going through an intermediate ./src/entry-points/* re-export. No public subpaths were removed.

Because each subpath now points straight at its implementation module, a subpath and the package root can resolve to the same module instance. Consumers that deep-import the internal entry-points/* files, or that jest.mock() a specific subpath, may observe changed resolution/behaviour and need updating.

Internally, every component that was export default is now a named export (ButtonItem, CustomItem, Footer, GoBackItem, Header, HeadingItem, LinkItem, LoadingItems, NavigationContent, NavigationFooter, NavigationHeader, NestableNavigationContent, NestingItem, Section, SideNavigation, SkeletonHeadingItem, SkeletonItem). The published subpaths already exposed these as named exports, so their public shape is unchanged.

Importing the published subpaths (or the package root) continues to work as before:

If you were reaching into the internal entry-point modules, switch to the public subpath:

Because each subpath now exposes its whole implementation module, some subpaths expose additional symbols that the old shims filtered out — for example ROOT_ID from ./nestable-navigation-content, and CustomItemComponentProps from ./custom-item.

cd097a2111788, (opens new window) - Republish packages depending on @atlaskit/react-compiler-gating so their published dependency reference is updated to the renamed @atlaskit/react-compiler-gating scope.

The earlier rename of @atlassian/react-compiler-gating to @atlaskit/react-compiler-gating only bumped the renamed package itself, so dependent packages were never republished and their published versions still referenced the old @atlassian/react-compiler-gating name, which is not available in the public npm registry. This minor bump republishes all affected packages with the corrected dependency.

f2dc9097319f0, (opens new window) - ### Dropped support for legacy Typescript 4 types. Typescript 5 is now the new minimum.

Removes the typesVersions property and dist/types-ts4.5 directory from the dist.

Types are now exclusively via the "types": "dist/types/index.d.ts" property.

#157531, (opens new window) dd1068010784d, (opens new window) - Migrated SkeletonItem and SkeletonHeadingItem components from @emotion/react to @compiled/react in order toimprove performance, align with the rest of the Atlaskit techstack, and support React 18 StreamingSSR.

Removed the cssFn prop from the SkeletonItem and SkeletonHeadingItem components. Customization can now be applied via the new xcss prop. This allows for safe/bounded style overrides.

Removed the following types related to the cssFn prop: CSSFn, StatelessCSSFn, ItemState.

#156707, (opens new window) 84d702274b2dd, (opens new window) - Migrated HeadingItem and Section components from @emotion/react to @compiled/react in order to improve performance, align with the rest of the Atlaskit techstack, and support React 18 Streaming SSR.

Removed the deprecated cssFn prop from the HeadingItem component, as this is not supported with @compiled/react.

#119150, (opens new window) 5ae7ca716c848, (opens new window) - Migrated from @emotion/react to @compiled/react in order to improve performance, align with the rest of the Atlaskit techstack, and support React 18 Streaming SSR.

Please note, in order to use this version of @atlaskit/side-navigation, you will need to ensure that your bundler is configured to handle .css imports correctly. Most bundlers come with built-in support for .css imports, so you may not need to do anything. If you are using a different bundler, please refer to the documentation for that bundler to understand how to handle .css imports.

For more information on the migration, please refer to RFC-73 Migrating our components to Compiled CSS-in-JS, (opens new window).

#117363, (opens new window) 10a0f7f6c2027, (opens new window) - This package's peerDependencies have been adjusted for react and/or react-dom to reflect the status of only supporting React 18 going forward. No explicit breaking change to React support has been made in this release, but this is to signify going forward, breaking changes for React 16 or React 17 may come via non-major semver releases.

Please refer this community post for more details: https://community.developer.atlassian.com/t/rfc-78-dropping-support-for-react-16-and-rendering-in-a-react-18-concurrent-root-in-jira-and-confluence/87026, (opens new window)

#95255, (opens new window) 155e525c3b156, (opens new window) - Migrated from @emotion/react to @compiled/react in order to improve performance, align with the rest of the Atlaskit techstack, and support React 18 Streaming SSR.

Please note, in order to use this version of @atlaskit/side-navigation, you will need to ensure that your bundler is configured to handle .css imports correctly. Most bundlers come with built-in support for .css imports, so you may not need to do anything. If you are using a different bundler, please refer to the documentation for that bundler to understand how to handle .css imports.

For more information on the migration, please refer to RFC-73 Migrating our components to Compiled CSS-in-JS, (opens new window).

#127511, (opens new window) db30e29344013, (opens new window) - Widening range of react and react-dom peer dependencies from ^16.8.0 || ^17.0.0 || ~18.2.0 to the wider range of ``^16.8.0 || ^17.0.0 || ^18.0.0` (where applicable).

This change has been done to enable usage of react@18.3 as well as to have a consistent peer dependency range for react and react-dom for /platform packages.

#41355, (opens new window) cd1c813da18, (opens new window) - Menu items now have a secondary selected state (border or notch), this was previously feature flagged for Atlassian experiences and is now available for everyone.

This change makes all menu items are now relatively positioned, if you had any child elements that leaned on this behaviour your experiences will now be broken!

For example the below code code previously the div would be positioned relatively to the menu group element. Now, it is positioned relatively to the button item element.

As a path forward you should not be leaning on this behaviour. If you need a popup experience use @atlaskit/dropdown-menu or @atlaskit/popup.

#30362, (opens new window) 62c9d42799c, (opens new window) - [ux] The Footer component will now warn a user if they are relying on a deprecated API. The cssFn, onClick and component are all considered deprecated APIs for Footer.

Additionally, the space between icons and content has been shifted form 16px to 12px. This matches @atlaskit/menu.

These APIs will be removed from Footer in a future major release. To suppress the warning you can choose to use the useDeprecatedApi={false} prop which opts into the new API.

• Application of primitives for more declarative code
• Application of spacing tokens to internal styles

#14777, (opens new window) 213bfd77e61, (opens new window) - The DOM structure of menu item components has been flattened. If you used CSS hacks (via className or cssFn) that targetted specific DOM nodes you may be broken.

Previously the structure looked like:

Now it looks like:

e4f332d8697, (opens new window) - Internal refactor to update style declarations to match menu changes.

#13864, (opens new window) 0e1894c8eb0, (opens new window) - Instrumented side navigation with the new theming package, @atlaskit/tokens.

New tokens will be visible only in applications configured to use the new Tokens API (currently in alpha). These changes are intended to be interoperable with the legacy theme implementation. Legacy dark mode users should expect no visual or breaking changes.

• Export VAR_SEPARATOR_COLOR to override separator color when using custom backrounds in side navigation.
• Export VAR_SCROLL_INDICATOR_COLOR to override menu scroll indicator color when using custom backrounds in side navigation.

#3885, (opens new window) 6c525a8229, (opens new window) - Upgraded to TypeScript 3.9.6 and tslib to 2.0.0

Since tslib is a dependency for all our packages we recommend that products also follow this tslib upgrade to prevent duplicates of tslib being bundled.

[minor]7e408e4037, (opens new window):

BREAKING - renames elemBefore and elemAfter props to iconBefore and iconAfter on all item components.- [minor]d1ef176211, (opens new window):

BREAKING - renames section heading to heading item- [minor]41760ea4a6, (opens new window):

BREAKING: modifies custom item component to take only valid HTML attributes. This means wrapperClass is now known as className.- [minor]b3441cd210, (opens new window):

BREAKING - removes render go back item component from nesting item and nestable navigation content. Replaces with overrides equivalent.- [minor]e67a87dbf2, (opens new window):

BREAKING - renames customItemComponent prop on nesting item to component.

[patch]724935beab, (opens new window):

Adds loading section component to use when wanting lazy load menu items.- [patch]6453c8de48, (opens new window):

Exposes typescript types alongside components.- [patch]3bfb526c22, (opens new window):

Corrects disabled nesting item to not show the after element on hover.- [patch]7a9bf45e58, (opens new window):

Fixes section heading to correctly compose passed in css function.- [patch]d8dc3813c1, (opens new window):

Fixes section heading spacing.- [patch]684ee794d6, (opens new window):

Improves type safety with custom item by using TypeScript generics to pass on the custom component types to the parent.- Updated dependencies 7e408e4037, (opens new window):

Updated dependencies 5633f516a4, (opens new window):

Updated dependencies 6453c8de48, (opens new window):

Updated dependencies 168b5f90e5, (opens new window):

Updated dependencies e4dde0ad13, (opens new window):

Updated dependencies 41760ea4a6, (opens new window):

Updated dependencies 0c270847cb, (opens new window):

Updated dependencies 971e294b1e, (opens new window):

Updated dependencies 684ee794d6, (opens new window):

Updated dependencies 109004a98e, (opens new window):

Updated dependencies b9903e773a, (opens new window):

Updated dependencies 286770886d, (opens new window):

Updated dependencies 2c1b78027c, (opens new window):

Updated dependencies fb3ca3a3b2, (opens new window):

• @atlaskit/menu@0.4.0
• @atlaskit/motion@0.2.3
• @atlaskit/docs@8.5.1
• @atlaskit/theme@9.5.3
• @atlaskit/button@13.3.10

[patch]ab133d934f, (opens new window):

Change imports to comply with Atlassian conventions

[minor]7ecbf8d0bd, (opens new window):

Breaking:

• SideNavigation now has a required label prop.

Accessibility Changes

• SideNavigation now has a navigation landmark for use with screen readers; this landmark is further described by the label prop to differentiate it from AtlassianNavigation- [minor]1fea6757c4, (opens new window):

BREAKING - NavigationFooter component has been renamed to Footer.

[patch]7b230682c2, (opens new window):

Adds controlled component support. It is now possible to use the stack and onChange props on the NestableNavigationContent component to dictate which view is active. This is useful for use cases where nested views need to be changed programmatically.

This is supported by a new hook called useShouldNestedElementRender(). All components that can be composed with NestableNavigationContent use it out of the box, but if you want to compose your own components you may have to opt into it else you will see your component rendering on every view (which may or may not be what you want).

• [patch]5c0bb69f7b, (opens new window):

Fixes horizontal alignment for item icons in relation to the app switcher in the horizontal navigation bar.- [patch]1a3192c1c1, (opens new window):

Introduces skeletons for heading and item components.- [patch]43353900f7, (opens new window):

Corrects and consolidates colors for item and side navigation components.- [patch]c60324c748, (opens new window):

Adds new Footer component. Ensures this and the Header component come with baked in styles for you to use out of the box.- [patch]c56d86d95c, (opens new window):

Adds scrolling indicators to the scrollable container component.

Updated dependencies ed8d8dea65, (opens new window):

Updated dependencies db2f869556, (opens new window):

Updated dependencies 81ea791176, (opens new window):

Updated dependencies 6e2dda87f4, (opens new window):

Updated dependencies e57c4aa96d, (opens new window):

Updated dependencies 8c9e4f1ec6, (opens new window):

Updated dependencies 89d35b919a, (opens new window):

Updated dependencies 083cfbaeb4, (opens new window):

Updated dependencies 46d95777ef, (opens new window):

Updated dependencies 9b264df34d, (opens new window):

• @atlaskit/menu@0.3.1
• @atlaskit/atlassian-navigation@0.10.0
• @atlaskit/docs@8.5.0

[minor]dce5efb012, (opens new window):

Support forward ref on side-navigation primitives

[patch]4da717940e, (opens new window):

Refactor side-navigation nesting logic to support async components- [patch]93709ca7eb, (opens new window):

Adds testId to NestingItem- Updated dependencies 66dcced7a0, (opens new window):

Updated dependencies fd5292fd5a, (opens new window):

Updated dependencies fd5292fd5a, (opens new window):

Updated dependencies eea5e9bd8c, (opens new window):

Updated dependencies 7a6e5f6e3d, (opens new window):

Updated dependencies fd5292fd5a, (opens new window):

• @atlaskit/docs@8.4.0
• @atlaskit/icon@20.1.0
• @atlaskit/logo@12.3.3
• @atlaskit/menu@0.3.0
• @atlaskit/button@13.3.9

[minor]e1416630ed, (opens new window):

BREAKING: Renamed exported components

• Renamed MainSection to NavigationContent
• Renamed NestingTransitionProvider to NestableNavigationContent
• NestableNavigationContent does not need to be wrapped by a MainSection
• Renamed HeaderSection to NavigationHeader
• Renamed Footer to NavigationFooter

Improve behaviour of scrollabe sections:

• Fixes a bug where different views shared the same scrollable section causing unexpected jumps on some unnesting interactions
• ScrollableSection now shows an overflow indicator when items are scrolled off the top border
• Fixes a bug where the Go Back component could scroll off the top in some cases- [minor]d752f27427, (opens new window):

API changes and design changes for side-navigation

• BREAKING: SectionHeader has been renamed to SectionHeading
• SIDEBAR_DEFAULT_WIDTH has been exported
• Item has been removed and replaced with CustomItem, ButtonItem, LinkItem which are thin wrappers around their @atlaskit/menu counterparts
• All exported components now have sensible default styles applied
• A GoBackItem has been exported
• testId props have been added to more components with side-navigation
• CustomItem, ButtonItem and LinkItem themselves have a cssFn prop exposed which will allow custom styles to be applied and combined with side-navigation defaults
• Heading and Footer have been updated to allow consumers to pass in their own custom components
• Rich examples have been updated for composing your own navigations with RBD etc.- [minor]08fa439ec7, (opens new window):

BREAKING: id prop is now required on NestingItems

The back button in nested views can now be customised

• By default an English Go Back button will be shown
• Use renderDefaultBackButton on the NestableNavigationContent to set a new default
• Use renderBackButton on each NestingItem to specifically set a back trigger for exiting the view it controls

The link form of nested views can now be customised

• Use customItemComponent to pass in a functional/class component that adds extra behaviour around the link (see @atlaskit/menu for examples on how to configure CustomItems)

[patch]babae63a7b, (opens new window):

• Refactors nested navigation implementation
• Now selects NestingItem & GoBackItem when it is exiting
• Fixes double clicking a NestingItem and GoBackItem resulting in an unwanted double navigation
• Fixes NestingItem not calling back on click
• Adds optional id prop to NestingItem- Updated dependencies 1f9c4f974a, (opens new window):

Updated dependencies b80c88fd26, (opens new window):

Updated dependencies 9ec1606d00, (opens new window):

Updated dependencies 0603860c07, (opens new window):

Updated dependencies 1b3069e06b, (opens new window):

• @atlaskit/menu@0.2.7
• @atlaskit/atlassian-navigation@0.9.6
• @atlaskit/icon@20.0.2

[patch]6548261c9a, (opens new window):

Remove namespace imports from React, ReactDom, and PropTypes- Updated dependencies 6548261c9a, (opens new window):

• @atlaskit/docs@8.3.2
• @atlaskit/icon@20.0.1
• @atlaskit/menu@0.2.6
• @atlaskit/theme@9.5.1
• @atlaskit/motion@0.2.2

[patch]f3433f2096, (opens new window):

NestingItem now has an extra prop isInitiallyOpen that allows the side-navigation to initially render a particular nested view

• To select a particular sidebar view to be rendered initially the isInitiallyOpen prop must be set on all parent NestingItems in the navigation tree- [patch]a806cde423, (opens new window):

Iterative updates to side-navigation:

• Go Back link in nested views now sticks to the top of the scrollable area
• Removed broken css styles
• Implemented sliding transitions rather than fades- Updated dependencies 4ed951b8d8, (opens new window):

Updated dependencies e0e91e02a6, (opens new window):

Updated dependencies c0102a3ea2, (opens new window):

Updated dependencies 166d7b1626, (opens new window):

• @atlaskit/menu@0.2.4
• @atlaskit/icon@20.0.0
• @atlaskit/motion@0.2.1
• @atlaskit/docs@8.3.1

[patch]0e6929fbb9, (opens new window):

Fixes a broken internal omport- [patch]146ca7139a, (opens new window):

Bump package to enable branch deploys- Updated dependencies d2b8166208, (opens new window):

Updated dependencies 1d72045e6b, (opens new window):

• @atlaskit/docs@8.3.0
• @atlaskit/motion@0.2.0