@atlaskit/navigation-system 0.166.0

package/src/ui/page-layout/top-nav/top-nav-middle.tsx

@@ -0,0 +1,111 @@
+/**
+ * @jsxRuntime classic
+ * @jsx jsx
+ */
+import React from 'react';
+
+import { jsx } from '@compiled/react';
+
+import { cssMap } from '@atlaskit/css';
+import { fg } from '@atlaskit/platform-feature-flags';
+import { token } from '@atlaskit/tokens';
+
+const styles = cssMap({
+	root: {
+		gap: token('space.100'),
+		width: '100%',
+		gridColumn: 2,
+		alignItems: 'center',
+	},
+	oldLayoutStyles: {
+		display: 'flex',
+		justifyContent: 'end',
+		'@media (min-width: 30rem)': {
+			justifyContent: 'center',
+		},
+	},
+	newLayoutStyles: {
+		/**
+		 * On small viewports the search is an icon button.
+		 *
+		 * We want the icon button (and Create button) to hug the right / end.
+		 */
+		display: 'flex',
+		justifyContent: 'end',
+		/**
+		 * On large viewports the search is a text field.
+		 *
+		 * We want our search bar to adapt to available space (up to a maximum of `780px`)
+		 * but we need to set that constraint in the grid.
+		 *
+		 * The parent grid on TopNav gives `TopNavMiddle` an `auto` width,
+		 * so `TopNavMiddle` must set up further layout constraints.
+		 *
+		 * Setting it just on the search directly does not seem possible,
+		 * because without the column `minmax` the search collapses to its `min-content` width.
+		 *
+		 * Because we need to set it on the column, we need to make an assumption / requirement
+		 * that the search is always the first item.
+		 */
+		'@media (min-width: 48rem)': {
+			display: 'grid',
+			// This column constraint is only relevant for the search bar
+			// It only applies to the first column
+			// We know we can safely shrink the search to `min-content` because its text content can't wrap
+			gridTemplateColumns: 'minmax(min-content, 780px)',
+			// Additional items will be inserted into implicitly-created columns
+			gridAutoFlow: 'column',
+			// Determines the width of any implicitly-created columns
+			// Using `max-content` because we don't want text to wrap
+			gridAutoColumns: 'max-content',
+			/**
+			 * The Search Platform component uses a `780px` breakpoint which is not aligned
+			 * with our `48rem` / `768px` breakpoint.
+			 *
+			 * This means there is a small range where the search is an icon button and we
+			 * are still on the grid layout. So there is a `32px` wide icon button inside
+			 * of a potentially `780px` column.
+			 *
+			 * We need to apply `justifyItems: 'end'` to ensure that icon button hugs the end of its column.
+			 *
+			 * We can remove this once the Search Platform component is aligned with our breakpoints.
+			 */
+			justifyItems: 'end',
+		},
+	},
+});
+
+/**
+ * __TopNavMiddle__
+ *
+ * Wrapper for the actions in the middle of the top navigation.
+ *
+ * Expects that the search bar is the first child.
+ * If it is not, you might see unexpected layout behavior.
+ */
+export function TopNavMiddle({
+	children,
+}: {
+	/**
+	 * The content of the layout area.
+	 *
+	 * The first child should be the search bar.
+	 * If it is not, you might see unexpected layout behavior.
+	 *
+	 * Should also contain the Create button.
+	 */
+	children: React.ReactNode;
+}) {
+	return (
+		<div
+			css={[
+				styles.root,
+				fg('platform_design_system_nav4_top_nav_columns')
+					? styles.newLayoutStyles
+					: styles.oldLayoutStyles,
+			]}
+		>
+			{children}
+		</div>
+	);
+}

package/src/ui/page-layout/top-nav/top-nav-start.tsx

@@ -0,0 +1,96 @@
+/**
+ * @jsxRuntime classic
+ * @jsx jsx
+ */
+import React, { useContext, useEffect, useRef } from 'react';
+
+import { jsx } from '@compiled/react';
+
+import { cssMap } from '@atlaskit/css';
+import { fg } from '@atlaskit/platform-feature-flags';
+import { token } from '@atlaskit/tokens';
+
+import { TopNavStartAttachRef } from '../../../context/top-nav-start/top-nav-start-context';
+
+const styles = cssMap({
+	root: {
+		// Taking up the full height of top bar to allow for monitoring mouse events, for improving the side nav flyout experience
+		height: '100%',
+		alignItems: 'center',
+		display: 'flex',
+		gap: token('space.050'),
+		gridColumn: 1,
+	},
+	// Adds extra padding between the logo and search bar when they are pressed against each other
+	logoPaddingStyles: {
+		'@media (min-width: 30rem)': {
+			paddingInlineEnd: token('space.075'),
+		},
+	},
+	// Sets a minimum width on the content so that it aligns with the side nav (when side nav is at default width)
+	contentMinWidthStyles: {
+		'@media (min-width: 64rem)': {
+			// Intrinsic width of content without wrapping
+			// The actual grid column can still be larger
+			width: 'max-content',
+			/**
+			 * Using `300px` because:
+			 *
+			 * - Side nav default width is `320px`
+			 * - Top bar has `12px` padding on each side
+			 * - There is an `8px` gap between TopNavStart and TopNavMiddle
+			 *
+			 * So `320px` - (`12px` + `8px`) = `300px`
+			 */
+			minWidth: '300px',
+			// We want the specified width to be inclusive of padding
+			boxSizing: 'border-box',
+		},
+	},
+});
+
+/**
+ * __TopNavStart__
+ *
+ * Wrapper for the top navigation actions on the inline-start (left) side of the top navigation.
+ */
+export function TopNavStart({
+	children,
+	testId,
+}: {
+	/**
+	 * The content of the layout area.
+	 *
+	 * Should contain `SideNavToggleButton`, `AppSwitcher`, and `NavLogo` components.
+	 */
+	children: React.ReactNode;
+	/**
+	 * A unique string that appears as data attribute `data-testid` in the rendered code, serving as a hook for automated tests.
+	 */
+	testId?: string;
+}) {
+	const ref = useContext(TopNavStartAttachRef);
+	const elementRef = useRef(null);
+
+	useEffect(() => {
+		if (fg('platform_fix_component_state_update_for_suspense')) {
+			ref(elementRef.current);
+		}
+	}, [elementRef, ref]);
+
+	return (
+		<div
+			css={[
+				styles.root,
+				fg('platform_design_system_nav4_top_nav_min_widths')
+					? styles.contentMinWidthStyles
+					: // Removing the extra logo padding when applying the content min width
+						styles.logoPaddingStyles,
+			]}
+			ref={fg('platform_fix_component_state_update_for_suspense') ? elementRef : ref}
+			data-testid={testId}
+		>
+			{children}
+		</div>
+	);
+}

package/src/ui/page-layout/top-nav/top-nav.tsx

@@ -0,0 +1,142 @@
+/**
+ * @jsxRuntime classic
+ * @jsx jsx
+ */
+import { useContext } from 'react';
+
+import { cssMap, jsx } from '@compiled/react';
+
+import type { StrictXCSSProp } from '@atlaskit/css';
+import { fg } from '@atlaskit/platform-feature-flags';
+import { token } from '@atlaskit/tokens';
+
+import { useSkipLink } from '../../../context/skip-links/skip-links-context';
+import { type CustomTheme } from '../../top-nav-items/themed/get-custom-theme-styles';
+import { HasCustomThemeContext } from '../../top-nav-items/themed/has-custom-theme-context';
+import { useCustomTheme } from '../../top-nav-items/themed/use-custom-theme';
+import {
+	bannerMountedVar,
+	localSlotLayers,
+	topNavMountedVar,
+	UNSAFE_topNavVar,
+} from '../constants';
+import { DangerouslyHoistSlotSizes } from '../hoist-slot-sizes-context';
+import { DangerouslyHoistCssVarToDocumentRoot, HoistCssVarToLocalGrid } from '../hoist-utils';
+import { useLayoutId } from '../id-utils';
+import type { CommonSlotProps } from '../types';
+
+const styles = cssMap({
+	root: {
+		gridArea: 'top-bar',
+		display: 'grid',
+		// For small viewports the top bar sets the center grid item to take up as much space as possible.
+		gridTemplateColumns: 'auto 1fr auto',
+		paddingInline: token('space.150'),
+		gap: token('space.100'),
+		alignItems: 'center',
+		backgroundColor: token('elevation.surface'),
+		boxSizing: 'border-box',
+		borderBlockEnd: `1px solid ${token('color.border')}`,
+		// eslint-disable-next-line @atlaskit/ui-styling-standard/no-imported-style-values, @atlaskit/ui-styling-standard/no-unsafe-values
+		height: `var(${topNavMountedVar})`,
+		// This sets the sticky point to be just below banner. It's needed to ensure the stick
+		// point is exactly where this element is rendered to with no wiggle room. Unfortunately the CSS
+		// spec for sticky doesn't support "stick to where I'm initially rendered" so we need to tell it.
+		// eslint-disable-next-line @atlaskit/ui-styling-standard/no-imported-style-values, @atlaskit/ui-styling-standard/no-unsafe-values
+		insetBlockStart: `var(${bannerMountedVar}, 0px)`,
+		position: 'sticky',
+		// eslint-disable-next-line @atlaskit/ui-styling-standard/no-unsafe-values, @atlaskit/ui-styling-standard/no-imported-style-values -- Ignored via go/DSP-18766
+		zIndex: localSlotLayers.topBar,
+		// eslint-disable-next-line @atlaskit/ui-styling-standard/no-nested-selectors
+		' > span[data-ep-placeholder-id="top_navigation_skeleton"]': {
+			// TODO: BLU-3336 This is needed as a workaround for the JIRA issue (it places a placeholder span as a direct child of TopNav which breaks the grid layout). Please remove when the proper fix is applied.
+			// We get the span that is immediately nested under TopNav and ignore how it affects the layout. We do this so our Grid layout ignores the `span` and applies to it's children.
+			// This is only applicable to the JIRA pages that use EntryPoint such as /jira/projects or /jira/software/projects/.../calendar
+			display: 'contents',
+		},
+	},
+	oldLayoutStyles: {
+		'@media (min-width: 64rem)': {
+			// The top bar is set so for as long as possible the center grid item
+			// ("common actions") are visually centered between the start and end grid items.
+			gridTemplateColumns: '1fr 3fr 1fr',
+		},
+	},
+	newLayoutStyles: {
+		// The layout switches at the same breakpoint as when the search bar becomes an icon button.
+		'@media (min-width: 48rem)': {
+			// Using `1fr` for the left and right columns allows them to stay equal for as long as possible
+			// There is another grid layout in `TopNavMiddle` that allows the middle column to grow and shrink in a constrained way
+			gridTemplateColumns: '1fr minmax(min-content, max-content) 1fr',
+		},
+	},
+});
+
+/**
+ * The top nav layout area. It will display at the top of the screen, below the banner if one is present.
+ */
+export function TopNav({
+	children,
+	xcss,
+	height = 48,
+	skipLinkLabel = 'Top Bar',
+	testId,
+	id: providedId,
+	UNSAFE_theme,
+}: CommonSlotProps & {
+	/**
+	 * The content of the layout area.
+	 * Should include `TopNavStart`, `TopNavMiddle`, and `TopNavEnd`.
+	 */
+	children: React.ReactNode;
+	/**
+	 * Bounded style overrides.
+	 */
+	xcss?: StrictXCSSProp<'backgroundColor', never>;
+	/**
+	 * Not intended for long term use. This is added to support the migration to the new page layout.
+	 * We may replace this prop in a future release.
+	 */
+	height?: number;
+	/**
+	 * EXPERIMENTAL - DO NOT USE
+	 *
+	 * Feature is incomplete and API is subject to change at any time
+	 */
+	UNSAFE_theme?: CustomTheme;
+}) {
+	const dangerouslyHoistSlotSizes = useContext(DangerouslyHoistSlotSizes);
+	const id = useLayoutId({ providedId });
+	useSkipLink(id, skipLinkLabel);
+
+	const customTheme = useCustomTheme(UNSAFE_theme);
+
+	return (
+		<HasCustomThemeContext.Provider value={customTheme.isEnabled}>
+			<header
+				id={id}
+				data-layout-slot
+				css={[
+					styles.root,
+					fg('platform_design_system_nav4_top_nav_columns')
+						? styles.newLayoutStyles
+						: styles.oldLayoutStyles,
+				]}
+				className={xcss}
+				data-testid={testId}
+				// eslint-disable-next-line @atlaskit/ui-styling-standard/enforce-style-prop
+				style={customTheme.isEnabled ? customTheme.style : undefined}
+			>
+				<HoistCssVarToLocalGrid variableName={topNavMountedVar} value={height} />
+				{dangerouslyHoistSlotSizes && (
+					// ------ START UNSAFE STYLES ------
+					// These styles are only needed for the UNSAFE legacy use case for Jira + Confluence.
+					// When they aren't needed anymore we can delete them wholesale.
+					<DangerouslyHoistCssVarToDocumentRoot variableName={UNSAFE_topNavVar} value={height} />
+					// ------ END UNSAFE STYLES ------
+				)}
+				{children}
+			</header>
+		</HasCustomThemeContext.Provider>
+	);
+}

package/src/ui/page-layout/types.tsx

@@ -0,0 +1,20 @@
+/**
+ * Common props for layout slots.
+ *
+ * Does not include `children`, because we want to provide tailored JSDocs for each layout slot.
+ */
+export type CommonSlotProps = {
+	/**
+	 * The label for this slot's skip link. Defaults to the slot's `label` value.
+	 */
+	skipLinkLabel?: string;
+	/**
+	 * The `id` attribute of the slot. Used to connect the layout slot's skip link to the layout element.
+	 * If not provided, a unique ID will be generated.
+	 */
+	id?: string;
+	/**
+	 * A unique string that appears as data attribute `data-testid` in the rendered code, serving as a hook for automated tests.
+	 */
+	testId?: string;
+};

package/src/ui/page-layout/use-resizing-width-css-var-on-root-element.tsx

@@ -0,0 +1,70 @@
+import { useEffect } from 'react';
+
+import { combine } from '@atlaskit/pragmatic-drag-and-drop/combine';
+import { monitorForElements } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
+
+import { isPanelSplitterDragData } from './panel-splitter/panel-splitter';
+
+/**
+ * Monitors resizing on the panel splitter with the provided `panelId`
+ * and writes the resizing width to the `cssVar` on the root element (`<html>`).
+ */
+export function useResizingWidthCssVarOnRootElement({
+	isEnabled = true,
+	cssVar,
+	panelId,
+}: {
+	isEnabled?: boolean;
+	cssVar: string;
+	panelId: symbol;
+}) {
+	useEffect(() => {
+		if (!isEnabled) {
+			return;
+		}
+
+		return combine(
+			monitorForElements({
+				canMonitor({ source }) {
+					return source.data.panelId === panelId;
+				},
+				onDrag({ source }) {
+					if (!isPanelSplitterDragData(source.data)) {
+						return;
+					}
+
+					/**
+					 * Copies the resizing width value to the `<html>` element.
+					 *
+					 * Required to reflect the live width of the side navigation.
+					 *
+					 * Used by:
+					 *   - Legacy `--leftSidebarWidth` variable
+					 *   - Panel slot max-width constraint
+					 *
+					 * When the legacy `--leftSidebarWidth` variable is no longer needed,
+					 * we could consider writing to the `Panel` element instead.
+					 */
+					document.documentElement.style.setProperty(cssVar, source.data.resizingWidth);
+				},
+				onDrop() {
+					document.documentElement.style.removeProperty(cssVar);
+				},
+			}),
+		);
+	}, [cssVar, isEnabled, panelId]);
+
+	useEffect(() => {
+		if (!isEnabled) {
+			return;
+		}
+
+		/**
+		 * Ensures that the resizing CSS var on the `<html>` element is cleaned up properly
+		 * if the component unmounts during a drag.
+		 */
+		return function cleanupGlobalResizingCssVar() {
+			document.documentElement.style.removeProperty(cssVar);
+		};
+	}, [cssVar, isEnabled]);
+}

package/src/ui/top-nav-items/__tests__/informational-vr-tests/top-navigation.vr.tsx

@@ -0,0 +1,108 @@
+import { Device, snapshotInformational } from '@atlassian/gemini';
+
+import TopNavWithTempNavAppIcon from '../../../../../examples/top-nav-with-temp-nav-app-icon';
+import { TopNavigationExample } from '../../../../../examples/top-navigation';
+import { TopNavigationThemingSingleExample } from '../../../../../examples/top-navigation-theming';
+
+snapshotInformational(TopNavigationExample, {
+	description: 'responsive menu items on click',
+	variants: [
+		{
+			environment: { colorScheme: 'light' },
+			name: 'mobile',
+		},
+	],
+	prepare: async (page) => {
+		await page.setViewportSize({ width: 430, height: 930 });
+
+		await page.getByText('Show more').click();
+	},
+});
+
+snapshotInformational(TopNavigationExample, {
+	description: 'responsive menu items',
+	variants: [
+		{
+			environment: { colorScheme: 'light' },
+			name: 'mobile',
+		},
+	],
+	prepare: async (page) => {
+		await page.setViewportSize({ width: 430, height: 930 });
+	},
+});
+
+const interactionStateSharedOptions: Parameters<typeof snapshotInformational>[1] = {
+	variants: [
+		{
+			name: 'desktop',
+			environment: { colorScheme: 'light' },
+			device: Device.DESKTOP_CHROME,
+		},
+		{
+			name: 'mobile',
+			environment: { colorScheme: 'light' },
+			device: Device.MOBILE_CHROME,
+		},
+	],
+	selector: {
+		// Snapshot only the top nav
+		byRole: 'banner',
+	},
+};
+
+/**
+ * Using informational for hovered snapshots too,
+ * so we can keep all the tests for this colocated.
+ *
+ * Can make all these normal VR tests once pressed state variants are added to Gemini.
+ */
+snapshotInformational(TopNavWithTempNavAppIcon, {
+	...interactionStateSharedOptions,
+	description: 'nav logo hover',
+	featureFlags: {
+		'platform-team25-app-icon-tiles': true,
+		platform_design_system_nav_logo_interaction_states: true,
+	},
+	prepare: async (page) => {
+		await page.getByRole('link', { name: 'Home page' }).hover();
+	},
+});
+
+snapshotInformational(TopNavWithTempNavAppIcon, {
+	...interactionStateSharedOptions,
+	description: 'nav logo pressed',
+	featureFlags: {
+		'platform-team25-app-icon-tiles': true,
+		platform_design_system_nav_logo_interaction_states: true,
+	},
+	prepare: async (page) => {
+		await page.getByRole('link', { name: 'Home page' }).hover();
+		await page.mouse.down();
+	},
+});
+
+snapshotInformational(TopNavigationThemingSingleExample, {
+	...interactionStateSharedOptions,
+	description: 'nav logo hover - custom theming',
+	featureFlags: {
+		'platform-team25-app-icon-tiles': true,
+		platform_design_system_nav_logo_interaction_states: true,
+	},
+	prepare: async (page) => {
+		await page.getByRole('link', { name: 'Home page' }).hover();
+	},
+});
+
+snapshotInformational(TopNavigationThemingSingleExample, {
+	...interactionStateSharedOptions,
+	description: 'nav logo pressed - custom theming',
+	featureFlags: {
+		'platform-team25-app-icon-tiles': true,
+		platform_design_system_nav_logo_interaction_states: true,
+	},
+	prepare: async (page) => {
+		await page.getByRole('link', { name: 'Home page' }).hover();
+		await page.mouse.down();
+	},
+});

package/src/ui/top-nav-items/__tests__/playwright/theming.spec.tsx

@@ -0,0 +1,21 @@
+import { AxeBuilder } from '@axe-core/playwright';
+
+import { expect, test } from '@af/integration-testing';
+
+test.describe('theming', () => {
+	test('it produces sufficient color contrast', async ({ page, skipAxeCheck }) => {
+		/**
+		 * This check is not useful here.
+		 *
+		 * The example has accessibility issues, but only because we are rendering
+		 * multiple top bars in a single page. That is not a scenario that will actually occur.
+		 */
+		skipAxeCheck();
+
+		await page.visitExample('design-system', 'navigation-system', 'top-navigation-theming');
+
+		const result = await new AxeBuilder({ page }).withRules('color-contrast').analyze();
+
+		expect(result.violations).toEqual([]);
+	});
+});

package/src/ui/top-nav-items/__tests__/unit/chat-button.test.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import { List } from '../../../../components/list';
+import { ChatButton } from '../../chat-button';
+
+describe('ChatButton', () => {
+	const chatLabel = 'Chat';
+
+	it('should be accessible', async () => {
+		const { container } = render(
+			<List>
+				<ChatButton>{chatLabel}</ChatButton>
+			</List>,
+		);
+
+		await expect(container).toBeAccessible();
+		expect(screen.getByRole('listitem')).toBeInTheDocument();
+	});
+
+	it('should render button', () => {
+		render(<ChatButton>{chatLabel}</ChatButton>);
+		expect(screen.getByRole('button', { name: chatLabel })).toBeInTheDocument();
+	});
+
+	it('should trigger the `onClick` when clicked', async () => {
+		const user = userEvent.setup();
+		const onClick = jest.fn();
+
+		render(<ChatButton onClick={onClick}>{chatLabel}</ChatButton>);
+
+		const el = screen.getByRole('button');
+
+		expect(onClick).toHaveBeenCalledTimes(0);
+		await user.click(el);
+		expect(onClick).toHaveBeenCalledTimes(1);
+	});
+});

package/src/ui/top-nav-items/__tests__/unit/create-button.test.tsx

@@ -0,0 +1,34 @@
+import React from 'react';
+
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import { axe } from '@af/accessibility-testing';
+
+import { CreateButton } from '../../create-button';
+
+describe('CreateButton', () => {
+	it('should be accessible', async () => {
+		const { container } = render(<CreateButton>Create</CreateButton>);
+
+		await axe(container);
+	});
+
+	it('should be visible', () => {
+		render(<CreateButton>Create</CreateButton>);
+
+		expect(screen.getByRole('button', { name: 'Create' })).toBeVisible();
+	});
+
+	it('should trigger the `onClick` when clicked', async () => {
+		const user = userEvent.setup();
+		const onClick = jest.fn();
+
+		render(<CreateButton onClick={onClick}>Create</CreateButton>);
+
+		expect(onClick).toHaveBeenCalledTimes(0);
+
+		await user.click(screen.getByRole('button'));
+		expect(onClick).toHaveBeenCalledTimes(1);
+	});
+});