@atlaskit/navigation-system 0.182.0 → 1.0.0

package/src/ui/menu-item/menu-list-item.tsx

@@ -1,12 +0,0 @@
-/**
- * @jsxRuntime classic
- * @jsx jsx
- */
-import { ListItem } from '../../components/list-item';
-
-/**
- * __Menu list item__
- *
- * A [list item](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li) with visual styles removed.
- */
-export const MenuListItem = ListItem;

package/src/ui/menu-item/menu-list.tsx

@@ -1,12 +0,0 @@
-import { List, type ListProps } from '../../components/list';
-
-/**
- * __Menu list__
- *
- * An [unordered list](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul) with visual styles removed,
- * for semantically grouping list items.
- */
-export const MenuList: React.ForwardRefExoticComponent<
-	Omit<ListProps, 'xcss'> & React.RefAttributes<HTMLDivElement>
-	// eslint-disable-next-line @repo/internal/react/require-jsdoc
-> = List;

package/src/ui/menu-item/top-level-spacer.tsx

@@ -1,49 +0,0 @@
-/**
- * @jsxRuntime classic
- * @jsx jsx
- */
-
-import { useEffect } from 'react';
-
-import { cssMap, jsx } from '@compiled/react';
-
-import { token } from '@atlaskit/tokens';
-
-import { useLevel } from './expandable-menu-item/expandable-menu-item-context';
-
-const styles = cssMap({
-	root: {
-		height: token('space.150'),
-	},
-});
-
-/**
- * Use this component to create visual separation between the:
- *
- * - global app shortcut section
- * - 'more' button menu item
- * - starred spaces (in Confluence)
- *
- * Only use this component in the top level of the menu,
- * and exercise caution when using it in new situations.
- *
- * This component exists to fulfil product design requirements but has not yet
- * been consolidated into the wider navigation system.
- *
- * It may not exist in the future when global apps are no longer in the side navigation.
- */
-export function TopLevelSpacer() {
-	const level = useLevel();
-
-	useEffect(() => {
-		if (process.env.NODE_ENV !== 'production') {
-			if (level !== 0) {
-				throw new Error(
-					'TopLevelSpacer should only be used in the top level of the menu. Please speak with DST if you have a novel use case.',
-				);
-			}
-		}
-	}, [level]);
-
-	return <div css={styles.root} />;
-}

package/src/ui/menu-item/types.tsx

@@ -1,181 +0,0 @@
-import type React from 'react';
-
-import type { UIAnalyticsEvent } from '@atlaskit/analytics-next';
-
-import { type COLLAPSE_ELEM_BEFORE_TYPE } from './menu-item-signals';
-
-export type MenuItemOnClick<T extends HTMLAnchorElement | HTMLButtonElement> = (
-	event: React.MouseEvent<T>,
-	analyticsEvent: UIAnalyticsEvent,
-) => void;
-
-/**
- * Props shared across _all_ menu item components:
- * - MenuItemBase
- * - LinkMenuItem
- * - ButtonMenuItem
- * - ExpandableMenuItemTrigger
- * - FlyoutMenuItemTrigger
- */
-export type MenuItemCommonProps = {
-	/**
-	 * The main textual content and label of the menu item.
-	 *
-	 * The content will be truncated to fit into the side nav in one line.
-	 *
-	 * **Note:** Placing non-textual content (such as lozenges) can cause unexpected truncation behavior.
-	 * Use the provided slot props such as `elemBefore` or `elemAfter` for non-textual content instead.
-	 */
-	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;
-
-	/**
-	 * An optional name used to identify events for [React UFO (Unified Frontend Observability) press interactions](https://developer.atlassian.com/platform/ufo/react-ufo/react-ufo/getting-started/#quick-start--press-interactions). For more information, see [React UFO integration into Design System components](https://go.atlassian.com/react-ufo-dst-integration).
-	 */
-	interactionName?: string;
-
-	/**
-	 * Disable tooltip for menu item content. This should only be done when there is some other way
-	 * to display the full menu content and description of a menu item close by (eg with another popup)
-	 */
-	isContentTooltipDisabled?: boolean;
-
-	/**
-	 * Exposes the visually complete menu item, including:
-	 *
-	 * - the main interactive element (exposed through `ref`)
-	 * - any `elemBefore`, `elemAfter`, `actions`, or `actionsOnHover`
-	 *
-	 * This specifically excludes the wrapping list item,
-	 * which is also exposed through either:
-	 * - the `listItemRef` prop for LinkMenuItem and ButtonMenuItem
-	 * - the `ref` prop for FlyoutMenuItem and ExpandableMenuItem
-	 */
-	visualContentRef?: React.Ref<HTMLDivElement>;
-
-	/**
-	 * Whether the element is being dragged. Will apply "dragging" styles to
-	 * menu item.
-	 */
-	isDragging?: boolean;
-
-	/**
-	 * Whether this menu item can be dragged. Add a drag handle to this item.
-	 * You are responsible for wiring up drag and drop to the menu item.
-	 *
-	 *
-	 * - Please be sure to make the MenuItem `ref` the `draggable` element
-	 * - See our navigation drag and drop guidelines for more technical details
-	 */
-	hasDragIndicator?: boolean;
-
-	/**
-	 * A slot to render drop indicators for drag and drop operations on the menu item.
-	 */
-	dropIndicator?: React.ReactNode;
-};
-
-/**
- * Menu item grid slots. These are used in:
- * - MenuItemBase
- * - LinkMenuItem
- * - ButtonMenuItem
- * - ExpandableMenuItemTrigger
- */
-export type MenuItemSlots = {
-	/**
-	 * `ReactNode` to be placed visually before the `children`.
-	 *
-	 * This `ReactNode` will be rendered visually on top of the main
-	 * interactive element for the menu item. If this element does not
-	 * contain an interactive element (`button` or `a`) then `pointer-events`
-	 * will be set to `none` on this slot so that users can click through
-	 * this element onto the main interactive element of the menu item.
-	 *
-	 * If you want to collapse the `elemBefore` so it takes up no space,
-	 * then pass in the `COLLAPSE_ELEM_BEFORE` symbol. Keep in mind that
-	 * collapsing the `elemBefore` can break visual alignment and
-	 * will make it difficult for users to visually distinguish levels
-	 * in the side navigation.
-	 *
-	 * @example
-	 *
-	 * ```tsx
-	 * <MenuItemButton elemBefore={<HomeIcon label="home" />}>Home</MenuItemButton>
-	 *
-	 * // collapse the elemBefore
-	 * <MenuItemButton elemBefore={COLLAPSE_ELEM_BEFORE}>Home</MenuItemButton>
-	 * ```
-	 */
-	elemBefore?: React.ReactNode | COLLAPSE_ELEM_BEFORE_TYPE;
-
-	/**
-	 * `ReactNode` to be placed visually after the `children`.
-	 *
-	 * It is intended for additional actions (e.g. IconButtons).
-	 *
-	 * They will not be rendered when the menu item is disabled.
-	 */
-	actions?: React.ReactNode;
-
-	/**
-	 * `ReactNode` to be placed visually after the `children`.
-	 *
-	 * It is intended for static content (e.g. a `Lozenge`).
-	 *
-	 * If both `elemAfter` and `actionsOnHover` are provided, `elemAfter` will
-	 * not be displayed when the item is hovered over or expanded. This is
-	 * because the `actionsOnHover` will be displayed instead.
-	 *
-	 * This `ReactNode` will be rendered visually on top of the main
-	 * interactive element for the menu item. If this element does not
-	 * contain an interactive element (`button` or `a`) then `pointer-events`
-	 * will be set to `none` on this slot so that users can click through
-	 * this element onto the main interactive element of the menu item.
-	 */
-	elemAfter?: React.ReactNode;
-
-	/**
-	 * `ReactNode` to be placed visually after the `children` and will
-	 * only be displayed on hover or focus.
-	 *
-	 * It is intended for additional actions (e.g. IconButtons).
-	 *
-	 * This `ReactNode` will replace `elemAfter` on hover or focus.
-	 *
-	 * They will not be rendered when the menu item is disabled.
-	 *
-	 * This `ReactNode` will be rendered visually on top of the main
-	 * interactive element for the menu item. If this element does not
-	 * contain an interactive element (`button` or `a`) then `pointer-events`
-	 * will be set to `none` on this slot so that users can click through
-	 * this element onto the main interactive element of the menu item.
-	 */
-	actionsOnHover?: React.ReactNode;
-};
-
-/**
- * Props shared across:
- * - MenuItemBase
- * - LinkMenuItem
- * - ButtonMenuItem
- */
-export type MenuItemLinkOrButtonCommonProps = MenuItemCommonProps &
-	MenuItemSlots & {
-		/**
-		 * Additional textual content for the menu item.
-		 * It is displayed underneath the main content.
-		 */
-		description?: string;
-
-		/**
-		 * Exposes the `<div role="listitem">` element that wraps the entire item.
-		 *
-		 * This is the root element rendered by the component.
-		 */
-		listItemRef?: React.Ref<HTMLDivElement>;
-	};

package/src/ui/menu-item/use-scroll-menu-item-into-view.tsx

@@ -1,78 +0,0 @@
-import { useEffect, useRef } from 'react';
-
-import invariant from 'tiny-invariant';
-
-import { useAreAllAncestorsExpanded } from './expandable-menu-item/expandable-menu-item-context';
-
-type WaitingState = {
-	type: 'waiting-to-be-selected-and-all-ancestors-expanded' | 'waiting-to-be-unselected';
-};
-
-function scrollMenuItemIntoView(element: HTMLDivElement): void {
-	/**
-	 * If [scrollIntoViewIfNeeded](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoViewIfNeeded) is available,
-	 * we are using it to scroll the element into view _in the center_ of the scroll container. Because it is a non-standard method
-	 * and not available on all browsers (currently not supported in Firefox), we are using it for progressive enhancement.
-	 *
-	 * Otherwise, we are falling back to [scrollIntoView](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView).
-	 */
-	if (typeof element.scrollIntoViewIfNeeded === 'function') {
-		element.scrollIntoViewIfNeeded(true);
-		return;
-	}
-
-	// JSDOM does not support scrollIntoView, so defensively using it (see https://github.com/jsdom/jsdom/issues/1695)
-	element.scrollIntoView?.({
-		// We are using `nearest` to prevent scrolling on user interaction when the menu item is already in view.
-		block: 'nearest',
-	});
-}
-
-/**
- * Scrolls the element into view once it is selected, and once all its ancestors (expandable
- * parent menu items) are expanded.
- *
- * Once that has happened, we don't want to scroll it into view again until it has been unselected.
- * This is to prevent the menu item from being scrolled into view again if the user collapses a
- * parent and then expands it again, without changing what menu item is selected.
- */
-export function useScrollMenuItemIntoView({
-	elementRef,
-	isSelected,
-}: {
-	elementRef: React.RefObject<HTMLDivElement>;
-	isSelected: boolean;
-}): void {
-	const areAllAncestorsExpanded = useAreAllAncestorsExpanded();
-
-	const waitingStateRef = useRef<WaitingState>({
-		type: 'waiting-to-be-selected-and-all-ancestors-expanded',
-	});
-
-	useEffect(() => {
-		if (waitingStateRef.current.type === 'waiting-to-be-selected-and-all-ancestors-expanded') {
-			const shouldScroll = areAllAncestorsExpanded && isSelected;
-
-			if (!shouldScroll) {
-				return;
-			}
-
-			const element = elementRef.current;
-			invariant(element, 'Element ref must be set');
-			scrollMenuItemIntoView(element);
-
-			// Now that we are scrolled the menu item into view, we need to wait for the menu item to
-			// be unselected before checking again.
-			waitingStateRef.current.type = 'waiting-to-be-unselected';
-			return;
-		}
-
-		if (waitingStateRef.current.type === 'waiting-to-be-unselected') {
-			if (!isSelected) {
-				waitingStateRef.current.type = 'waiting-to-be-selected-and-all-ancestors-expanded';
-			}
-
-			return;
-		}
-	}, [areAllAncestorsExpanded, elementRef, isSelected]);
-}

package/src/ui/menu-section/__tests__/unit/menu-section.test.tsx

@@ -1,96 +0,0 @@
-import React from 'react';
-
-import { render, screen } from '@testing-library/react';
-
-import { Divider } from '../../divider';
-import { MenuSection } from '../../menu-section';
-import { MenuSectionHeading } from '../../menu-section-heading';
-
-describe('Divider', () => {
-	// We have VR coverage in addition to this
-	it('should not render a semantic separator', () => {
-		render(<Divider />);
-
-		expect(screen.queryByRole('separator')).not.toBeInTheDocument();
-	});
-});
-
-describe('MenuSection', () => {
-	it('should be accessible when heading is provided', async () => {
-		const { container } = render(
-			<MenuSection>
-				<MenuSectionHeading>Test title</MenuSectionHeading>
-				<button>Some menu item</button>
-				<Divider />
-			</MenuSection>,
-		);
-
-		await expect(container).toBeAccessible();
-	});
-
-	it('should be accessible when heading is not provided', async () => {
-		const { container } = render(
-			<MenuSection>
-				<button>Some menu item</button>
-				<Divider />
-			</MenuSection>,
-		);
-
-		await expect(container).toBeAccessible();
-	});
-
-	it('should display children', () => {
-		render(<MenuSection>Child</MenuSection>);
-
-		expect(screen.getByText('Child')).toBeVisible();
-	});
-
-	it('should be labelled by the MenuSectionHeading', () => {
-		render(
-			<MenuSection>
-				<MenuSectionHeading>Test title</MenuSectionHeading>
-			</MenuSection>,
-		);
-
-		expect(screen.getByRole('group', { name: 'Test title' })).toBeVisible();
-	});
-
-	describe('isMenuListItem', () => {
-		it('should not be a list item when false', () => {
-			render(
-				<MenuSection isMenuListItem={false}>
-					<MenuSectionHeading>Test title</MenuSectionHeading>
-				</MenuSection>,
-			);
-
-			expect(screen.queryByRole('listitem')).not.toBeInTheDocument();
-		});
-
-		it('should be a list item when true', () => {
-			render(
-				<MenuSection isMenuListItem>
-					<MenuSectionHeading>Test title</MenuSectionHeading>
-				</MenuSection>,
-			);
-
-			const listitem = screen.getByRole('listitem');
-			const group = screen.getByRole('group', { name: 'Test title' });
-
-			expect(listitem).toBeInTheDocument();
-			expect(listitem).toContainElement(group);
-		});
-	});
-});
-
-describe('MenuSectionHeading', () => {
-	it('should display a heading with correct name', () => {
-		render(
-			// Wrapping in MenuSection to provide context
-			<MenuSection>
-				<MenuSectionHeading>Test title</MenuSectionHeading>
-			</MenuSection>,
-		);
-
-		expect(screen.getByRole('heading', { name: 'Test title' })).toBeVisible();
-	});
-});

package/src/ui/menu-section/__tests__/vr-tests/divider.vr.tsx

@@ -1,14 +0,0 @@
-import { type Hooks, snapshot, type SnapshotTestOptions } from '@af/visual-regression';
-
-import { Divider } from '../../divider';
-
-const lightModeVariant: SnapshotTestOptions<Hooks>['variants'] = [
-	{
-		environment: { colorScheme: 'light' },
-		name: 'default',
-	},
-];
-
-snapshot(Divider, {
-	variants: lightModeVariant,
-});

package/src/ui/menu-section/__tests__/vr-tests/menu-section.vr.tsx

@@ -1,14 +0,0 @@
-import { type Hooks, snapshot, type SnapshotTestOptions } from '@af/visual-regression';
-
-import MenuSectionExample from '../../../../../examples/menu-section';
-
-const lightModeVariant: SnapshotTestOptions<Hooks>['variants'] = [
-	{
-		environment: { colorScheme: 'light' },
-		name: 'default',
-	},
-];
-
-snapshot(MenuSectionExample, {
-	variants: lightModeVariant,
-});

package/src/ui/menu-section/divider.tsx

@@ -1,33 +0,0 @@
-/**
- * @jsxRuntime classic
- * @jsx jsx
- */
-import { css, jsx } from '@compiled/react';
-
-import { token } from '@atlaskit/tokens';
-
-const styles = css({
-	width: '100%',
-	borderBlockEnd: 'none',
-	borderBlockStart: `1px solid ${token('color.border')}`,
-	borderInline: 'none',
-});
-
-/**
- * __Divider__
- *
- * A divider for use between menu sections.
- */
-export const Divider = () => (
-	<hr
-		/**
-		 * The existing usage of these dividers is presentational,
-		 * so we are removing the separator semantics by default.
-		 *
-		 * In the future we may consider allowing opt-in separator semantics,
-		 * but it probably isn't necessary.
-		 */
-		role="none"
-		css={styles}
-	/>
-);

package/src/ui/menu-section/menu-section-context.tsx

@@ -1,15 +0,0 @@
-import { createContext, useContext } from 'react';
-
-import invariant from 'tiny-invariant';
-
-/**
- * Context for the current menu section. It holds a unique ID for the section, used for associating the section heading
- * as an accessible label for the group.
- */
-export const MenuSectionContext = createContext<string | null>(null);
-
-export const useMenuSectionContext = () => {
-	const context = useContext(MenuSectionContext);
-	invariant(context, 'useMenuSectionContext must be used within a MenuSection');
-	return context;
-};

package/src/ui/menu-section/menu-section-heading.tsx

@@ -1,43 +0,0 @@
-/**
- * @jsxRuntime classic
- * @jsx jsx
- */
-import { type ReactNode } from 'react';
-
-import { cssMap, jsx } from '@compiled/react';
-
-import { token } from '@atlaskit/tokens';
-
-import { useMenuSectionContext } from './menu-section-context';
-
-const styles = cssMap({
-	root: {
-		color: token('color.text.subtlest'),
-		font: token('font.heading.xxsmall'),
-		paddingBlock: token('space.100'),
-		paddingInlineStart: token('space.075'),
-	},
-});
-
-/**
- * __MenuSectionHeading__
- *
- * The label for the menu section group.
- */
-export const MenuSectionHeading = ({
-	children,
-}: {
-	/**
-	 * The text of the heading.
-	 */
-	children: ReactNode;
-}): JSX.Element => {
-	const id = useMenuSectionContext();
-
-	return (
-		// eslint-disable-next-line @atlaskit/design-system/use-heading
-		<h2 css={styles.root} id={`${id}-heading`}>
-			{children}
-		</h2>
-	);
-};

package/src/ui/menu-section/menu-section.tsx

@@ -1,70 +0,0 @@
-import React, { type ReactNode } from 'react';
-
-import { useId } from '@atlaskit/ds-lib/use-id';
-
-import { MenuListItem } from '../menu-item/menu-list-item';
-
-import { MenuSectionContext } from './menu-section-context';
-
-type MenuSectionProps = {
-	/**
-	 * The contents of the menu section.
-	 * Should contain a `MenuSectionHeading`, and a `Divider` if appropriate.
-	 */
-	children?: ReactNode;
-	/**
-	 * Wraps the `MenuSection` in a `MenuListItem` so that it can validly be the child of a `MenuList`
-	 *
-	 * In the future this will become the default behavior, and the prop will be removed.
-	 */
-	isMenuListItem?: boolean;
-
-	/**
-	 * A unique string that appears as data attribute `data-testid` in the rendered code, serving as a hook for automated tests.
-	 *
-	 * It is applied to the outer rendered element.
-	 *
-	 * Right now, it is only applied when `isMenuListItem:true`
-	 */
-	testId?: string;
-};
-
-/**
- * __MenuSection__
- *
- * A composable component for grouping menu items, along with a heading (`MenuSectionHeading`) and a divider (`Divider`).
- *
- * Usage example:
- * ```tsx
- * <MenuSection>
- *   <MenuSectionHeading>Section heading</MenuSectionHeading>
- *   <MenuList>
- *     <MenuItem>Item 1</MenuItem>
- *     <MenuItem>Item 2</MenuItem>
- *   </MenuList>
- *   <Divider />
- * </MenuSection>
- * ```
- */
-export const MenuSection = ({
-	children,
-	testId,
-	isMenuListItem = false,
-}: MenuSectionProps): JSX.Element => {
-	const id = useId();
-
-	const content = (
-		<MenuSectionContext.Provider value={id}>
-			<div role="group" aria-labelledby={`${id}-heading`}>
-				{children}
-			</div>
-		</MenuSectionContext.Provider>
-	);
-
-	if (isMenuListItem) {
-		return <MenuListItem testId={testId}>{content}</MenuListItem>;
-	}
-
-	// Legacy. isMenuListItem should become default.
-	return content;
-};