@atlaskit/navigation-system 0.182.0 → 1.0.0

package/src/ui/menu-item/expandable-menu-item/expandable-menu-item-trigger.tsx

@@ -1,334 +0,0 @@
-/**
- * @jsxFrag
- * @jsxRuntime classic
- * @jsx jsx
- */
-import React, { forwardRef, type ReactNode, useCallback, useId, useRef } from 'react';
-
-import { cssMap, jsx } from '@compiled/react';
-
-import type { UIAnalyticsEvent } from '@atlaskit/analytics-next';
-import { IconButton } from '@atlaskit/button/new';
-import type { IconProps } from '@atlaskit/icon';
-import ChevronDownIcon from '@atlaskit/icon/core/chevron-down';
-import ChevronRightIcon from '@atlaskit/icon/core/chevron-right';
-import { fg } from '@atlaskit/platform-feature-flags';
-import { token } from '@atlaskit/tokens';
-
-import { MenuItemBase, nestedOpenPopupCSSSelector } from '../menu-item';
-import type { MenuItemCommonProps, MenuItemSlots } from '../types';
-import { useScrollMenuItemIntoView } from '../use-scroll-menu-item-into-view';
-
-import {
-	useIsExpanded,
-	useOnExpansionToggle,
-	useSetIsExpanded,
-} from './expandable-menu-item-context';
-
-type ExpandableMenuItemIconProps = {
-	isExpanded: boolean;
-	isHovering: boolean;
-	isSelected?: boolean;
-	/**
-	 * The element to display when the user is not hovering over the icon. If not provided, the chevron icon will be used
-	 */
-	providedElemBefore?: ReactNode;
-	iconProps?: IconProps;
-};
-
-// Widening type to `string` to side-step Compiled cssMap typescript warnings with unknown properties
-const chevronDisplayCssVar: string = '--expandable-chevron-display';
-const providedElemBeforeDisplayCssVar: string = '--expandable-provided-elembefore-display';
-
-const wrapperStyles = cssMap({
-	root: {
-		/**
-		 * By default, we display the chevron icon only.
-		 */
-		// Using `display: flex` to ensure the chevron icon is center aligned.
-		// We can't use `display: contents` as it won't apply the `transform` property.
-		[chevronDisplayCssVar]: 'flex',
-		[providedElemBeforeDisplayCssVar]: 'none',
-	},
-	showProvidedElemBefore: {
-		/**
-		 * If there is a provided `elemBefore`, we display it in the default state instead of the chevron icon.
-		 *
-		 * We replace it with the chevron icon when:
-		 * - The user hovers over the menu item
-		 * - The user is focused on the menu item, or any of the interactive elements within the menu item
-		 * - The menu item has a nested open popup (e.g. a `More` submenu in the `actions` or `actionsOnHover` slot)
-		 */
-		[chevronDisplayCssVar]: 'none',
-		// We can use `display: contents` here as we don't need to apply the `transform` property on the provided
-		// elemBefore - we only apply it to the chevron icon.
-		[providedElemBeforeDisplayCssVar]: 'contents',
-		/**
-		 * We are using `:has(:focus-visible)` to target the menu item when it, or any of its interactive elements, should
-		 * actually appear focused. If we just used `:focus-within`, in some browsers it could (incorrectly) stay in the
-		 * focus state after being clicked.
-		 *
-		 * Ideally we want something like `:focus-visible-within`, but that doesn't exist yet - but we can emulate it
-		 * with `:has`. See: https://larsmagnus.co/blog/focus-visible-within-the-missing-pseudo-class
-		 */
-		// eslint-disable-next-line @atlaskit/ui-styling-standard/no-unsafe-selectors
-		'&:hover, &:has(:focus-visible)': {
-			[chevronDisplayCssVar]: 'flex',
-			[providedElemBeforeDisplayCssVar]: 'none',
-		},
-		// eslint-disable-next-line @atlaskit/ui-styling-standard/no-nested-selectors, @atlaskit/ui-styling-standard/no-unsafe-values, @atlaskit/ui-styling-standard/no-imported-style-values
-		[nestedOpenPopupCSSSelector]: {
-			[chevronDisplayCssVar]: 'flex',
-			[providedElemBeforeDisplayCssVar]: 'none',
-		},
-	},
-});
-
-const iconStyles = cssMap({
-	chevron: {
-		display: `var(${chevronDisplayCssVar})`,
-		// Flip the chevron icon when the direction is right-to-left
-		// eslint-disable-next-line @atlaskit/ui-styling-standard/no-nested-selectors, @atlaskit/ui-styling-standard/no-unsafe-selectors
-		'[dir="rtl"] &': {
-			transform: 'scaleX(-1)',
-		},
-	},
-	providedElemBefore: {
-		display: `var(${providedElemBeforeDisplayCssVar})`,
-	},
-	providedElemBeforeSelected: {
-		color: token('color.icon.selected'),
-	},
-});
-
-const ExpandableMenuItemIcon = ({
-	iconProps,
-	isExpanded,
-	isSelected,
-	providedElemBefore,
-}: Omit<ExpandableMenuItemIconProps, 'isHovering'>): JSX.Element => {
-	const ChevronIcon = isExpanded ? ChevronDownIcon : ChevronRightIcon;
-
-	const chevronElem = (
-		<ChevronIcon
-			{...iconProps}
-			label=""
-			color={isSelected ? token('color.icon.selected') : undefined}
-			size="small"
-		/>
-	);
-
-	return (
-		<>
-			<div css={iconStyles.chevron}>{chevronElem}</div>
-			{/* If there is no provided elemBefore, not rendering the wrapper either to simplify the DOM */}
-			{providedElemBefore && (
-				<div
-					css={[iconStyles.providedElemBefore, isSelected && iconStyles.providedElemBeforeSelected]}
-				>
-					{providedElemBefore}
-				</div>
-			)}
-		</>
-	);
-};
-
-export type ExpandableMenuItemTriggerProps = MenuItemCommonProps &
-	// Overriding `MenuItemSlots` that have distinct behaviour in expandable menu items.
-	// Using `Omit` prevents the jsdoc from MenuItemSlots also being merged in.
-	Omit<MenuItemSlots, 'actionsOnHover' | 'elemBefore'> & {
-		// Overriding the `actionsOnHover` prop to add specific JSDOCs for expandable behaviour.
-		/**
-		 * `ReactNode` to be placed visually after the `children` and will
-		 * only be displayed on hover or focus, or when the expandable menu item
-		 * is expanded.
-		 *
-		 * It is intended for additional actions (e.g. IconButtons).
-		 *
-		 * This `ReactNode` will replace `elemAfter` on hover/focus or when expanded.
-		 *
-		 * 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?: ReactNode;
-
-		// Overriding the `elemBefore` prop to remove the `COLLAPSE_ELEM_BEFORE_TYPE` functionality
-		// and to add custom jsdoc
-		/**
-		 * The element to display before the content of the menu item.
-		 *
-		 * By default, a chevron icon will be displayed in this slot. If a custom `elemBefore`
-		 * is provided, the custom element will replaced by the chevron icon while the user is
-		 * hovering or focused on the item.
-		 *
-		 * `ExpandableMenuItemTrigger` does not respect `COLLAPSE_ELEM_BEFORE` as a chevron
-		 * will always be displayed.
-		 */
-		elemBefore?: ReactNode;
-
-		/**
-		 * Indicates that the menu item is selected.
-		 */
-		isSelected?: boolean;
-
-		/**
-		 * If provided, the chevron icon (expand/collapse symbol) will be rendered within a separate
-		 * icon button element. Clicking on this icon button will not trigger the `onClick` event. It
-		 * will only expand or collapse the expandable.
-		 *
-		 * If a `href` is not provided, the chevron icon is rendered as part of the element.
-		 */
-		href?: string;
-
-		// Not using the shared `MenuItemOnClick` type here as we need to support additional arguments (analyticsAttributes)
-		/**
-		 * Called when the user has clicked on the trigger content.
-		 *
-		 * __It is not called when the user clicks on the expand/collapse chevron icon button.__
-		 * This is to differentiate a click that will only "expand" the menu item _without selecting it_,
-		 * from a click to expand _and_ "select" or navigate to the menu item.
-		 *
-		 * If you need a callback for when the user expands or collapses the expandable, use
-		 * `onExpansionToggle` on the `ExpandableMenuItem` component instead.
-		 */
-		onClick?: (
-			event: React.MouseEvent<HTMLAnchorElement | HTMLButtonElement>,
-			analyticsEvent: UIAnalyticsEvent,
-			analyticsAttributes: { isExpanded: boolean },
-		) => void;
-	};
-
-/**
- * __ExpandableMenuItemTrigger__
- *
- * The trigger component for an `ExpandableMenuItem`. Interacting with it will expand or collapse the expandable.
- */
-export const ExpandableMenuItemTrigger = forwardRef<
-	HTMLButtonElement | HTMLAnchorElement,
-	ExpandableMenuItemTriggerProps
->(
-	(
-		{
-			actions,
-			isSelected,
-			href,
-			elemBefore: providedElemBefore,
-			elemAfter,
-			actionsOnHover,
-			onClick,
-			children,
-			testId,
-			interactionName,
-			isContentTooltipDisabled,
-			visualContentRef,
-			isDragging,
-			hasDragIndicator,
-			dropIndicator,
-		},
-		forwardedRef,
-	) => {
-		const id = useId();
-		const onExpansionToggle = useOnExpansionToggle();
-		const isExpanded = useIsExpanded();
-		const setIsExpanded = useSetIsExpanded();
-		const itemRef = useRef<HTMLDivElement>(null);
-
-		const handleIconClick = useCallback(() => {
-			onExpansionToggle?.(!isExpanded);
-			setIsExpanded(!isExpanded);
-		}, [isExpanded, onExpansionToggle, setIsExpanded]);
-
-		const handleMenuContentClick = useCallback(
-			(
-				event: React.MouseEvent<HTMLAnchorElement | HTMLButtonElement>,
-				analyticsEvent: UIAnalyticsEvent,
-			) => {
-				const newValue = !isExpanded;
-				onClick?.(event, analyticsEvent, { isExpanded: newValue });
-				onExpansionToggle?.(newValue);
-				setIsExpanded(newValue);
-			},
-			[onClick, onExpansionToggle, isExpanded, setIsExpanded],
-		);
-
-		const isSelectable = typeof href !== 'undefined';
-
-		useScrollMenuItemIntoView({
-			elementRef: itemRef,
-			isSelected: Boolean(isSelectable && isSelected),
-		});
-
-		// Wrapped in an IconButton if the expandable menu item trigger is selectable
-		const elemBefore = isSelectable ? (
-			<IconButton
-				icon={(iconProps) => (
-					<ExpandableMenuItemIcon
-						iconProps={iconProps}
-						isExpanded={isExpanded}
-						isSelected={isSelected}
-						providedElemBefore={providedElemBefore}
-					/>
-				)}
-				aria-expanded={isExpanded}
-				// We are labelling the icon button using the containing menu item's content, to provide context to
-				// screen readers on what will actually be expanded or collapsed. Screen readers will also use the
-				// `aria-expanded` attribute to indicate the expanded state of the menu item.
-				// We are not using the `aria-label` attribute here as it is not supported by the `IconButton` component.
-				aria-labelledby={fg('platform_dst_expandable_menu_item_elembefore_label') ? id : undefined}
-				// IconButton requires a label prop, however it will not be used by screen readers as we are setting
-				// `aria-labelledby`, which will be used instead.
-				label={
-					fg('platform_dst_expandable_menu_item_elembefore_label')
-						? ''
-						: isExpanded
-							? 'Collapse'
-							: 'Expand'
-				}
-				appearance="subtle"
-				spacing="compact"
-				onClick={handleIconClick}
-				interactionName={interactionName}
-				testId={testId ? `${testId}--elem-before-button` : undefined}
-			/>
-		) : (
-			<ExpandableMenuItemIcon
-				isExpanded={isExpanded}
-				isSelected={isSelected}
-				providedElemBefore={providedElemBefore}
-			/>
-		);
-
-		// For expandable menu items, we shouldn't wrap in a `li` here. The `li` is instead at a higher level (`ExpandableMenuItem`), grouping the expandable menu item trigger and its content
-		return (
-			<div
-				css={[wrapperStyles.root, providedElemBefore && wrapperStyles.showProvidedElemBefore]}
-				ref={itemRef}
-			>
-				<MenuItemBase
-					id={id}
-					actions={actions}
-					actionsOnHover={actionsOnHover}
-					elemBefore={elemBefore}
-					ariaExpanded={isExpanded}
-					elemAfter={elemAfter}
-					href={href}
-					isSelected={isSelected}
-					onClick={handleMenuContentClick}
-					ref={forwardedRef}
-					visualContentRef={visualContentRef}
-					testId={testId}
-					interactionName={interactionName}
-					isContentTooltipDisabled={isContentTooltipDisabled}
-					isDragging={isDragging}
-					hasDragIndicator={hasDragIndicator}
-					dropIndicator={dropIndicator}
-				>
-					{children}
-				</MenuItemBase>
-			</div>
-		);
-	},
-);

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

@@ -1,114 +0,0 @@
-/**
- * @jsxFrag
- * @jsxRuntime classic
- * @jsx jsx
- */
-import { forwardRef, type ReactNode } from 'react';
-
-import { cssMap, jsx } from '@atlaskit/css';
-import useControlled from '@atlaskit/ds-lib/use-controlled';
-
-import { MenuListItem } from '../menu-list-item';
-
-import {
-	IsExpandedContext,
-	OnExpansionToggleContext,
-	SetIsExpandedContext,
-} from './expandable-menu-item-context';
-
-export type ExpandableMenuItemProps = {
-	/**
-	 * The controlled expanded state of the menu item. Allows you to control the expanded state of
-	 * the menu item externally.
-	 *
-	 * If you are controlling the state, you should update your state using `onExpansionToggle`.
-	 */
-	isExpanded?: boolean;
-	/**
-	 * The default expanded state of the menu item.
-	 *
-	 * You can use this to set the default expanded state without needing to entirely control the state.
-	 */
-	isDefaultExpanded?: boolean;
-	/**
-	 * Called when the user has interacted with the menu item to expand or collapse it.
-	 *
-	 * It is not called when the `isExpanded` controlled state prop is changed.
-	 *
-	 * If you are controlling the expanded state, you should use this callback to update your state.
-	 */
-	onExpansionToggle?: (isExpanded: boolean) => void;
-	/**
-	 * Should contain `ExpandableMenuItemTrigger` and `ExpandableMenuItemContent`.
-	 */
-	children: ReactNode;
-
-	/**
-	 * A slot to render a drop indicator on an entire menu item (trigger + content).
-	 *
-	 * This should only be used when the **whole `ExpandableMenuItem` is a drop target**,
-	 * and not when only the `ExpandableMenuItemTrigger` is a drop target.
-	 */
-	dropIndicator?: ReactNode;
-};
-
-const relativeStyles = cssMap({
-	root: {
-		position: 'relative',
-	},
-});
-
-/**
- * __ExpandableMenuItem__
- *
- * A composable component for nested menu items that can be revealed and hidden by interacting witih the parent menu item.
- *
- * Follows the [disclosure pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/).
- *
- * Should be used with `ExpandableMenuItemTrigger` as the parent menu item, and children menu items should be wrapped in a `ExpandableMenuItemContent`.
- *
- * Usage example:
- * ```jsx
- * <ExpandableMenuItem>
- *   <ExpandableMenuItemTrigger>Parent menu item</ExpandableMenuItemTrigger>
- *   <ExpandableMenuItemContent>
- *     <ButtonMenuItem>Item 1</ButtonMenuItem>
- *     <ButtonMenuItem>Item 2</ButtonMenuItem>
- *   </ExpandableMenuItemContent>
- * </ExpandableMenuItem>
- * ```
- */
-export const ExpandableMenuItem = forwardRef<HTMLDivElement, ExpandableMenuItemProps>(
-	(
-		{
-			isExpanded: isExpandedControlled,
-			isDefaultExpanded = false,
-			onExpansionToggle,
-			children,
-			dropIndicator,
-		},
-		forwardedRef,
-	) => {
-		const [isExpanded, setIsExpanded] = useControlled(
-			isExpandedControlled,
-			() => isDefaultExpanded,
-		);
-
-		return (
-			<IsExpandedContext.Provider value={isExpanded}>
-				<SetIsExpandedContext.Provider value={setIsExpanded}>
-					<OnExpansionToggleContext.Provider value={onExpansionToggle ?? null}>
-						{/* Wrapping in a `li` to group all the composable elements together, as part of the disclosure pattern */}
-						<MenuListItem ref={forwardedRef}>
-							{/* Adding `position:relative` only when it's needed by the drop indicator */}
-							<div css={[dropIndicator && relativeStyles.root]}>
-								{children}
-								{dropIndicator}
-							</div>
-						</MenuListItem>
-					</OnExpansionToggleContext.Provider>
-				</SetIsExpandedContext.Provider>
-			</IsExpandedContext.Provider>
-		);
-	},
-);

package/src/ui/menu-item/flyout-menu-item/flyout-menu-item-content.tsx

@@ -1,188 +0,0 @@
-/**
- * @jsxRuntime classic
- * @jsx jsx
- */
-import React, {
-	forwardRef,
-	useCallback,
-	useContext,
-	useEffect,
-	useMemo,
-	useRef,
-	useState,
-} from 'react';
-
-import { jsx } from '@compiled/react';
-
-import { cssMap } from '@atlaskit/css';
-import mergeRefs from '@atlaskit/ds-lib/merge-refs';
-import { fg } from '@atlaskit/platform-feature-flags';
-import { PopupContent } from '@atlaskit/popup/experimental';
-import { token } from '@atlaskit/tokens';
-
-import { SetIsOpenContext } from './flyout-menu-item-context';
-
-const flyoutMenuItemContentStyles = cssMap({
-	root: {
-		// Expanding `padding` shorthand for Compiled: see eslint rule @atlaskit/platform/expand-spacing-shorthand
-		paddingBlockStart: token('space.100'),
-		paddingBlockEnd: token('space.100'),
-		paddingInlineStart: token('space.100'),
-		paddingInlineEnd: token('space.100'),
-		'@media (min-width: 48rem)': {
-			width: '400px',
-		},
-	},
-});
-
-export type FlyoutMenuItemContentProps = {
-	/**
-	 * The contents of the flyout menu.
-	 */
-	children: React.ReactNode;
-	/**
-	 * A `testId` that is applied to the container element as the `data-testid` attribute.
-	 */
-	containerTestId?: string;
-	/**
-	 * Called when the flyout menu is closed.
-	 *
-	 * If you are controlling the open state of the flyout menu, use this to update your state.
-	 */
-	onClose?: () => void;
-	/**
-	 * Whether the flyout menu should be focused when opened.
-	 * @default true
-	 */
-	autoFocus?: boolean;
-};
-
-/**
- * __FlyoutMenuItemContent__
- *
- * The content that appears when the flyout menu is open.
- */
-export const FlyoutMenuItemContent = forwardRef<HTMLDivElement, FlyoutMenuItemContentProps>(
-	({ children, containerTestId, onClose, autoFocus }, forwardedRef) => {
-		const setIsOpen = useContext(SetIsOpenContext);
-
-		const handleClose = useCallback(() => {
-			onClose?.();
-			setIsOpen(false);
-		}, [setIsOpen, onClose]);
-
-		return (
-			<PopupContent
-				appearance="UNSAFE_modal-below-sm"
-				onClose={handleClose}
-				placement="right-start"
-				// Using a capture event listener so that we are more resilient against
-				// code that stops events. We _really_ want to close the flyout whenever
-				// user user clicks outside the flyout content
-				shouldUseCaptureOnOutsideClick={fg('platform_dst_nav4_flyout_use_capture_outside')}
-				shouldFitViewport
-				testId={containerTestId}
-				xcss={flyoutMenuItemContentStyles.root}
-				autoFocus={autoFocus}
-				/**
-				 * Disabling GPU acceleration removes the use of `transform` by popper.js for this popup.
-				 *
-				 * This allows makers to use popups with `shouldRenderToParent` inside the flyout.
-				 *
-				 * Without this, the `transform` makes the flyout the containing element for fixed positioning.
-				 * Because the flyout is also a scroll container then any nested, layered element is unable to
-				 * escape the flyout.
-				 *
-				 * Disabling the `transform` is the simplest way to resolve this layering issue,
-				 * and should have negligible performance impacts, because the flyout menus should rarely
-				 * need to be repositioned.
-				 */
-				shouldDisableGpuAcceleration
-			>
-				{({ update }) => (
-					<UpdatePopperOnContentResize ref={forwardedRef} update={update}>
-						{children}
-					</UpdatePopperOnContentResize>
-				)}
-			</PopupContent>
-		);
-	},
-);
-
-function createResizeObserver(update: ResizeObserverCallback) {
-	return new ResizeObserver(update);
-}
-
-/**
- * Will call the Popper.js `update()` method to recalculate positioning, when the flyout menu changes size.
- * This is the size of the scroll container, NOT the scroll content.
- *
- * We could potentially bake this into `@atlaskit/popup` or `@atlaskit/popper` but there are a few
- * reasons to keep it scoped to flyout menus for now:
- *
- * 1. It's easier to unwind
- * 2. We've only had bug reports for flyout menus
- * 3. Popup exposes the `update` function so consumers can already do this themselves if necessary
- * 4. Flyout menus are a lot more restricted to other popups, it might not make sense more generally
- */
-const UpdatePopperOnContentResize = forwardRef(
-	(
-		{ update, children }: { update: () => void; children: React.ReactNode },
-		forwardedRef: React.ForwardedRef<HTMLDivElement>,
-	) => {
-		/**
-		 * Storing our `update` function in a ref so that we have a stable reference to it.
-		 * We need this because our `ResizeObserver` callback cannot be changed after creating it.
-		 */
-		const updateRef = useRef(update);
-
-		useEffect(() => {
-			updateRef.current = update;
-		}, [update]);
-
-		/**
-		 * Stable function that calls the latest `update` function by calling it through the stable ref.
-		 */
-		const triggerUpdate: ResizeObserverCallback = useCallback(() => {
-			updateRef.current?.();
-		}, []);
-
-		const [resizeObserver] = useState(() => createResizeObserver(triggerUpdate));
-
-		/**
-		 * This is a callback ref that will update which `HTMLElement` we are observing,
-		 * if or when the underlying `HTMLElement` changes or unmounts.
-		 */
-		const observeCallbackRef = useCallback(
-			(element: HTMLElement | null) => {
-				/**
-				 * Unobserves all observed elements.
-				 * Allows us to cleanup without needing to store a reference to the previous element.
-				 */
-				resizeObserver.disconnect();
-
-				if (!element) {
-					return;
-				}
-
-				resizeObserver.observe(element);
-			},
-			[resizeObserver],
-		);
-
-		/**
-		 * We need to memoize the ref otherwise `triggerUpdate` is repeatedly called.
-		 *
-		 * This stems from ResizeObserver firing once after calling `.observe()` even if there
-		 * was no resize.
-		 *
-		 * Without memoizing the ref, the update causes a rerender, which causes the ref to
-		 * get recreated, which triggers an update and so on in a loop.
-		 */
-		const ref = useMemo(() => {
-			return mergeRefs([forwardedRef, observeCallbackRef]);
-		}, [forwardedRef, observeCallbackRef]);
-
-		return <div ref={ref}>{children}</div>;
-	},
-);

package/src/ui/menu-item/flyout-menu-item/flyout-menu-item-context.tsx

@@ -1,19 +0,0 @@
-import { createContext, useContext } from 'react';
-
-import noop from '@atlaskit/ds-lib/noop';
-
-/**
- * __Is open context__
- *
- * A context for storing the isOpen value of the FlyoutMenuItem.
- */
-export const IsOpenContext = createContext(false);
-
-/**
- * __Set is open context__
- *
- * A context for storing a function that sets isOpen value of the FlyoutMenuItem.
- */
-export const SetIsOpenContext = createContext<(value: boolean) => void>(noop);
-export const useFlyoutMenuOpen = () => useContext(IsOpenContext);
-export const useSetFlyoutMenuOpen = () => useContext(SetIsOpenContext);