@automattic/vip-design-system 2.4.5 → 2.5.0

package/build/system/theme/index.js

@@ -6,6 +6,7 @@ import ColorBuilder from './colors';
 import ValetDark from './generated/valet-theme-dark.json';
 import Valet from './generated/valet-theme-light.json';
 import ThemeBuilder from './getPropValue';
+import { linkUnderlineProperties } from '../Link/Link';
 
 // Light
 const { getPropValue, getVariants, ValetTheme, getHeadingStyles } = ThemeBuilder( Valet );
@@ -402,21 +403,19 @@ export default {
 
 	links: {
 		primary: {
+			...linkUnderlineProperties,
+
 			color: 'link',
 			'&:visited': {
 				color: 'links.visited',
 			},
 			'&:hover': {
 				color: 'links.hover',
-				textDecorationLine: 'underline',
-				textDecorationThickness: '0.125rem',
+				textDecorationThickness: '0.15rem',
 			},
 			'&:active': {
 				color: 'links.active',
 			},
-
-			textDecorationThickness: '0.125rem',
-			textUnderlineOffset: '0.250rem',
 		},
 		'button-primary': {
 			variant: 'buttons.primary',
@@ -531,7 +530,7 @@ export default {
 			a: {
 				'&:hover': {
 					textDecorationLine: 'underline',
-					textDecorationThickness: '0.125rem',
+					textDecorationThickness: '0.1rem',
 					textUnderlineOffset: '0.250rem',
 				},
 			},

package/build/system/utils/stories/CustomLink.d.ts

@@ -1,2 +1,3 @@
 import React from 'react';
 export declare const CustomLink: React.ForwardRefExoticComponent<React.RefAttributes<HTMLAnchorElement>>;
+export declare const CustomLinkComponentized: React.ForwardRefExoticComponent<React.RefAttributes<HTMLAnchorElement>>;

package/build/system/utils/stories/CustomLink.js

@@ -1,8 +1,9 @@
 "use strict";
 
 exports.__esModule = true;
-exports.CustomLink = void 0;
+exports.CustomLinkComponentized = exports.CustomLink = void 0;
 var _react = _interopRequireWildcard(require("react"));
+var _Link = require("../../Link/Link");
 var _jsxRuntime = require("theme-ui/jsx-runtime");
 function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function _getRequireWildcardCache(e) { return e ? t : r; })(e); }
 function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { "default": e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && Object.prototype.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n["default"] = e, t && t.set(e, n), n; }
@@ -13,4 +14,9 @@ function (props, ref) {
   return (0, _jsxRuntime.jsx)("a", _extends({}, props, {
     ref: ref
   }));
+});
+var CustomLinkComponentized = exports.CustomLinkComponentized = /*#__PURE__*/(0, _react.forwardRef)(function (props, ref) {
+  return (0, _jsxRuntime.jsx)(_Link.Link, _extends({}, props, {
+    ref: ref
+  }));
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automattic/vip-design-system",
-  "version": "2.4.5",
+  "version": "2.5.0",
   "main": "build/system/index.js",
   "scripts": {
     "build-storybook": "storybook build",

package/src/system/Breadcrumbs/Breadcrumbs.stories.tsx

@@ -1,12 +1,13 @@
+/** @jsxImportSource theme-ui */
+
 import React from 'react';
 
 import { Breadcrumbs as Breadcrumbs } from './Breadcrumbs';
+import { Box } from '../Box';
+import { CustomLink, CustomLinkComponentized } from '../utils/stories/CustomLink';
 
 import type { StoryObj } from '@storybook/react';
 
-// eslint-disable-next-line jsx-a11y/anchor-has-content
-const CustomLink = props => <a { ...props } />;
-
 export default {
 	title: 'Navigation/Breadcrumbs',
 	component: Breadcrumbs,
@@ -78,3 +79,31 @@ export const Default: Story = {
 		/>
 	),
 };
+
+export const Collapsible: Story = {
+	render: () => (
+		<Box sx={ { display: 'flex', flexDirection: 'column', gap: 4 } }>
+			<p>
+				When entering Mobile views, the first and the last link will appear. A button with a … will
+				also be visible. Once pressed, the rest of the links become available, and the focus is
+				moved to the next link.
+			</p>
+
+			<hr sx={ { width: '100%', my: 4 } } />
+
+			<Breadcrumbs
+				wrapMode="collapsible"
+				LinkComponent={ CustomLinkComponentized }
+				label="Nav Breadcrumbs"
+				links={ [
+					{ href: '/', label: 'Home' },
+					{ href: 'https://datadog.com/', label: 'Data dog' },
+					{ href: 'https://newrelic.com/', label: 'New Relic' },
+					{ href: 'https://rollbar.com/', label: 'Rollbar' },
+					{ href: 'https://areallylong.com/', label: 'A really long name' },
+					{ href: 'https://google.com/', label: 'I am the last item' },
+				] }
+			/>
+		</Box>
+	),
+};

package/src/system/Breadcrumbs/Breadcrumbs.test.tsx

@@ -2,12 +2,17 @@
 /* eslint-disable @typescript-eslint/ban-ts-comment */
 // @ts-nocheck
 import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import * as matchMedia from '@theme-ui/match-media';
 import { axe } from 'jest-axe';
 import { ThemeUIProvider } from 'theme-ui';
 
 import { Breadcrumbs } from './Breadcrumbs';
 import { theme } from '../';
 
+jest.mock( '@theme-ui/match-media' );
+const mockBreakpointIndex = matchMedia.useBreakpointIndex;
+
 // eslint-disable-next-line jsx-a11y/anchor-has-content
 const CustomLink = props => <a { ...props } />;
 
@@ -39,6 +44,7 @@ describe( '<Breadcrumbs />', () => {
 			} ),
 		} );
 	} );
+
 	it( 'renders the Breadcrumbs component', async () => {
 		const { container } = renderComponent();
 
@@ -53,4 +59,58 @@ describe( '<Breadcrumbs />', () => {
 		// Check for accessibility issues
 		expect( await axe( container ) ).toHaveNoViolations();
 	} );
+
+	describe( 'wrapMode tests', () => {
+		beforeEach( () => {
+			mockBreakpointIndex.mockReset();
+		} );
+
+		it( 'expands the breadcrumb items when clicking in the collapsible link', async () => {
+			mockBreakpointIndex.mockReturnValue( 0 );
+
+			const links = [
+				{ label: 'Home', href: '/' },
+				{ label: 'Applications', href: '/apps' },
+				{ label: 'Applications 3', href: '/apps/3' },
+				{ label: 'Applications 4', href: '/apps/4' },
+				{ label: 'The last' },
+			];
+
+			const user = userEvent.setup();
+
+			const { container } = renderWithTheme(
+				<Breadcrumbs
+					wrapMode="collapsible"
+					label="Main Collapsible Breadcrumb"
+					LinkComponent={ CustomLink }
+					links={ links }
+				/>
+			);
+
+			// Should find the nav label
+			const navEl = screen.getByLabelText( 'Main Collapsible Breadcrumb' );
+
+			expect( navEl ).toBeInTheDocument();
+
+			// Contract should have
+			expect( navEl.querySelectorAll( 'li' ) ).toHaveLength( 3 );
+
+			const pressToShowButton = screen.getByRole( 'button', {
+				name: 'Press to show more breadcrumbs',
+			} );
+
+			// Should find all links
+			expect( screen.getByText( 'Home' ) ).toBeInTheDocument();
+			expect( pressToShowButton ).toBeInTheDocument();
+			expect( screen.getByText( 'The last' ) ).toHaveAttribute( 'aria-current', 'page' );
+
+			// Click to expand the breadcrumbs
+			await user.click( pressToShowButton );
+
+			expect( navEl.querySelectorAll( 'li' ) ).toHaveLength( 5 );
+
+			// Check for accessibility issues
+			expect( await axe( container ) ).toHaveNoViolations();
+		} );
+	} );
 } );

package/src/system/Breadcrumbs/Breadcrumbs.tsx

@@ -3,12 +3,13 @@
 import * as NavigationMenu from '@radix-ui/react-navigation-menu';
 import { useBreakpointIndex } from '@theme-ui/match-media';
 import classNames from 'classnames';
-import React, { Ref, forwardRef } from 'react';
+import { useTranslate } from 'i18n-calypso';
+import React, { forwardRef, useEffect, useRef, useState } from 'react';
 import { ThemeUIStyleObject } from 'theme-ui';
 
 export const VIP_BREACRUMBS = 'vip-breadcrumbs-component';
 
-import { smallestScreenItemStyles } from './styles';
+import { collapsibleSeparatorStyles, smallestScreenItemStyles } from './styles';
 import { ItemBreadcrumb, NavItemProps, NavRawLink } from '../Nav/NavItem';
 import { navItemStyles, navMenuListStyles } from '../Nav/styles';
 
@@ -22,37 +23,39 @@ export type BreadcrumbsLinkProps = {
 export interface BreacrumbsProps extends NavigationMenu.NavigationMenuProps {
 	className?: string;
 	label?: string;
+	wrapMode?: 'collapsible' | 'lastItem';
 	LinkComponent: NavItemProps[ 'as' ];
 	links?: BreadcrumbsLinkProps[];
 }
 
-export const Breadcrumbs = forwardRef< HTMLElement, BreacrumbsProps >(
-	(
-		{ className, links = [], label = 'Breadcrumbs', LinkComponent = NavRawLink }: BreacrumbsProps,
-		ref: Ref< HTMLElement >
-	) => {
-		// The breadcrumb shrinks on smaller screens (mobile) and we need to hide some links
-		const bpIndex = useBreakpointIndex( { defaultIndex: 1 } );
-
-		const isSmallestScreen = bpIndex < 3;
-
-		let penultimateLink: BreadcrumbsLinkProps | null = null;
-		let lastLink: BreadcrumbsLinkProps | null = null;
-		let otherLinks: BreadcrumbsLinkProps[] = [];
-
-		const totalLinks = links?.length || 0;
-
-		if ( totalLinks === 0 ) {
-			return null;
-		}
+const breadcrumbLinks = (
+	links: BreadcrumbsLinkProps[],
+	isSmallestScreen: boolean = false,
+	wrapMode: BreacrumbsProps[ 'wrapMode' ],
+	showAllItems: boolean = false
+): {
+	separatorLink: boolean;
+	lastLink: BreadcrumbsLinkProps | null;
+	otherLinks: BreadcrumbsLinkProps[];
+} => {
+	let separatorLink: boolean = false;
+	let lastLink: BreadcrumbsLinkProps | null = null;
+	let otherLinks: BreadcrumbsLinkProps[] = [];
+
+	const totalLinks = links?.length;
+
+	if ( totalLinks === 1 ) {
+		lastLink = links?.[ 0 ];
+		otherLinks = [];
+	}
 
-		if ( totalLinks === 1 ) {
-			lastLink = links?.[ 0 ];
-			otherLinks = [];
-		}
+	if ( totalLinks > 1 ) {
+		const otherLinksRaw = links?.slice( 0, totalLinks - 1 );
+		lastLink = links?.[ totalLinks - 1 ];
 
-		if ( totalLinks > 1 ) {
-			penultimateLink = links?.[ totalLinks - 2 ];
+		if ( wrapMode === 'lastItem' ) {
+			const penultimateLink = links?.[ totalLinks - 2 ];
+			lastLink = isSmallestScreen ? null : links?.[ totalLinks - 1 ];
 
 			otherLinks = isSmallestScreen
 				? [
@@ -62,11 +65,62 @@ export const Breadcrumbs = forwardRef< HTMLElement, BreacrumbsProps >(
 							sx: smallestScreenItemStyles,
 						},
 				  ]
-				: links?.slice( 0, totalLinks - 1 );
+				: otherLinksRaw;
+		} else if ( wrapMode === 'collapsible' ) {
+			separatorLink = isSmallestScreen && ! showAllItems && totalLinks > 2;
+			otherLinks = isSmallestScreen && ! showAllItems ? [ links?.[ 0 ] ] : otherLinksRaw;
+		}
+	}
 
-			lastLink = isSmallestScreen ? null : links?.[ totalLinks - 1 ];
+	return { separatorLink, lastLink, otherLinks };
+};
+
+export const Breadcrumbs = forwardRef< HTMLElement, BreacrumbsProps >(
+	(
+		{
+			className,
+			links = [],
+			label = 'Breadcrumbs',
+			LinkComponent = NavRawLink,
+			wrapMode = 'lastItem',
+		}: BreacrumbsProps,
+		ref
+	) => {
+		const breadcrumbsListRef = useRef< HTMLOListElement >( null );
+		const [ showAllItems, setShowAllItems ] = useState( false );
+		const translate = useTranslate();
+
+		// Focus on the next link when the collapsible separator is true
+		useEffect( () => {
+			if ( wrapMode !== 'collapsible' ) {
+				return;
+			}
+
+			const breadcrumbList = breadcrumbsListRef?.current;
+
+			if ( showAllItems && breadcrumbList ) {
+				const nextActiveLink: HTMLAnchorElement | null =
+					breadcrumbList.querySelector( 'li:nth-child(2) a' );
+
+				nextActiveLink?.focus();
+			}
+		}, [ showAllItems, wrapMode ] );
+
+		// The breadcrumb shrinks on smaller screens (mobile) and we need to hide some links
+		const bpIndex = useBreakpointIndex( { defaultIndex: 1 } );
+		const isSmallestScreen = bpIndex < 3;
+
+		if ( links?.length === 0 ) {
+			return null;
 		}
 
+		const { separatorLink, lastLink, otherLinks } = breadcrumbLinks(
+			links,
+			isSmallestScreen,
+			wrapMode,
+			showAllItems
+		);
+
 		return (
 			<NavigationMenu.Root
 				aria-label={ label }
@@ -77,6 +131,7 @@ export const Breadcrumbs = forwardRef< HTMLElement, BreacrumbsProps >(
 				<NavigationMenu.List
 					className={ classNames( `${ VIP_BREACRUMBS }-list` ) }
 					sx={ navMenuListStyles( 'horizontal' ) }
+					ref={ breadcrumbsListRef }
 					asChild
 				>
 					<ol>
@@ -92,6 +147,22 @@ export const Breadcrumbs = forwardRef< HTMLElement, BreacrumbsProps >(
 							</ItemBreadcrumb>
 						) ) }
 
+						{ separatorLink && (
+							<li
+								sx={ {
+									...navItemStyles( 'horizontal', 'breadcrumbs' ),
+								} }
+							>
+								<button
+									sx={ collapsibleSeparatorStyles }
+									aria-label={ translate( 'Press to show more breadcrumbs' ) }
+									onClick={ () => setShowAllItems( true ) }
+								>
+									…
+								</button>
+							</li>
+						) }
+
 						{ lastLink && (
 							<li
 								sx={ {

package/src/system/Breadcrumbs/styles.ts

@@ -1,3 +1,8 @@
+import { ThemeUIStyleObject } from 'theme-ui';
+
+import { linkUnderlineProperties } from '../Link/Link';
+import { breadcrumbsLinkStyles } from '../Nav/styles/variants/breadcrumbs';
+
 export const smallestScreenItemStyles = {
 	'&::before': {
 		display: 'inline-block',
@@ -10,3 +15,9 @@ export const smallestScreenItemStyles = {
 		content: "'←'",
 	},
 };
+
+export const collapsibleSeparatorStyles: ThemeUIStyleObject = {
+	all: 'unset',
+	...breadcrumbsLinkStyles,
+	...linkUnderlineProperties,
+};

package/src/system/Link/Link.stories.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { Link } from '..';
+import { Link, LinkVariant } from './Link';
 import { Flex } from '../Flex/Flex';
 
 import type { LinkProps } from './Link';
@@ -14,6 +14,47 @@ import type { StoryObj } from '@storybook/react';
 export default {
 	title: 'Navigation/Link',
 	component: Link,
+	argTypes: {
+		variant: {
+			type: 'select',
+			options: Object.values( LinkVariant ),
+		},
+	},
+	parameters: {
+		docs: {
+			description: {
+				component: `
+
+Links are navigational elements that direct visitors to other locations, either on the same page or to a different page or site. They can be inline or separate from the text flow. Since every link is a potential user interaction, too many links can be overwhelming.
+
+## Guidance
+
+### When to use the link component
+
+- When you want to direct users to another page or site.
+- When you want to direct users to another section of the same page (anchors).
+
+### When to consider something else
+
+- When you want to trigger an action (use a button instead).
+- When you want to display a message (use a notification instead).
+
+### Accessibility
+
+- Don’t rely on only color to distinguish links
+- Don’t block external links with disruptive notifications
+- Icons can be helpful. Consider adding an icon to signal specific actions (Download, Open in a new window, etc).
+- Don’t use the same link text for different URLs on the same page. This can confuse users and make it difficult for them to understand where the link will take them.
+
+-------
+
+This documentation is heavily inspired by the [U.S Web Design System (USWDS)](https://designsystem.digital.gov/components/link/). We use USWDS as trusted source of truth for accessibility and usability best practices.
+
+## Component Properties
+`,
+			},
+		},
+	},
 };
 
 type Story = StoryObj< typeof Link >;

package/src/system/Link/Link.tsx

@@ -14,17 +14,26 @@ interface LinkTheme extends Theme {
 	outline?: Record< string, string >;
 }
 
+export enum LinkVariant {
+	'primary',
+	'button-primary',
+	'button-secondary',
+	'button-tertiary',
+	'button-ghost',
+	'button-display',
+	'button-danger',
+}
+
 export interface LinkProps extends ThemeLinkProps {
-	variant?:
-		| 'primary'
-		| 'button-primary'
-		| 'button-secondary'
-		| 'button-tertiary'
-		| 'button-ghost'
-		| 'button-display'
-		| 'button-danger';
+	variant?: keyof typeof LinkVariant;
 }
 
+export const linkUnderlineProperties: ThemeUIStyleObject = {
+	textDecorationLine: 'underline',
+	textDecorationThickness: '0.07rem',
+	textUnderlineOffset: '0.250rem',
+};
+
 export const defaultLinkComponentStyle: ThemeUIStyleObject = {
 	'&:focus-visible': ( theme: LinkTheme ) => theme.outline,
 };

package/src/system/Nav/styles.ts

@@ -141,5 +141,6 @@ export const navMenuListStyles = ( orientation: NavProps[ 'orientation' ] ): The
 		gap: 1,
 		px: 0,
 		flexDirection: orientation === 'horizontal' ? 'row' : 'column',
+		flexWrap: orientation === 'horizontal' ? 'wrap' : undefined,
 	};
 };

package/src/system/theme/index.js

@@ -6,6 +6,7 @@ import ColorBuilder from './colors';
 import ValetDark from './generated/valet-theme-dark.json';
 import Valet from './generated/valet-theme-light.json';
 import ThemeBuilder from './getPropValue';
+import { linkUnderlineProperties } from '../Link/Link';
 
 // Light
 const { getPropValue, getVariants, ValetTheme, getHeadingStyles } = ThemeBuilder( Valet );
@@ -402,21 +403,19 @@ export default {
 
 	links: {
 		primary: {
+			...linkUnderlineProperties,
+
 			color: 'link',
 			'&:visited': {
 				color: 'links.visited',
 			},
 			'&:hover': {
 				color: 'links.hover',
-				textDecorationLine: 'underline',
-				textDecorationThickness: '0.125rem',
+				textDecorationThickness: '0.15rem',
 			},
 			'&:active': {
 				color: 'links.active',
 			},
-
-			textDecorationThickness: '0.125rem',
-			textUnderlineOffset: '0.250rem',
 		},
 		'button-primary': {
 			variant: 'buttons.primary',
@@ -531,7 +530,7 @@ export default {
 			a: {
 				'&:hover': {
 					textDecorationLine: 'underline',
-					textDecorationThickness: '0.125rem',
+					textDecorationThickness: '0.1rem',
 					textUnderlineOffset: '0.250rem',
 				},
 			},

package/src/system/utils/stories/CustomLink.tsx

@@ -1,6 +1,12 @@
 import React, { Ref, forwardRef } from 'react';
 
+import { Link } from '../../Link/Link';
+
 export const CustomLink = forwardRef< HTMLAnchorElement >(
 	// eslint-disable-next-line jsx-a11y/anchor-has-content
 	( props, ref: Ref< HTMLAnchorElement > ) => <a { ...props } ref={ ref } />
 );
+
+export const CustomLinkComponentized = forwardRef< HTMLAnchorElement >(
+	( props, ref: Ref< HTMLAnchorElement > ) => <Link { ...props } ref={ ref } />
+);