@hashicorp/react-components 0.0.0 → 1.0.0

package/src/components/related-content/index.test.tsx

@@ -0,0 +1,74 @@
+import { render, screen } from '@testing-library/react'
+import RelatedContent from '.'
+
+const defaultProps = {
+	headline: 'Related Content',
+	description:
+		'Leo mauris fermentum pharetra blandit tellus euismod. Leo mauris fermentum pharetra blandit tellus euismod.',
+	cards: [
+		{
+			link: 'https://hashicorp.com',
+			meta: ['USE CASES'],
+			heading:
+				'Display 5 - 4 lines with character limit of 130. Leo mauris fermentum pharetra blandit tellus euismod…',
+			description:
+				'Body small - 4 lines with character limit of 170. Leo mauris fermentum pharetra blandit tellus euismod pharetra. Duis egestas volutpat dolor…',
+		},
+		{
+			link: 'https://hashicorp.com',
+			meta: ['USE CASES'],
+			heading:
+				'Display 5 - 4 lines with character limit of 130. Leo mauris fermentum pharetra blandit tellus euismod…',
+			description:
+				'Body small - 4 lines with character limit of 170. Leo mauris fermentum pharetra blandit tellus euismod pharetra. Duis egestas volutpat dolor…',
+		},
+		{
+			link: 'https://hashicorp.com',
+			meta: ['USE CASES'],
+			heading:
+				'Display 5 - 4 lines with character limit of 130. Leo mauris fermentum pharetra blandit tellus euismod…',
+			description:
+				'Body small - 4 lines with character limit of 170. Leo mauris fermentum pharetra blandit tellus euismod pharetra. Duis egestas volutpat dolor…',
+		},
+		{
+			link: 'https://hashicorp.com',
+			meta: ['USE CASES'],
+			heading:
+				'Display 5 - 4 lines with character limit of 130. Leo mauris fermentum pharetra blandit tellus euismod…',
+			description:
+				'Body small - 4 lines with character limit of 170. Leo mauris fermentum pharetra blandit tellus euismod pharetra. Duis egestas volutpat dolor…',
+		},
+	],
+	cta: {
+		text: 'Sign up now',
+		href: '/components/relatedcontent',
+	},
+}
+
+describe('<RelatedContent />', () => {
+	it('should render the headline prop', () => {
+		render(<RelatedContent {...defaultProps} />)
+		const headlineText = screen.getByText(defaultProps.headline)
+		expect(headlineText.tagName).toBe('H2')
+		expect(headlineText).toHaveClass(/headline/)
+	})
+
+	it('should render the description prop', () => {
+		render(<RelatedContent {...defaultProps} />)
+		const descText = screen.getByText(defaultProps.description)
+		expect(descText.tagName).toBe('P')
+		expect(descText).toHaveClass(/description/)
+	})
+
+	it('should render cards', () => {
+		render(<RelatedContent {...defaultProps} />)
+		const cardsContainer = screen.getByTestId('wpl-cards-container')
+		expect(cardsContainer.children.length).toBeGreaterThan(0)
+	})
+
+	it('should render the optional CTA', () => {
+		render(<RelatedContent {...defaultProps} />)
+		const ctaContainer = screen.getByTestId('wpl-cta-container')
+		expect(ctaContainer).toHaveClass(/cta/)
+	})
+})

package/src/components/related-content/index.tsx

@@ -0,0 +1,56 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import Card from '../card'
+import classNames from 'classnames'
+import Link from 'next/link'
+import type { RelatedContentProps } from './types'
+import s from './style.module.css'
+
+const RelatedContent = ({
+	appearance = 'light',
+	headline,
+	description,
+	cards,
+	cta,
+}: RelatedContentProps) => {
+	return (
+		<div
+			className={classNames([
+				s.wrapper,
+				s[appearance],
+				{ ['hdsplus-dark-mode']: appearance === 'dark' },
+			])}
+		>
+			<div className={s.textStack}>
+				<h2 className={classNames([s.headline, s[appearance]])}>{headline}</h2>
+				{description ? (
+					<p className={classNames([s.description, s[appearance]])}>
+						{description}
+					</p>
+				) : null}
+			</div>
+			<div className={s.cards} data-testid="wpl-cards-container">
+				{cards.map((card, i) => (
+					<Card
+						key={i}
+						link={card.link}
+						thumbnail={card.thumbnail}
+						meta={card.meta}
+						heading={card.heading}
+						description={card.description}
+					/>
+				))}
+			</div>
+			<div className={s.cta} data-testid="wpl-cta-container">
+				<Link href={cta.href} legacyBehavior>
+					{cta.text}
+				</Link>
+			</div>
+		</div>
+	)
+}
+
+export default RelatedContent

package/src/components/related-content/style.module.css

@@ -0,0 +1,89 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+.wrapper {
+  composes: g-grid from global;
+  composes: g-grid-container from global;
+  padding-top: 64px;
+  padding-bottom: 64px;
+
+  @media (--large) {
+    padding-top: 88px;
+    padding-bottom: 88px;
+  }
+  &.dark {
+    background-color: var(--wpl-neutral-900);
+  }
+}
+
+.textStack {
+  grid-column: 1 / -1;
+  margin-bottom: 24px;
+
+  @media (--medium) {
+    grid-column: 1 / span 7;
+    margin-bottom: 32px;
+  }
+
+  @media (--large) {
+    grid-column: 1 / span 6;
+    margin-bottom: 32px;
+  }
+}
+
+.headline {
+  composes: g-type-display-3 from global;
+  color: var(--wpl-neutral-900);
+  margin: 0 0 16px 0;
+
+  &.dark {
+    color: white;
+  }
+}
+
+.description {
+  composes: g-type-body from global;
+  color: var(--wpl-neutral-500);
+  margin: 0;
+
+  &.dark {
+    color: white;
+  }
+}
+
+.cards {
+  --columns: 1;
+
+  grid-column: 1 / -1;
+  display: grid;
+  grid-gap: 32px;
+  grid-template-columns: repeat(var(--columns), 1fr);
+  margin-bottom: 32px;
+
+  @media (--medium) {
+    --columns: 2;
+  }
+  @media (--large) {
+    --columns: 4;
+  }
+}
+
+.cta {
+  grid-column: 1 / -1;
+
+  & a {
+    font-weight: 500;
+    font-size: 17px;
+    line-height: 20px;
+    letter-spacing: 0.0125em;
+    text-decoration: underline;
+    text-underline-offset: 3px;
+    display: inline;
+
+    @nest .dark & {
+      color: var(--wpl-neutral-300);
+    }
+  }
+}

package/src/components/related-content/types.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import type { CardProps } from '../card/types'
+
+export interface RelatedContentProps {
+	appearance?: 'light' | 'dark'
+	headline: string
+	description?: string
+	cards: Array<RelatedContentCardProps>
+	cta: RelatedContentCtaProps
+}
+
+interface RelatedContentCtaProps {
+	href: string
+	text: string
+}
+
+type RelatedContentCardProps = Omit<CardProps, 'appearance'>

package/src/components/subnav/helpers/areBasePathsMatching.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+export function areBasePathsMatching(pathA: string, pathB: string) {
+	if (!pathA || !pathB) return false
+	// use .filter(Boolean) to remove any falsy values, like ""
+	const [pathABase] = pathA.split('/').filter(Boolean)
+	const [pathBBase] = pathB.split('/').filter(Boolean)
+
+	return pathABase === pathBBase
+}

package/src/components/subnav/helpers/traverse/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+function visitObject(objectIn, handleNode) {
+	const objectOut = {}
+	Object.keys(objectIn).forEach((key) => {
+		objectOut[key] = visitProperty(key, objectIn[key], handleNode)
+	})
+	return objectOut
+}
+
+function visitProperty(key, value, handleNode) {
+	const handledValue = handleNode(key, value)
+	if (isObject(value)) {
+		return visitObject(handledValue, handleNode)
+	} else if (isArray(handledValue)) {
+		return handledValue.map((v) => visitProperty(key, v, handleNode))
+	} else {
+		return handledValue
+	}
+}
+
+// Returns true if a value is an array, false otherwise
+export function isArray(value) {
+	return value && typeof value === 'object' && value.constructor === Array
+}
+
+// Returns true if a value is an object, false otherwise
+export function isObject(value) {
+	return value && typeof value === 'object' && value.constructor === Object
+}
+
+function traverse(
+	valueIn: unknown,
+	handleNode: (key: unknown, value: unknown) => unknown = (n) => n
+) {
+	return visitProperty(false, valueIn, handleNode)
+}
+
+export default traverse

package/src/components/subnav/helpers/useHeightRef.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import { useCallback, useState } from 'react'
+
+export default function useHeightRef(): [number, (target: any) => void] {
+	const [height, setHeight] = useState(0)
+
+	const heightRef = useCallback((target) => {
+		let viewport
+		let requestId
+
+		if (target) {
+			viewport = target.ownerDocument.defaultView
+			viewport.addEventListener('resize', requestHeight)
+
+			requestHeight()
+
+			return cleanup
+		}
+
+		function requestHeight() {
+			if (!requestId) requestId = requestAnimationFrame(checkHeight)
+		}
+
+		function checkHeight() {
+			requestId = null
+			setHeight(target.offsetHeight)
+		}
+
+		function cleanup() {
+			cancelAnimationFrame(requestId)
+			viewport.removeEventListener('resize', requestHeight)
+		}
+	}, undefined as any)
+	// Current behavior requires that this callback have a dependency list of
+	// `undefined` even though that's not a valid invocation of useCallback.
+
+	return [height, heightRef]
+}

package/src/components/subnav/helpers/useNavRef.ts

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import useHeightRef from './useHeightRef'
+import useOverflowRef from './useOverflowRef'
+import useStuckRef from './useStuckRef'
+
+export default function useNavRef(): [
+	boolean,
+	boolean,
+	number,
+	(target: any) => void
+] {
+	const [isStuck, stuckRef] = useStuckRef()
+	const [hasOverflow, overflowRef] = useOverflowRef()
+	const [height, heightRef] = useHeightRef()
+
+	return [
+		isStuck,
+		hasOverflow,
+		height,
+		function navRef(target) {
+			if (typeof stuckRef === 'function') stuckRef(target)
+			if (typeof overflowRef === 'function') overflowRef(target)
+			if (typeof heightRef === 'function') heightRef(target)
+		},
+	]
+}

package/src/components/subnav/helpers/useOverflowRef.ts

@@ -0,0 +1,85 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import { useCallback, useState } from 'react'
+
+const MutationObserver =
+	(typeof window !== 'undefined' && window.MutationObserver) || null
+const mutationOpts = { attributes: true, childList: true, subtree: true }
+
+/*
+
+Overflow is determined by whether the width of a target element’s content is
+greater than the width of its layout.
+
+Overflow is checked on viewport resize and on a target element’s DOM mutation.
+Both are throttled by animation frame requests.
+
+MutationObserver Compatibility (https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver):
+
+- Chrome 26+
+- Edge 12+
+- Firefox 14+
+- Internet Explorer 11+
+- Safari 17+
+
+*/
+
+export default function useOverflowRef(): [boolean, (target: any) => void] {
+	const [[hasOverflow, currentScrollWidth], setState] = useState([false, 0])
+
+	const overflowRef = useCallback((target) => {
+		let viewport
+		let requestId
+		let mutationObserver
+
+		if (target) {
+			viewport = target.ownerDocument.defaultView
+
+			viewport.addEventListener('resize', requestOverflow)
+
+			if (MutationObserver) {
+				mutationObserver = new MutationObserver(requestOverflow)
+
+				mutationObserver.observe(target, mutationOpts)
+			}
+
+			requestOverflow()
+
+			return cleanup
+		}
+
+		function requestOverflow() {
+			if (!requestId) requestId = requestAnimationFrame(checkOverflow)
+		}
+
+		function checkOverflow() {
+			requestId = null
+
+			const newScrollWidth = target.scrollWidth
+			const newOffsetWidth = target.offsetWidth
+			const newHasOverflow =
+				(currentScrollWidth || newScrollWidth) > newOffsetWidth
+
+			if (hasOverflow !== newHasOverflow) {
+				cleanup()
+
+				setState([newHasOverflow, newScrollWidth])
+			}
+		}
+
+		function cleanup() {
+			cancelAnimationFrame(requestId)
+
+			viewport.removeEventListener('resize', requestOverflow)
+
+			if (MutationObserver) mutationObserver.disconnect()
+		}
+	}, undefined as any)
+	// Current behavior requires that this callback have a dependency list of
+	// `undefined` even though that's not a valid invocation of useCallback.
+
+	return [hasOverflow, overflowRef]
+}

package/src/components/subnav/helpers/useStuckRef.ts

@@ -0,0 +1,51 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import { useCallback, useState } from 'react'
+
+const IntersectionObserver =
+	(typeof window !== 'undefined' && window.IntersectionObserver) || null
+const intersectionOpts = { threshold: [1] }
+
+/*
+
+Stuck-ness is determined by whether a sticky target element has intersected the
+top boundary of its viewport.
+
+Stuck-ness is checked on intersection observation.
+
+IntersectionObserver Compatibility (https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver#Browser_compatibility):
+
+- Chrome 51+
+- Edge 15+
+- Firefox 55+
+- Safari 12.1+
+
+Internet Explorer 11 gracefully skips over this functionality, as it does not
+support `IntersectionObserver` or CSS `position: sticky`.
+
+*/
+
+export default function useStuckRef(): [boolean, (target: any) => void] {
+	const [isStuck, setStuck] = useState(false)
+
+	const stuckRef = useCallback((target) => {
+		if (target && IntersectionObserver) {
+			const intersectionObserver = new IntersectionObserver(([entry]) => {
+				const nowIsStuck = entry.intersectionRatio < 1
+
+				if (isStuck !== nowIsStuck) setStuck(nowIsStuck)
+			}, intersectionOpts)
+
+			intersectionObserver.observe(target)
+
+			return intersectionObserver.disconnect.bind(intersectionObserver)
+		}
+	}, undefined as any)
+	// Current behavior requires that this callback have a dependency list of
+	// `undefined` even though that's not a valid invocation of useCallback.
+
+	return [isStuck, stuckRef]
+}

package/src/components/subnav/index.tsx

@@ -0,0 +1,199 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+'use client'
+
+import { useState } from 'react'
+import classNames from 'classnames'
+import useProductMeta, { Products } from '@hashicorp/platform-product-meta'
+import { THEMES } from './subnav-consts'
+import useNavRef from './helpers/useNavRef'
+import s from './style.module.css'
+import themeStyles from './theme.module.css'
+
+import MenuItemsOverflow from './partials/MenuItemsOverflow'
+import TitleLink from './partials/TitleLink'
+import MenuItemsDefault from './partials/MenuItemsDefault'
+import CtaLinks, { type CtaLinkProps } from './partials/CtaLinks'
+import traverse, { isObject } from './helpers/traverse'
+import { areBasePathsMatching } from './helpers/areBasePathsMatching'
+import * as NavigationMenu from '@radix-ui/react-navigation-menu'
+
+const productAllowList = {
+	consul: 'consul',
+	hcp: 'hcp',
+	nomad: 'nomad',
+	packer: 'packer',
+	terraform: 'terraform',
+	tfc: 'terraform',
+	vagrant: 'vagrant',
+	vault: 'vault',
+	boundary: 'boundary',
+	waypoint: 'waypoint',
+}
+
+type SubnavLink = {
+	text: string
+	url: string
+	_isActiveUrl?: boolean
+}
+
+type SubnavDropdown = {
+	text: string
+	submenu: Array<SubnavLink>
+}
+
+type MenuItem = SubnavLink | SubnavDropdown | 'divider'
+
+export interface SubnavInnerProps {
+	hasOverflow?: boolean
+	titleLink: { text: string; url: string }
+	product?: Products
+	ctaLinks?: CtaLinkProps
+	hideGithubStars?: boolean
+	menuItems: Array<MenuItem>
+	constrainWidth?: boolean
+	currentPath: string
+	matchOnBasePath?: boolean
+	theme?: (typeof THEMES)[number]
+	menuText?: string
+	activatePanel: (panel: string) => void
+}
+
+function SubnavInner({
+	hasOverflow,
+	titleLink,
+	product,
+	ctaLinks = [],
+	hideGithubStars,
+	menuItems,
+	constrainWidth,
+	currentPath,
+	matchOnBasePath = false,
+	theme = 'light',
+	menuText = 'Menu',
+	activatePanel,
+}: SubnavInnerProps) {
+	const { themeClass } = useProductMeta(product) // overrides --brand css vars
+	// Add _isActiveUrl to menuItems so we can highlight them appropriately
+	const menuItemsWithActive = traverse(menuItems, (_key, value: any) => {
+		const hasUrl = isObject(value) && value.url
+		if (hasUrl) {
+			value._isActiveUrl = matchOnBasePath
+				? areBasePathsMatching(value.url, currentPath)
+				: value.url === currentPath
+		}
+		return value
+	})
+
+	/**
+	 * Note on constrainWidth & g-grid-container
+	 *
+	 * TEMPORARY: this is a temporary patch
+	 * to constrain the width of the subnav.
+	 * We want to settle on fully consistent subnav
+	 * max-width and alignment behavior at some point
+	 * Related Asana task:
+	 * https://app.asana.com/0/1126477231080283/1162972875950505/f
+	 */
+	return (
+		<div className={s.subnavInnerRoot}>
+			<div
+				className={classNames(s.subnavInner, themeClass, {
+					'g-grid-container': constrainWidth,
+					[s.notConstrained]: !constrainWidth,
+					[s.hasOverflow]: hasOverflow,
+				})}
+				data-overflow-target
+			>
+				<NavigationMenu.Link asChild>
+					<TitleLink
+						text={titleLink.text}
+						url={titleLink.url}
+						product={product}
+						theme={theme}
+					/>
+				</NavigationMenu.Link>
+				{!hasOverflow && (
+					<div className={s.subNavRight}>
+						<MenuItemsDefault
+							menuItems={menuItemsWithActive}
+							activatePanel={activatePanel}
+						/>
+						{ctaLinks?.length > 0 && (
+							<CtaLinks
+								links={ctaLinks}
+								product={product}
+								hideGithubStars={hideGithubStars}
+							/>
+						)}
+					</div>
+				)}
+				{hasOverflow && (
+					<MenuItemsOverflow
+						menuItems={menuItemsWithActive}
+						ctaLinks={ctaLinks}
+						hideGithubStars={hideGithubStars}
+						product={product}
+						menuText={menuText}
+						constrainWidth={constrainWidth}
+						activatePanel={activatePanel}
+					/>
+				)}
+			</div>
+		</div>
+	)
+}
+
+export interface SubnavProps extends Omit<SubnavInnerProps, 'activatePanel'> {
+	className?: string
+}
+
+function Subnav({ className, theme = 'light', ...restProps }: SubnavProps) {
+	const [activePanel, setActivePanel] = useState('')
+	const [isSticky, hasOverflow, height, wrapperRef] = useNavRef()
+	// Set the brand theme automatically based on the nav's title
+	const product =
+		(restProps.product &&
+			restProps.product in productAllowList &&
+			productAllowList[restProps.product]) ||
+		'hashicorp'
+
+	const activatePanel = (panel) => {
+		setActivePanel(panel)
+	}
+
+	return (
+		<>
+			{/**
+			 * Injecting a :root css var for subnav-height so the `scroll-margin-top`
+			 * property on all page anchors can be dynamic based on the height of
+			 * the subnav.
+			 */}
+			<style>{`:root{--subnav-height:${height}px}`}</style>
+			<NavigationMenu.Root
+				ref={wrapperRef}
+				className={classNames(s.root, themeStyles[theme], className, {
+					[s.isSticky]: isSticky,
+					[s.hasOverflow]: hasOverflow,
+				})}
+				aria-label={`${product} website navigation`}
+				onValueChange={activatePanel}
+				value={activePanel}
+				delayDuration={0}
+			>
+				<SubnavInner
+					{...restProps}
+					product={product}
+					hasOverflow={hasOverflow}
+					theme={theme}
+					activatePanel={activatePanel}
+				/>
+			</NavigationMenu.Root>
+		</>
+	)
+}
+
+export default Subnav