@atlaskit/navigation-system 0.173.0 → 0.175.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @atlassian/navigation-system
 
+## 0.175.0
+
+### Minor Changes
+
+- [#189410](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/pull-requests/189410)
+  [`5e491d9960a3f`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/5e491d9960a3f) -
+  When a `FlyoutMenuItemContent` is open, clicking outside the content will close the flyout. We
+  have improved this functionality to make it more resilient to application code that stops events.
+  This changed is behind the feature flag `"platform_dst_nav4_flyout_use_capture_outside"`
+
+### Patch Changes
+
+- Updated dependencies
+
+## 0.174.0
+
+### Minor Changes
+
+- [#186591](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/pull-requests/186591)
+  [`66ab2cbaba968`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/66ab2cbaba968) -
+  Internal refactor of a test. No public API or behaviour changes.
+- [#187173](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/pull-requests/187173)
+  [`c3ac41e33f28b`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/c3ac41e33f28b) -
+  Cleans up the `platform_design_system_nav4_top_nav_columns` and
+  `platform_design_system_nav4_top_nav_min_widths` feature gates. This enables technical
+  improvements to the top nav layout for all consumers.
+
+### Patch Changes
+
+- Updated dependencies
+
 ## 0.173.0
 
 ### Minor Changes

package/afm-dev-agents/tsconfig.json

@@ -0,0 +1,75 @@
+{
+	"extends": "../../../../tsconfig.entry-points.dev-agents.json",
+	"compilerOptions": {
+		"declaration": true,
+		"target": "es5",
+		"outDir": "../../../../../dev-agents/tsDist/@atlaskit__navigation-system/app",
+		"rootDir": "../",
+		"composite": true
+	},
+	"include": [
+		"../src/**/*.ts",
+		"../src/**/*.tsx"
+	],
+	"exclude": [
+		"../src/**/__tests__/*",
+		"../src/**/*.test.*",
+		"../src/**/test.*"
+	],
+	"references": [
+		{
+			"path": "../../../analytics/analytics-next/afm-dev-agents/tsconfig.json"
+		},
+		{
+			"path": "../../avatar/afm-dev-agents/tsconfig.json"
+		},
+		{
+			"path": "../../button/afm-dev-agents/tsconfig.json"
+		},
+		{
+			"path": "../../css/afm-dev-agents/tsconfig.json"
+		},
+		{
+			"path": "../../ds-lib/afm-dev-agents/tsconfig.json"
+		},
+		{
+			"path": "../../icon/afm-dev-agents/tsconfig.json"
+		},
+		{
+			"path": "../../layering/afm-dev-agents/tsconfig.json"
+		},
+		{
+			"path": "../../logo/afm-dev-agents/tsconfig.json"
+		},
+		{
+			"path": "../../../platform/feature-flags/afm-dev-agents/tsconfig.json"
+		},
+		{
+			"path": "../../popup/afm-dev-agents/tsconfig.json"
+		},
+		{
+			"path": "../../../pragmatic-drag-and-drop/core/afm-dev-agents/tsconfig.json"
+		},
+		{
+			"path": "../../../pragmatic-drag-and-drop/hitbox/afm-dev-agents/tsconfig.json"
+		},
+		{
+			"path": "../../../pragmatic-drag-and-drop/react-drop-indicator/afm-dev-agents/tsconfig.json"
+		},
+		{
+			"path": "../../primitives/afm-dev-agents/tsconfig.json"
+		},
+		{
+			"path": "../../../navigation/temp-nav-app-icons/afm-dev-agents/tsconfig.json"
+		},
+		{
+			"path": "../../tokens/afm-dev-agents/tsconfig.json"
+		},
+		{
+			"path": "../../tooltip/afm-dev-agents/tsconfig.json"
+		},
+		{
+			"path": "../../visually-hidden/afm-dev-agents/tsconfig.json"
+		}
+	]
+}

package/constellation/layout/usage.mdx

@@ -0,0 +1,122 @@
+---
+title: Layout
+description: Layout components define a page’s structure and the areas for navigation and content.
+order: 4
+---
+
+import layoutDo from './images/layout-do.png';
+import layoutDont from './images/layout-dont.png';
+
+## Usage
+
+Use layout to compose the structure of your application. It also defines the page behavior and
+navigational areas.
+
+When applying components to the navigational areas,
+[see navigation experience guidelines (Atlassians only)](https://hello.atlassian.net/wiki/spaces/navx/pages/5104144812).
+
+![Diagram of the navigation system layout areas](./images/layout-anatomy.png)
+
+<ol>
+	<li>
+		<strong>Banner:</strong> Optional. Use to display a <a href="/components/banner">banner</a>.
+	</li>
+	<li>
+		<strong>Top nav:</strong> Use to display{' '}
+		<a href="/components/navigation-system/top-nav-items">top nav items</a>.
+		<ol type="a">
+			<li>
+				<strong>Top nav start:</strong> Area for left-aligned actions.
+			</li>
+			<li>
+				<strong>Top nav middle:</strong> Area for centre-aligned actions.
+			</li>
+			<li>
+				<strong>Top nav end:</strong> Area for right-aligned actions.
+			</li>
+		</ol>
+	</li>
+	<li>
+		<strong>Side nav:</strong> Use to display{' '}
+		<a href="/components/navigation-system/side-nav-items">side nav items</a>. Is resizable and
+		collapsible.
+		<ol type="a" start="4">
+			<li>
+				<strong>Side nav header:</strong> Optional. Top part of the side nav (fixed).
+			</li>
+			<li>
+				<strong>Side nav content:</strong> Middle part of the side nav. Acts as the scroll
+				container.
+			</li>
+			<li>
+				<strong>Side nav footer:</strong> Optional. Bottom part of the side nav (fixed).
+			</li>
+		</ol>
+	</li>
+	<li>
+		<strong>Main:</strong> Use for the page content. Expands to fill available space.
+	</li>
+	<li>
+		<strong>Aside:</strong> Optional. Use to display supporting or supplementary content. Is
+		resizable.
+	</li>
+	<li>
+		<strong>Panel:</strong> Optional. Use to display supporting or supplementary content. Is
+		resizable and collapsible.
+	</li>
+</ol>
+
+### The difference between Aside, Panel and Modal dialog
+
+The main difference between Aside, Panel and Modal dialog is their behaviours:
+
+- **Aside** is not collapsible, while **Panel** can be collapsible.
+- **Panel** and **Aside** present content alongside the **Main** area, while **Modal dialog** exists
+  in a layer above the page.
+- On small viewports (1024px and below), the **Panel** becomes an overlay, while the **Aside** moves
+  below **Main**.
+
+#### Usage guidance:
+
+- Use **Aside** for content that needs to be constantly visible and accessible without requiring the
+  user to open it, or have the ability to close it.
+- Use **Panel** for contextual information or tertiary actions that complement the user's workflow.
+  Panels enable greater multitasking by functioning as an additional work space, while keeping users
+  connected to their primary task.
+- Use **Modal dialog** when you need your user to focus their attention on a single or specific
+  task, like requiring a decision or action before they can return to their primary task.
+
+## Best practices
+
+### Design using grid in the Main area
+
+<DoDont
+	type="do"
+	image={{
+		url: layoutDo,
+		alt: 'A layout with a grid overlay on the Main area.',
+	}}
+	isFullWidth
+>
+	When designing, use <a href="/foundations/grid-beta">Grid</a> to position content within the Main
+	area only.
+</DoDont>
+
+<DoDont
+	type="dont"
+	image={{
+		url: layoutDont,
+		alt: 'A layout with a grid overlay on the Main area, but also on the Side nav, Aside and Panel areas.',
+	}}
+	isFullWidth
+>
+	Don't include Side nav, Aside or Panel areas as part of your Grid.
+</DoDont>
+
+## Related
+
+- [Page header](/components/page-header)
+- [Side nav items](/components/navigation-system/side-nav-items)
+- [Top nav items](/components/navigation-system/top-nav-items)
+- [Navigation experience guidelines (Atlassians only)](https://hello.atlassian.net/wiki/spaces/navx/pages/5104144812)
+- [Preview panel (Atlassians only)](https://atlaskit-website-staging.stg-east.frontend.public.atl-paas.net/#/packages/navigation/preview-panel)

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

@@ -0,0 +1,324 @@
+---
+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).
+
+<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>
+
+### 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)
+
+<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>
+
+## 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.
+
+<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>
+
+### 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).
+
+<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>
+
+### 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.
+
+<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>
+
+### Use ContainerAvatar
+
+<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>
+
+## 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
+product or feature name that has been approved by legal.
+
+If the menu name is user generated, display as is.
+
+<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 product or feature name (not
+	all features are capitalized).
+</DoDont>
+
+## 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)