@atlaskit/navigation-system 5.40.0 → 6.1.0

package/constellation/side-nav-items/examples.mdx

@@ -1,235 +0,0 @@
----
-title: Side nav items
-description: Menu items and elements for the side nav area.
-order: 1
----
-
-import SectionMessage from '@atlaskit/section-message';
-
-import { LinkMenuItemExample } from '../../examples/constellation/side-nav-items/link-menu-item';
-import { ButtonMenuItemExample } from '../../examples/constellation/side-nav-items/button-menu-item';
-import { ExpandableMenuItemDefaultVariantExample } from '../../examples/constellation/side-nav-items/expandable-menu-item-default-variant';
-import { ExpandableMenuItemLinkVariantExample } from '../../examples/constellation/side-nav-items/expandable-menu-item-link-variant';
-import { FlyoutMenuItemExample } from '../../examples/constellation/side-nav-items/flyout-menu-item';
-import { ElemBeforeExample } from '../../examples/constellation/side-nav-items/elem-before';
-import { ElemAfterExample } from '../../examples/constellation/side-nav-items/elem-after';
-import { ContainerAvatarExample } from '../../examples/constellation/side-nav-items/container-avatar';
-import { ActionsAndActionsOnHoverExample } from '../../examples/constellation/side-nav-items/actions-and-actions-on-hover';
-import { TruncationExample } from '../../examples/constellation/side-nav-items/truncation';
-import { MenuSectionExample } from '../../examples/constellation/side-nav-items/menu-section';
-import { MenuDividerExample } from '../../examples/constellation/side-nav-items/menu-divider';
-import { TopLevelSpacerExample } from '../../examples/constellation/side-nav-items/top-level-spacer';
-import { RightToLeftExample } from '../../examples/constellation/side-nav-items/right-to-left';
-import { SkeletonMenuItemDescriptionExample } from '../../examples/constellation/side-nav-items/skeleton-menu-item-description';
-import { SkeletonMenuItemElemBeforeExample } from '../../examples/constellation/side-nav-items/skeleton-menu-item-elem-before';
-import { SkeletonMenuSectionHeadingExample } from '../../examples/constellation/side-nav-items/skeleton-menu-section-heading';
-
-These components can be used within
-the [side nav](/components/navigation-system/layout/examples#side-nav).
-
-For other components that can be used within the side nav, see
-[navigation experience guidelines (Atlassians only)](https://hello.atlassian.net/wiki/x/rBE7MAE).
-
-## Menu items
-
-There are four types of side nav menu items:
-
-1. [Link menu item](#link-menu-item)
-2. [Button menu item](#button-menu-item)
-3. [Expandable menu item](#expandable-menu-item)
-4. [Flyout menu item](#flyout-menu-item)
-
-Within menu items, you can customize [`elemBefore`](#elembefore), [`elemAfter`](#elemafter),
-[`actions`](#actions-and-actionsonhover) and [`actionsOnHover`](#actions-and-actionsonhover).
-
-### Link menu item
-
-A menu item that is wrapped in an anchor tag `<a>`. This is the most common type of menu item, as
-most menu items are used to send people to another location.
-
-For menu items that trigger an action, instead use [button menu item](#button-menu-item).
-
-Use the [app provider](/components/app-provider/examples) to specify a custom router link component.
-
-<Example Component={LinkMenuItemExample} />
-
-### Button menu item
-
-A menu item wrapped in a button tag `<button>`. Use this component when you have an action that does
-something other than navigating to another location.
-
-- [Avoid disabling button menu items](/components/button/usage#avoid-disabling-buttons) as this can
-  cause accessibility problems. When disabled, [`actions`](#actions-and-actionsonhover) and
-  [`actionsOnHover`](#actions-and-actionsonhover) will not display.
-- Be cautious of using [`elemAfter`](#elemafter) in menu item disabled states, as it may result in
-  an unintended appearance if this component has no disabled states.
-
-<Example Component={ButtonMenuItemExample} />
-
-### Expandable menu item
-
-#### Default (button)
-
-A menu item that expands to expose other menu items. Use this component to form nested navigation
-hierarchies.
-
-- Expandable menu item will always display something in [`elemBefore`](#elembefore). If no element
-  is provided, it will display a chevron icon by default. If an element is provided, a chevron icon
-  will replace the element for hover, press and focus states.
-- Unlike other menu items, it does not support a `description`.
-- When expandable menu item is open, any [`actionsOnHover`](#actions-and-actionsonhover) will
-  display permanently.
-- Every menu item type can be nested inside an expandable menu item.
-
-<Example Component={ExpandableMenuItemDefaultVariantExample} />
-
-#### Link
-
-The expandable menu item can also be a link location.
-
-- In this variant, the [`elemBefore`](#elembefore) chevron is an icon button so the menu can be
-  opened and closed independently from navigating to the link location.
-- A tootlip is not applied to the icon button.
-
-<Example Component={ExpandableMenuItemLinkVariantExample} />
-
-### Flyout menu item
-
-A menu item that triggers a popup (flyout menu content) to expose side nav items. It can also
-contain other items, such as search bars and filters.
-
-- The flyout menu always displays a chevron icon at the end position.
-- Unlike other menu items, it does not support a `description`, [`elemAfter`](#elemafter),
-  [`actions`](#actions-and-actionsonhover) or [`actionsOnHover`](#actions-and-actionsonhover).
-- The flyout menu content has a fixed 400px width. Height is not defined and can be set by makers.
-
-<Example Component={FlyoutMenuItemExample} />
-
-#### Responsive flyout menu
-
-At [breakpoints](/foundations/grid-beta/#breakpoints) `s` and below (less than 1024px), the flyout
-menu content converts to a modal.
-
-The modal max height is 50% of the viewport height. The modal has a 4px margin.
-
-To see an example of this, open the [flyout menu item example](#flyout-menu-item) above in
-codesandbox and resize your browser.
-
-## Menu item customization
-
-### elemBefore
-
-A slot for custom elements to be added to the start position of the menu item.
-
-- Only one element is allowed. Recommended usages are icons, [ContainerAvatar](#containeravatar),
-  and app tiles. For [expandable link menu item](#expandable-menu-item), it will render an icon
-  button without a tooltip.
-- When no `elemBefore` is provided, the menu item will maintain the empty space. You can remove this
-  space by passing in the `COLLAPSE_ELEM_BEFORE` symbol. Consider how this will impact the overall
-  visual hierarchy before using.
-
-When using icons and icon buttons, follow the
-[usage guidance](/components/navigation-system/side-nav-items/usage) on the correct sizes.
-
-<Example Component={ElemBeforeExample} />
-
-#### ContainerAvatar
-
-A container for displaying images that are styled to look like an avatar, but with the correct
-sizing for the side nav menu items.
-
-- Use to display avatars in [elemBefore](#elembefore) (do not use regular avatar).
-- Only use ContainerAvatar with the side nav menu items.
-
-<Example Component={ContainerAvatarExample} />
-
-### elemAfter
-
-A slot for custom elements to be added to the end position of the menu item.
-
-- Optional for all menu items except [flyout menu item](#flyout-menu-item), which doesn’t offer this
-  slot.
-- Can be more than one element, although we recommended avoiding where possible due to space
-  constraints. Recommended usages are for non-interactive elements such as small icons (12px),
-  badge, and lozenge.
-- Disappears when [`actionsOnHover`](#actions-and-actionsonhover) display. If
-  [`actions`](#actions-and-actionsonhover) are present, these take the end position and shift
-  `elemAfter` to the left.
-
-<Example Component={ElemAfterExample} />
-
-### actions and actionsOnHover
-
-Slots for icon buttons that trigger actions independent from the menu item.
-
-- Note that `actions` always display, and `actionsOnHover` display when interacting with the menu
-  item (hover, press, and focus states). When an [expandable menu item](#expandable-menu-item) is
-  open, if `actionsOnHover` are present they will display on default.
-- Always use subtle compact [icon buttons](/components/button/icon-button/examples) in these slots
-  and enable tooltips. When using more than one icon button, apply 4px spacing.
-- If the icon button triggers a
-  [dropdown menu](/components/dropdown-menu/examples#default-placement), use the default (cozy)
-  density and default `bottom-start` placement, and follow dropdown menu best practice.
-- Do not apply side nav items in dropdown menus triggered by `actions` or `actionsOnHover`.
-
-<Example Component={ActionsAndActionsOnHoverExample} />
-
-### Truncation
-
-When the label or description of side nav menu items exceed the available horizontal space, the text
-becomes truncated. Tooltips expose the full menu label and are positioned right-start.
-
-<Example Component={TruncationExample} />
-
-### Menu section and menu section heading
-
-Use **menu section** to group related menu items. This is important for accessibility as it acts as
-a landmark for assistive technology.
-
-A **menu section heading** is optional. When using, make sure it’s both a visual heading and ARIA
-label to name a menu section.
-
-<Example Component={MenuSectionExample} />
-
-### Menu divider
-
-A graphic divider to separate menu items or sections.
-
-Reserve for use in [flyout menu content](#flyout-menu-item). Avoid using directly in the side nav,
-use [top level spacer](#top-level-spacer) instead to create separation.
-
-<Example Component={MenuDividerExample} />
-
-### Top level spacer
-
-A 12px space to separate level 0 menu items or sections.
-
-<Example Component={TopLevelSpacerExample} />
-
-### Right to left languages
-
-All side nav items support right to left languages.
-
-<Example Component={RightToLeftExample} />
-
-## Loading states
-
-### Menu item skeleton
-
-#### With description
-
-Menu item skeletons can include a description, a secondary line of text. Use the `hasDescription`
-prop to match the corresponding menu item that will be loaded.
-
-<Example Component={SkeletonMenuItemDescriptionExample} backgroundColor="white" />
-
-#### With icon
-
-Menu item skeletons can include an icon or avatar before the label. Use the `hasElemBefore` prop to
-match the corresponding menu item that will be loaded.
-
-<Example Component={SkeletonMenuItemElemBeforeExample} backgroundColor="white" />
-
-### Menu section heading skeleton
-
-<Example Component={SkeletonMenuSectionHeadingExample} backgroundColor="white" />

package/constellation/side-nav-items/usage.mdx

@@ -1,328 +0,0 @@
----
-title: Side nav items
-description: Menu items and elements for the side nav area.
-order: 4
----
-
-import sideNavDo1 from './images/side-nav-do-1.png';
-import sideNavDont1 from './images/side-nav-dont-1.png';
-import sideNavDo2 from './images/side-nav-do-2.png';
-import sideNavDont2 from './images/side-nav-dont-2.png';
-import sideNavDo3 from './images/side-nav-do-3.png';
-import sideNavDont3 from './images/side-nav-dont-3.png';
-import sideNavDo4 from './images/side-nav-do-4.png';
-import sideNavDont4 from './images/side-nav-dont-4.png';
-import sideNavDo5 from './images/side-nav-do-5.png';
-import sideNavDont5 from './images/side-nav-dont-5.png';
-import sideNavDo6 from './images/side-nav-do-6.png';
-import sideNavDont6 from './images/side-nav-dont-6.png';
-import sideNavDo7 from './images/side-nav-do-7.png';
-import sideNavDont7 from './images/side-nav-dont-7.png';
-import sideNavDont8 from './images/side-nav-dont-8.png';
-import sideNavDont9 from './images/side-nav-dont-9.png';
-import sideNavDont10 from './images/side-nav-dont-10.png';
-
-## Usage
-
-Use side nav items to create different sections, actions, and links in the
-[side nav](/components/navigation-system/side-nav-items).
-
-![Diagram of the navigation system side nav](./images/side-nav-anatomy-1.png)
-
-![Diagram of the navigation system side nav items](./images/side-nav-anatomy-2.png)
-
-<ol>
-	<li>
-		<strong>Menu items:</strong> The interactive elements in the side nav that help users navigate
-		or perform actions.
-		<ol type="a">
-			<li>
-				<strong>elemBefore.</strong> Optional*. Only one allowed.
-			</li>
-			<li>
-				<strong>Label.</strong> Text that succinctly describes the menu item.
-			</li>
-			<li>
-				<strong>Description.</strong> Optional*. Additional information on the menu item, such as
-				meta data.
-			</li>
-			<li>
-				<strong>elemAfter.</strong> Optional*. Disappears when actionsOnHover display.
-			</li>
-			<li>
-				<strong>actions</strong> or <strong>actionsOnHover</strong>. Optional*. Icon buttons that
-				trigger actions independent from the menu item.
-			</li>
-		</ol>
-	</li>
-	<li>
-		<strong>Menu section:</strong> Use to group related menu items. Acts as a landmark for assistive
-		technology.
-	</li>
-	<li>
-		<strong>Menu section heading:</strong> Both a visual heading and ARIA label to name a menu
-		section.
-	</li>
-</ol>
-
-\*Some variations exist between menu item types. View the
-[menu item examples](/components/navigation-system/side-nav-items) for details.
-
-### Follow Atlassian's navigation patterns
-
-The current navigation has specific menu items that are similar across apps. Make sure your side
-navigation follows Atlassian patterns consistently,
-[see navigation experience guidelines (Atlassians only)](https://hello.atlassian.net/wiki/spaces/navx/pages/5104144812).
-
-### Choose side nav menu items based on action type
-
-There are four types of side nav menu items:
-
-1. Link menu items – navigates to another page.
-2. Button menu items – triggers an action.
-3. Expandable menu item – nests side nav menu items to create hierarchies.
-4. Flyout menu item – opens a popup.
-
-View the [menu item examples](/components/navigation-system/side-nav-items) for full behavior and
-guidance for each menu item.
-
-### Use side nav items only within the side nav
-
-Side nav menus are reserved for use directly within the
-[side nav](/components/navigation-system/side-nav-items) and the
-[flyout menu content](/components/navigation-system/side-nav-items/examples#flyout-menu-item)
-(popup).
-
-Menus anywhere else in the app, including those triggered from the top navigation, should also use
-regular [menu](/components/menu) or [dropdown menu](/components/dropdown-menu).
-
-<DoDontGrid>
-	<DoDont
-		type="do"
-		image={{
-			url: sideNavDo1,
-			alt: 'A side nav with side nav items only.',
-		}}
-	>
-		Use side nav menus directly in the side nav or flyout menu content.
-	</DoDont>
-	<DoDont
-		type="dont"
-		image={{
-			url: sideNavDont1,
-			alt: 'Side nav items incorrectly used in the top nav.',
-		}}
-	>
-		Don’t use side nav menus in other parts of the app.
-	</DoDont>
-</DoDontGrid>
-
-### Use dropdown menu for menus triggered from the side nav
-
-Use [dropdown menu](/components/dropdown-menu) for menus triggered by `actions` or `actionsOnHover`.
-Ensure you follow the general usage guidance for dropdown menu and use the following variants:
-
-- default density (cozy)
-- default placement (bottom-start; adjusts accordingly when space is limited)
-
-<DoDontGrid>
-	<DoDont
-		type="do"
-		image={{
-			url: sideNavDo2,
-			alt: 'An open dropdown menu with a list of items.',
-		}}
-		isFullWidth
-	>
-		Use dropdown menu for menus triggered by actions or actionsOnHover.
-	</DoDont>
-	<DoDont
-		type="dont"
-		image={{
-			url: sideNavDont2,
-			alt: 'A dropdown menu with a list of items.',
-		}}
-	>
-		Don’t use side nav menu in dropdown menus.
-	</DoDont>
-	<DoDont
-		type="dont"
-		image={{
-			url: sideNavDont3,
-			alt: 'A dropdown menu with menu item that uses compact density.',
-		}}
-	>
-		Don’t use compact density for dropdown menus.
-	</DoDont>
-	<DoDont
-		type="dont"
-		image={{
-			url: sideNavDont4,
-			alt: 'A dropdown menu with menu item that does not have a selected state.',
-		}}
-	>
-		Don’t omit the selected state on the dropdown trigger when open.
-	</DoDont>
-	<DoDont
-		type="dont"
-		image={{
-			url: sideNavDont5,
-			alt: 'A dropdown menu with a disabled menu item.',
-		}}
-	>
-		Don’t use disabled menu items, see [menu](/components/menu/usage) guidance.
-	</DoDont>
-</DoDontGrid>
-
-## Best practices
-
-### Use the provided slots as intended
-
-Use [`elemBefore`](/components/navigation-system/side-nav-items/examples#elembefore),
-[`elemAfter`](/components/navigation-system/side-nav-items/examples#elemafter),
-[`actions`](/components/navigation-system/side-nav-items/examples#actions-and-actionsonhover), and
-[`actionsOnHover`](/components/navigation-system/side-nav-items/examples#actions-and-actionsonhover)
-slots for configuring menu items.
-
-<DoDontGrid>
-	<DoDont
-		type="do"
-		image={{
-			url: sideNavDo3,
-			alt: 'A menu item with "Templates" label and "TRY" text properly placed in a designated slot on the right.',
-		}}
-	>
-		Use the slots in side nav menus as intended.
-	</DoDont>
-	<DoDont
-		type="dont"
-		image={{
-			url: sideNavDont6,
-			alt: 'A menu item with "Templates" label and "TRY" text incorrectly placed within the same text area.',
-		}}
-	>
-		Don't add custom elements where they're not intended, such as within the label.
-	</DoDont>
-</DoDontGrid>
-
-### Apply icon sizes correctly
-
-Consider the following when applying icon sizes:
-
-- Use [default (medium 16px) icons](/components/icon/examples#default-16px) in `elemBefore`.
-- Use [small (12px) icons](/components/icon/examples#small-12px) in `elemAfter` as well as `actions`
-  and `actionsOnHover` icon buttons.
-- Chevrons always use small (12px) icons, regardless of where they're being applied.
-- All icons in side nav menu items use [spacious padding](/components/icon/examples#spacing-props).
-
-<DoDontGrid>
-	<DoDont
-		type="do"
-		image={{
-			url: sideNavDo4,
-			alt: 'A menu item with "Projects" label, 16px rocket icon on the left, and 12px plus and ellipsis icons on the right.',
-		}}
-	>
-		Use small (12px) icons for actions, actionOnHover, and elemAfter. Use default (medium 16px)
-		icons for elemBefore.
-	</DoDont>
-	<DoDont
-		type="dont"
-		image={{
-			url: sideNavDont7,
-			alt: 'A menu item with "Projects" label, rocket icon, and incorrectly sized plus and ellipsis icons on the right.',
-		}}
-	>
-		Don't use incorrect icons sizes in menu items, which can feel unbalanced.
-	</DoDont>
-</DoDontGrid>
-
-### Apply icon button correctly
-
-Use subtle compact [icon buttons](/components/button/icon-button/examples) in side nav menu items,
-such as in `actions` and `actionsOnHover`, or `elemBefore` in expandable menu items.
-
-For `actions` and `actionsOnHover`, when there is more than one icon button, use 4px spacing.
-
-<DoDontGrid>
-	<DoDont
-		type="do"
-		image={{
-			url: sideNavDo5,
-			alt: 'A menu item with "Projects" label, rocket icon, and subtle compact plus and ellipsis icon buttons with hover tooltip.',
-		}}
-	>
-		Use subtle compact icon buttons in side nav menu items.
-	</DoDont>
-	<DoDont
-		type="dont"
-		image={{
-			url: sideNavDont8,
-			alt: 'A menu item with "Projects" label, rocket icon, and default icon buttons instead of subtle compact ones.',
-		}}
-	>
-		Don't use default icon buttons in side nav menu items.
-	</DoDont>
-</DoDontGrid>
-
-### Use ContainerAvatar
-
-<DoDontGrid>
-	<DoDont
-		type="do"
-		image={{
-			url: sideNavDo6,
-			alt: 'A menu item with "Mobile app" label and ContainerAvatar icon on the left.',
-		}}
-	>
-		Use{' '}
-		<a href="/components/navigation-system/side-nav-items/code#containeravatar">ContainerAvatar</a>{' '}
-		in side nav menu items, which are designed with the correct size and spacing.
-	</DoDont>
-	<DoDont
-		type="dont"
-		image={{
-			url: sideNavDont9,
-			alt: 'A menu item with "Mobile app" label and regular avatar icon instead of ContainerAvatar.',
-		}}
-	>
-		Don't use <a href="/components/avatar">regular avatar</a> in side nav menu items.
-	</DoDont>
-</DoDontGrid>
-
-## Content guidelines
-
-### Write labels in sentence case for menu items and labels
-
-Only capitalize the first letter of the menu item name, unless the label contains a trademarked app
-or feature name that has been approved by legal.
-
-If the menu name is user generated, display as is.
-
-<DoDontGrid>
-	<DoDont
-		type="do"
-		image={{
-			url: sideNavDo7,
-			alt: 'A menu item with "For you" label using sentence case.',
-		}}
-	>
-		Only capitalize the first letter of the first word of the label.
-	</DoDont>
-	<DoDont
-		type="dont"
-		image={{
-			url: sideNavDont10,
-			alt: 'A menu item with "For You" label using title case.',
-		}}
-	>
-		Don't capitalize other parts of the label unless it is a trademarked app or feature name (not
-		all features are capitalized).
-	</DoDont>
-</DoDontGrid>
-
-## Related
-
-- [Layout](/components/navigation-system/layout)
-- [Top nav items](/components/navigation-system/top-nav-items)
-- [Navigation experience guidelines (Atlassians only)](https://hello.atlassian.net/wiki/spaces/navx/pages/5104144812)

package/dist/cjs/entry-points/side-nav-items/button-menu-item.js

@@ -1,18 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "ButtonMenuItem", {
-  enumerable: true,
-  get: function get() {
-    return _buttonMenuItem.ButtonMenuItem;
-  }
-});
-Object.defineProperty(exports, "COLLAPSE_ELEM_BEFORE", {
-  enumerable: true,
-  get: function get() {
-    return _buttonMenuItem.COLLAPSE_ELEM_BEFORE;
-  }
-});
-var _buttonMenuItem = require("@atlaskit/side-nav-items/button-menu-item");

package/dist/cjs/entry-points/side-nav-items/container-avatar.js

@@ -1,12 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "ContainerAvatar", {
-  enumerable: true,
-  get: function get() {
-    return _containerAvatar.ContainerAvatar;
-  }
-});
-var _containerAvatar = require("@atlaskit/side-nav-items/container-avatar");

package/dist/cjs/entry-points/side-nav-items/drag-and-drop/drag-handle.js

@@ -1,12 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "LazyDragHandle", {
-  enumerable: true,
-  get: function get() {
-    return _dragHandle.LazyDragHandle;
-  }
-});
-var _dragHandle = require("@atlaskit/side-nav-items/drag-and-drop/drag-handle");

package/dist/cjs/entry-points/side-nav-items/drag-and-drop/drag-preview.js

@@ -1,12 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "DragPreview", {
-  enumerable: true,
-  get: function get() {
-    return _dragPreview.DragPreview;
-  }
-});
-var _dragPreview = require("@atlaskit/side-nav-items/drag-and-drop/drag-preview");

package/dist/cjs/entry-points/side-nav-items/drag-and-drop/drop-indicator.js

@@ -1,12 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "DropIndicator", {
-  enumerable: true,
-  get: function get() {
-    return _dropIndicator.DropIndicator;
-  }
-});
-var _dropIndicator = require("@atlaskit/side-nav-items/drag-and-drop/drop-indicator");