@atlaskit/navigation-system 0.182.0 → 1.0.0

package/src/components/skip-links/__tests__/unit/skip-links-container.test.tsx

@@ -1,411 +0,0 @@
-import React from 'react';
-
-import { render, screen, within } from '@testing-library/react';
-import userEvent from '@testing-library/user-event';
-
-import noop from '@atlaskit/ds-lib/noop';
-
-import {
-	SkipLinksContext,
-	type SkipLinksContextData,
-	useSkipLink,
-} from '../../../../context/skip-links/skip-links-context';
-import { SkipLinksDataContext } from '../../../../context/skip-links/skip-links-data-context';
-import {
-	filterFromConsoleErrorOutput,
-	parseCssErrorRegex,
-	type ResetConsoleErrorFn,
-	resetMatchMedia,
-} from '../../../../ui/page-layout/__tests__/unit/_test-utils';
-import { Aside } from '../../../../ui/page-layout/aside';
-import { Banner } from '../../../../ui/page-layout/banner';
-import { Main } from '../../../../ui/page-layout/main/main';
-import { Panel } from '../../../../ui/page-layout/panel';
-import { Root } from '../../../../ui/page-layout/root';
-import { SideNav } from '../../../../ui/page-layout/side-nav/side-nav';
-import { TopNav } from '../../../../ui/page-layout/top-nav/top-nav';
-import { SkipLinksContainer } from '../../skip-links-container';
-
-beforeAll(() => {
-	// Stubbing calls that don't make sense outside of the browser
-	HTMLElement.prototype.scrollIntoView = noop;
-	window.scrollTo = noop;
-});
-
-describe('skip links', () => {
-	describe('SkipLinksContainer', () => {
-		const label = '跳转到';
-		const context: SkipLinksContextData = {
-			registerSkipLink: noop,
-			unregisterSkipLink: noop,
-		};
-		const dataContext = [
-			{ id: 'left', label: 'Left panel' },
-			{ id: 'right', label: 'Right panel' },
-		];
-		const skipLinksContainer = (
-			<SkipLinksDataContext.Provider value={dataContext}>
-				<SkipLinksContext.Provider value={context}>
-					<SkipLinksContainer label={label} />
-				</SkipLinksContext.Provider>
-			</SkipLinksDataContext.Provider>
-		);
-
-		it('generate 3 links', () => {
-			render(skipLinksContainer);
-			expect(screen.getByText(label)).toBeInTheDocument();
-			expect(screen.getAllByRole('link')).toHaveLength(2);
-		});
-	});
-
-	describe('Custom skip links', () => {
-		it('generates 3 links - 1 through standard slot method, 2 custom, in the correct order', () => {
-			const IntroSection = () => {
-				useSkipLink('intro-section', 'Intro Section', 0);
-
-				return (
-					// Adding data-layout-slot prop to prevent console errors for incorrect page layout children composition
-					<div id="intro-section" data-layout-slot>
-						intro
-					</div>
-				);
-			};
-			const ExternalFooter = () => {
-				useSkipLink('external-footer', 'External Footer', 7);
-
-				return (
-					// Adding data-layout-slot prop to prevent console errors for incorrect page layout children composition
-					<div id="external-footer" data-layout-slot>
-						external footer
-					</div>
-				);
-			};
-			render(
-				<Root>
-					<IntroSection />
-					<ExternalFooter />
-					<Banner>
-						<p>Child</p>
-					</Banner>
-				</Root>,
-			);
-			const allLinksInSkipLinks = screen.getAllByRole('link');
-
-			expect(allLinksInSkipLinks).toHaveLength(3);
-			expect(allLinksInSkipLinks[0]).toHaveTextContent('Intro Section');
-			expect(allLinksInSkipLinks[1]).toHaveTextContent('Banner');
-			expect(allLinksInSkipLinks[2]).toHaveTextContent('External Footer');
-		});
-
-		describe('when a duplicate skip link is registered', () => {
-			const consoleWarn = jest.spyOn(console, 'warn');
-			const NODE_ENV = process.env.NODE_ENV;
-
-			afterEach(() => {
-				process.env.NODE_ENV = NODE_ENV;
-				consoleWarn.mockReset();
-			});
-
-			afterAll(() => {
-				consoleWarn.mockRestore();
-			});
-
-			it.each(['development', 'staging'])('should error in %', (environment) => {
-				process.env.NODE_ENV = environment;
-
-				const CustomSkipLink = () => {
-					useSkipLink('banner', 'Skip to banner', 0);
-					return null;
-				};
-
-				expect(() =>
-					render(
-						<Root>
-							<CustomSkipLink />
-							<Banner id="banner">
-								<p>Child</p>
-							</Banner>
-						</Root>,
-					),
-				).not.toThrow();
-
-				expect(consoleWarn).toHaveBeenCalledWith(
-					expect.stringContaining("Tried registering duplicate skip link for ID 'banner'."),
-				);
-			});
-
-			it('should silently ignore it in production', () => {
-				process.env.NODE_ENV = 'production';
-
-				const CustomSkipLink = () => {
-					useSkipLink('banner', 'Skip to banner', 0);
-					return null;
-				};
-
-				expect(() =>
-					render(
-						<Root testId="root">
-							<CustomSkipLink />
-							<Banner id="banner">
-								<p>Child</p>
-							</Banner>
-						</Root>,
-					),
-				).not.toThrow();
-
-				const skipLinksContainer = within(screen.getByTestId('root--skip-links-container'));
-
-				// Only one skip link was registered
-				expect(skipLinksContainer.getAllByRole('link')).toHaveLength(1);
-				// The `useSkipLink` in `CustomSkipLink` was called first so that 'won'
-				expect(skipLinksContainer.getByRole('link')).toHaveTextContent('Skip to banner');
-			});
-		});
-	});
-
-	/**
-	 * There are almost no restrictions on valid IDs in HTML5:
-	 * https://www.w3.org/TR/2010/WD-html-markup-20100624/datatypes.html#common.data.id-def
-	 */
-	test.each([':id:', '1234', '_', '.', '$', '-', "'"])(
-		'should not error when the skip link id is "%s"',
-		(id) => {
-			const MyLandmark = () => {
-				useSkipLink(id, 'My landmark', 0);
-
-				return (
-					// Adding data-layout-slot prop to prevent console errors for incorrect page layout children composition
-					<div id={id} data-layout-slot />
-				);
-			};
-
-			render(
-				<Root>
-					<MyLandmark />
-				</Root>,
-			);
-
-			const link = screen.getByRole('link', { name: 'My landmark' });
-
-			expect(() => link.click()).not.toThrow();
-		},
-	);
-
-	it('should use the provided label', () => {
-		const { rerender } = render(
-			<Root testId="root">
-				<Main>Hello world</Main>
-			</Root>,
-		);
-
-		expect(screen.getByTestId('root--skip-links-container--label')).toHaveTextContent('Skip to:');
-
-		rerender(
-			<Root testId="root" skipLinksLabel="custom label">
-				<Main>Hello world</Main>
-			</Root>,
-		);
-
-		expect(screen.getByTestId('root--skip-links-container--label')).toHaveTextContent(
-			'custom label',
-		);
-	});
-
-	it.each(['', ' '])(
-		'should not render a label if it is just whitespace (skipLinksLabel="%s")',
-		(skipLinksLabel) => {
-			render(
-				<Root testId="root" skipLinksLabel={skipLinksLabel}>
-					<Main>Hello world</Main>
-				</Root>,
-			);
-
-			expect(screen.queryByTestId('root--skip-links-container--label')).not.toBeInTheDocument();
-		},
-	);
-
-	describe('hidden skip links', () => {
-		it('should not render the skip link for a Banner slot with `height={0}`', () => {
-			render(
-				<Root testId="root">
-					<Banner height={0}>{null}</Banner>
-				</Root>,
-			);
-
-			// There is no skip links container because there's no skip links
-			expect(screen.queryByTestId('root--skip-links-container')).not.toBeInTheDocument();
-		});
-
-		it('should not render the skip link for an Aside slot with `defaultWidth={0}`', () => {
-			render(
-				<Root testId="root">
-					<Aside defaultWidth={0}>{null}</Aside>
-				</Root>,
-			);
-
-			// There is no skip links container because there's no skip links
-			expect(screen.queryByTestId('root--skip-links-container')).not.toBeInTheDocument();
-		});
-
-		it('should not render the skip link for a Panel slot with `defaultWidth={0}`', () => {
-			render(
-				<Root testId="root">
-					<Panel defaultWidth={0}>{null}</Panel>
-				</Root>,
-			);
-
-			// There is no skip links container because there's no skip links
-			expect(screen.queryByTestId('root--skip-links-container')).not.toBeInTheDocument();
-		});
-
-		it('should render the skip link if the slot size changes', () => {
-			const { rerender } = render(
-				<Root testId="root">
-					<Banner height={0}>{null}</Banner>
-					<Aside defaultWidth={0}>{null}</Aside>
-					<Panel defaultWidth={0}>{null}</Panel>
-				</Root>,
-			);
-
-			// There is no skip links container because there's no skip links
-			expect(screen.queryByTestId('root--skip-links-container')).not.toBeInTheDocument();
-
-			rerender(
-				<Root testId="root">
-					<Banner height={1}>{null}</Banner>
-					<Aside defaultWidth={1}>{null}</Aside>
-					<Panel defaultWidth={1}>{null}</Panel>
-				</Root>,
-			);
-
-			const skipLinksContainer = within(screen.getByTestId('root--skip-links-container'));
-			expect(skipLinksContainer.queryAllByRole('link')).toHaveLength(3);
-
-			expect(skipLinksContainer.getByRole('link', { name: 'Banner' })).toBeInTheDocument();
-			expect(skipLinksContainer.getByRole('link', { name: 'Aside' })).toBeInTheDocument();
-			expect(skipLinksContainer.getByRole('link', { name: 'Panel' })).toBeInTheDocument();
-		});
-	});
-
-	describe('page layout slots', () => {
-		let resetConsoleErrorSpyFn: ResetConsoleErrorFn;
-		beforeAll(() => {
-			// Rendering the `SideNav` causes `parseCss` errors in JSDOM
-			resetConsoleErrorSpyFn = filterFromConsoleErrorOutput(parseCssErrorRegex);
-			resetMatchMedia();
-		});
-
-		afterAll(() => {
-			resetConsoleErrorSpyFn();
-		});
-
-		it('should use the `label` if there is no `skipLinkLabel` provided', () => {
-			render(
-				<Root testId="root">
-					<SideNav label="my side nav">side nav</SideNav>
-					<Aside label="my aside">aside</Aside>
-					<Panel label="my panel">panel</Panel>
-				</Root>,
-			);
-
-			const skipLinksContainer = within(screen.getByTestId('root--skip-links-container'));
-
-			expect(skipLinksContainer.getByRole('link', { name: 'my side nav' })).toBeInTheDocument();
-			expect(skipLinksContainer.getByRole('link', { name: 'my aside' })).toBeInTheDocument();
-			expect(skipLinksContainer.getByRole('link', { name: 'my panel' })).toBeInTheDocument();
-		});
-
-		it('should use the default `skipLinkLabel` value if the slot does not support a `label` prop', () => {
-			render(
-				<Root testId="root">
-					<Banner>banner</Banner>
-					<TopNav>top bar</TopNav>
-					<Main>main</Main>
-				</Root>,
-			);
-
-			const skipLinksContainer = within(screen.getByTestId('root--skip-links-container'));
-
-			expect(skipLinksContainer.getByRole('link', { name: 'Banner' })).toBeInTheDocument();
-			expect(skipLinksContainer.getByRole('link', { name: 'Top Bar' })).toBeInTheDocument();
-			expect(skipLinksContainer.getByRole('link', { name: 'Main Content' })).toBeInTheDocument();
-		});
-
-		it('should use the default `label` value if neither `label` or `skipLinkLabel` is provided', () => {
-			render(
-				<Root testId="root">
-					<Banner>banner</Banner>
-					<TopNav>top bar</TopNav>
-					<SideNav>side nav</SideNav>
-					<Aside>aside</Aside>
-					<Panel>panel</Panel>
-				</Root>,
-			);
-
-			const skipLinksContainer = within(screen.getByTestId('root--skip-links-container'));
-
-			expect(skipLinksContainer.getByRole('link', { name: 'Banner' })).toBeInTheDocument();
-			expect(skipLinksContainer.getByRole('link', { name: 'Top Bar' })).toBeInTheDocument();
-			expect(skipLinksContainer.getByRole('link', { name: 'Sidebar' })).toBeInTheDocument();
-			expect(skipLinksContainer.getByRole('link', { name: 'Aside' })).toBeInTheDocument();
-			expect(skipLinksContainer.getByRole('link', { name: 'Panel' })).toBeInTheDocument();
-		});
-
-		it('should use the `skipLinkLabel` value', () => {
-			render(
-				<Root testId="root">
-					<Banner skipLinkLabel="Skip to banner">banner</Banner>
-					<TopNav skipLinkLabel="Skip to top bar">top bar</TopNav>
-					<SideNav label="my side nav" skipLinkLabel="Skip to side nav">
-						side nav
-					</SideNav>
-					<Main skipLinkLabel="Skip to main">main</Main>
-					<Aside label="my aside" skipLinkLabel="Skip to aside">
-						aside
-					</Aside>
-					<Panel label="my panel" skipLinkLabel="Skip to panel">
-						panel
-					</Panel>
-				</Root>,
-			);
-
-			const skipLinksContainer = within(screen.getByTestId('root--skip-links-container'));
-
-			expect(skipLinksContainer.getByRole('link', { name: 'Skip to banner' })).toBeInTheDocument();
-			expect(skipLinksContainer.getByRole('link', { name: 'Skip to top bar' })).toBeInTheDocument();
-			expect(
-				skipLinksContainer.getByRole('link', { name: 'Skip to side nav' }),
-			).toBeInTheDocument();
-			expect(skipLinksContainer.getByRole('link', { name: 'Skip to main' })).toBeInTheDocument();
-			expect(skipLinksContainer.getByRole('link', { name: 'Skip to aside' })).toBeInTheDocument();
-			expect(skipLinksContainer.getByRole('link', { name: 'Skip to panel' })).toBeInTheDocument();
-		});
-	});
-
-	it('should manage focus for the targeted element', async () => {
-		render(
-			<Root>
-				<Main testId="main">Hello world</Main>
-			</Root>,
-		);
-
-		const main = screen.getByTestId('main');
-
-		// The main slot has no tab index by default
-		expect(main).not.toHaveAttribute('tabindex');
-
-		// We click on the skip link to the main slot
-		screen.getByRole('link', { name: 'Main Content' }).click();
-
-		// The main slot now has tabIndex="-1" and is focussed
-		expect(main).toHaveAttribute('tabindex', '-1');
-		expect(main).toHaveFocus();
-
-		// User moves focus
-		await userEvent.tab();
-
-		// The main slot no longer has focus or the tab index
-		expect(main).not.toHaveFocus();
-		expect(main).not.toHaveAttribute('tabindex');
-	});
-});

package/src/components/skip-links/skip-link.tsx

@@ -1,140 +0,0 @@
-/**
- * @jsxRuntime classic
- * @jsx jsx
- */
-import React, { type ReactNode, useCallback } from 'react';
-
-import { jsx } from '@compiled/react';
-import { bind } from 'bind-event-listener';
-
-import { cssMap } from '@atlaskit/css';
-// eslint-disable-next-line @atlaskit/design-system/no-emotion-primitives -- to be migrated to @atlaskit/primitives/compiled – go/akcss
-import { Anchor } from '@atlaskit/primitives';
-import { token } from '@atlaskit/tokens';
-
-import type { SkipLinkData } from '../../context/skip-links/types';
-
-const styles = cssMap({
-	skipLinkListItem: {
-		marginBlockStart: token('space.0'),
-	},
-});
-
-/**
- * Used for moving focus to the corresponding slot or custom target after clicking on a skip link.
- */
-function focusElement(element: HTMLElement) {
-	/**
-	 * Elements without an explicit `tabindex` attribute are not guaranteed to be focusable:
-	 * https://html.spec.whatwg.org/multipage/interaction.html#attr-tabindex
-	 *
-	 * Our slots are not interactive, so this is required.
-	 *
-	 * In the future we may want to check if there is an existing `tabindex` attribute,
-	 * as custom skip linked elements might already have one.
-	 */
-	element.setAttribute('tabindex', '-1');
-
-	/**
-	 * Cleanup the `tabindex` attribute we set when the slot or custom target loses focus.
-	 *
-	 * This is preferable to always having `tabindex="-1"` because always applying the tab index can:
-	 *
-	 * - mess with click events
-	 * - potentially cause a focus ring to be always visible
-	 */
-	bind(element, {
-		type: 'blur',
-		listener() {
-			element.removeAttribute('tabindex');
-		},
-		options: {
-			// Using a one-time listener so it cleans itself up
-			once: true,
-		},
-	});
-
-	/**
-	 * Move focus to the slot or custom target.
-	 *
-	 * Calling `.focus()` will also scroll the element into view:
-	 * https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus
-	 */
-	element.focus({
-		// Forces the focus ring to appear after moving focus to the slot
-		// https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#focusvisible
-		// @ts-expect-error - new and not in types yet
-		focusVisible: true,
-	});
-}
-
-/**
- * A link that moves current tab position to a different element
- *
- * This component is rendered internally and is not exported publicly.
- */
-export const SkipLink = ({
-	id,
-	children,
-	onBeforeNavigate,
-}: {
-	id: string;
-	children: ReactNode;
-	onBeforeNavigate?: SkipLinkData['onBeforeNavigate'];
-}) => {
-	const href = `#${id}`;
-
-	const onClick = useCallback(
-		(event: React.MouseEvent<HTMLAnchorElement>) => {
-			event.preventDefault();
-
-			// Intentionally not using `document.querySelector` because many valid IDs are not valid selectors.
-			const target = document.getElementById(id);
-			if (!target) {
-				return;
-			}
-
-			/**
-			 * Internal slots can attach an `onBeforeNavigate` callback.
-			 *
-			 * Side nav uses this to ensure it is expanded.
-			 */
-			onBeforeNavigate?.();
-
-			focusElement(target);
-
-			/**
-			 * We should look into removing this, or only calling it in specific cases.
-			 *
-			 * It means if the skip link element is in the window scroll container
-			 * then it might not get scrolled into view properly.
-			 *
-			 * This is not an issue for the default slots on desktop, but could break custom skip links or
-			 * even `Aside` on mobile.
-			 *
-			 * Keeping existing behavior for now because resetting the window scroll is actually good for some cases.
-			 * E.g. jumping to main / aside it makes sense to look at the start of the content.
-			 */
-			window.scrollTo(0, 0);
-		},
-		[id, onBeforeNavigate],
-	);
-
-	return (
-		<li css={styles.skipLinkListItem}>
-			<Anchor
-				/**
-				 * It looks like Safari handles link clicks during `pointerdown` unless it has an explicit `tabIndex={0}` :/
-				 *
-				 * Adding this explicitly makes the behavior consistent between browsers and lets us `event.preventDefault()`
-				 * in the `onClick` handler.
-				 */
-				tabIndex={0}
-				href={href}
-				onClick={onClick}
-			>
-				{children}
-			</Anchor>
-		</li>
-	);
-};

package/src/components/skip-links/skip-links-container.tsx

@@ -1,112 +0,0 @@
-/**
- * @jsxRuntime classic
- * @jsx jsx
- */
-import { cssMap, jsx } from '@atlaskit/css';
-// eslint-disable-next-line @atlaskit/design-system/no-emotion-primitives -- to be migrated to @atlaskit/primitives/compiled – go/akcss
-import { Text } from '@atlaskit/primitives';
-import { token } from '@atlaskit/tokens';
-
-import { useSortedSkipLinks } from '../../context/skip-links/skip-links-data-context';
-import { type SkipLinkData } from '../../context/skip-links/types';
-
-import { SkipLink } from './skip-link';
-
-const styles = cssMap({
-	root: {
-		display: 'flex',
-		flexDirection: 'column',
-		gap: token('space.050'),
-		paddingBlock: token('space.150'),
-		paddingInline: token('space.150'),
-		position: 'fixed',
-		insetInlineStart: token('space.250'),
-		insetBlockStart: token('space.250'),
-		backgroundColor: token('elevation.surface.overlay'),
-		borderRadius: token('border.radius'),
-		boxShadow: token('elevation.shadow.overlay'),
-		/**
-		 * Hiding the element while it has no focus within
-		 */
-		zIndex: -1,
-		opacity: 0,
-		pointerEvents: 'none', // Prevent clicks just in case
-		'&:focus-within': {
-			// @ts-expect-error - should be over any other element
-			// We _could_ explore using the popover API to guarantee this without z-index hacks
-			// Alternatively, if all slots + portal container are separate stacking contexts, then `zIndex: 1` should be safe
-			zIndex: 'calc(infinity)',
-			opacity: 1,
-			pointerEvents: 'auto',
-		},
-	},
-	skipLinkList: {
-		display: 'flex',
-		flexDirection: 'column',
-		gap: token('space.050'),
-		listStylePosition: 'outside',
-		listStyleType: 'none',
-		marginBlockStart: token('space.0'),
-		paddingInlineStart: token('space.0'),
-	},
-});
-
-/**
- * Keydown handler to hide the skip links when escape is pressed.
- *
- * TODO: consider removing this, it doesn't make a lot of sense.
- * The skip links look like a popup but in reality they aren't.
- * Even though we hide them if you press TAB it will reopen the list and move to the next one...
- */
-const closeOnEscape = (event: React.KeyboardEvent) => {
-	if (event.key !== 'Escape') {
-		return;
-	}
-
-	const activeElement = document.activeElement;
-	if (activeElement instanceof HTMLElement) {
-		activeElement.blur();
-	}
-};
-
-const isOnlyWhitespaceRegex = /^\s*$/;
-
-/**
- * A container element for the skip links
- * The default label will be used when the `skipLinksLabel` attribute is not
- * provided or the attribute is an empty string. If a string comprised only of
- * spaces is provided, the skip link heading element will be removed, but the
- * default label will still be used in `title` attribute of the skip links
- * themselves.
- */
-export const SkipLinksContainer = ({ label, testId }: { label: string; testId?: string }) => {
-	const sortedSkipLinks = useSortedSkipLinks();
-	if (sortedSkipLinks.length === 0) {
-		return null;
-	}
-
-	const isEmptyLabel = isOnlyWhitespaceRegex.test(label);
-
-	return (
-		// Capturing bubbled events, element itself is not interactive
-		// eslint-disable-next-line jsx-a11y/no-static-element-interactions
-		<div
-			onKeyDown={closeOnEscape}
-			css={[styles.root]}
-			data-testid={testId ? `${testId}--skip-links-container` : undefined}
-		>
-			{!isEmptyLabel && (
-				<Text weight="bold" testId={testId ? `${testId}--skip-links-container--label` : undefined}>
-					{label}
-				</Text>
-			)}
-			<ol css={[styles.skipLinkList]}>
-				{sortedSkipLinks.map(({ id, label, onBeforeNavigate }: SkipLinkData) => (
-					<SkipLink key={id} id={id} onBeforeNavigate={onBeforeNavigate}>
-						{label}
-					</SkipLink>
-				))}
-			</ol>
-		</div>
-	);
-};